This file is indexed.

/usr/share/doc/shapelib/shp_api.html is in shapelib 1.2.10-5.

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
<html>
<head>
<title>.SHP File API</title>
</head>
<body>

<h1>.SHP File API</h1>

The .SHP API uses a SHPHandle to represent an open .shp/.shx file pair.
The contents of the SHPHandle are visible (see shapefile.h) but should
be ignored by the application.  It is intended that all information be
accessed by the API functions.  <p>

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

<h2>Shape Types</h2>

Shapes have types associated with them.  The following is a list of the
different shapetypes supported by Shapefiles.  At this time all shapes in
a Shapefile must be of the same type (with the exception of NULL shapes). <p>

<pre>
  #define SHPT_NULL             0

  2D Shape Types (pre ArcView 3.x):

  #define SHPT_POINT		1	Points
  #define SHPT_ARC		3	Arcs (Polylines, possible in parts)
  #define SHPT_POLYGON		5	Polygons (possible in parts)
  #define SHPT_MULTIPOINT	8	MultiPoint (related points)

  3D Shape Types (may include "measure" values for vertices):

  #define SHPT_POINTZ		11	
  #define SHPT_ARCZ		13
  #define SHPT_POLYGONZ		15
  #define SHPT_MULTIPOINTZ 	18

  2D + Measure Types:

  #define SHPT_POINTM		21
  #define SHPT_ARCM		23
  #define SHPT_POLYGONM		25
  #define SHPT_MULTIPOINTM 	28

  Complex (TIN-like) with Z, and Measure:

  #define SHPT_MULTIPATCH 	31
</pre>

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

<h2>SHPObject</h2>

An individual shape is represented by the SHPObject structure.  SHPObject's
created with SHPCreateObject(), SHPCreateSimpleObject(), or SHPReadObject()
should be disposed of with SHPDestroyObject().<p>

<pre>
  typedef struct
  {
    int		nSHPType;	Shape Type (SHPT_* - see list above)

    int		nShapeId; 	Shape Number (-1 is unknown/unassigned)

    int		nParts;		# of Parts (0 implies single part with no info)
    int		*panPartStart;  Start Vertex of part
    int		*panPartType;	Part Type (SHPP_RING if not SHPT_MULTIPATCH)
    
    int		nVertices;	Vertex list 
    double	*padfX;		
    double	*padfY;
    double	*padfZ;		(all zero if not provided)
    double	*padfM;		(all zero if not provided)

    double	dfXMin;		Bounds in X, Y, Z and M dimensions
    double	dfYMin;
    double	dfZMin;
    double	dfMMin;

    double	dfXMax;
    double	dfYMax;
    double	dfZMax;
    double	dfMMax;
  } SHPObject;
</pre>

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

<h2>SHPOpen()</h2>

<pre>
SHPHandle SHPOpen( const char * pszShapeFile, const char * pszAccess );

  pszShapeFile:		The name of the layer to access.  This can be the
			name of either the .shp or the .shx file or can
			just be the path plus the basename of the pair.

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

  The SHPOpen() function should be used to establish access to the two files
  for accessing vertices (.shp and .shx).  Note that both files have to 
  be in the indicated directory, and must have the expected extensions in
  lower case.  The returned SHPHandle is passed to other access functions, 
  and SHPClose() should be invoked to recover resources, and flush changes 
  to disk when complete.<p>

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

<h2>SHPGetInfo()</h2>

<pre>
void SHPGetInfo( SHPHandle hSHP, int * pnEntities, int * pnShapeType,
                 double * padfMinBound, double * padfMaxBound );

  hSHP:			The handle previously returned by SHPOpen() 
			or SHPCreate().

  pnEntities:		A pointer to an integer into which the number of
			entities/structures should be placed.  May be NULL.

  pnShapetype:		A pointer to an integer into which the shapetype
			of this file should be placed.  Shapefiles may contain
			either SHPT_POINT, SHPT_ARC, SHPT_POLYGON or 
			SHPT_MULTIPOINT entities.  This may be NULL.

  padfMinBound:		The X, Y, Z and M minimum values will be placed into
                        this four entry array.  This may be NULL.
			
  padfMaxBound:		The X, Y, Z and M maximum values will be placed into
                        this four entry array.  This may be NULL.
