Libdladm APIs for managing link and secure properties ------------------------------------------------------ 1. Link property APIs --------------------- 1.1. dladm_set_prop() -------------------- dladm_status_t dladm_set_prop(const char *link, const char *prop_name, char **prop_val, uint_t val_cnt, uint_t flags); Description: dladm_set_prop() assigns the value(s) specified in the array prop_val (of size val_cnt) to the property prop_name on the specified link. If prop_val is NULL, the property prop_name will be set to its default value(s). If prop_name is NULL, all properties on the specified link will be set to their default value(s). Supported flags include: DLADM_OPT_TEMP: If this flag is set, changes will be made to the current configuration. DLADM_OPT_PERSIST: If this flag is set, changes will be made to the persistent configuration. If both flags are set, changes will be made to both the current and persistent configurations. Not setting either of the flags will result in an error. Implementation Notes: dladm_set_prop() is meant to be a wrapper for media-specific set_prop() interfaces. Its internal structure is similar to: dladm_set_prop(...) { ... if (wladm_is_valid(link)) { s = wladm_set_prop(link, ...); .... goto save; } if (ether_is_valid(link)) { s = ether_set_prop(link, ...); .... goto save; } ... save: if ((flags & DLADM_OPT_TEMP) == 0) save_config(link, ...); ... } Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. DLADM_STATUS_FAILED is returned if the specified property cannot be set to the desired value. 1.2. dladm_walk_prop() ---------------------- dladm_status_t dladm_walk_prop(const char *link, void *arg, boolean_t (*func)(void *, const char *)); Description: For each property belonging to the specified link, dladm_walk_prop() will call func() with arguments arg and the property's name. If func() returns B_FALSE, dladm_walk_prop() will terminate; otherwise, it will continue until all properties are encountered. Implementation Notes: dladm_walk_prop() is meant to be a wrapper for media-specific walk_prop() interfaces. Its internal structure is similar to: dladm_walk_prop(...) { ... if (wladm_is_valid(link)) { wladm_walk_prop(link, ...); return; } if (ether_is_valid(link)) { ether_walk_prop(link, ...); return; } ... } Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_FAILED is returned if a fatal error occurs while walking link properties. 1.3. dladm_get_prop() --------------------- dladm_status_t dladm_get_prop(const char *link, dladm_prop_type_t type, const char *prop_name, char **prop_val, uint_t *val_cntp); Description: dladm_get_prop() obtains the specified property value(s) from the specified link. type can be one of DLADM_PROP_VAL_CURRENT, DLADM_PROP_VAL_PERSISTENT, DLADM_PROP_VAL_DEFAULT, or DLADM_PROP_VAL_MODIFIABLE. prop_name specifies the name of the property whose value(s) is/are to be retrieved. prop_val is a string array of size *val_cntp used for storing the retrieved property value(s). If no error occurs, dladm_get_prop() will set *val_cntp to the actual number of values retrieved upon return; otherwise, *val_cntp will be left unmodified. Implementation Notes: dladm_get_prop() is meant to be a wrapper for media-specific get_prop() interfaces. Its internal structure is similar to: dladm_get_prop(...) { ... if (type == DLADM_PROP_VAL_PERSISTENT) { ... return (DLADM_STATUS_OK); } if (wladm_is_valid(link)) { s = wladm_get_prop(link, ...); ... } if (ether_is_valid(link)) { s = ether_get_prop(link, ...); ... } ... } Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. DLADM_STATUS_TOOSMALL is returned if the array prop_val is not large enough to hold the retrieved values. DLADM_STATUS_NOMEM is returned if a memory allocation failure has occurred. DLADM_STATUS_FAILED is returned if the specified property value(s) cannot be retrieved. 1.4. dladm_init_linkprop() -------------------------- dladm_status_t dladm_init_linkprop(void); Description: dladm_init_linkprop() will reinitialize link(s) with the properties saved in persistent storage. This function is meant to be called at boot time. Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_FAILED is returned if properties cannot be retrieved from persistent storage. 2. Secure Property APIs ----------------------- 2.1. dladm_set_secobj() ------------------------ dladm_status_t dladm_set_secobj(const char *obj_name, dladm_secobj_class_t class, uint8_t *obj_val, uint_t obj_len, uint_t flags); Description: dladm_set_secobj() sets the value of secure object obj_name to the value obj_val (byte array of size obj_len). Currently, DLADM_SECOBJ_CLASS_WEP is the only supported class. The following flags are supported: DLADM_OPT_CREATE: If this flag is set and the specified secure object does not already exist, the secure object will be created. DLADM_OPT_TEMP: If this flag is set, changes will be made to the current configuration. DLADM_OPT_PERSIST: If this flag is set, changes will be made to the persistent configuration. If both flags are set, changes will be made to both the current and persistent configurations. Not setting either of the flags will result in an error. Implementation Notes: dladm_set_secobj() uses the ioctl DLDIOCSECOBJSET (see 2.5.1). Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. DLADM_STATUS_FAILED is returned if the specified secure object cannot be set. 2.2. dladm_get_secobj() ------------------------ dladm_status_t dladm_get_secobj(const char *obj_name, dladm_secobj_class_t *classp, uint8_t *obj_val, uint_t *obj_lenp, uint_t flags); Description: dladm_get_secobj() obtains the secure object obj_name's value and assigns it to obj_val (a byte array of size *obj_lenp). *obj_lenp's length will be set to the actual number of bytes in obj_val. *classp will be set to the object's class. Currently, DLADM_SECOBJ_CLASS_WEP is the only supported class. The following flags are supported: DLADM_OPT_PERSIST: If this flag is set, dladm_get_secobj() will obtain the secure object's value from the persistent configuration instead of the current configuration. Implementation Notes: dladm_get_secobj() uses the ioctl DLDIOCSECOBJGET (see 2.5.2). Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. DLADM_STATUS_TOOSMALL is returned if the array obj_val is not large enough to hold the retrieved value. DLADM_STATUS_FAILED is returned if the specified secure object cannot be retrieved. 2.3. dladm_unset_secobj() ------------------------- dladm_status_t dladm_unset_secobj(const char *obj_name, uint_t flags); Description: dladm_unset_secobj() removes the secure object obj_name. The following flags are supported: DLADM_OPT_TEMP: If this flag is set, changes will be made to the current configuration. DLADM_OPT_PERSIST: If this flag is set, changes will be made to the persistent configuration. If both flags are set, changes will be made to both the current and persistent configurations. Not setting either of the flags will result in an error. Implementation Notes: dladm_unset_secobj() uses the ioctl DLDIOCSECOBJUNSET (see 2.5.3). Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_BADARG is returned if any of the specified arguments are invalid. DLADM_STATUS_FAILED is returned if the specified secure object cannot be unset. 2.4. dladm_walk_secobj() ------------------------- dladm_status_t dladm_walk_secobj(void *arg, boolean_t (*func)(void *, const char *), uint_t flags); Description: For each secure object in the system, dladm_walk_secobj() will call func() with arguments arg and the object's name. If func() returns B_FALSE, dladm_walk_secobj() will terminate; otherwise, it will continue until all secure objects are encountered. The following flags are supported: DLADM_OPT_PERSIST: If this flag is set, dladm_walk_secobj() will only walk objects in the persistent configuration. Implementation Notes: dladm_walk_secobj() uses the ioctl DLDIOCSECOBJGET (see 2.5.2). Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_FAILED is returned if a fatal error occurs while walking secure objects. 2.5. Supporting ioctls ----------------------- 2.5.1. DLDIOCSECOBJSET ----------------------- This command takes the argument: typedef struct dld_ioc_secobj_set { dld_secobj_t ss_obj; uint_t ss_flags; } dld_ioc_secobj_set_t; where ss_obj is of type: typedef struct dld_secobj { char so_name[DLD_SECOBJ_NAME_MAX]; dld_secobj_class_t so_class; uint8_t so_val[DLD_SECOBJ_VAL_MAX]; uint_t so_len; } dld_secobj_t; and so_class is of type: typedef enum { DLD_SECOBJ_CLASS_WEP = 1 } dld_secobj_class_t; Description: DLDIOCSECOBJPSET first checks if an object with name ss_obj.so_name already exists. If so, the existing entry is replaced with the contents of ss_obj; If ss_obj.so_name does not exist, a new dld_secobj_t is created only if the flag DLD_SECOBJ_OPT_CREATE is set; an error would be returned if this flag is not set. Return Values: 0 is returned if the command is successful. on error, -1 is returned and errno is set to one of the following: EINVAL: if any of the input arguments are invalid. (i.e. ss_obj.so_class is of unknown type. ss_obj.so_name is not nul-terminated.) 2.5.2. DLDIOCSECOBJGET ----------------------- This command takes the argument: typedef struct dld_ioc_secobj_get { dld_secobj_t sg_obj; uint_t sg_count; } dld_ioc_secobj_get_t; Description: DLDIOCSECOBJGET operates in one of two ways. If sg_obj.so_name is a non-empty string, DLDIOCSECOBJGET will use this string to lookup the corresponding object and the object will be placed in sg_obj. sg_count will be set to 1. If sg_obj.so_name is an empty string (i.e. begins with NUL), DLDIOCSECOBJGET will append all objects immediately after the dld_ioc_secobj_get_t structure within the input buffer. sg_count will be set to the number of objects appended. Return Values: 0 is returned if the command is successful. on error, -1 is returned and errno is set to one of the following: EINVAL: if any of the input arguments are invalid. (i.e. sg_obj.so_name is not empty and not nul-terminated.) ENOENT: if the specified object cannot be found. ENOSPC: if the input buffer is not large enough to hold all objects. 2.5.3. DLDIOCSECOBJUNSET ------------------------- This command takes the argument: typedef struct dld_ioc_secobj_unset { char su_name[DLD_SECOBJ_SIZE_MAX]; } dld_ioc_secobj_unset_t; Description: DLDIOCSECOBJUNSET will remove the object with name su_name from the kernel. Return Values: 0 is returned if the command is successful. on error, -1 is returned and errno is set to one of the following: EINVAL: if any of the input arguments are invalid. (i.e. su_name is not nul-terminated.) ENOENT: if the specified object cannot be found. 2.6. dladm_init_secobj() -------------------------- dladm_status_t dladm_init_secobj(void); Description: dladm_init_secobj() will reinitialize system with secure objects saved in persistent storage. This function is meant to be called at boot time. Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_FAILED is returned if properties cannot be retrieved from persistent storage. 3. String Conversion APIs ------------------------- 3.1. Datatype to string ----------------------- The following routines convert dladm datatypes to strings. The 2nd argument is the buffer to which the converted string will be written. This buffer will be returned to the caller. Its size must be at least DLADM_STRSIZE bytes. const char *dladm_status2str(dladm_status_t, char *); const char *dladm_secobjclass2str(dladm_secobj_class_t, char *); 3.2. String to datatype ----------------------- The following routines convert strings to dladm datatypes. DLADM_STATUS_OK is returned if conversion is successful. DLADM_STATUS_BADARG is returned if conversion is unsuccessful. dladm_status_t dladm_str2secobjclass(const char *, dladm_secobj_class_t *); 4. Misc APIs ------------ 4.1. dladm_set_rootdir() ------------------------ dladm_status_t dladm_set_rootdir(const char *rootdir); Upon success, subsequent libdladm operations operate as if rootdir represented the root of the filesystem. The value provided by rootdir must be non-NULL and must refer to an accessible directory. Return Values: DLADM_STATUS_OK is returned if the operation is successful. DLADM_STATUS_FAILED is returned if rootdir does not refer to a directory.