modules/src/idf/idf.3

   1 .TH IDF 3 "$Revision: 1.6 $"
   2 .ad
   3 .SH NAME
   4 init_idf, str2idf, findidf\ \-\ a namelist module
   5 .SH SYNOPSIS
   6 .PP
   7 .B void init_idf()
   8 .PP
   9 .B struct idf *str2idf(tag, cpy)
  10 .br
  11 .B char *tag;
  12 .PP
  13 .B struct idf *findidf(tag)
  14 .br
  15 .B char *tag;
  16 .SH DESCRIPTION
  17 This is a generic namelist module. It provides a fast mechanism for
  18 associating information with identifiers. To get an instantiation, the
  19 user must provide two files \fIidf.h\fR and \fIidf.c\fR.
  20 \fIidf.h\fR could contain the following:
  21 .br
  22 .PP
  23 .RS
  24 .nf
  25 #define IDF_TYPE struct id_info
  26 #define IDF_HSIZE 8
  27
  28 #include <idf_pkg.spec>
  29 .fi
  30 .RE
  31 .PP
  32 and \fIidf.c\fR could contain:
  33 .br
  34 .PP
  35 .RS
  36 .nf
  37 #include "id_info.h"          /* contains definition for struct id_info */
  38 #include "idf.h"
  39 #include <idf_pkg.body>
  40 .fi
  41 .RE
  42 .PP
  43 IDF_TYPE denotes a type containing all information associated with
  44 an identifier. If it is not defined, the instantiation will not contain
  45 any user-defined information.
  46 .PP
  47 IDF_HSIZE denotes the number of significant characters for the hashing
  48 function. It's default value is 64. Notice that this value does \fBnot\fP
  49 denote the number of significant characters, but only the number of characters
  50 that are used for hashing.
  51 .PP
  52 The user can also define IDF_NAME, to give a name to the selector in the
  53 idf-structure. It's default value is \fIid_user\fP.
  54 .PP
  55 The routine \fIinit_idf\fR initializes the namelist.
  56 .PP
  57 The function
  58 \fIstr2idf\fR searches for the string \fItag\fR in the namelist, and
  59 creates an entry for it if necessary. A pointer to this entry is
  60 returned. If \fIcpy\fR is non-zero, a copy of the \fItag\fR is made,
  61 otherwise the \fItag\fR itself is used.
  62 The entry has the following structure, defined in \fIidf_pkg.spec\fR:
  63 .PP
  64 .nf
  65 struct idf      {
  66         struct idf *next;             \kx/* links idf-structures together */
  67         char *id_text;\h'|\nxu'/* string representing the name */
  68 #ifdef IDF_TYPE
  69         IDF_TYPE IDF_NAME;\h'|\nxu'/* user defined type */
  70 #endif
  71 };
  72 .fi
  73 .PP
  74 The field \fIid_text\fR will point to a copy of \fItag\fR, or
  75 to the \fItag\fR itself, depending on \fIcpy\fR.
  76 The field \fInext\fR is used for internal information and must not
  77 be changed by the user of this module.
  78 The user-defined part of the structure is initialized with zeros.
  79 .PP
  80 The function \fIfindidf\fP searches for the string \fItag\fP in the
  81 namelist, but returns 0 when it is not present.
  82 .SH "MODULES USED"
  83 alloc(3)
  84 .SH FILES
  85 ~em/modules/pkg/idf_pkg.spec
  86 .br
  87 ~em/modules/pkg/idf_pkg.body