This file is indexed.

/usr/share/doc/shapelib/dbf_api.html is in shapelib 1.4.1-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
<html>
<head>
<title>Attribute (.DBF) API</title>
</head>
<body>
<h1>Attribute (.DBF) API</h1>

The Attribute (DBF) API uses DBFHandle to represent a handle for access
to one .dbf file.  The contents of the DBFHandle are visible (see shapefil.h)
but should be ignored by the application.  It is intended that all information
be accessed by API functions.  Note that there should be exactly one record
in the .dbf file for each shape in the .shp/.shx files.  This constraint
must be maintained by the application.<p>

<!-------------------------------------------------------------------------->

<h2>DBFOpen()</h2>

<pre>
DBFHandle DBFOpen( const char * pszDBFFile, const char * pszAccess );

  pszDBFFile:		The name of the xBase (.dbf) file to access.

  pszAccess:		The fopen() style access string.  At this time only
			"rb" (read-only binary) and "rb+" (read/write binary) 
		        should be used.
</pre>

  The DBFOpen() function should be used to establish access to an existing
  xBase format table file.  The returned DBFHandle is passed to other 
  access functions, and DBFClose() should be invoked to recover resources, and 
  flush changes to disk when complete.  The DBFCreate() function should
  called to create new xBase files.  As a convenience, DBFOpen() can be
  called with the name of a .shp or .shx file, and it will figure out the
  name of the related .dbf file.<p>

<!-------------------------------------------------------------------------->

<h2>DBFCreate()</h2>

<pre>
DBFHandle DBFCreate( const char * pszDBFFile );

  pszDBFFile:		The name of the xBase (.dbf) file to create.
</pre>
  
  The DBFCreate() function creates a new xBase format file with the given 
  name, and returns an access handle that can be used with other DBF functions.
  The newly created file will have no fields, and no records.  Fields should
  be added with DBFAddField() before any records add written.

<!-------------------------------------------------------------------------->

<h2>DBFGetFieldCount()</h2>

<pre>
int DBFGetFieldCount( DBFHandle hDBF );

  hDBF:		The access handle for the file to be queried, as returned
                by DBFOpen(), or DBFCreate().
</pre>

  The DBFGetFieldCount() function returns the number of fields currently
  defined for the indicated xBase file.

<!-------------------------------------------------------------------------->

<h2>DBFGetRecordCount()</h2>

<pre>
int DBFGetRecordCount( DBFHandle hDBF );

  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().
</pre>

  The DBFGetRecordCount() function returns the number of records that
  exist on the xBase file currently.  Note that with shape files one xBase
  record exists for each shape in the .shp/.shx files.<p>

<!-------------------------------------------------------------------------->

<h2>DBFGetFieldIndex()</h2>

<pre>
int DBFGetFieldIndex( DBFHandle hDBF, const char *pszFieldName );

  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().

  pszFieldName: Name of the field to search for.
</pre>

  Returns the index of the field matching this name, or -1 on failure.  The
  comparison is case insensitive.  However, lengths must match exactly.<p>

<!-------------------------------------------------------------------------->

<h2>DBFGetFieldInfo()</h2>

<pre>
DBFFieldType DBFGetFieldInfo( DBFHandle hDBF, int iField, char * pszFieldName,
                              int * pnWidth, int * pnDecimals );

  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().

  iField:	The field to be queried.  This should be a number between 
                0 and n-1, where n is the number fields on the file, as
                returned by DBFGetFieldCount().

  pszFieldName:	If this pointer is not NULL the name of the requested field
		will be written to this location.  The pszFieldName buffer 
                should be at least 12 character is size in order to hold
		the longest possible field name of 11 characters plus a 
                terminating zero character.

  pnWidth:	If this pointer is not NULL, the width of the requested field
		will be returned in the int pointed to by pnWidth.  This is
                the width in characters.  

  pnDecimals:	If this pointer is not NULL, the number of decimal places
                precision defined for the field will be returned.  This is
                zero for integer fields, or non-numeric fields.
</pre>

  The DBFGetFieldInfo() returns the type of the requested field, which is
  one of the DBFFieldType enumerated values.  As well, the field name, and
  field width information can optionally be returned.  The field type returned
  does not correspond one to one with the xBase field types.  For instance
  the xBase field type for Date will just be returned as being FTInteger.  <p>