</pre>

 The SHPGetInfo() function retrieves various information about shapefile
 as a whole.  The bounds are read from the file header, and may be 
 inaccurate if the file was improperly generated. <p>
			
<!-------------------------------------------------------------------------->

<h2>SHPReadObject()</h2>

<pre>
SHPObject *SHPReadObject( SHPHandle hSHP, int iShape );

  hSHP:			The handle previously returned by SHPOpen() 
			or SHPCreate().

  iShape:		The entity number of the shape to read.  Entity 
			numbers are between 0 and nEntities-1 (as returned
			by SHPGetInfo()).
</pre>

  The SHPReadObject() call is used to read a single structure, or entity
  from the shapefile.  See the definition of the SHPObject structure for
  detailed information on fields of a SHPObject.  SHPObject's returned from
  SHPReadObject() should be deallocated with SHPDestroyShape().  
  SHPReadObject() will return NULL if an illegal iShape value is requested.<p>

  Note that the bounds placed into the SHPObject are those read from the
  file, and may not be correct.   For points the bounds are generated from
  the single point since bounds aren't normally provided for point types.<p>

  Generally the shapes returned will be of the type of the file as a whole.
  However, any file may also contain type SHPT_NULL shapes which will have
  no geometry.  Generally speaking applications should skip rather than
  preserve them, as they usually represented interactively deleted shapes.<p>

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

<h2>SHPClose()</h2>

<pre>
void	SHPClose( SHPHandle hSHP );

  hSHP:			The handle previously returned by SHPOpen() 
			or SHPCreate().
</pre>

  The SHPClose() function will close the .shp and .shx files, and flush
  all outstanding header information to the files.  It will also recover
  resources associated with the handle.  After this call the hSHP handle
  cannot be used again.<p>

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

<h2>SHPCreate()</h2>

<pre>
SHPHandle SHPCreate( const char * pszShapeFile, int nShapeType );

  pszShapeFile:		The name of the layer to access.  This can be the
			name of either the .shp or the .shx file or can
			just be the path plus the basename of the pair.

  nShapeType:		The type of shapes to be stored in the newly created
			file.  It may be either SHPT_POINT, SHPT_ARC, 
		        SHPT_POLYGON or SHPT_MULTIPOINT.
</pre>

  The SHPCreate() function will create a new .shp and .shx file of the
  desired type.<p>

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

<h2>SHPCreateSimpleObject()</h2>

<pre>
SHPObject * 
     SHPCreateSimpleObject( int nSHPType, int nVertices, 
			    double *padfX, double * padfY, double *padfZ, );

  nSHPType:		The SHPT_ type of the object to be created, such
                        as SHPT_POINT, or SHPT_POLYGON.
  
  nVertices:		The number of vertices being passed in padfX,    
                        padfY, and padfZ. 

  padfX:		An array of nVertices X coordinates of the vertices
                        for this object.

  padfY:		An array of nVertices Y coordinates of the vertices
                        for this object.

  padfZ:		An array of nVertices Z coordinates of the vertices
                        for this object.  This may be NULL in which case
		        they are all assumed to be zero.
</pre>

  The SHPCreateSimpleObject() allows for the convenient creation of 
  simple objects.  This is normally used so that the SHPObject can be
  passed to SHPWriteObject() to write it to the file.  The simple object
  creation API assumes an M (measure) value of zero for each vertex.  For
  complex objects (such as polygons) it is assumed that there is only one
  part, and that it is of the default type (SHPP_RING). <p>

  Use the SHPCreateObject() function for more sophisticated objects.  The
  SHPDestroyObject() function should be used to free resources associated with
  an object allocated with SHPCreateSimpleObject(). <p>

  This function computes a bounding box for the SHPObject from the given 
  vertices.<p>

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

<h2>SHPCreateObject()</h2>

