prg_list_access()

Abstract

Obtains a pointer to an element stored in the specified list, at the specified list position.

Syntax

prg_list_access (list_ptr, pos_index)
Argument Type Description
list_ptr PrgT_List * pointer to the list-of-interest.
A pointer to a list can be obtained from several functions: an empty list can be originally obtained from prg_list_create(), a list representing the contents of a file can be obtained from prg_gdf_read(), or a list can be allocated by user code and initialized via prg_list_init().
pos_index int numeric position index of the element to be accessed in the list.
Position indices start at 0 at the head of the list, and increment by one until the tail is reached. Instead of an explicit numeric position index, an abstract list position index can be specified; the acceptable values are PRGC_LISTPOS_HEAD and PRGC_LISTPOS_TAIL.

Return Type

Vartype *

Pointer to the element accessed within the specified list. The special value represented by the symbolic constant PRGC_NIL will be returned if the specified position index is larger than the index of the tail element in the specified list, or if the index is less than zero.

prg_list_funcs.h

Example:

/* Obtain the i_th line. */
line = (char*) prg_list_access (line_list_ptr, i);

/* Decompose it into fields (field boundaries are */
/* indicated by spaces, tabs, slashes, or commas). */
field_list_ptr = prg_str_decomp (line, " ,/\t");

/* ...Incomplete lines are skipped. */
if (prg_list_size (field_list_ptr) < 6) continue;

/* Create a routing instruction structure. */
iri_ptr = (ip_rte_instruction*) 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*)(prg_list_access (field_list_ptr, IP_TBL_DEST_NET_FIELD));
iri_ptr->dest_node = ip_rte_sup_str_to_addr (
	(char*) prg_list_access (field_list_ptr, IP_TBL_DEST_NODE_FIELD));

Details

Accessing a list element via this function does not affect the element’s contents, status as a member of the list, or position within the list. However, statements that use the pointer value returned by this function can manipulate the contents of the element, if desired.

The pointer value returned by this function should be cast into the appropriate data type to access the element’s contents. An example is shown below, in which instances of the data structure type block are stored in a list:

struct block *bptr;
bptr = (struct block *) prg_list_access (list_ptr, PRGC_LISTPOS_TAIL);

WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.

Purpose:

Provides a mechanism to obtain the pointer of an element contained within a list. Typically this is used to scan the contents of a list, parse, search, or otherwise process its contents. Scanning can be implemented by first determining the number of elements in a list via prg_list_size(). A loop can be constructed which obtains the pointer to each element in the list in turn, using this function.

Errors:

  • Program Abort: Segmentation violation. (due to invalid list pointer or malformed list)
  • Recoverable Error: List position (<pos_index>) is invalid for list.

Reference:

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com