1. Overview of Solaris DHCP Data Access Architecture
2. Architecture Features for Module Writers
The API functions described in this section are used with the dhcptab container.
To list the name of the dhcptab container.
int list_dt(const char *location, char ***listppp, uint_t *count);
Produces a dynamically allocated list of dhcptab container objects (listppp) found at location and stores the number of list items in count. If no dhcptab container objects exist, then DSVC_SUCCESS is returned, listppp is set to NULL, and count is set to 0.
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NO_LOCATION.
To open a dhcptab container or create a new one.
int open_dt(void **handpp, const char *location, uint_t flags);
Opens an existing dhcptab container or creates a new container at location and initializes handp to point to the instance handle. Performs any initialization needed by the data store. When creating a new dhcptab, the caller's identity is used for owner/permissions. Valid flags include DSVC_CREATE, DSVC_READ, DSVC_WRITE, DSVC_NONBLOCK. Note that the creation of a dhcptab container as read-only (DSVC_CREATE | DSVC_READ) is invalid.
DSVC_SUCCESS, DSVC_EXISTS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.
To perform a lookup query for records in the dhcptab container.
int lookup_dt(void *handp, boolean_t partial, uint_t query, int count, const dt_rec_t *targetp, dt_rec_list_t **resultp, uint_t *records);
Searches the dhcptab container for instances that match the query described by the combination of query and targetp. If the partial argument is B_TRUE, then partial query results are acceptable to the caller. Thus, when partial is B_TRUE, any query that returns at least one matching record is considered successful. When partial is B_FALSE, the query returns DSVC_SUCCESS only if it has been applied to the entire container.
The query argument consists of 2 fields, each 16 bits long. The lower 16 bits select which fields {key, type} of targetp are to be considered in the query. The upper 16 bits identify whether a particular field value selected in the lower 16 bits must match (bit set) or not match (bit clear). Bits 2 through 15 in both 16-bit fields are currently unused, and must be set to 0. Useful macros for constructing queries can be found in Example 3-1.
The count field specifies the maximum number of matching records to return. A count value of -1 requests the return of all records that match, regardless of the number. A count value of 0 causes lookup_dt to return immediately with no data.
resultp is set to point to the returned list of records. If resultp is NULL, then the caller is simply interested in knowing how many records match the query. Note that these records are dynamically allocated, and therefore the caller is responsible for freeing them. lookup_dt() returns the number of matching records in the records argument. A records value of 0 means that no records matched the query.
The following example includes macros you might find useful for constructing and manipulating lookup queries for the DHCP network and dhcptab containers.
Example 3-1 Useful Macros for Lookup Queries
/* * Query macros - used for initializing query fields (lookup_d?) */ /* dhcp network container */ #define DN_QCID 0x0001 #define DN_QCIP 0x0002 #define DN_QSIP 0x0004 #define DN_QLEASE 0x0008 #define DN_QMACRO 0x0010 #define DN_QFDYNAMIC 0x0020 #define DN_QFAUTOMATIC 0x0040 #define DN_QFMANUAL 0x0080 #define DN_QFUNUSABLE 0x0100 #define DN_QFBOOTP_ONLY 0x0200 #define DN_QALL (DN_QCID | DN_QCIP | DN_QSIP | DN_QLEASE | \ DN_QMACRO | DN_QFDYNAMIC DN_QFAUTOMATIC |\ DN_QFMANUAL | DN_QFUNUSABLE | \ DN_QFBOOTP_ONLY) /* dhcptab */ #define DT_DHCPTAB "dhcptab" /* default name of container */ #define DT_QKEY 0x01 #define DT_QTYPE 0x02 #define DT_QALL (DT_QKEY | DT_QTYPE) /* general query macros */ #define DSVC_QINIT(q) ((q) = 0) #define DSVC_QEQ(q, v) ((q) = ((q) | (v) | ((v) << 16))) #define DSVC_QNEQ(q, v) ((q) = ((~(v << 16)) & (q)) | (v))) #define DSVC_QISEQ(q, v) (((q) & (v)) && ((q) & ((v) << 16))) #define DSVC_QISNEQ(q, v) (((q) & (v)) && (!((q) & ((v) << 16)))) /* Examples */ uint_t query; /* search for dhcptab record with key value, but not flags value */ DSVC_QINIT(query); DSVC_QEQ(query, DT_QKEY); DSVC_QNEQ(query, DT_QTYPE); /* search for dhcp network record that matches cid, client ip, server ip. */ DSVC_QINIT(query); DSVC_QEQ(query, (DN_QCID | DN_QCIP | DN_QSIP));
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL.
To add a record to the dhcptab container.
int add_dt(void *handp, dt_rec_t *newp);
Adds the record newp to the dhcptab container referred to by handp. The signature associated with newp is updated by the underlying public module. If an update collision occurs, the data store is not updated. The caller is responsible for freeing any dynamically allocated arguments.
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_INTERNAL, DSVC_EXISTS.
To modify a record in the dhcptab container.
int modify_dt(void *handp, const dt_rec_t *origp, dt_rec_t *newp);
Atomically modifies the record origp with the record newp in the dhcptab container referred to by handp. The signature associated with newp is updated by the underlying public module. If an update collision occurs, the data store is not updated. The caller is responsible for freeing any dynamically allocated arguments.
DSVC_SUCCESS, DSVC_ACCESS, DSVC_BUSY, DSVC_COLLISION, DSVC_INTERNAL, DSVC_NOENT.
To delete a record from the dhcptab container.
int delete_dt(void *handp, const dt_rec_t *dtp);
Deletes the record identified by the key, type and dt_sig fields of dtp from the dhcptab container referred to by the handle handp. If an update collision occurs, the matching record is not deleted from the data store, and DSVC_COLLISION is returned. The caller is responsible for freeing any dynamically allocated arguments.
If the dtp signature (dt_sig) is 0, the matching record is simply deleted with no detection of update collisions.
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_BUSY, DSVC_INTERNAL, DSVC_COLLISION.
To close the dhcptab container.
int close_dt(void **handpp);
Frees the instance handle and cleans up per-instance state.
DSVC_SUCCESS, DSVC_ACCESS, DSVC_INTERNAL.
To delete the dhcptab container from the data store location.
int remove_dt(const char *location);
Removes the dhcptab container in location from the data store.
DSVC_SUCCESS, DSVC_ACCESS, DSVC_NOENT, DSVC_NO_LOCATION, DSVC_BUSY, DSVC_INTERNAL.