added cflags
[util-vserver.git] / util-vserver / lib / vserver.h
index 4c71fad..eaa2026 100644 (file)
 #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,7 +52,9 @@
 #  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
 
 #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;
   };
 
     /** \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 +229,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 +253,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,17 +301,46 @@ 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);
 
 
@@ -262,6 +370,8 @@ 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();
@@ -274,6 +384,7 @@ extern "C" {
   
   struct  vc_ctx_caps {
       uint_least64_t   bcaps;
+      uint_least64_t   bmask;
       uint_least64_t   ccaps;
       uint_least64_t   cmask;
   };
@@ -283,8 +394,8 @@ extern "C" {
       size_t           len;
   };
  
-  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 *);
@@ -301,36 +412,27 @@ 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);
-  
-  int          vc_text2cap(char const *);
-  char const * vc_cap2text(unsigned int);
-
-  inline static uint_least32_t vc_get_securecaps() {
-    return ( (1<<VC_CAP_LINUX_IMMUTABLE) | (1<<VC_CAP_NET_BROADCAST) |
-            (1<<VC_CAP_NET_ADMIN) | (1<<VC_CAP_NET_RAW) |
-            (1<<VC_CAP_IPC_LOCK) | (1<<VC_CAP_IPC_OWNER) |
-            (1<<VC_CAP_SYS_MODULE) | (1<<VC_CAP_SYS_RAWIO) |
-            (1<<VC_CAP_SYS_PACCT) | (1<<VC_CAP_SYS_ADMIN) |
-            (1<<VC_CAP_SYS_BOOT) | (1<<VC_CAP_SYS_NICE) |
-            (1<<VC_CAP_SYS_RESOURCE) | (1<<VC_CAP_SYS_TIME) |
-            (1<<VC_CAP_MKNOD) | (1<<VC_CAP_QUOTACTL) );
-  }
+  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);
 
-  inline static int            vc_setfilecontext(char const *filename, xid_t xid) {
+
+  inline static int    vc_setfilecontext(char const *filename, xid_t xid) {
     return vc_set_iattr(filename, xid, 0, VC_IATTR_XID);
   }
   
-  inline static xid_t          vc_getfilecontext(char const *filename) {
+  inline static xid_t  vc_getfilecontext(char const *filename) {
     xid_t      res;
     if (vc_get_iattr(filename, &res, 0,0)==-1) return VC_NOCTX;
     return res;
@@ -339,9 +441,11 @@ extern "C" {
 
   struct vc_set_sched {
       int32_t  fill_rate;
-      int32_t  period;
-      int32_t  fill_level;
-      int32_t  bucket_size;
+      int32_t  interval;
+      int32_t  tokens;
+      int32_t  tokens_min;
+      int32_t  tokens_max;
+      uint64_t cpu_mask;
   };
 
   int          vc_set_sched(xid_t xid, struct vc_set_sched const *);
@@ -349,12 +453,13 @@ extern "C" {
   
   typedef enum { vcFEATURE_VKILL,  vcFEATURE_IATTR,   vcFEATURE_RLIMIT,
                 vcFEATURE_COMPAT, vcFEATURE_MIGRATE, vcFEATURE_NAMESPACE,
-                vcFEATURE_SCHED,  vcFEATURE_VINFO,   vcFEATURE_VHI }
+                vcFEATURE_SCHED,  vcFEATURE_VINFO,   vcFEATURE_VHI,
+                 vcFEATURE_VSHELPER0, vcFEATURE_VSHELPER }
     vcFeatureSet;
 
-  bool         vc_isSupported(vcFeatureSet);
+  bool         vc_isSupported(vcFeatureSet) VC_ATTR_CONST;
   bool         vc_isSupportedString(char const *);
-  
+
   /* The management part */
 
 #define VC_LIMIT_VSERVER_NAME_LEN      1024
@@ -364,6 +469,10 @@ extern "C" {
                 vcCFG_RECENT_SHORT,
                 vcCFG_RECENT_FULL }            vcCfgStyle;
 
+
+  /** Maps an xid given at '--xid' options to an xid_t */
+  xid_t                vc_xidopt2xid(char const *, bool honor_static, char const **err_info);
+
   vcCfgStyle   vc_getVserverCfgStyle(char const *id);
   
   /** Resolves the name of the vserver. The result will be allocated and must