GRASS GIS 8 Programmer's Manual  8.2.2dev(2023)-3d2c704037
vector/Vlib/open.c File Reference

Vector library - Open existing or create new vector map (native or OGR/PostGIS format) More...

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <grass/vector.h>
#include <grass/glocale.h>
#include "local_proto.h"
#include "pg_local_proto.h"
Include dependency graph for vector/Vlib/open.c:

Go to the source code of this file.

Macros

#define MAX_OPEN_LEVEL   2
 

Functions

int Vect_set_open_level (int level)
 Predetermine level at which a vector map will be opened for reading. More...
 
int Vect__open_old (struct Map_info *Map, const char *name, const char *mapset, const char *layer, int update, int head_only, int is_tmp)
 Open existing vector map for reading (internal use only) More...
 
int Vect_open_old (struct Map_info *Map, const char *name, const char *mapset)
 Open existing vector map for reading. More...
 
int Vect_open_tmp_old (struct Map_info *Map, const char *name, const char *mapset)
 Open existing temporary vector map for reading. More...
 
int Vect_open_old2 (struct Map_info *Map, const char *name, const char *mapset, const char *layer)
 Open existing vector map for reading. More...
 
int Vect_open_update (struct Map_info *Map, const char *name, const char *mapset)
 Open existing vector map for reading/writing. More...
 
int Vect_open_tmp_update (struct Map_info *Map, const char *name, const char *mapset)
 Open existing temporary vector map for reading/writing. More...
 
int Vect_open_update2 (struct Map_info *Map, const char *name, const char *mapset, const char *layer)
 Open existing vector map for reading/writing. More...
 
int Vect_open_old_head (struct Map_info *Map, const char *name, const char *mapset)
 Reads only info about vector map (headers) More...
 
int Vect_open_old_head2 (struct Map_info *Map, const char *name, const char *mapset, const char *layer)
 Reads only info about vector map (headers) More...
 
int Vect_open_update_head (struct Map_info *Map, const char *name, const char *mapset)
 Open header file of existing vector map for updating (mostly for database link updates) More...
 
int Vect_open_new (struct Map_info *Map, const char *name, int with_z)
 Create new vector map for reading/writing. More...
 
int Vect_open_tmp_new (struct Map_info *Map, const char *name, int with_z)
 Create new temporary vector map. More...
 
int Vect_coor_info (const struct Map_info *Map, struct Coor_info *Info)
 Update Coor_info structure. More...
 
const char * Vect_maptype_info (const struct Map_info *Map)
 Gets vector map format (as string) More...
 
int Vect_maptype (const struct Map_info *Map)
 Gets vector map format. More...
 
int Vect_open_topo (struct Map_info *Map, int head_only)
 Open topology file ('topo') More...
 
int Vect_open_sidx (struct Map_info *Map, int mode)
 Open spatial index file ('sidx') More...
 
char * Vect__get_path (char *path, const struct Map_info *Map)
 Get map directory name (internal use only) More...
 
char * Vect__get_element_path (char *file_path, const struct Map_info *Map, const char *element)
 Get map element full path (internal use only) More...
 

Detailed Description

Vector library - Open existing or create new vector map (native or OGR/PostGIS format)

Higher level functions for reading/writing/manipulating vectors.

(C) 2001-2015 by the GRASS Development Team

This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

Author
Original author CERL, probably Dave Gerdes or Mike Higgins.
Update to GRASS 5.7 Radim Blazek and David D. Gray.
Update to GRASS 7 Martin Landa <landa.martin gmail.com> (better OGR support and native PostGIS access)

Definition in file vector/Vlib/open.c.

Macro Definition Documentation

◆ MAX_OPEN_LEVEL

#define MAX_OPEN_LEVEL   2

Definition at line 44 of file vector/Vlib/open.c.

Function Documentation

◆ Vect__get_element_path()

char* Vect__get_element_path ( char *  file_path,
const struct Map_info Map,
const char *  element 
)

Get map element full path (internal use only)

Allocate string should be freed by G_free().

Parameters
Mappointer to Map_info struct
elementelement name, eg. GV_TOPO_ELEMENT
Returns
allocated buffer containing path

