prg_gdf_read()

Abstract

Reads the contents of an ASCII file and returns the file contents as a list of strings.

Syntax

prg_gdf_read (file_name)
Argument Type Description
file_name char* name of the file to read.
If this argument is given as only a file name (no path or suffix), it must match the name of a general data file (.gdf suffix) contained in the model directories.
If this argument is given as an absolute path name, it can be any ASCII file (such as a general data file or comma-separated value file).

Return Type

Prg_List*

Pointer to a list of strings representing lines read from the specified file. Each line of the file is copied into a string within the returned list. If the file could not be opened, the symbolic constant PRGC_NIL is returned.

prg_file_funcs.h

Example

Prg_List*
arp_sup_table_load (file_name)
	{
	Prg_List*			line_list_ptr;
	char			err_str [256]

	/* Read in an address-map table from an ASCII */
	/* file adhering to the format defined above. */
	FIN (arp_sup_table_load (file_name))

	/* Open and read the file into the list. */
	line_list_ptr = prg_gdf_read (file_name);
	/* Test for error in reading. */
	if (line_list_ptr == PRGC_NIL)
		{
		sprintf (err_str, "File Name: %s", file_name);
		op_sim_end ("Package: arp_sup", <...>

Details

This function looks in the model directories for the specified ASCII file, either:

  • A general data file (.gdf suffix), if only a file name is specified
  • Any ASCII file (.gdf, .csv, or other suffix), if a full path name and suffix is specified

The ASCII file is opened by this function before being read and closed after being read, thus providing an all-in-one file operation. Invoking this function has no destructive or modifying effect on the file. The contents of the file are returned in a list of strings, with the beginning of the file starting at the head of the list and the end of the file at the tail of the list. The list is created within this function and can later be cleared out using prg_list_free().

Several processing functions are performed on the file contents:

  • Blank lines (consisting of only white space) are not placed in the list
  • Comment lines that start with a pound sign (#) in the first column are not placed in the list
  • Leading white space on each line is removed

Purpose

Provides a mechanism for reading in ASCII text information from files, thus avoiding direct use of the standard I/O functions (such as fopen(), fread(), and fclose()). This is typically useful for processes that need to load in tabular information stored in files, such as routing tables. In a single function call, the file is located and opened, its contents read and organized into a list, non-interesting lines are avoided, and the file is closed. The returned list can then be conveniently manipulated using prg_list_access() or prg_list_remove().

The function prg_tfile_generic_data_file_read() expands the functionality of prg_gdf_read() by also supporting generic settings files (.gsf) and by allowing the returned strings to be appended to a specified list.

Errors

  • Program Abort: Segmentation Violation. (due to invalid file_name argument)
  • Program Abort: Allocation of memory failed.
  • Recoverable Error: Unable to open file (<file_name>) for reading
  • Recoverable Error: Unable to allocate sufficient memory for reading from (<file_name>).

Reference

  • use prg_list_free() to deallocate the contents of the list returned by this function
  • use prg_mem_free() to deallocate the list structure memory allocated by this function
  • use prg_list_access() to obtain a pointer to a single line in the list returned by this function
  • use prg_list_remove() to remove a single line (and obtain a pointer to it) from the list returned by this function
  • use prg_str_decomp() to decompose a line of the file into a series of field strings

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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