X-Git-Url: http://git.linux-vserver.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=util-vserver%2Flib%2Fvserver.h;h=eaa2026406f52e36c7534d77b88791a73af484ef;hb=604935bf1fd1734779f20b537aef15b9486940a8;hp=88c708512d4c23a8d727d5732f877076a2c1aab7;hpb=6827f541b7589f47873f594660709fc163cdd902;p=util-vserver.git diff --git a/util-vserver/lib/vserver.h b/util-vserver/lib/vserver.h index 88c7085..eaa2026 100644 --- a/util-vserver/lib/vserver.h +++ b/util-vserver/lib/vserver.h @@ -17,6 +17,10 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** \file vserver.h + * \brief The public interface of the the libvserver library. + */ + #ifndef H_VSERVER_SYSCALL_H #define H_VSERVER_SYSCALL_H @@ -25,10 +29,39 @@ #include #include +#ifndef IS_DOXYGEN +#if defined(__GNUC__) +# define VC_ATTR_UNUSED __attribute__((__unused__)) +# define VC_ATTR_NORETURN __attribute__((__noreturn__)) +# 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__*0x10000 + __GNUC_MINOR__*0x100 + __GNUC_PATCHLEVEL__ >= 0x30303 +# define VC_ATTR_PURE __attribute__((__pure__)) +# else +# define VC_ATTR_PURE +# endif +#else +# define VC_ATTR_NONNULL(ARGS) +# 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)) /** the value which means a random (the next free) ctx */ -#define VC_RANDCTX ((xid_t)(-1)) +#define VC_DYNAMIC_XID ((xid_t)(-1)) /** the value which means the current ctx */ #define VC_SAMECTX ((xid_t)(-2)) @@ -64,6 +97,10 @@ # define S_CTX_INFO_ULIMIT 64 #endif +#ifndef S_CTX_INFO_NAMESPACE +# define S_CTX_INFO_NAMESPACE 128 +#endif + #define VC_CAP_CHOWN 0 #define VC_CAP_DAC_OVERRIDE 1 #define VC_CAP_DAC_READ_SEARCH 2 @@ -99,88 +136,330 @@ #define VC_IMMUTABLE_LINK_FL 0x00008000l #define VC_IMMUTABLE_ALL (VC_IMMUTABLE_LINK_FL|VC_IMMUTABLE_FILE_FL) +#define VC_IATTR_XID 0x01000000 + +#define VC_IATTR_ADMIN 0x00000001 +#define VC_IATTR_WATCH 0x00000002 +#define VC_IATTR_HIDE 0x00000004 +#define VC_IATTR_FLAGS 0x00000007 + +#define VC_IATTR_BARRIER 0x00010000 +#define VC_IATTR_IUNLINK 0x00020000 +#define VC_IATTR_IMMUTABLE 0x00040000 + + +// the flags +#define VC_VXF_INFO_LOCK 0x00000001 +#define VC_VXF_INFO_NPROC 0x00000004 +#define VC_VXF_INFO_PRIVATE 0x00000008 +#define VC_VXF_INFO_INIT 0x00000010 + +#define VC_VXF_INFO_HIDEINFO 0x00000020 +#define VC_VXF_INFO_ULIMIT 0x00000040 +#define VC_VXF_INFO_NAMESPACE 0x00000080 + +#define VC_VXF_SCHED_HARD 0x00000100 +#define VC_VXF_SCHED_PRIO 0x00000200 +#define VC_VXF_SCHED_PAUSE 0x00000400 + +#define VC_VXF_VIRT_MEM 0x00010000 +#define VC_VXF_VIRT_UPTIME 0x00020000 +#define VC_VXF_VIRT_CPU 0x00040000 + +#define VC_VXF_HIDE_MOUNT 0x01000000 +#define VC_VXF_HIDE_NETIF 0x02000000 + +#define VC_VXF_STATE_SETUP (1ULL<<32) +#define VC_VXF_STATE_INIT (1ULL<<33) + +// the ccapabilities +#define VC_VXC_SET_UTSNAME 0x00000001 +#define VC_VXC_SET_RLIMIT 0x00000002 + +#define VC_VXC_ICMP_PING 0x00000100 + +#define VC_VXC_SECURE_MOUNT 0x00010000 + + +/** \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; +#endif + #ifdef __cplusplus extern "C" { #endif struct vc_ip_mask_pair { uint32_t ip; - uint32_t mask; + uint32_t mask; }; - /** Returns version of the given API-category */ - int vc_get_version(int category); + /** \brief Returns the version of the current kernel API. + * \ingroup syscalls + * \returns The versionnumber of the kernel API + */ + int vc_get_version(); - /** Puts current process into context , removes the given caps and - * sets flags. - * Special values for ctx are - * - VC_SAMECTX which means the current context (just for changing caps and flags) - * - VC_RANDCTX which means the next free context; this value can be used by - * ordinary users also + /** \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. + * + * \param ctx The new context; special values for are + * - VC_SAMECTX which means the current context (just for changing caps and flags) + * - VC_DYNAMIC_XID which means the next free context; this value can be used by + * ordinary users also + * \param remove_cap The linux capabilities which will be \b removed. + * \param flags Special flags which will be set. + * + * \returns The new context-id, or VC_NOCTX on errors; errno + * will be set appropriately + * * See http://vserver.13thfloor.at/Stuff/Logic.txt for details */ - int vc_new_s_context(xid_t ctx, unsigned int remove_cap, unsigned int flags); - - /** Sets the ipv4root information. - * \precondition: nb<16 */ - int vc_set_ipv4root(uint32_t bcast, size_t nb, struct vc_ip_mask_pair const *ips); - - /* rlimit related functions */ - typedef uint64_t vc_limit_t; + 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. + * + * \param xid The new context; special values are: + * - VC_DYNAMIC_XID which means to create a dynamic context + * + * \returns the xid of the created context, or VC_NOCTX on errors. errno + * will be set appropriately. */ + 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_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; - vc_limit_t soft; - vc_limit_t hard; + 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 { - uint32_t min; - uint32_t soft; - uint32_t hard; + 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 }; - int vc_get_rlimit(xid_t ctx, int resource, struct vc_rlimit *lim); - int vc_set_rlimit(xid_t ctx, int resource, struct vc_rlimit const *lim); - int vc_get_rlimit_mask(xid_t ctx, struct vc_rlimit_mask *lim); + /** \brief Returns 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 result which will be filled with the limits + * + * \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)); + /** \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)); + + + /** \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); - /** 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 */ - int vc_ctx_kill(xid_t ctx, pid_t pid, int sig); + int vc_set_iattr(char const *filename, xid_t xid, + uint_least32_t flags, uint_least32_t mask) VC_ATTR_NONNULL((1)); + int vc_get_iattr(char const *filename, xid_t * /*@null@*/ xid, + uint_least32_t * /*@null@*/ flags, + uint_least32_t * /*@null@*/ mask) VC_ATTR_NONNULL((1)); + struct vc_vx_info { + xid_t xid; + pid_t initpid; + }; + /** Returns the context of the given process. pid==0 means the current process. */ - xid_t vc_X_getctx(pid_t pid); + 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)); + - /** Returns the pid of the 'init' process */ - pid_t vc_X_getinitpid(pid_t pid); + typedef enum { vcVHI_CONTEXT, vcVHI_SYSNAME, vcVHI_NODENAME, + vcVHI_RELEASE, vcVHI_VERSION, vcVHI_MACHINE, + vcVHI_DOMAINNAME } vc_uts_type; + + int vc_set_vhi_name(xid_t xid, vc_uts_type type, + char const *val, size_t len) VC_ATTR_NONNULL((3)); + 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); - xid_t vc_X_get_filecontext(int fd); - int vc_X_set_filecontext(int fd, xid_t ctx); + int vc_enter_namespace(xid_t xid); + int vc_set_namespace(); + int vc_cleanup_namespace(); - int vc_X_get_ext2flags(int fd, long *flags); - int vc_X_set_ext2flags(int fd, long set_flags, long del_flags); + struct vc_ctx_flags { + uint_least64_t flagword; + uint_least64_t mask; + }; + + struct vc_ctx_caps { + uint_least64_t bcaps; + uint_least64_t bmask; + uint_least64_t ccaps; + uint_least64_t cmask; + }; + + struct vc_err_listparser { + char const *ptr; + size_t len; + }; + + 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, + struct vc_err_listparser *err, + struct vc_ctx_caps *); + + uint_least64_t vc_text2ccap(char const *, size_t len); + char const * vc_loccap2text(uint_least64_t *); + int vc_list2ccap(char const *, size_t len, + struct vc_err_listparser *err, + struct vc_ctx_caps *); + + int vc_list2cflag(char const *, size_t len, + struct vc_err_listparser *err, + struct vc_ctx_flags *flags); + uint_least64_t vc_text2cflag(char const *, size_t len); + char const * vc_locflag2text(uint_least64_t *); + + uint_least32_t vc_list2cflag_compat(char const *, size_t len, + struct vc_err_listparser *err); + uint_least32_t vc_text2cflag_compat(char const *, size_t len); + char const * vc_hicflag2text_compat(uint_least32_t); + uint_least32_t vc_get_insecurecaps() VC_ATTR_CONST; + int vc_text2cap(char const *); + char const * vc_cap2text(unsigned int); - int vc_text2cap(char const *); - char const * vc_cap2text(int); - inline static int vc_get_securecaps() { - return ( (1<