op_prg_list_access()
摘要
获取指定列表中指定列表位置处所存储元素的指针。
注意: 该内核过程是一个仅为向后兼容而保留的宏调用。新代码应使用 prg_list_access()。
语法
op_prg_list_access (list_ptr, pos_index)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
List* |
指向目标列表的指针 [列表指针可以从多个内核过程获得:空列表最初可由 op_prg_list_create() 获得,表示文件内容的列表可由 op_prg_gdf_read() 获得,或者列表可由用户代码分配并通过 op_prg_list_init() 初始化。]。 |
pos_index |
int |
要在列表中访问的元素的数字位置索引 [位置索引从列表头部的 0 开始,逐次加一直到尾部。除了显式的数字位置索引,也可以指定抽象列表位置索引;可接受的值为 OPC_LISTPOS_HEAD 和 OPC_LISTPOS_TAIL。] |
返回类型
void*
指向所访问的指定列表内元素的指针。
如果指定的位置索引大于指定列表中尾部元素的索引,或者索引小于零,则返回符号常量 OPC_NIL 所代表的特殊值。
示例
摘自:示例模型(std/ip);外部 C 文件(ip_rte_sup.ex.c);函数(ip_rte_sup_list_parse())。
/* Obtain the i_th line. */
line = (char*) op_prg_list_access (line_list_ptr, i);
/* Decompose it into fields (field boundaries are */
/* indicated by spaces, tabs, slashes, or commas). */
field_list_ptr = op_prg_str_decomp (line, " ,/\t");
/* ...Incomplete lines are skipped. */
if (op_prg_list_size (field_list_ptr) < 6) continue;
/* Create a routing instruction structure. */
iri_ptr = (ip_rte_instruction*) op_prg_mem_alloc (sizeof (ip_rte_instruction));
/* ...First obtain the destination network and node fields. */
iri_ptr->dest_net = ip_rte_sup_str_to_addr (
(char*)(op_prg_list_access (field_list_ptr, IP_TBL_DEST_NET_FIELD));
iri_ptr->dest_node = ip_rte_sup_str_to_addr (
(char*) op_prg_list_access (field_list_ptr, IP_TBL_DEST_NODE_FIELD));
详情
通过该内核过程访问列表元素不会影响元素的内容、其作为列表成员的状态或在列表中的位置。不过,使用该内核过程返回的指针值的语句可以按需操纵元素的内容。
该内核过程返回的指针值应转换为合适的数据类型以访问元素的内容。下面给出一个示例,其中数据结构类型 block 的实例存储在列表中:
struct block *bptr;
bptr = (struct block *) op_prg_list_access (list_ptr, OPC_LISTPOS_TAIL);
注意: 该内核过程不是 MT 安全的,如 “Multi-Threading Safety“ 第 11 页所述。对共享列表的访问必须由外部串行化。
用途
提供一种获取列表内元素指针的机制。通常用于扫描列表内容、解析、查找或以其他方式处理列表内容。扫描可以先通过内核过程 op_prg_list_size() 确定列表中的元素数量来实现。可以构造一个循环,使用该内核过程依次获取列表中每个元素的指针。
错误
- 程序中止:段错误。(由于列表指针无效或列表格式错误)
- 可恢复错误:列表位置(
<pos_index>)超出范围。
参考
- 使用内核过程 op_prg_list_size() 确定列表中的元素数量
- 使用内核过程 op_prg_list_remove() 访问并从列表中移除元素
- 使用内核过程 op_prg_list_insert() 向列表插入新元素