Definition at line 1479 of file vector/Vlib/open.c.

References G_file_name(), G_file_name_tmp(), GPATH_MAX, Map_info::mapset, Map_info::temporary, and Vect__get_path().

Referenced by V1_close_nat(), V1_open_new_nat(), V2_close_pg(), Vect_cidx_open(), Vect_coor_info(), Vect_open_topo(), Vect_save_fidx(), and Vect_save_sidx().

◆ Vect__get_path()

char* Vect__get_path ( char *  path,
const struct Map_info Map 
)

Get map directory name (internal use only)

Parameters
file_pathpath string buffer
Mappointer to Map_info struct
Returns
buffer containing path

Definition at line 1455 of file vector/Vlib/open.c.

References G__temp_element(), GPATH_MAX, GV_DIRECTORY, Map_info::name, Map_info::temporary, and TRUE.

Referenced by V1_open_new_nat(), V1_open_old_nat(), Vect__get_element_path(), Vect__read_head(), Vect__write_head(), Vect_cidx_open(), Vect_open_topo(), Vect_save_topo(), and Vect_write_dblinks().

◆ Vect__open_old()

int Vect__open_old ( struct Map_info Map,
const char *  name,
const char *  mapset,
const char *  layer,
int  update,
int  head_only,
int  is_tmp 
)

Open existing vector map for reading (internal use only)

Parameters
[out]Mappointer to Map_info structure
namename of vector map to open
mapsetmapset name ("" for search path)
layerlayer name (OGR format only)
updatenon-zero to open for update otherwise read-only mode
head_onlyread only header info from 'head', 'dbln', 'topo', 'cidx' is not opened. The header may be opened on level 2 only.
is_tmpnon-zero code for temporary maps
Returns
level of openness (1, 2)
-1 in error

Definition at line 162 of file vector/Vlib/open.c.

References GMAPSET_MAX, GNAME_MAX, and GPATH_MAX.

Referenced by Vect_open_old(), Vect_open_old2(), Vect_open_old_head(), Vect_open_old_head2(), Vect_open_tmp_old(), Vect_open_tmp_update(), Vect_open_update(), Vect_open_update2(), and Vect_open_update_head().

◆ Vect_coor_info()

int Vect_coor_info ( const struct Map_info Map,
struct Coor_info Info 
)

◆ Vect_maptype()

int Vect_maptype ( const struct Map_info Map)

Gets vector map format.

Currently are implemented:

  • Native format (GV_FORMAT_NATIVE)
  • OGR format linked via v.external (GV_FORMAT_OGR)
  • OGR format (GV_FORMAT_OGR_DIRECT)
  • PostGIS fomat (GV_FORMAT_POSTGIS)
Parameters
Mappointer to Map_info structure
Returns
map format code

Definition at line 1069 of file vector/Vlib/open.c.

References Format_info_pg::conninfo, Format_info_ogr::driver_name, Map_info::fInfo, Map_info::format, GV_FORMAT_OGR, GV_FORMAT_POSTGIS, Format_info::ogr, Format_info::pg, and Map_info::temporary.

Referenced by Vect_fidx_dump().

◆ Vect_maptype_info()

const char* Vect_maptype_info ( const struct Map_info Map)

Gets vector map format (as string)

Note: string is allocated by G_store(). Free allocated memory with G_free().

Currently are implemented:

  • Native format (native)
  • OGR format (ogr)
  • PostGIS format (postgis)
Parameters
Mappointer to Map_info structure
Returns
maptype string on success (allocated by G_store())
error message on error

Definition at line 1033 of file vector/Vlib/open.c.

References _, Map_info::format, G_store(), GV_FORMAT_NATIVE, GV_FORMAT_OGR, GV_FORMAT_OGR_DIRECT, and GV_FORMAT_POSTGIS.

Referenced by Vect_fidx_dump().

◆ Vect_open_new()

int Vect_open_new ( struct Map_info Map,
const char *  name,
int  with_z 
)

Create new vector map for reading/writing.

By default list of updated features is not maintained, see Vect_set_updated() for details.

