client/vasum.h

   1 /*
   2  * Vasum : Tizen Zone Control Framework
   3  *
   4  * Copyright (c) 2000 - 2014 Samsung Electronics Co., Ltd All Rights Reserved
   5  *
   6  * Contact: Keunhwan Kwak <kh243.kwak@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21 #ifndef __VASUM_H__
  22 #define __VASUM_H__
  23
  24 #include <unistd.h>
  25 #include <limits.h>
  26 #include <inttypes.h>
  27 #include <sys/types.h>
  28 #include <sys/mount.h>
  29
  30 #include "vasum_list.h"
  31
  32 #ifndef API
  33 #define API __attribute__((visibility("default")))
  34 #endif // API
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39 /*
  40  * @file        vasum.h
  41  * @version     0.3
  42  * @brief       This file contains APIs of the Zone control Framework
  43  */
  44
  45 /*
  46  * <tt>
  47  * Revision History:
  48  *   2014-09-01 sungbae you    First created
  49  *   2014-10-07 sungbae you    First doxygen commented
  50  *   2015-03-19 kuenhwan Kwak  doxygen revise
  51  * </tt>
  52  */
  53
  54 /**
  55  * @addtogroup CONTEXT vasum context
  56  * @{
  57 */
  58
  59 /**
  60  *@brief vasum handle for interact with vasum server process. This is opaque data type.
  61  */
  62 typedef struct vsm_context* vsm_context_h;
  63
  64 /**
  65  * @brief Create vsm context
  66  * \par Description:
  67  * The vsm context is an abstraction of the logical connection between the zone controller and it's clients.
  68  * and vsm_context_h object should be finalized when interaction with the vasum server is no longer required.\n
  69  * \return An instance of vsm context on success, or NULL
  70  * \retval vsm_context_h     successful
  71  * \retval NULL               get vasum context failed.
  72  * \par Known issues/bugs:
  73  *  Only a host process has permission for vsm_create_context();
  74  * \pre vsm-zone-svc must be started
  75  * \see vsm_cleanup_context()
  76 */
  77 API vsm_context_h vsm_create_context(void);
  78
  79 /**
  80  * @brief Cleanup zone control context
  81  * \par Description:
  82  * vsm_cleanup_context() finalizes vsm context and release all resources allocated to the vsm context.\n
  83  * This function should be called if interaction with the zone controller is no longer required.
  84  * \param[in] ctx vsm context
  85  * \return #VSM_ERROR_NONE on success.
  86  * \pre vsm_context_h must be initialized by vsm_create_context()
  87  * \post vsm context_h will not be valid after calling this API
  88  * \see vsm_create_context()
  89 */
  90 API int vsm_cleanup_context(vsm_context_h ctx);
  91
  92 /**
  93  * @brief Get file descriptor associated with event dispatcher of zone control context
  94  * \par Description:
  95  * The function vsm_get_poll_fd() returns the file descriptor associated with the event dispatcher of vsm context.\n
  96  * The file descriptor can be bound to another I/O multiplexing facilities like epoll, select, and poll.
  97  * \param[in] ctx vsm context
  98  * \return On success, a nonnegative file descriptor is returned. On negative error code is returned.
  99  * \retval fd nonnegative integer fd value for getting vasum event and refresh vsm_context_h.
 100  * \retval #VSM_ERROR_INVALID invalid vsm_context_h
 101  * \pre vsm_context_h must be initialized by vsm_create_context()
 102  * \see vsm_create_context()
 103 */
 104 API int vsm_get_poll_fd(vsm_context_h ctx);
 105
 106 /**
 107  * @brief Wait for an I/O event on a VSM context
 108  * \par Description:
 109  * vsm_enter_eventloop() waits for event on the vsm context.\n
 110  *\n
 111  * The call waits for a maximum time of timout milliseconds. Specifying a timeout of -1 makes vsm_enter_eventloop() wait indefinitely,
 112  * while specifying a timeout equal to zero makes vsm_enter_eventloop() to return immediately even if no events are available.
 113  * \param[in] ctx vsm context
 114  * \param[in] flags Reserved
 115  * \param[in] timeout Timeout time (milisecond), -1 is infinite
 116  * \return 0 on success,  or negative error code.
 117  * \pre vsm context must be initialized by vsm_create_context()
 118  * \see vsm_create_context(), vsm_get_poll_fd()
 119 */
 120 API int vsm_enter_eventloop(vsm_context_h ctx, int flags, int timeout);
 121
 122 /**
 123  * @brief Enumeration for vasum error.
 124  */
 125 typedef enum {
 126         VSM_ERROR_NONE,                 /**< The operation was successful */
 127         VSM_ERROR_GENERIC,              /**< Non-specific cause */
 128         VSM_ERROR_INVALID,              /**< Invalid argument */
 129         VSM_ERROR_CANCELED,             /**< The requested operation was cancelled */
 130         VSM_ERROR_ABORTED,              /**< Operation aborted */
 131         VSM_ERROR_REFUSED,              /**< Connection refused */
 132         VSM_ERROR_EXIST,                /**< Target exists */
 133         VSM_ERROR_BUSY,                 /**< Resource is busy */
 134         VSM_ERROR_IO,                   /**< I/O error*/
 135         VSM_ERROR_TIMEOUT,              /**< Timer expired */
 136         VSM_ERROR_OVERFLOW,             /**< Value too large to be stored in data type */
 137         VSM_ERROR_OUT_OF_MEMORY,        /**< No memory space */
 138         VSM_ERROR_OUT_OF_RANGE,         /**< Input is out of range */
 139         VSM_ERROR_NOT_PERMITTED,                /**< Operation not permitted */
 140         VSM_ERROR_NOT_IMPLEMENTED,      /**< Function is not implemented yet */
 141         VSM_ERROR_NOT_SUPPORTED,        /**< Operation is not supported */
 142         VSM_ERROR_ACCESS_DENIED,        /**< Access privilege is not sufficient */
 143         VSM_ERROR_NO_OBJECT,            /**< Object not found */
 144         VSM_ERROR_BAD_STATE,            /**< Bad state */
 145         VSM_MAX_ERROR = VSM_ERROR_BAD_STATE
 146 }vsm_error_e;
 147
 148 /**
 149  * @brief Get last vasum error code from vsm_context.
 150  * \param[in] ctx vsm context
 151  * \return vasum error enum value.
 152  * \par Known issues/bugs:
 153  *     thread non-safe
 154  * \see vsm_error_string()
 155 */
 156 API vsm_error_e vsm_last_error(vsm_context_h ctx);
 157
 158 /**
 159  * @brief Get vasum error string.
 160  * \par Description:
 161  * return string pointer for vasum error string.
 162  * \param[in] error vsm_error_e.
 163  * \return string pointer value represent to error code.
 164  * \warning Do not free returned pointer.
 165 */
 166 API const char *vsm_error_string(vsm_error_e error);
 167
 168 /// @}
 169
 170 /**
 171  * @addtogroup LIFECYCLE Vasum Lifecycle
 172  * @{
 173  */
 174
 175 /**
 176  * @brief vsm_zone_h opaque datatype which is used to represent an instance of zone.
 177  */
 178
 179 typedef struct vsm_zone* vsm_zone_h;
 180
 181 /**
 182  * @brief Definition for default zone name.
 183  * Default zone is started at boot sequence by systemd.
 184 */
 185 #define VSM_DEFAULT_ZONE "personal"
 186
 187
 188 /**
 189  * @brief Create a new persistent zone
 190  * \par Description:
 191  * vsm_create_zone() triggers zone controller to create new persistent zone.\n\n
 192  * The zone controller distinguishes two types of zones: peristent and transient.
 193  * Persistent zones exist indefinitely in storage.
 194  * While, transient zones are created and started on-the-fly.\n\n
 195  * Creating zone requires template.\n
 196  * In general, creating a zone involves constructing root file filesystem and
 197  * generating configuration files which is used to feature the zone.
 198  * Moreover, it often requires downloading tools and applications pages,
 199  * which are not available in device.
 200  * In that reason, Vasum Framework delegates this work to templates.
 201  * \param[in] ctx vsm context
 202  * \param[in] zone_name zone name
 203  * \param[in] template_name template name to be used for constructing the zone
 204  * \param[in] flag Reserved
 205  * \return 0 on success, or negative integer error code on error.
 206  * \retval #VSM_ERROR_NONE     Successful
 207  * \retval #VSM_ERROR_INVALID  Invalid arguments
 208  * \retval #VSM_ERROR_EXIST    The same name zone is existed.
 209  * \retval #VSM_ERROR_GENERIC  Lxc failed to create zone.
 210  * \retval #VSM_ERROR_IO       Database access failed
 211 */
 212 API int vsm_create_zone(vsm_context_h ctx, const char *zone_name, const char *template_name, int flag);
 213
 214 /**
 215  * @brief Destroy persistent zone
 216  * \par Description:
 217  * The function vsm_destroy_zone() triggers zone controller to destroy persistent zone corresponding to the given name.\n
 218  * All data stored in the repository of the zone are also deleted if force argument is set.
 219  * Once the zone repository is deleted, it cannot be recovered.
 220  * \param[in] ctx vsm context
 221  * \param[in] zone_name zone name
 222  * \param[in] force forced flags
 223  * - 0 : do not destory running zone.
 224  * - non-zero : if zone is running, shutdown forcefully, and destroy.
 225  * \return 0 on success, or negative integer error code on error.i
 226  * \retval #VSM_ERROR_NONE       Successful
 227  * \retval #VSM_ERROR_BUSY       Target zone is running
 228  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 229  * \retval #VSM_ERROR_GENERIC    Lxc failed to destroy zone
 230  * \retval #VSM_ERROR_IO         Database access failed
 231 */
 232 API int vsm_destroy_zone(vsm_context_h ctx, const char *zone_name, int force);
 233
 234 /**
 235  * @brief Start an execution of a persistent zone
 236  * \par Description:
 237  * The function vsm_start_zone() triggers zone controller to start zone corresponding to the given name.\n
 238  * Caller can speficy the type of zones: transient and peristent.
 239  * Persistent zones need to be defined before being start up(see vsm_create_zone())
 240  * While, transient zones are created and started on-the-fly.
 241  * \param[in] ctx vsm context
 242  * \param[in] zone_name zone name
 243  * \return 0 on success, or negative integer error code on error.
 244  * \retval #VSM_ERROR_NONE       Successful
 245  * \retval #VSM_ERROR_INVALID    Invalid argument.
 246  * \retval #VSM_ERROR_BUSY       Target zone is already running state.
 247  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 248  * \retval #VSM_ERROR_GENERIC    Lxc failed to start zone
 249 */
 250 API int vsm_start_zone(vsm_context_h ctx, const char *zone_name);
 251
 252 /**
 253  * @brief Stop an execution of running zone
 254  * \par Description:
 255  * Send request to stop running zone.\n
 256  * \param[in] ctx vsm context
 257  * \param[in] zone_name zone name
 258  * \param[in] force option to shutdown.
 259  *      - 0 : send SIGPWR signal to init process of target zone.
 260  *  - non-zero : terminate all processes in target zone.
 261  * \return 0 on success, or negative integer error code on error.
 262  * \retval #VSM_ERROR_NONE       Successful
 263  * \retval #VSM_ERROR_INVALID    Invalid argument.
 264  * \retval #VSM_ERROR_BAD_STATE  Failed to lookup running zone.
 265  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 266  * \retval #VSM_ERROR_GENERIC    Lxc failed to destroy zone
 267 */
 268 API int vsm_shutdown_zone(vsm_context_h ctx, const char *zone_name, int force);
 269
 270 /**
 271  * @brief Shutdown zone and prevent starting zone
 272  * \par Description:
 273  *  Prevent starting target zone.
 274  *  If target zone is running, shutdown the zone first.
 275  * \param[in] ctx vsm context
 276  * \param[in] zone_name zone name
 277  * \return 0 on success, or negative integer error code on error.
 278  * \retval #VSM_ERROR_NONE       Successful
 279  * \retval #VSM_ERROR_NO_OBJECT  Target zone does not exist
 280  * \retval #VSM_ERROR_GENERIC    Locking failed.
 281 */
 282 API int vsm_lock_zone(vsm_context_h ctx, const char *zone_name, int shutdown);
 283
 284 /**
 285  * @brief Allow a zone to be launched
 286  * \par Description:
 287  * Remove lock applied to the zone corresponding to the given name.
 288  * \param[in] ctx vsm context
 289  * \param[in] zone_name zone name
 290  * \return 0 on success, or negative integer error code on error.
 291  * \retval #VSM_ERROR_NONE       Successful
 292  * \retval #VSM_ERROR_GENERIC    Unlocking failed.
 293 */
 294 API int vsm_unlock_zone(vsm_context_h ctx, const char *zone_name);
 295
 296 /**
 297  * @brief Switch target zone to foreground
 298  * \par Description:
 299  * Switch target zone to foreground on device.
 300  * \param[in] zone vsm_zone_h
 301  * \return 0 on success, or negative integer error code on error.
 302  * \retval #VSM_ERROR_NONE       Successful
 303  * \retval #VSM_ERROR_INVALID    vsm_zone_h is invalid
 304  */
 305 API int vsm_set_foreground(vsm_zone_h zone);
 306
 307 /**
 308  * @brief Get current foreground zone on device
 309  * \par Description:
 310  * Get foreground zone handle.
 311  * \param[in] ctx vsm_context_h
 312  * \return 0 on success, or negative integer error code on error.
 313  * \retval #VSM_ERROR_NONE       Successful
 314  * \retval #VSM_ERROR_INVALID    vsm_context_h is invalid
 315  */
 316 API vsm_zone_h vsm_get_foreground(vsm_context_h ctx);
 317
 318 /// @}
 319 /**
 320  * @addtogroup ACCESS Vasum Access
 321  * @{
 322 */
 323
 324 /**
 325  * @brief Definition for zone states.
 326  * This definition shows the available states.
 327 */
 328 typedef enum {
 329         VSM_ZONE_STATE_STOPPED,  /**< Zone stopped */
 330         VSM_ZONE_STATE_STARTING, /**< Zone is prepare for running */
 331         VSM_ZONE_STATE_RUNNING,  /**< Zone is running on device */
 332         VSM_ZONE_STATE_STOPPING, /**< Zone is stopping by request */
 333         VSM_ZONE_STATE_ABORTING, /**< Zone is failed to start */
 334         VSM_ZONE_STATE_FREEZING, /**< Reserved State */
 335         VSM_ZONE_STATE_FROZEN,   /**< Reserved State */
 336         VSM_ZONE_STATE_THAWED,   /**< Reserved State */
 337         VSM_ZONE_MAX_STATE = VSM_ZONE_STATE_THAWED
 338 } vsm_zone_state_t;
 339
 340
 341 /**
 342  * @brief Definition for zone events
 343 */
 344 typedef enum {
 345         VSM_ZONE_EVENT_NONE,      /**< Zone has no event */
 346         VSM_ZONE_EVENT_CREATED,   /**< Zone is created */
 347         VSM_ZONE_EVENT_DESTROYED, /**< Zone is destroted */
 348         VSM_ZONE_EVENT_SWITCHED,  /**< Foreground is switched */
 349         VSM_ZONE_MAX_EVENT = VSM_ZONE_EVENT_SWITCHED
 350 } vsm_zone_event_t;
 351
 352
 353 /**
 354  * @brief Definition for zone iteration callback function.
 355  */
 356 typedef void (*vsm_zone_iter_cb)(vsm_zone_h zone, void *user_data);
 357 /**
 358  * @brief Definition for zone state changed callback function.
 359  */
 360 typedef int (*vsm_zone_state_changed_cb)(vsm_zone_h zone, vsm_zone_state_t state,  void *user_data);
 361 /**
 362  * @brief Definition for zone event callback function.
 363  */
 364 typedef int (*vsm_zone_event_cb)(vsm_zone_h zone, vsm_zone_event_t event, void *user_data);
 365
 366 /**
 367  * @brief Interate all zone instances which are in running state
 368  * \par Description:
 369  * This API traverses all zones which are in running state, and callback function will be called on every entry.
 370  * \param[in] ctx vsm context
 371  * \param[in] callback Function to be executed in iteration, which can be NULL
 372  * \param[in] user_data Parameter to be passed to callback function
 373  * \return 0 on success, or negative integer error code on error.
 374  * \retval #VSM_ERROR_NONE           Successful
 375  * \retval #VSM_ERROR_OUT_OF_MEMORY  Zone handle allocation failed
 376  * \retval #VSM_ERROR_GENERIC        Zone initialize failed
 377  * \remark In case of callback and is NULL,
 378  *  This API refresh vsm_context which means reloading current running zone to vsm_context again.
 379 */
 380 API int vsm_iterate_zone(vsm_context_h ctx, vsm_zone_iter_cb callback, void *user_data);
 381
 382 /**
 383  * @brief Find zone corresponding to the name
 384  * The function vsm_lookup_zone_by_name() looks for the zone instance corresponding to the given name.
 385  * \param[in] ctx vsm context
 386  * \param[in] name zone name
 387  * \return Zone instance on success, or NULL on error.
 388  * \retval vsm_zone_h  Successful
 389  * \retval NULL        Failed to lookup
 390  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or vsm_context_h does not have current zone status.
 391  * \see vsm_create_context(), vsm_enter_eventloop()
 392 */
 393 API vsm_zone_h vsm_lookup_zone_by_name(vsm_context_h ctx, const char *name);
 394
 395 /**
 396  * @brief Find zone instance associated with the process id
 397  * \par Description:
 398  * The function vsm_lookup_zone_by_pid() looks for the zone instance associated with the given pid.
 399  * \param[in] ctx vsm context
 400  * \param[in] pid Process id
 401  * \return Zone instance on success, or NULL on error.
 402  * \retval vsm_zone_h  Successful
 403  * \retval NULL        Failed to lookup
 404  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or vsm_context_h does not have current zone status.
 405  * \see vsm_create_context(), vsm_enter_eventloop()
 406 */
 407 API vsm_zone_h vsm_lookup_zone_by_pid(vsm_context_h ctx, pid_t pid);
 408
 409 /**
 410  * @brief Register zone status changed callback
 411  * \par Description:
 412  * Register a callback function for zone status change.
 413  * \param[in] ctx vsm context
 414  * \param[in] callback Callback function to invoke when zone satte event occurs
 415  * \return Callback handle on success, or negative error code on error.
 416  * \retval handle nonnegative handle id for callback.
 417  * \retval #VSM_ERROR_OUT_OF_MEMORY  Callback hanlder allocation failed.
 418  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or callback function does not called.
 419  * \see vsm_create_context(), vsm_enter_eventloop(), vsm_del_state_changed_callback()
 420 */
 421 API int vsm_add_state_changed_callback(vsm_context_h ctx, vsm_zone_state_changed_cb callback, void *user_data);
 422
 423 /**
 424  * @brief Deregister zone status changed callback handler
 425  * \par Description:
 426  * Remove an event callback from the zone control context.
 427  * \param[in] ctx vsm context
 428  * \param[in] handle Callback Id to remove
 429  * \return 0 on success, or negative integer error code on error.
 430  * \retval #VSM_ERROR_NONE Successful
 431  * \retval #VSM_ERROR_NO_OBJECT Failed to lookup callback handler
 432 */
 433 API int vsm_del_state_changed_callback(vsm_context_h ctx, int handle);
 434
 435 /**
 436  * @brief Register zone event callback
 437  * \par Description:
 438  * Register a callback function for zone event.
 439  * \param[in] ctx vsm context
 440  * \param[in] callback callback function to invoke when zone event occurs
 441  * \return positive callback handle on success, or negative error code on error.
 442  * \retval handle nonnegative handle id for callback.
 443  * \retval #VSM_ERROR_OUT_OF_MEMORY  Callback hanlder allocation failed.
 444  * \pre  vsm_context_h have to bind by vsm_enter_eventloop() or callback function does not called.
 445  * \see vsm_create_context(), vsm_enter_eventloop(), vsm_del_state_changed_callback()
 446 */
 447 API int vsm_add_event_callback(vsm_context_h ctx, vsm_zone_event_cb callback, void *user_data);
 448
 449 /**
 450  * @brief Deregister zone event callback handler
 451  * \par Description:
 452  * Remove an event callback from the zone control context.
 453  * \param[in] ctx vsm context
 454  * \param[in] handle callback handle to remove
 455  * \return 0 on success, or negative integer error code on error.
 456  * \retval #VSM_ERROR_NONE Successful
 457  * \retval #VSM_ERROR_NO_OBJECT Failed to lookup callback handler
 458 */
 459 API int vsm_del_event_callback(vsm_context_h ctx, int handle);
 460
 461 /**
 462  * @brief Zone attach parameters
 463  * Arguments are same as linux system-call execv()
 464  */
 465 typedef struct vsm_attach_command_s {
 466         char * exec;      /**< Program binary path */
 467         char ** argv;     /**< An array of argument pointers to null-terminated strings include program path */
 468 } vsm_attach_command_s;
 469
 470 /**
 471  * @brief Zone attach option
 472  */
 473 typedef struct vsm_attach_options_s {
 474         uid_t uid;        /**< requested uid*/
 475         gid_t gid;        /**< requested gid*/
 476         int env_num;      /**< requested environ count */
 477         char **extra_env; /**< requested environ string pointer array. */
 478 } vsm_attach_options_s;
 479
 480 /**
 481  * @brief default attach options
 482  * \n
 483  * uid = root\n
 484  * gid = root\n
 485  * env = no extra env\n
 486  */
 487
 488 #define VSM_ATTACH_OPT_DEFAULT {  (uid_t)0, (gid_t)0,  0, NULL }
 489
 490 /**
 491  * @brief Launch a process in a running zone.
 492  * \par Description:
 493  * Execute specific command inside the zone with given arguments and environment
 494  * \param[in] zone_name vsm_zone_h
 495  * \param[in] command vsm attach command
 496  * \param[in] opt vsm attach options (can be NULL), using VSM_ATTACH_OPT_DEFAULT
 497  * \param[out] attached_process process pid
 498  * \return On sucess 0, otherwise, a negative integer error code on error
 499  * \retval #VSM_ERROR_NONE           Successful
 500  * \retval #VSM_ERROR_INVALID        Invalid arguments
 501  * \retval #VSM_ERROR_NO_OBJECT      Target zone is not running state
 502  * \retval #VSM_ERROR_GENERIC        IPC failed
 503  */
 504 API int vsm_attach_zone(vsm_context_h ctx, const char * zone_name, vsm_attach_command_s * command, vsm_attach_options_s * opt, pid_t *attached_process);
 505
 506 /**
 507  * @brief Launch a process in a running zone and wait till child process exited.
 508  * \par Description:
 509  * Execute specific command inside the zone with given arguments and environment
 510  * \param[in] zone_name vsm_zone_h
 511  * \param[in] command vsm attach command
 512  * \param[in] opt vsm attach options (can be NULL), using VSM_ATTACH_OPT_DEFAULT
 513  * \return On sucess waitpid exit code or attached process, or a negative error code
 514  * \retval #VSM_ERROR_NONE           Successful
 515  * \retval #VSM_ERROR_INVALID        Invalid arguments
 516  * \retval #VSM_ERROR_NO_OBJECT      Target zone is not running state
 517  * \retval #VSM_ERROR_GENERIC        IPC failed or waitpid error
 518  */
 519 API int vsm_attach_zone_wait(vsm_context_h ctx, const char * zone_name, vsm_attach_command_s * command, vsm_attach_options_s * opt);
 520
 521 /**
 522  * @brief Get name string of zone.
 523  * \par Description:
 524  * Get name string of zone.
 525  * \param[in] zone vsm zone handle
 526  * \return a pointer of zone name string on sucess or NULL on fail.
 527  * \retval name string value of zone.
 528  * \retval NULL vsm_zone_h is invalid.
 529  * \warning Do not modify or free returned pointer memroy.
 530  *          This memory will be cleanup by vsm_cleanup context()
 531 */
 532 API const char * vsm_get_zone_name(vsm_zone_h zone);
 533
 534 /**
 535  * @brief Get zone root ablsolute path on host side.
 536  * \par Description:
 537  * Get rootpath string of zone.
 538  * \param[in] zone vsm zone handle
 539  * \return a pointer of zone rootpath string on sucess or NULL on fail.
 540  * \retval rootpath string value of zone.
 541  * \retval NULL vsm_zone_h is invalid.
 542  * \warning Do not modify or free returned memroy.
 543  *          This memory will be cleanup by vsm_cleanup context()
 544 */
 545 API const char * vsm_get_zone_rootpath(vsm_zone_h zone);
 546
 547 /**
 548  * @brief Get type of running zone.
 549  * \par Description:
 550  * Get type string of zone. This value is defined in template file when using vsm_create_zone()
 551  * \param[in] zone vsm zone handle
 552  * \return a pointer of zone path string on sucess or NULL on fail.
 553  * \retval rootpath string value of zone.
 554  * \retval NULL vsm_zone_h is invalid.
 555  * \see vsm_create_zone()
 556  * \warning Do not modify or free returned memroy.
 557  *          This memory will be cleanup by vsm_cleanup context()
 558 */
 559 API const char * vsm_get_zone_type(vsm_zone_h zone);
 560
 561 /**
 562  * @brief Check zone handle, a host or a normal zone by zone handle.
 563  * \param[in] zone vsm zone handle
 564  * \return positive integer on host case, or 0 on normal zone.
 565  * \retval positive target zone is host zone.
 566  * \retval NULL     target zone is NOT host.
 567 */
 568 API int vsm_is_host_zone(vsm_zone_h zone);
 569
 570 /**
 571  * @brief get zone state.
 572  * \par Description:
 573  * Get zone state value by zone handle.
 574  * \param[in] zone vsm zone handle
 575  * \return vsm_zone_state_t value, or negative value.
 576  * \retval state vsm_zone_state_t value of zone
 577  * \retval #VSM_ERROR_INVALID vsm_zone_h is invalid
 578 */
 579
 580 API vsm_zone_state_t vsm_get_zone_state(vsm_zone_h zone);
 581
 582 /**
 583  * @brief get zone id by handle.
 584  * \par Description:
 585  * Get zone id value by zone handle.
 586  * \param[in] zone vsm zone handle
 587  * \return interger id value of zone or negative error.
 588  * \retval id nonnegative interger value.
 589  * \retval #VSM_ERROR_INVALID vsm_zone_h is invalid
 590  * \remarks id '0' is reserved for host.
 591 */
 592 API int vsm_get_zone_id(vsm_zone_h zone);
 593
 594
 595 /**
 596  * @brief Set userdata pointer value in vsm_zone_h.
 597  * \par Description:
 598  * Get zone id value by zone handle.
 599  * \param[in] zone vsm zone handle
 600  * \return On success 0, or negative error.
 601  * \retval #VSM_ERROR_NONE     Successful.
 602  * \retval #VSM_ERROR_INVALID  vsm_zone_h is invalid
 603  * \warning This userdata have to be free before vsm_cleanup_context() or VSM_ZONE_STATE_STOPPED callback handler
 604 */
 605 API int vsm_set_userdata(vsm_zone_h zone, void * userdata);
 606
 607 /**
 608  * @brief Set userdata pointer value in vsm_zone_h.
 609  * \par Description:
 610  * Get zone id value by zone handle.
 611  * \param[in] zone vsm zone handle
 612  * \return On success pointer of userdata, or NULL pointer
 613  * \retval userdata pointer of userdata.
 614  * \retval NULL invalid vsm_zone_h.
 615  * \remark initial value is pointer of self vsm_zone_h
 616 */
 617 API void * vsm_get_userdata(vsm_zone_h zone);
 618
 619 /**
 620  * @brief join current process into zone.
 621  * \par Synopsys:
 622  * Change self peer credential to target zone
 623  * \param[in] zone vsm_zone_h
 624  * \return before vsm_zone on success, or NULL on error.
 625  * \retval vsm_zone_h before zone handle, If caller process running in host, then host handle returned.
 626  * \retval NULL       invalid zone handle.
 627  * \pre parameter vsm zone must be lookup by vsm lookup APIs
 628  * \post  After finish target zone procedure, must join again before zone by same API.
 629  * \warning This function is not thread-safe. \n
 630  *   All requests of threads in same process are considered target zone request to other host processes.
 631  */
 632 API vsm_zone_h vsm_join_zone(vsm_zone_h zone);
 633
 634 /**
 635  * @brief get canonical file path based on current zone.
 636  * \par Description:
 637  *    get canonical file path based on current zone.
 638  * \param[in] input_path requested zone path
 639  * \param[out] output_path string pointer for canonicalized output path
 640  * \return int positive string length of output_path, or negative error code on error.
 641  * \retval #VSM_ERROR_INVALID Invalid arguments.
 642  * \retval #VSM_ERROR_GENERIC gethostname() is failed.
 643  * \post Out buffer(*output_path) have to be freed by caller after use.
 644  * \remarks This API can call inside zone without vsm_context_h
 645  *   It means this API can call library side for apps.
 646  */
 647 API int vsm_canonicalize_path(const char *input_path, char **output_path);
 648
 649 /**
 650  * @brief Check current environment, a host or virtualized zone.
 651  * \par Description:
 652  *    Check current caller process environment.
 653  * \return positive integer on running in zone, or 0 on running in host.
 654  * \retval NULL     Current process running in host.
 655  * \remarks This API can call inside zone without vsm_context_h
 656  *   It means this API can call library side for apps.
 657  */
 658 API int vsm_is_virtualized(void);
 659
 660 /**
 661  * @brief Check equivalence between caller and target pid.
 662  * \par Description:
 663  *    Check API caller process and target pid running in same zone.
 664  * \retval NULL       target process is running in another zone.
 665  * \retval 1        target process is running in same zone.
 666  * \retval -1       failed to check target process.
 667  * \remarks This API can check real zone of target pid.
 668             Real zone is not changed by even join API.
 669  */
 670 API int vsm_is_equivalent_zone(vsm_context_h ctx, pid_t pid);
 671
 672 /**
 673  * @brief Translate zone pid to host pid.
 674  * \par Description:
 675  *    This API would translate zone namespace pid to host namespace pid.
 676  * \param[in] zone  the zone of target process
 677  * \param[in] pid   target process id of zone namespace
 678  * \return positive pid or negative error code.
 679  * \retval pid                       translated host pid of zone process.
 680  * \retval #VSM_ERROR_NO_OBJECT      No such process in a target zone.
 681  * \retval #VSM_ERROR_NOT_PERMITTED  Permission denied to get target pid info.
 682  * \retval #VSM_ERROR_NOT_SUPPORTED  Kernel config is not enabled about pid namespace.
 683  * \retval #VSM_ERROR_INVALID        Arguments is invalid.
 684  * \retval #VSM_ERROR_IO             Failed to get process info.
 685  * \retval #VSM_ERROR_GENERIC        Failed to matching zone pid to host pid.
 686  */
 687 API int vsm_get_host_pid(vsm_zone_h zone, pid_t pid);
 688
 689
 690 /// @}
 691
 692 /**
 693  * @addtogroup NETWORK Vasum Network
 694  * @{
 695 */
 696
 697 /**
 698  * @brief Types of virtual network interfaces
 699  */
 700 typedef enum {
 701         VSM_NETDEV_VETH, /**< Virtual Ethernet(veth), this type device will be attached to host-side network bridge */
 702         VSM_NETDEV_PHYS, /**< Physical device */
 703         VSM_NETDEV_MACVLAN /**< Mac VLAN, this type isn't implemented yet */
 704 } vsm_netdev_type_t;
 705
 706 typedef enum {
 707         VSM_NETDEV_ADDR_IPV4, /**< IPV4 Address family */
 708         VSM_NETDEV_ADDR_IPV6 /**< IPV6 Address family */
 709 } vsm_netdev_addr_t;
 710
 711 /**
 712  * @brief Network device information
 713  */
 714 typedef struct vsm_netdev *vsm_netdev_h;
 715
 716 /**
 717  * @brief Definition for zone network devince iteration callback function.
 718  */
 719 typedef void (*vsm_zone_netdev_iter)(struct vsm_netdev *, void *user_data);
 720
 721 /**
 722  * @brief Create a new network device and assisgn it to zone
 723  * \par Description:
 724  * This function creates net netdev instance and assign it to the given zone.
 725  * \param[in] zone Zone
 726  * \param[in] type Type of network device to be create
 727  * \param[in] target
 728  * - If type is veth, this will be bridge name to attach.
 729  * - If type is phys, this will be ignored.
 730  * \param[in] netdev Name of network device to be create
 731  * \return Network devce on success, or NULL on error.
 732  * \retval vsm_netdev_h New net device handle
 733  * \retval NULL         Failed to create netdev
 734  * \see vsm_create_netdev()
 735  * \par Known Issues:
 736  *  Macvlan is not implemented yet.
 737  */
 738 API vsm_netdev_h vsm_create_netdev(vsm_zone_h zone, vsm_netdev_type_t type, const char *target, const char *netdev);
 739
 740 /**
 741  * @brief Removes a network device from zone
 742  * \par Description:
 743  * This function remove the given netdev instance from the zone control context.
 744  * \param[in] netdev network device to be removed
 745  * \return 0 on success, or negative integer error code on error.
 746  * \retval #VSM_ERROR_NONE           Successful
 747  * \retval #VSM_ERROR_INVALID        Invalid arguments
 748  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 749  * \see vsm_destroy_netdev()
 750  */
 751 API int vsm_destroy_netdev(vsm_netdev_h netdev);
 752
 753 /**
 754  * @brief Iterates network devices found in the zone vsm context and executes callback() on each interface.
 755  * \par Description:
 756  * vsm_destroy_netdev() scans all network interfaces which are registered in the vsm context, and calls callback() on each entry.
 757  * \param[in] zone Zone
 758  * \param[in] callback Function to be executed in iteration, which can be NULL
 759  * \param[in] user_data Parameter to be delivered to callback function
 760  * \return 0 on success, or negative integer error code on error.
 761  * \retval #VSM_ERROR_NONE           Successful
 762  * \retval #VSM_ERROR_INVALID        Invalid arguments
 763  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 764  * \see vsm_create_netdev(), vsm_destroy_netdev()
 765  */
 766 API int vsm_iterate_netdev(vsm_zone_h zone, vsm_zone_netdev_iter callback, void *user_data);
 767
 768 /**
 769  * @brief Find a network device corresponding to the name
 770  * \par Description:
 771  * The function vsm_lookup_netdev_by_name() looks for a network interface.
 772  * \param[in] name Network device name to search
 773  * \return Network device on success, or NULL on error.
 774  * \retval vsm_netdev_h Target net device handle
 775  * \retval NULL         Failed to lookup netdev
 776  */
 777
 778 API vsm_netdev_h vsm_lookup_netdev_by_name(vsm_zone_h zone, const char *name);
 779
 780 /**
 781  * @brief Turn up a network device in the zone
 782  * \par Description:
 783  * This function turns up the given netdev instance in the zone.
 784  * \param[in] netdev network device to be removed
 785  * \return 0 on success, or negative integer error code on error.
 786  * \retval #VSM_ERROR_NONE           Successful
 787  * \retval #VSM_ERROR_INVALID        Invalid arguments
 788  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 789  * \see vsm_down_netdev()
 790  */
 791 API int vsm_up_netdev(vsm_netdev_h netdev);
 792
 793 /**
 794  * @brief Turn down a network device in the zone
 795  * \par Description:
 796  * This function turns down the given netdev instance in the zone.
 797  * \param[in] netdev network device to be removed
 798  * \return 0 on success, or negative integer error code on error.
 799  * \retval #VSM_ERROR_NONE           Successful
 800  * \retval #VSM_ERROR_INVALID        Invalid arguments
 801  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 802  * \see vsm_down_netdev()
 803  */
 804 API int vsm_down_netdev(vsm_netdev_h netdev);
 805
 806 /**
 807  * @brief Get ip address from a network device
 808  * \par Description:
 809  * The function vsm_get_ip_addr_netdev() get ip address from a network interface
 810  * \param[in] netdev Network device to get address
 811  * \param[in] addr_family Address family
 812  * \param[out] addr Buffer to get address from a network device
 813  * \param[out] size Size of buffer
 814  * \return 0 on success, or negative integer error code on error.
 815  * \retval #VSM_ERROR_NONE           Successful
 816  * \retval #VSM_ERROR_INVALID        Invalid arguments
 817  * \retval #VSM_ERROR_OVERFLOW       Parameter overflow
 818  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 819  * \see vsm_set_ip_addr_netdev()
 820  */
 821 API int vsm_get_ip_addr_netdev(vsm_netdev_h netdev, vsm_netdev_addr_t addr_family, char *addr, int size);
 822
 823 /**
 824  * @brief Set ip address to a network device
 825  * \par Description:
 826  * The function vsm_set_ip_addr_netdev() set ipv4 address to a network interface
 827  * \param[in] netdev Network device to set address
 828  * \param[in] addr_family Address family
 829  * \param[in] addr IP address string to be set
 830  * \param[in] prefix prefix ( ex> 192.168.122.1/24, 24 is prefix )
 831  * \return 0 on success, or negative integer error code on error.
 832  * \retval #VSM_ERROR_NONE           Successful
 833  * \retval #VSM_ERROR_INVALID        Invalid arguments
 834  * \retval #VSM_ERROR_OVERFLOW       Parameter overflow
 835  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 836  * \see vsm_get_ip_addr_netdev()
 837  */
 838 API int vsm_set_ip_addr_netdev(vsm_netdev_h netdev, vsm_netdev_addr_t addr_family, const char *addr, int prefix);
 839
 840
 841
 842 /// @}
 843
 844 /**
 845  * @addtogroup DEVICE Vasum Device
 846  * @{
 847 */
 848
 849 /**
 850  * @brief Grant device to zone
 851  * \par Description:
 852  * Request permission device file node to target zone.
 853  * \param[in] zone vsm_zone_h
 854  * \param[in] path device node path
 855  * \param[in] flags requested permission O_RDWR, O_WRONLY, O_RDONLY
 856  * \return 0 on success, or negative integer error code on error.
 857  * \retval #VSM_ERROR_NONE           Successful
 858  * \retval #VSM_ERROR_INVALID        Invalid arguments
 859  * \retval #VSM_ERROR_NOT_PERMITTED  Change cgroup is not permitted
 860  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 861  * \see vsm_revoke_device()
 862  */
 863 API int vsm_grant_device(vsm_zone_h zone, const char *path, uint32_t flags);
 864
 865 /**
 866  * @brief Revoke device from the zone
 867  * \par Description:
 868  * Revoke device node permissions from target zone.
 869  * \param[in] zone vsm_zone_h
 870  * \param[in] path device node path
 871  * \return 0 on success, or negative integer error code on error.
 872  * \retval #VSM_ERROR_NONE           Successful
 873  * \retval #VSM_ERROR_INVALID        Invalid arguments
 874  * \retval #VSM_ERROR_NOT_PERMITTED  Change cgroup is not permitted
 875  * \retval #VSM_ERROR_GENERIC        Failed to interact with vasum server
 876  * \see vsm_grant_device()
 877  */
 878 API int vsm_revoke_device(vsm_zone_h zone, const char *path);
 879 /// @}
 880
 881
 882 /**
 883  * @addtogroup RESOURCE Vasum Resource
 884  * @{
 885  */
 886
 887 /**
 888  * @brief Definition for declare file type.
 889 */
 890 typedef enum {
 891         VSM_FSO_TYPE_DIR,  /**< Directoy type */
 892         VSM_FSO_TYPE_REG,  /**< Regular file type */
 893         VSM_FSO_TYPE_FIFO, /**< Fifo file type */
 894         VSM_FSO_TYPE_SOCK, /**< Socket file type */
 895         VSM_FSO_TYPE_DEV,  /**< Device node type */
 896         VSM_FSO_MAX_TYPE = VSM_FSO_TYPE_DEV
 897 } vsm_fso_type_t;
 898
 899 /**
 900  * @brief Declare file mode.
 901 */
 902
 903 typedef mode_t vsm_mode_t;
 904
 905 /**
 906  * @brief Declare specific file object to every zone.
 907  * \par Description:
 908  * Declare host file system to every running zone.
 909  * In case of host target file exist, create new file in running zone. or create a new file in running zone.
 910  * And add hook info in vsm-resource-provier for automatically link host target file to starting zone.
 911  * Smack labels are also copied as same as host labels.
 912  * \param[in] ctx vsm context
 913  * \param[in] ftype Type of file system object
 914  * \param[in] path Path for the file system object
 915  * \param[in] flags Flasg
 916  * \param[in] mode mode
 917  * \return zero on success, or negative value on error.
 918  * \retval #VSM_ERROR_NONE      successful.
 919  * \retval #VSM_ERROR_INVALID   Invalid file type or path.
 920  * \retval #VSM_ERROR_GENERIC   Error in vasum server side.
 921  * \retval #VSM_ERROR_NO_OBJECT Source file is not exist in host filesystem
 922 */
 923 API int vsm_declare_file(vsm_context_h ctx, vsm_fso_type_t ftype, const char *path, int flags, vsm_mode_t mode);
 924
 925 /**
 926  * @brief Declare hardlink to every zone.
 927  * \par Description:
 928  * Declare hardlink to host file to every running zone.
 929  * And add hook info in vsm-resource-provier for automatically link host target file to starting zone.
 930  * In general, this function is used to share file host and all running zones.
 931  * Smack labels are also copied as same as host labels.
 932  * \param[in] ctx vsm context
 933  * \param[in] source source
 934  * \param[in] target target
 935  * \return zero on success, or negative value on error.
 936  * \retval #VSM_ERROR_NONE      successful
 937  * \retval #VSM_ERROR_INVALID   Invalid provision type to db.
 938  * \retval #VSM_ERROR_GENERIC   Error in vasum server side.
 939  * \retval #VSM_ERROR_NO_OBJECT Source file is not exist in host filesystem
 940 */
 941 API int vsm_declare_link(vsm_context_h ctx , const char *source, const char *target);
 942
 943 /// @}
 944
 945
 946 #ifdef __cplusplus
 947 }
 948 #endif
 949
 950 #endif /*! __VASUM_H__ */