= Background = Sometimes you may experience a bug in PostGIS and/or any of its dependent libraries which causes a crash when you try and execute a query. If this happens, chances are you will be asked to submit a backtrace to the mailing list. A backtrace gives an indication of the state of a program when it crashes, and is hence very useful for developers. = Prerequisites = This tutorial assumes that you are running a POSIX-based operating system such as Linux, Solaris, MacOS etc. If you are running Windows then you can obtain a similar result once you have installed the required MingW components (you can download precompiled gdb 7.0 for MingW from [http://sourceforge.net/projects/mingw/files/GNU%20Source-Level] and then extract contents into your c:\mingw folder ). You will need to make sure that gdb (GNU debugger) has been installed on your system; to verify this, simply type "gdb -v" and check the output. If gdb is installed, you'll see something like this: {{{ GNU gdb 6.8-debian Copyright (C) 2008 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "x86_64-linux-gnu". }}} = Getting the backtrace = In order to obtain the backtrace, you'll need two terminal windows open. One to launch psql and connect to your PostGIS-enabled database as normal, and one to control the debugger. From here, the process to obtain a backtrace looks like this: * call a PostGIS C library function to ensure that PostGIS is loaded in the PostgreSQL backend * find out the process number (pid) of the PostgreSQL backend you are connected to * connect the debugger to the PostgreSQL backend * execute your crashing query * obtain the backtrace === Window 1 - Launching PostgreSQL === {{{ pg83@zeno:~/rel-8.3.7/lib/postgresql$ psql -d postgis Welcome to psql 8.3.7, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help with psql commands \g or terminate with semicolon to execute query \q to quit postgis=# select postgis_full_version(), pg_backend_pid(); postgis_full_version | pg_backend_pid ----------------------------------------------------------------------------------------+---------------- POSTGIS="1.4.0SVN" GEOS="3.2.0-CAPI-1.6.0" PROJ="Rel. 4.6.1, 21 August 2008" USE_STATS | 29736 (1 row) }}} Once you are connected to your database, you need to connect the debugger to the process listed above as pg_backend_pid by passing a "-p" parameter into gdb like this: === Window 2 - Connecting the debugger to PostgreSQL/PostGIS === {{{ pg83@zeno:~/src/postgis-svn/trunk$ gdb -p 29736 GNU gdb 6.8-debian Copyright (C) 2008 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "x86_64-linux-gnu". Attaching to process 29736 Reading symbols from /home/pg83/rel-8.3.7/bin/postgres...done. Reading symbols from /lib/libcrypt.so.1...done. Loaded symbols for /lib/libcrypt.so.1 Reading symbols from /lib/libdl.so.2...done. Loaded symbols for /lib/libdl.so.2 Reading symbols from /lib/libm.so.6...done. Loaded symbols for /lib/libm.so.6 Reading symbols from /lib/libc.so.6...done. Loaded symbols for /lib/libc.so.6 Reading symbols from /lib/ld-linux-x86-64.so.2...done. Loaded symbols for /lib64/ld-linux-x86-64.so.2 Reading symbols from /lib/libnss_files.so.2...done. Loaded symbols for /lib/libnss_files.so.2 Reading symbols from /home/pg83/rel-8.3.7/lib/postgresql/plpgsql.so...done. Loaded symbols for /home/pg83/rel-8.3.7/lib/postgresql/plpgsql.so Reading symbols from /home/pg83/rel-8.3.7/lib/postgresql/postgis-1.4.so...done. Loaded symbols for /home/pg83/rel-8.3.7/lib/postgresql/postgis-1.4.so Reading symbols from /home/pg83/rel-8.3.7/lib/libgeos_c.so.1...done. Loaded symbols for /home/pg83/rel-8.3.7/lib/libgeos_c.so.1 Reading symbols from /usr/local/lib/libproj.so.0...done. Loaded symbols for /usr/local/lib/libproj.so.0 Reading symbols from /home/pg83/rel-8.3.7/lib/libgeos-3.2.0.so...done. Loaded symbols for /home/pg83/rel/lib/libgeos-3.2.0.so Reading symbols from /usr/lib/libstdc++.so.6...done. Loaded symbols for /usr/lib/libstdc++.so.6 Reading symbols from /lib/libgcc_s.so.1...done. Loaded symbols for /lib/libgcc_s.so.1 0x00007f585979b305 in recv () from /lib/libc.so.6 (gdb) }}} Initially, gdb will pause the PostgreSQL/PostGIS process when it connects. To unpause the process, type "cont" and hit enter: {{{ (gdb) cont Continuing. }}} === Window 1 - Execute your crashing query === {{{ postgis=# select postgis_crash(); }}} When the crash occurs, this window will pause. You can then use gdb to obtain the backtrace using the "bt" command like this: === Window 2 - Obtain the backtrace === {{{ Program received signal SIGSEGV, Segmentation fault. 0x00007f5859747ec1 in memcpy () from /lib/libc.so.6 (gdb) bt #0 0x00007f5859747ec1 in memcpy () from /lib/libc.so.6 #1 0x00007f5857321621 in postgis_crash (fcinfo=0x7fff622f5f70) at lwgeom_functions_basic.c:114 #2 0x000000000058a7a9 in ExecMakeFunctionResult (fcache=0xc51310, econtext=0xc511e0, isNull=0xc518c0 "\177~\177\177\177\177\177\177\220��", isDone=0xc51978) at execQual.c:1351 #3 0x000000000058b0a4 in ExecEvalFunc (fcache=0xc51310, econtext=0xc511e0, isNull=0xc518c0 "\177~\177\177\177\177\177\177\220��", isDone=0xc51978) at execQual.c:1753 #4 0x0000000000591a72 in ExecTargetList (targetlist=0xc51750, econtext=0xc511e0, values=0xc518a0, isnull=0xc518c0 "\177~\177\177\177\177\177\177\220��", itemIsDone=0xc51978, isDone=0x7fff622f6494) at execQual.c:4610 #5 0x0000000000591f3a in ExecProject (projInfo=0xc518e0, isDone=0x7fff622f6494) at execQual.c:4811 #6 0x00000000005a200a in ExecResult (node=0xc510c8) at nodeResult.c:155 #7 0x0000000000587bc1 in ExecProcNode (node=0xc510c8) at execProcnode.c:319 #8 0x00000000005853af in ExecutePlan (estate=0xc50e98, planstate=0xc510c8, operation=CMD_SELECT, numberTuples=0, direction=ForwardScanDirection, dest=0xc07008) at execMain.c:1335 #9 0x0000000000583796 in ExecutorRun (queryDesc=0xbe9150, direction=ForwardScanDirection, count=0) at execMain.c:270 #10 0x000000000066022d in PortalRunSelect (portal=0xc08ba8, forward=1 '\001', count=0, dest=0xc07008) at pquery.c:943 #11 0x000000000065fe7d in PortalRun (portal=0xc08ba8, count=9223372036854775807, isTopLevel=1 '\001', dest=0xc07008, altdest=0xc07008, completionTag=0x7fff622f6890 "") at pquery.c:769 #12 0x000000000065a32e in exec_simple_query (query_string=0xbcb078 "select postgis_crash();") at postgres.c:1004 #13 0x000000000065e232 in PostgresMain (argc=4, argv=0xb360c0, username=0xb36080 "pg83") at postgres.c:3631 #14 0x000000000061f9f2 in BackendRun (port=0xb4bce0) at postmaster.c:3207 #15 0x000000000061efc2 in BackendStartup (port=0xb4bce0) at postmaster.c:2830 #16 0x000000000061cb35 in ServerLoop () at postmaster.c:1274 #17 0x000000000061c570 in PostmasterMain (argc=3, argv=0xb33310) at postmaster.c:1029 #18 0x00000000005b61ba in main (argc=3, argv=0xb33310) at main.c:188 (gdb) }}} = Conclusion = The output from the "bt" command contains the information required by the PostGIS developers to determine the cause of the crash, so cut and paste this text unaltered into an email and send it to either the developer who requested the backtrace or the -users mailinglist if it isn't too large.