By default map format is native (GV_FORMAT_NATIVE). If OGR file is found in the current mapset then the map (ie. OGR layer) is created in given OGR datasource (GV_FORMAT_OGR). Similarly if PG file exists then the map (ie. PostGIS table) is created using PostGIS interface (GV_FORMAT_POSTGIS). The format of map is stored in Map->format.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to be created
with_zWITH_Z for 3D vector data otherwise WITHOUT_Z
Returns
1 on success
-1 on error

Definition at line 921 of file vector/Vlib/open.c.

References G_debug(), and getenv().

Referenced by Vect_close().

◆ Vect_open_old()

int Vect_open_old ( struct Map_info Map,
const char *  name,
const char *  mapset 
)

Open existing vector map for reading.

This function is replaced by Vect_open_old2() to handle also direct OGR support.

Calls G_fatal_error() on failure.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to open
mapsetmapset name ("" for search path)
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 573 of file vector/Vlib/open.c.

References FALSE, NULL, and Vect__open_old().

◆ Vect_open_old2()

int Vect_open_old2 ( struct Map_info Map,
const char *  name,
const char *  mapset,
const char *  layer 
)

Open existing vector map for reading.

Calls G_fatal_error() on failure.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to open (datasource for direct OGR access)
mapsetmapset name ("" for search path, "OGR" for direct OGR access)
layerlayer name (OGR layer for direct OGR access)
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 615 of file vector/Vlib/open.c.

References FALSE, and Vect__open_old().

◆ Vect_open_old_head()

int Vect_open_old_head ( struct Map_info Map,
const char *  name,
const char *  mapset 
)

Reads only info about vector map (headers)

Reads from headers of 'head', 'dbln', 'topo' and 'cidx' file.

This function is replaced by Vect_open_old_head2() to handle also direct OGR support.

Calls G_fatal_error() on failure.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to read
mapsetmapset name ("" for search path)
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 711 of file vector/Vlib/open.c.

References FALSE, NULL, TRUE, and Vect__open_old().

◆ Vect_open_old_head2()

int Vect_open_old_head2 ( struct Map_info Map,
const char *  name,
const char *  mapset,
const char *  layer 
)

Reads only info about vector map (headers)

Reads from headers of 'head', 'dbln', 'topo' and 'cidx' file.

Calls G_fatal_error() on failure.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to read (dsn for OGR)
mapsetmapset name ("" for search path)
layerlayer name (OGR format)
[out]Mappointer to Map_info structure
namename of vector map to open (datasource for direct OGR access)
mapsetmapset name ("" for search path, "OGR" for direct OGR access)
layerlayer name (OGR layer for direct OGR access)
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 737 of file vector/Vlib/open.c.

References FALSE, TRUE, and Vect__open_old().

◆ Vect_open_sidx()

int Vect_open_sidx ( struct Map_info Map,
int  mode 
)

Open spatial index file ('sidx')

Parameters
[in,out]Mappointer to Map_info
mode0 old, 1 update, 2 new
Returns
1 if sidx file is not available
0 on success
-1 on error

Definition at line 1176 of file vector/Vlib/open.c.

Referenced by Vect_build_partial().

◆ Vect_open_tmp_new()

int Vect_open_tmp_new ( struct Map_info Map,
const char *  name,
int  with_z 
)

Create new temporary vector map.

Temporary vector maps are stored in the current mapset (directory .tmp/<hostname>/vector). If the map already exists, it is overwritten.

Temporary vector maps are automatically deleted when closing the map (see Vect_close() for details).

If name is not given (is NULL), then the name is determined by process id (tmp_<pid>).

Parameters
[out]Mappointer to output Map_info struct
namename for new vector map (or NULL)
with_zWITH_Z for 3D vector data otherwise WITHOUT_Z
Returns
1 on success
-1 on error

Definition at line 951 of file vector/Vlib/open.c.

References G_debug(), and GNAME_MAX.

◆ Vect_open_tmp_old()

int Vect_open_tmp_old ( struct Map_info Map,
const char *  name,
const char *  mapset 
)

Open existing temporary vector map for reading.