<pre>
    typedef enum {
      FTString,			/* fixed length string field 		*/
      FTInteger,		/* numeric field with no decimals 	*/
      FTDouble,			/* numeric field with decimals 		*/
      FTLogical,		/* logical field.                       */
      FTInvalid                 /* not a recognised field type 		*/
    } DBFFieldType;
</pre>

<!-------------------------------------------------------------------------->

<h2>DBFAddField()</h2>

<pre>
int DBFAddField( DBFHandle hDBF, const char * pszFieldName, 
                 DBFFieldType eType, int nWidth, int nDecimals );

  hDBF:		The access handle for the file to be updated, as returned by
		DBFOpen(), or DBFCreate().

  pszFieldName:	The name of the new field.  At most 11 character will be used.
                In order to use the xBase file in some packages it may be
                necessary to avoid some special characters in the field names
                such as spaces, or arithmetic operators.

  eType:	One of FTString, FTInteger or FTDouble in order to establish
                the type of the new field.  Note that some valid xBase field
                types cannot be created such as date fields.

  nWidth:	The width of the field to be created.  For FTString fields this
                establishes the maximum length of string that can be stored.
                For FTInteger this establishes the number of digits of the
                largest number that can
                be represented.  For FTDouble fields this in combination
                with the nDecimals value establish the size, and precision
                of the created field.

  nDecimals:    The number of decimal places to reserve for FTDouble fields.
                For all other field types this should be zero.  For instance
                with nWidth=7, and nDecimals=3 numbers would be formatted
                similarly to `123.456'.
</pre>

  The DBFAddField() function is used to add new fields to an existing xBase
  file opened with DBFOpen(), or created with DBFCreate().<p>

  The DBFAddField() return value is the field number of the new field, or
  -1 if the addition of the field failed.<p>

<!-------------------------------------------------------------------------->

<h2>DBFReadIntegerAttribute()</h2>

<pre>
int DBFReadIntegerAttribute( DBFHandle hDBF, int iShape, int iField );
  
  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) from which the field value
                should be read.

  iField:	The field within the selected record that should be read.
</pre>

  The DBFReadIntegerAttribute() will read the value of one field and return
  it as an integer.  This can be used even with FTString fields, though the
  returned value will be zero if not interpretable as a number.<p>

<!-------------------------------------------------------------------------->

<h2>DBFReadDoubleAttribute()</h2>

<pre>
double DBFReadDoubleAttribute( DBFHandle hDBF, int iShape, int iField );
  
  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) from which the field value
                should be read.

  iField:	The field within the selected record that should be read.
</pre>

  The DBFReadDoubleAttribute() will read the value of one field and return
  it as a double.  This can be used even with FTString fields, though the
  returned value will be zero if not interpretable as a number.<p>

<!-------------------------------------------------------------------------->

<h2>DBFReadStringAttribute()</h2>

<pre>
const char *DBFReadStringAttribute( DBFHandle hDBF, int iShape, int iField );
  
  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) from which the field value
                should be read.

  iField:	The field within the selected record that should be read.
</pre>

  The DBFReadStringAttribute() will read the value of one field and return
  it as a string.  This function may be used on any field type (including 
  FTInteger and FTDouble) and will return the string representation stored
  in the .dbf file.  The returned pointer is to an internal buffer
  which is only valid untill the next DBF function call.  It's contents may
  be copied with normal string functions such as strcpy(), or strdup().  If
  the TRIM_DBF_WHITESPACE macro is defined in shapefil.h (it is by default)
  then all leading and trailing space (ASCII 32) characters will be stripped
  before the string is returned.<p>

<!-------------------------------------------------------------------------->

<h2>DBFIsAttributeNULL()</h2>

<pre>
int DBFIsAttributeNULL( DBFHandle hDBF, int iShape, int iField );
  
  hDBF:		The access handle for the file to be queried, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) from which the field value
                should be read.

  iField:	The field within the selected record that should be read.
</pre>

  This function will return TRUE if the indicated field is NULL valued
  otherwise FALSE.  Note that NULL fields are represented in the .dbf file
  as having all spaces in the field.  Reading NULL fields will result in
  a value of 0.0 or an empty string with the other DBFRead*Attribute() 
  functions.<p>

<!-------------------------------------------------------------------------->

<h2>DBFWriteIntegerAttribute</h2>

<pre>
int DBFWriteIntegerAttribute( DBFHandle hDBF, int iShape, int iField,
                              int nFieldValue );

  hDBF:		The access handle for the file to be written, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) to which the field value
                should be written.

  iField:	The field within the selected record that should be written.

  nFieldValue:	The integer value that should be written.
</pre>

The DBFWriteIntegerAttribute() function is used to write a value to a numeric
field (FTInteger, or FTDouble).  If the write succeeds the value TRUE will
be returned, otherwise FALSE will be returned.  If the value is too large to 
fit in the field, it will be truncated and FALSE returned.<p>

<!-------------------------------------------------------------------------->

<h2>DBFWriteDoubleAttribute()</h2>

<pre>
int DBFWriteDoubleAttribute( DBFHandle hDBF, int iShape, int iField,
                             double dFieldValue );

  hDBF:		The access handle for the file to be written, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) to which the field value
                should be written.

  iField:	The field within the selected record that should be written.

  dFieldValue:	The floating point value that should be written.
</pre>

The DBFWriteDoubleAttribute() function is used to write a value to a numeric
field (FTInteger, or FTDouble).  If the write succeeds the value TRUE will
be returned, otherwise FALSE will be returned.  If the value is too large to 
fit in the field, it will be truncated and FALSE returned.<p>

<!-------------------------------------------------------------------------->

<h2>DBFWriteStringAttribute()</h2>

<pre>
int DBFWriteStringAttribute( DBFHandle hDBF, int iShape, int iField,
                             const char * pszFieldValue );

  hDBF:		The access handle for the file to be written, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) to which the field value
                should be written.

  iField:	The field within the selected record that should be written.

  pszFieldValue: The string to be written to the field.
</pre>

The DBFWriteStringAttribute() function is used to write a value to a string
field (FString).  If the write succeeds the value TRUE willbe returned, 
otherwise FALSE will be returned.  If the value is too large to 
fit in the field, it will be truncated and FALSE returned.<p>

<!-------------------------------------------------------------------------->

<h2>DBFWriteNULLAttribute()</h2>

<pre>
int DBFWriteNULLAttribute( DBFHandle hDBF, int iShape, int iField );

  hDBF:		The access handle for the file to be written, as returned by
		DBFOpen(), or DBFCreate().

  iShape:	The record number (shape number) to which the field value
                should be written.

  iField:	The field within the selected record that should be written.
</pre>

The DBFWriteNULLAttribute() function is used to clear the indicated field
to a NULL value.  In the .dbf file this is represented by setting the entire
field to spaces.  If the write succeeds the value TRUE willbe returned, 
otherwise FALSE will be returned.<p>

<!-------------------------------------------------------------------------->

<h2>DBFClose()</h2>

<pre>
void DBFClose( DBFHandle hDBF );

  hDBF:		The access handle for the file to be closed.
</pre>

  The DBFClose() function will close the indicated xBase file (opened with
  DBFOpen(), or DBFCreate()), flushing out all information to the file on
  disk, and recovering any resources associated with having the file open.
  The file handle (hDBF) should not be used again with the DBF API after
  calling DBFClose().<p>

<!-------------------------------------------------------------------------->

<h2>DBFIsRecordDeleted()</h2>

<pre>
int DBFIsRecordDeleted( DBFHandle hDBF, int iShape );

  hDBF:		The access handle for the file to be checked.
  iShape:       The record index to check.
</pre>

  Returns TRUE (non-zero) if the record is marked for deletion, otherwise
  it returns FALSE.<p>

<!-------------------------------------------------------------------------->

<h2>DBFMarkRecordDeleted()</h2>

<pre>
int DBFMarkRecordDeleted( DBFHandle hDBF, int iShape, int bIsDeleted );

  hDBF:		The access handle for the file.
  iShape:       The record index to update.
  bIsDeleted:   TRUE to mark record deleted, or FALSE to undelete it.
</pre>

  Returns TRUE on success, or FALSE on error.<p>

<!-------------------------------------------------------------------------->

<h2>DBFGetNativeFieldType()</h2>

<pre>
char DBFGetNativeFieldType( DBFHandle hDBF, int iField );

  hDBF:		The access handle for the file.
  iField:       The field index to query.
  
</pre>

  This function returns the DBF type code of the indicated field. It will
  be one of:<p>

<ul>
<li> 'C' (String)
<li> 'D' (Date)
<li> 'F' (Float)
<li> 'N' (Numeric, with or without decimal)
<li> 'L' (Logical)
<li> 'M' (Memo: 10 digits .DBT block ptr)
<li> ' ' (field out of range)
</ul>

</body>
</html>