instzones_lib.h revision 10455:2cbe19c439c1
1/* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21/* 22 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 23 * Use is subject to license terms. 24 */ 25 26 27 28#ifndef _INSTZONES_LIB_H 29#define _INSTZONES_LIB_H 30 31 32/* 33 * Module: instzones_lib.h 34 * Group: libinstzones 35 * Description: This module contains the libinstzones internal data structures, 36 * constants, and function prototypes. This include should not be 37 * needed by any external code (consumers of this library). 38 */ 39 40/* 41 * required includes 42 */ 43 44/* System includes */ 45 46#include <zone.h> 47#include <libzonecfg.h> 48#include <libcontract.h> 49#include <instzones_api.h> 50 51 52 53/* 54 * C++ prefix 55 */ 56 57#ifdef __cplusplus 58extern "C" { 59#endif 60 61/* constants */ 62 63 64/* macros */ 65 66/* 67 * argument array processing type 68 */ 69 70/* 71 * This is the "argument array" definition that is returned by _z_new_args 72 * and is used by _z_add_args, _z_free_args, etc. 73 */ 74 75struct _argArray_t { 76 long _aaNumArgs; /* number of arguments set */ 77 long _aaMaxArgs; /* number of arguments allocated */ 78 char **_aaArgs; /* actual arguments */ 79}; 80 81typedef struct _argArray_t argArray_t; 82 83/* 84 * lock objects 85 */ 86 87/* 88 * this allows a root path to be prepended to a lock object; e.g. 89 * rootpath.%s/zone.%s/... 90 */ 91#define LOBJ_ROOTPATH "rootpath.%s" 92 93/* this locks a single zone (zone.name) */ 94#define LOBJ_ONE_ZONE "zone.%s" 95 96/* this locks all zones */ 97#define LOBJ_ZONEADMIN "zone.*" 98 99/* this locks all packages, in all zones */ 100#define LOBJ_PKGADMIN "zone.*/package.*" 101 102/* this locks all patches, in all zones */ 103#define LOBJ_PATCHADMIN "zone.*/patch.*" 104 105#define LOCK_OBJECT_MAXLEN 512 106#define LOCK_KEY_MAXLEN 37 107 108/* paths to commands executed by this module */ 109 110#define PKGADM_CMD "/usr/bin/pkgadm" 111#define ZONEADM_CMD "/usr/sbin/zoneadm" 112 113/* max message size for program output functions (echo, echo debug, progerr) */ 114 115#define MAX_MESSAGE_SIZE 4096 116 117/* maximum number of retries when waiting for lock */ 118 119#define MAX_RETRIES 300 120 121/* delay (in seconds) between retries when waiting for lock */ 122 123#define RETRY_DELAY_SECS 1 124 125/* Size of buffer increments when reading from pipe */ 126 127#define PIPE_BUFFER_INCREMENT 256 128 129/* Maximum number of arguments to pkg_ExecCmdList */ 130 131#define MAX_EXEC_CMD_ARGS 100 132 133/* 134 * These dynamic libraries are required in order to use the zones 135 * functionality - if these libraries are not available at runtime, 136 * then zones are assumed to NOT be available, and it is assumed that 137 * the program is running in the global zone with no non-global zones. 138 */ 139 140#if defined(LIBZONECFG_PATH) 141#define ZONECFG1_LIBRARY LIBZONECFG_PATH 142#else /* defined(LIBZONECFG_PATH) */ 143#define ZONECFG1_LIBRARY "libzonecfg.so.1" 144#endif /* defined(LIBZONECFG_PATH) */ 145 146#define ZONECFG_LIBRARY "libzonecfg.so" 147 148#define CONTRACT1_LIBRARY "libcontract.so.1" 149#define CONTRACT_LIBRARY "libcontract.so" 150 151/* 152 * Environment values used when running commands within a non-global zone 153 */ 154 155/* SHELL= */ 156 157#define ZONE_FAILSAFESHELL "/sbin/sh" 158 159/* PATH= */ 160 161#define ZONE_DEF_PATH "/usr/sbin:/usr/bin" 162 163/* error codes */ 164#define ERR_MALLOC_FAIL -50 165 166/* 167 * zone brand list structure 168 */ 169 170struct _zoneBrandList { 171 char *string_ptr; 172 struct _zoneBrandList *next; 173}; 174 175/* 176 * zone status structure - used to retrieve and hold status of zones 177 */ 178 179typedef unsigned long _zone_status_t; 180 181struct _zoneListElement_t { 182 char **_zlInheritedDirs; 183 char *_zlName; 184 char *_zlPath; 185 char *_zlScratchName; 186 char *_zlLockObjects; 187 /* 188 * the install "state" refers to the zone states listed in 189 * /usr/include/libzonecfg.h that is stored in the zone_state_t 190 * structure and returned from getzoneent_private() - such as: 191 * ZONE_STATE_CONFIGURED, ZONE_STATE_INCOMPLETE, 192 * ZONE_STATE_INSTALLED, ZONE_STATE_READY, ZONE_STATE_MOUNTED, 193 * ZONE_STATE_SHUTTING_DOWN, ZONE_STATE_DOWN. 194 */ 195 zone_state_t _zlOrigInstallState; 196 zone_state_t _zlCurrInstallState; 197 /* 198 * the kernel "status" refers to the zone status listed in 199 * /usr/include/sys/zone.h, returned by zone_get_state(), 200 * and defined in the zone_status_t enum - such as: 201 * ZONE_IS_UNINITIALIZED, ZONE_IS_READY, ZONE_IS_BOOTING, 202 * ZONE_IS_RUNNING, ZONE_IS_SHUTTING_DOWN, ZONE_IS_EMPTY, 203 * ZONE_IS_DOWN, ZONE_IS_DYING, ZONE_IS_DEAD. 204 */ 205 zone_status_t _zlOrigKernelStatus; 206 zone_status_t _zlCurrKernelStatus; 207 /* 208 * this is an internal state recorded about the zone (ZSF_xxx). 209 */ 210 _zone_status_t _zlStatus; 211}; 212 213typedef struct _zoneListElement_t zoneListElement_t; 214 215/* bits used in the _zoneListElement _zlStatus variable */ 216 217#define ZST_NOT_BOOTABLE ((_zone_status_t)0x00000001) 218#define ZST_LOCKED ((_zone_status_t)0x00000002) 219 220/* 221 * User-specified list of zones. 222 */ 223 224typedef struct zone_spec_s { 225 struct zone_spec_s *zl_next; 226 boolean_t zl_used; 227 char zl_name[ZONENAME_MAX]; 228} zone_spec_t; 229 230/* 231 * The global data structure used to hold all of the global (extern) data 232 * used by this library. 233 * 234 * --> THESE DEFINITIONS ARE ORDER DEPENDENT BASED <-- 235 * --> ON THE ORDER OF THE STRUCTURE INITIALIZERS! <-- 236 */ 237 238struct _z_global_data_t { 239 char *_z_ObjectLocks; /* object locks held */ 240 char *_z_root_dir; /* root for zone lib fctns */ 241 int _z_SigReceived; /* received signal count */ 242 pid_t _z_ChildProcessId; /* child to propagate sigs to */ 243 zone_spec_t *_zone_spec; /* zones to operate on */ 244 _z_printf_fcn_t _z_echo; /* operational message fcn */ 245 _z_printf_fcn_t _z_echo_debug; /* debug message fcn */ 246 _z_printf_fcn_t _z_progerr; /* program error fcn */ 247}; 248 249typedef struct _z_global_data_t z_global_data_t; 250 251/* 252 * When _INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA is defined, 253 * instzones_lib.h will define the z_global_data structure. 254 * Otherwise an extern to the structure is inserted. 255 * 256 * --> THESE DEFINITIONS ARE ORDER DEPENDENT BASED ON <-- 257 * --> THE ORDER OF THE _z_global_data_t STRUCTURE!!! <-- 258 */ 259 260#if defined(_INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA) 261 262/* define and initialize structure */ 263 264z_global_data_t _z_global_data = { 265 NULL, /* *_z_ObjectLocks */ 266 "", /* *_z_root_dir */ 267 0, /* _z_SigReceived */ 268 -1, /* _z_ChildProcessId */ 269 NULL, /* *_zone_spec */ 270 NULL, /* _z_echo */ 271 NULL, /* _z_echo_debug */ 272 NULL /* _z_progerr */ 273}; 274 275#else /* !defined(_INSTZONES_LIB__Z_DEFINE_GLOBAL_DATA) */ 276 277/* define structure extern */ 278 279extern z_global_data_t _z_global_data; 280 281#endif /* defined(_INSTZONES_LIB_Z_DEFINE_GLOBAL_DATA) */ 282 283/* function prototypes */ 284 285/* 286 * The following functions can be used by other libs, but not 287 * by applications. 288 */ 289 290/* ---> zones_states.c */ 291 292boolean_t _z_make_zone_ready(zoneListElement_t *a_zlem); 293boolean_t _z_make_zone_down(zoneListElement_t *a_zlem); 294boolean_t _z_make_zone_running(zoneListElement_t *a_zlem); 295int UmountAllZones(char *mntpnt); 296void *_z_calloc(size_t size); 297void *_z_malloc(size_t size); 298void *_z_realloc(void *ptr, size_t size); 299void *_z_strdup(char *str); 300 301/* ---> zones_utils.c */ 302 303/*PRINTFLIKE1*/ 304void _z_program_error(char *fmt, ...); 305/*PRINTFLIKE1*/ 306void _z_echo(char *fmt, ...); 307/*PRINTFLIKE1*/ 308void _z_echoDebug(char *a_fmt, ...); 309int _z_is_directory(char *path); 310char **_z_get_inherited_dirs(char *a_zoneName); 311boolean_t _z_running_in_global_zone(void); 312boolean_t _z_zones_are_implemented(void); 313void _z_sig_trap(int a_signo); 314int _z_close_file_descriptors(void *a_fds, int a_fd); 315boolean_t _z_brands_are_implemented(void); 316 317 318/* ---> zones_locks.c */ 319 320boolean_t _z_adjust_lock_object_for_rootpath(char **r_result, 321 char *a_lockObject); 322boolean_t _z_acquire_lock(char **r_lockKey, char *a_zoneName, 323 char *a_lock, pid_t a_pid, boolean_t a_wait); 324boolean_t _z_lock_zone(zoneListElement_t *a_zlst, 325 ZLOCKS_T a_lflags); 326boolean_t _z_lock_zone_object(char **r_objectLocks, 327 char *a_zoneName, char *a_lockObject, 328 pid_t a_pid, char *a_waitingMsg, 329 char *a_busyMsg); 330boolean_t _z_release_lock(char *a_zoneName, char *a_lock, 331 char *a_key, boolean_t a_wait); 332boolean_t _z_unlock_zone(zoneListElement_t *a_zlst, 333 ZLOCKS_T a_lflags); 334boolean_t _z_unlock_zone_object(char **r_objectLocks, 335 char *a_zoneName, char *a_lockObject, 336 char *a_errMsg); 337 338/* ---> zones_args.c */ 339 340void _z_free_args(argArray_t *a_args); 341argArray_t *_z_new_args(int initialCount); 342/*PRINTFLIKE2*/ 343boolean_t _z_add_arg(argArray_t *a_args, char *a_format, ...); 344int _z_get_argc(argArray_t *a_args); 345char **_z_get_argv(argArray_t *a_args); 346 347/* ---> zones_str.c */ 348 349boolean_t _z_strContainsToken(char *a_string, char *a_token, 350 char *a_separators); 351char *_z_strGetToken(char *r_sep, char *a_string, 352 int a_index, char *a_separators); 353void _z_strRemoveLeadingWhitespace(char **a_str); 354void _z_strGetToken_r(char *r_sep, char *a_string, 355 int a_index, char *a_separators, char *a_buf, 356 int a_bufLen); 357void _z_strAddToken(char **a_old, char *a_new, 358 char a_separator); 359void _z_strRemoveToken(char **r_string, char *a_token, 360 char *a_separators, int a_index); 361/*PRINTFLIKE3*/ 362void _z_strPrintf_r(char *a_buf, int a_bufLen, 363 char *a_format, ...); 364/*PRINTFLIKE1*/ 365char *_z_strPrintf(char *a_format, ...); 366 367/* ---> zones_exec.c */ 368 369int _z_zone_exec(int *r_status, char **r_results, char *a_inputFile, 370 char *a_path, char *a_argv[], const char *a_zoneName, 371 int *a_fds); 372int _zexec(const char *a_zoneName, 373 const char *path, char *argv[]); 374char *_zexec_add_env(char *name, char *value); 375int _zexec_init_template(void); 376char **_zexec_prep_env(); 377 378/* 379 * C++ postfix 380 */ 381 382#ifdef __cplusplus 383} 384#endif 385 386#endif /* _INSTZONES_LIB_H */ 387