Temporary vector maps are stored in the current mapset (directory .tmp/<hostname>/vector).

Calls G_fatal_error() on failure.

Todo:
Create new vector map if doesn't exist.
Parameters
[out]Mappointer to Map_info structure
namename of vector map to open
mapsetmapset name ("" for search path)
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 596 of file vector/Vlib/open.c.

References FALSE, NULL, TRUE, and Vect__open_old().

◆ Vect_open_tmp_update()

int Vect_open_tmp_update ( struct Map_info Map,
const char *  name,
const char *  mapset 
)

Open existing temporary vector map for reading/writing.

Temporary vector maps are stored in the current mapset (directory .tmp/<hostname>/vector).

By default list of updated features is not maintained, see Vect_set_updated() for details.

Calls G_fatal_error() on failure.

Todo:
Create new vector map if doesn't exist.
Parameters
[out]Mappointer to Map_info structure
namename of vector map to update
mapsetmapset name
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 666 of file vector/Vlib/open.c.

References FALSE, NULL, TRUE, and Vect__open_old().

◆ Vect_open_topo()

int Vect_open_topo ( struct Map_info Map,
int  head_only 
)

Open topology file ('topo')

Parameters
[in,out]Mappointer to Map_info structure
head_onlyTRUE to read only header
Returns
0 on success
1 file does not exist
-1 on error

Definition at line 1096 of file vector/Vlib/open.c.

References _, Plus_head::coor_mtime, Plus_head::coor_size, dig_file_init(), dig_load_plus(), dig_Rd_Plus_head(), err(), gvfile::file, G_debug(), G_fopen_old(), G_warning(), GPATH_MAX, GV_TOPO_ELEMENT, Map_info::mapset, Map_info::name, NULL, Map_info::plus, Coor_info::size, Vect__get_element_path(), Vect__get_path(), and Vect_coor_info().

◆ Vect_open_update()

int Vect_open_update ( struct Map_info Map,
const char *  name,
const char *  mapset 
)

Open existing vector map for reading/writing.

This function is replaced by Vect_open_update2() to handle also direct OGR support.

By default list of updated features is not maintained, see Vect_set_updated() for details.

Calls G_fatal_error() on failure.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to update
mapsetmapset name
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 640 of file vector/Vlib/open.c.

References FALSE, NULL, TRUE, and Vect__open_old().

◆ Vect_open_update2()

int Vect_open_update2 ( struct Map_info Map,
const char *  name,
const char *  mapset,
const char *  layer 
)

Open existing vector map for reading/writing.

By default list of updated features is not maintained, see Vect_set_updated() for details.

Calls G_fatal_error() on failure.

Parameters
[out]Mappointer to Map_info structure
namename of vector map to open (datasource for direct OGR access)
mapsetmapset name ("" for search path, "OGR" for direct OGR access)
layerlayer name (OGR layer for direct OGR access)
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 688 of file vector/Vlib/open.c.

References FALSE, TRUE, and Vect__open_old().

◆ Vect_open_update_head()

int Vect_open_update_head ( struct Map_info Map,
const char *  name,
const char *  mapset 
)

Open header file of existing vector map for updating (mostly for database link updates)

Parameters
[out]Mappointer to Map_info structure
namename of vector map to update
mapsetmapset name
Returns
1 open on level 1 (without topology)
2 open on level 2 (with topology)
-1 on error

Definition at line 754 of file vector/Vlib/open.c.

References FALSE, NULL, TRUE, and Vect__open_old().

◆ Vect_set_open_level()

int Vect_set_open_level ( int  level)

Predetermine level at which a vector map will be opened for reading.

If it can't open that level, the open will fail. The specified level must be set before any call to open. The default is to try to open the highest level possible, and keep stepping down until success.

NOTE: This should only be used to set when you wish to force a lower level open. If you require a higher level, then just check the return to verify the level instead of forcing it. This is because future releases will have higher levels which will be downward compatible and which your programs should support by default.

Parameters
levelvector access level
Returns
0 on success
1 on error (invalid access level)

Definition at line 134 of file vector/Vlib/open.c.