<pre>
SHPObject * 
     SHPCreateObject( int nSHPType, int iShape,
                      int nParts, int * panPartStart, int * panPartType,
                      int nVertices, double *padfX, double * padfY, 
                      double *padfZ, double *padfM );

  nSHPType:		The SHPT_ type of the object to be created, such
                        as SHPT_POINT, or SHPT_POLYGON.

  iShape:		The shapeid to be recorded with this shape.

  nParts:		The number of parts for this object.  If this is
                        zero for ARC, or POLYGON type objects, a single 
                        zero valued part will be created internally.
  
  panPartStart:		The list of zero based start vertices for the rings
                        (parts) in this object.  The first should always be
                        zero.  This may be NULL if nParts is 0.
  
  panPartType:		The type of each of the parts.  This is only meaningful
                        for MULTIPATCH files.  For all other cases this may
                        be NULL, and will be assumed to be SHPP_RING.
  
  nVertices:		The number of vertices being passed in padfX,    
                        padfY, and padfZ. 

  padfX:		An array of nVertices X coordinates of the vertices
                        for this object.

  padfY:		An array of nVertices Y coordinates of the vertices
                        for this object.

  padfZ:		An array of nVertices Z coordinates of the vertices
                        for this object.  This may be NULL in which case
		        they are all assumed to be zero.

  padfM:		An array of nVertices M (measure values) of the 
			vertices for this object.  This may be NULL in which 
			case they are all assumed to be zero.
</pre>

  The SHPCreateSimpleObject() allows for the creation of objects (shapes).  
  This is normally used so that the SHPObject can be passed to 
  SHPWriteObject() to write it to the file. <p>

  The SHPDestroyObject() function should be used to free resources associated 
  with an object allocated with SHPCreateObject(). <p>

  This function computes a bounding box for the SHPObject from the given 
  vertices.<p>

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

<h2>SHPComputeExtents()</h2>

<pre>
void SHPComputeExtents( SHPObject * psObject );

  psObject:		An existing shape object to be updated in place.
</pre>
 
  This function will recompute the extents of this shape, replacing the
  existing values of the dfXMin, dfYMin, dfZMin, dfMMin, dfXMax, dfYMax, 
  dfZMax, and dfMMax values based on the current set of vertices for the
  shape.   This function is automatically called by SHPCreateObject() but
  if the vertices of an existing object are altered it should be called again
  to fix up the extents.<p>

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

<h2>SHPWriteObject()</h2>

<pre>
int SHPWriteObject( SHPHandle hSHP, int iShape, SHPObject *psObject );

  hSHP:			The handle previously returned by SHPOpen("r+") 
			or SHPCreate().

  iShape:		The entity number of the shape to write.  A value of
		        -1 should be used for new shapes.  

  psObject:		The shape to write to the file. This should have
                        been created with SHPCreateObject(), or 
                        SHPCreateSimpleObject().
</pre>

  The SHPWriteObject() call is used to write a single structure, or entity
  to the shapefile.  See the definition of the SHPObject structure for
  detailed information on fields of a SHPObject.  The return value is the
  entity number of the written shape. <p>

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

<h2>SHPDestroyObject()</h2>

<pre>
void SHPDestroyObject( SHPObject *psObject );

  psObject:		The object to deallocate.
</pre>

  This function should be used to deallocate the resources associated with
  a SHPObject when it is no longer needed, including those created with
  SHPCreateSimpleObject(), SHPCreateObject() and returned from SHPReadObject().
  <p>

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

<h2>SHPRewindObject()</h2>

<pre>
int SHPRewindObject( SHPHandle hSHP, SHPObject *psObject );

  hSHP:                 The shapefile (not used at this time).
  psObject:		The object to deallocate.
</pre>

  This function will reverse any rings necessary in order to enforce the
  shapefile restrictions on the required order of inner and outer rings in
  the Shapefile specification.  It returns TRUE if a change is made and FALSE
  if no change is made.  Only polygon objects will be affected though any   
  object may be passed.
  <p>

</body>
</html>