Update FAQ_DEV.

2 files changed, 710 insertions, 693 deletions

diff --git a/doc/FAQ_DEV b/doc/FAQ_DEV
index d5faef76a0c..073a3917a1d 100644
--- a/doc/FAQ_DEV
+++ b/doc/FAQ_DEV
@@ -9,31 +9,146 @@
    postgreSQL Web site, http://www.PostgreSQL.org.
      _________________________________________________________________
    
-                                 Questions
+                             General Questions
                                       
-   1) What tools are available for developers?
-   2) What books are good for developers?
-   3) Why do we use palloc() and pfree() to allocate memory?
-   4) Why do we use Node and List to make data structures?
-   5) How do I add a feature or fix a bug?
-   6) How do I download/update the current source tree?
-   7) How do I test my changes?
-   7) I just added a field to a structure. What else should I do?
-   8) Why are table, column, type, function, view names sometimes
+   1.1) How do I get involved in PostgreSQL development?
+   1.2) How do I add a feature or fix a bug?
+   1.3) How do I download/update the current source tree?
+   1.4) How do I test my changes?
+   1.5) What tools are available for developers?
+   1.6) What books are good for developers?
+   1.7) What is configure all about?
+   1.8) How do I add a new port?
+   1.9) Why don't we use threads in the backend?
+   1.10) How are RPM's packaged?
+   1.11) How are CVS branches handled?
+   
+Technical Questions
+
+   2.1) How do I efficiently access information in tables from the
+   backend code?
+   2.2) Why are table, column, type, function, view names sometimes
    referenced as Name or NameData, and sometimes as char *?
-   9) How do I efficiently access information in tables from the backend
-   code?
-   10) What is elog()?
-   11) What is configure all about?
-   12) How do I add a new port?
-   13) What is CommandCounterIncrement()?
-   14) Why don't we use threads in the backend?
-   15) How are RPM's packaged?
-   16) How are CVS branches handled?
-   17) How do I get involved in PostgreSQL development?
+   2.3) Why do we use Node and List to make data structures?
+   2.4) I just added a field to a structure. What else should I do?
+   2.5) Why do we use palloc() and pfree() to allocate memory?
+   2.6) What is elog()?
+   2.7) What is CommandCounterIncrement()?
      _________________________________________________________________
    
-  1) What tools are available for developers?
+                             General Questions
+                                      
+  1.1) How go I get involved in PostgreSQL development?
+  
+   This was written by Lamar Owen:
+   
+   2001-06-22
+   What open source development process is used by the PostgreSQL team?
+   
+   Read HACKERS for six months (or a full release cycle, whichever is
+   longer). Really. HACKERS _is_the process. The process is not well
+   documented (AFAIK -- it may be somewhere that I am not aware of) --
+   and it changes continually.
+   What development environment (OS, system, compilers, etc) is required
+   to develop code?
+   
+   Developers Corner on the website has links to this information. The
+   distribution tarball itself includes all the extra tools and documents
+   that go beyond a good Unix-like development environment. In general, a
+   modern unix with a modern gcc, GNU make or equivalent, autoconf (of a
+   particular version), and good working knowledge of those tools are
+   required.
+   What areas need support?
+   
+   The TODO list.
+   
+   You've made the first step, by finding and subscribing to HACKERS.
+   Once you find an area to look at in the TODO, and have read the
+   documentation on the internals, etc, then you check out a current
+   CVS,write what you are going to write (keeping your CVS checkout up to
+   date in the process), and make up a patch (as a context diff only) and
+   send to the PATCHES list, prefereably.
+   
+   Discussion on the patch typically happens here. If the patch adds a
+   major feature, it would be a good idea to talk about it first on the
+   HACKERS list, in order to increase the chances of it being accepted,
+   as well as toavoid duplication of effort. Note that experienced
+   developers with a proven track record usually get the big jobs -- for
+   more than one reason. Also note that PostgreSQL is highly portable --
+   nonportable code will likely be dismissed out of hand.
+   
+   Once your contributions get accepted, things move from there.
+   Typically, you would be added as a developer on the list on the
+   website when one of the other developers recommends it. Membership on
+   the steering committee is by invitation only, by the other steering
+   committee members, from what I have gathered watching froma distance.
+   
+   I make these statements from having watched the process for over two
+   years.
+   
+   To see a good example of how one goes about this, search the archives
+   for the name 'Tom Lane' and see what his first post consisted of, and
+   where he took things. In particular, note that this hasn't been _that_
+   long ago -- and his bugfixing and general deep knowledge with this
+   codebase is legendary. Take a few days to read after him. And pay
+   special attention to both the sheer quantity as well as the
+   painstaking quality of his work. Both are in high demand.
+   
+  1.2) How do I add a feature or fix a bug?
+  
+   The source code is over 250,000 lines. Many problems/features are
+   isolated to one specific area of the code. Others require knowledge of
+   much of the source. If you are confused about where to start, ask the
+   hackers list, and they will be glad to assess the complexity and give
+   pointers on where to start.
+   
+   Another thing to keep in mind is that many fixes and features can be
+   added with surprisingly little code. I often start by adding code,
+   then looking at other areas in the code where similar things are done,
+   and by the time I am finished, the patch is quite small and compact.
+   
+   When adding code, keep in mind that it should use the existing
+   facilities in the source, for performance reasons and for simplicity.
+   Often a review of existing code doing similar things is helpful.
+   
+  1.3) How do I download/update the current source tree?
+  
+   There are several ways to obtain the source tree. Occasional
+   developers can just get the most recent source tree snapshot from
+   ftp.postgresql.org. For regular developers, you can use CVS. CVS
+   allows you to download the source tree, then occasionally update your
+   copy of the source tree with any new changes. Using CVS, you don't
+   have to download the entire source each time, only the changed files.
+   Anonymous CVS does not allows developers to update the remote source
+   tree, though privileged developers can do this. There is a CVS FAQ on
+   our web site that describes how to use remote CVS. You can also use
+   CVSup, which has similarly functionality, and is available from
+   ftp.postgresql.org.
+   
+   To update the source tree, there are two ways. You can generate a
+   patch against your current source tree, perhaps using the make_diff
+   tools mentioned above, and send them to the patches list. They will be
+   reviewed, and applied in a timely manner. If the patch is major, and
+   we are in beta testing, the developers may wait for the final release
+   before applying your patches.
+   
+   For hard-core developers, Marc(scrappy@postgresql.org) will give you a
+   Unix shell account on postgresql.org, so you can use CVS to update the
+   main source tree, or you can ftp your files into your account, patch,
+   and cvs install the changes directly into the source tree.
+   
+  1.4) How do I test my changes?
+  
+   First, use psql to make sure it is working as you expect. Then run
+   src/test/regress and get the output of src/test/regress/checkresults
+   with and without your changes, to see that your patch does not change
+   the regression test in unexpected ways. This practice has saved me
+   many times. The regression tests test the code in ways I would never
+   do, and has caught many bugs in my patches. By finding the problems
+   now, you save yourself a lot of debugging later when things are
+   broken, and you can't figure out when it happened.
+   
+  1.5) What tools are available for developers?
   
    Aside from the User documentation mentioned in the regular FAQ, there
    are several development tools available. First, all the files in the
@@ -141,7 +256,7 @@
    is also a script called unused_oids in pgsql/src/include/catalog that
    shows the unused oids.
    
-  2) What books are good for developers?
+  1.6) What books are good for developers?
   
    I have four good books, An Introduction to Database Systems, by C.J.
    Date, Addison, Wesley, A Guide to the SQL Standard, by C.J. Date, et.
@@ -151,239 +266,7 @@
    There is also a database performance site, with a handbook on-line
    written by Jim Gray at http://www.benchmarkresources.com.
    
-  3) Why do we use palloc() and pfree() to allocate memory?
-  
-   palloc() and pfree() are used in place of malloc() and free() because
-   we automatically free all memory allocated when a transaction
-   completes. This makes it easier to make sure we free memory that gets
-   allocated in one place, but only freed much later. There are several
-   contexts that memory can be allocated in, and this controls when the
-   allocated memory is automatically freed by the backend.
-   
-  4) Why do we use Node and List to make data structures?
-  
-   We do this because this allows a consistent way to pass data inside
-   the backend in a flexible way. Every node has a NodeTag which
-   specifies what type of data is inside the Node. Lists are groups of
-   Nodes chained together as a forward-linked list.
-   
-   Here are some of the List manipulation commands:
-   
-   lfirst(i)
-          return the data at list element i.
-          
-   lnext(i)
-          return the next list element after i.
-          
-   foreach(i, list)
-          loop through list, assigning each list element to i. It is
-          important to note that i is a List *, not the data in the List
-          element. You need to use lfirst(i) to get at the data. Here is
-          a typical code snipped that loops through a List containing Var
-          *'s and processes each one:
-          
-List *i, *list;
-
-    foreach(i, list)
-    {
-        Var *var = lfirst(i);
-
-        /* process var here */
-    }
-
-   lcons(node, list)
-          add node to the front of list, or create a new list with node
-          if list is NIL.
-          
-   lappend(list, node)
-          add node to the end of list. This is more expensive that lcons.
-          
-   nconc(list1, list2)
-          Concat list2 on to the end of list1.
-          
-   length(list)
-          return the length of the list.
-          
-   nth(i, list)
-          return the i'th element in list.
-          
-   lconsi, ...
-          There are integer versions of these: lconsi, lappendi, nthi.
-          List's containing integers instead of Node pointers are used to
-          hold list of relation object id's and other integer quantities.
-          
-   You can print nodes easily inside gdb. First, to disable output
-   truncation when you use the gdb print command:
-(gdb) set print elements 0
-
-   Instead of printing values in gdb format, you can use the next two
-   commands to print out List, Node, and structure contents in a verbose
-   format that is easier to understand. List's are unrolled into nodes,
-   and nodes are printed in detail. The first prints in a short format,
-   and the second in a long format:
-(gdb) call print(any_pointer)
-    (gdb) call pprint(any_pointer)
-
-   The output appears in the postmaster log file, or on your screen if
-   you are running a backend directly without a postmaster.
-   
-  5) How do I add a feature or fix a bug?
-  
-   The source code is over 250,000 lines. Many problems/features are
-   isolated to one specific area of the code. Others require knowledge of
-   much of the source. If you are confused about where to start, ask the
-   hackers list, and they will be glad to assess the complexity and give
-   pointers on where to start.
-   
-   Another thing to keep in mind is that many fixes and features can be
-   added with surprisingly little code. I often start by adding code,
-   then looking at other areas in the code where similar things are done,
-   and by the time I am finished, the patch is quite small and compact.
-   
-   When adding code, keep in mind that it should use the existing
-   facilities in the source, for performance reasons and for simplicity.
-   Often a review of existing code doing similar things is helpful.
-   
-  6) How do I download/update the current source tree?
-  
-   There are several ways to obtain the source tree. Occasional
-   developers can just get the most recent source tree snapshot from
-   ftp.postgresql.org. For regular developers, you can use CVS. CVS
-   allows you to download the source tree, then occasionally update your
-   copy of the source tree with any new changes. Using CVS, you don't
-   have to download the entire source each time, only the changed files.
-   Anonymous CVS does not allows developers to update the remote source
-   tree, though privileged developers can do this. There is a CVS FAQ on
-   our web site that describes how to use remote CVS. You can also use
-   CVSup, which has similarly functionality, and is available from
-   ftp.postgresql.org.
-   
-   To update the source tree, there are two ways. You can generate a
-   patch against your current source tree, perhaps using the make_diff
-   tools mentioned above, and send them to the patches list. They will be
-   reviewed, and applied in a timely manner. If the patch is major, and
-   we are in beta testing, the developers may wait for the final release
-   before applying your patches.
-   
-   For hard-core developers, Marc(scrappy@postgresql.org) will give you a
-   Unix shell account on postgresql.org, so you can use CVS to update the
-   main source tree, or you can ftp your files into your account, patch,
-   and cvs install the changes directly into the source tree.
-   
-  6) How do I test my changes?
-  
-   First, use psql to make sure it is working as you expect. Then run
-   src/test/regress and get the output of src/test/regress/checkresults
-   with and without your changes, to see that your patch does not change
-   the regression test in unexpected ways. This practice has saved me
-   many times. The regression tests test the code in ways I would never
-   do, and has caught many bugs in my patches. By finding the problems
-   now, you save yourself a lot of debugging later when things are
-   broken, and you can't figure out when it happened.
-   
-  7) I just added a field to a structure. What else should I do?
-  
-   The structures passing around from the parser, rewrite, optimizer, and
-   executor require quite a bit of support. Most structures have support
-   routines in src/backend/nodes used to create, copy, read, and output
-   those structures. Make sure you add support for your new field to
-   these files. Find any other places the structure may need code for
-   your new field. mkid is helpful with this (see above).
-   
-  8) Why are table, column, type, function, view names sometimes referenced as
-  Name or NameData, and sometimes as char *?
-  
-   Table, column, type, function, and view names are stored in system
-   tables in columns of type Name. Name is a fixed-length,
-   null-terminated type of NAMEDATALEN bytes. (The default value for
-   NAMEDATALEN is 32 bytes.)
-typedef struct nameData
-    {
-        char        data[NAMEDATALEN];
-    } NameData;
-    typedef NameData *Name;
-
-   Table, column, type, function, and view names that come into the
-   backend via user queries are stored as variable-length,
-   null-terminated character strings.
-   
-   Many functions are called with both types of names, ie. heap_open().
-   Because the Name type is null-terminated, it is safe to pass it to a
-   function expecting a char *. Because there are many cases where
-   on-disk names(Name) are compared to user-supplied names(char *), there
-   are many cases where Name and char * are used interchangeably.
-   
-  9) How do I efficiently access information in tables from the backend code?
-  
-   You first need to find the tuples(rows) you are interested in. There
-   are two ways. First, SearchSysCache() and related functions allow you
-   to query the system catalogs. This is the preferred way to access
-   system tables, because the first call to the cache loads the needed
-   rows, and future requests can return the results without accessing the
-   base table. The caches use system table indexes to look up tuples. A
-   list of available caches is located in
-   src/backend/utils/cache/syscache.c.
-   src/backend/utils/cache/lsyscache.c contains many column-specific
-   cache lookup functions.
-   
-   The rows returned are cache-owned versions of the heap rows.
-   Therefore, you must not modify or delete the tuple returned by
-   SearchSysCache(). What you should do is release it with
-   ReleaseSysCache() when you are done using it; this informs the cache
-   that it can discard that tuple if necessary. If you neglect to call
-   ReleaseSysCache(), then the cache entry will remain locked in the
-   cache until end of transaction, which is tolerable but not very
-   desirable.
-   
-   If you can't use the system cache, you will need to retrieve the data
-   directly from the heap table, using the buffer cache that is shared by
-   all backends. The backend automatically takes care of loading the rows
-   into the buffer cache.
-   
-   Open the table with heap_open(). You can then start a table scan with
-   heap_beginscan(), then use heap_getnext() and continue as long as
-   HeapTupleIsValid() returns true. Then do a heap_endscan(). Keys can be
-   assigned to the scan. No indexes are used, so all rows are going to be
-   compared to the keys, and only the valid rows returned.
-   
-   You can also use heap_fetch() to fetch rows by block number/offset.
-   While scans automatically lock/unlock rows from the buffer cache, with
-   heap_fetch(), you must pass a Buffer pointer, and ReleaseBuffer() it
-   when completed.
-   
-   Once you have the row, you can get data that is common to all tuples,
-   like t_self and t_oid, by merely accessing the HeapTuple structure
-   entries. If you need a table-specific column, you should take the
-   HeapTuple pointer, and use the GETSTRUCT() macro to access the
-   table-specific start of the tuple. You then cast the pointer as a
-   Form_pg_proc pointer if you are accessing the pg_proc table, or
-   Form_pg_type if you are accessing pg_type. You can then access the
-   columns by using a structure pointer:
-((Form_pg_class) GETSTRUCT(tuple))->relnatts
-
-   You must not directly change live tuples in this way. The best way is
-   to use heap_modifytuple() and pass it your original tuple, and the
-   values you want changed. It returns a palloc'ed tuple, which you pass
-   to heap_replace(). You can delete tuples by passing the tuple's t_self
-   to heap_destroy(). You use t_self for heap_update() too. Remember,
-   tuples can be either system cache copies, which may go away after you
-   call ReleaseSysCache(), or read directly from disk buffers, which go
-   away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
-   heap_fetch() case. Or it may be a palloc'ed tuple, that you must
-   pfree() when finished.
-   
-  10) What is elog()?
-  
-   elog() is used to send messages to the front-end, and optionally
-   terminate the current query being processed. The first parameter is an
-   elog level of NOTICE, DEBUG, ERROR, or FATAL. NOTICE prints on the
-   user's terminal and the postmaster logs. DEBUG prints only in the
-   postmaster logs. ERROR prints in both places, and terminates the
-   current query, never returning from the call. FATAL terminates the
-   backend process. The remaining parameters of elog are a printf-style
-   set of parameters to print.
-   
-  11) What is configure all about?
+  1.7) What is configure all about?
   
    The files configure and configure.in are part of the GNU autoconf
    package. Configure allows us to test for various capabilities of the
@@ -405,7 +288,7 @@ typedef struct nameData
    removed, so you see only the file contained in the source
    distribution.
    
-  12) How do I add a new port?
+  1.8) How do I add a new port?
   
    There are a variety of places that need to be modified to add a new
    port. First, start in the src/template directory. Add an appropriate
@@ -422,19 +305,7 @@ typedef struct nameData
    src/makefiles directory for port-specific Makefile handling. There is
    a backend/port directory if you need special files for your OS.
    
-  13) What is CommandCounterIncrement()?
-  
-   Normally, transactions can not see the rows they modify. This allows
-   UPDATE foo SET x = x + 1 to work correctly.
-   
-   However, there are cases where a transactions needs to see rows
-   affected in previous parts of the transaction. This is accomplished
-   using a Command Counter. Incrementing the counter allows transactions
-   to be broken into pieces so each piece can see rows modified by
-   previous pieces. CommandCounterIncrement() increments the Command
-   Counter, creating a new part of the transaction.
-   
-  14) Why don't we use threads in the backend?
+  1.9) Why don't we use threads in the backend?
   
    There are several reasons threads are not used:
      * Historically, threads were unsupported and buggy.
@@ -443,7 +314,7 @@ typedef struct nameData
        remaining backend startup time.
      * The backend code would be more complex.
        
-  15) How are RPM's packaged?
+  1.10) How are RPM's packaged?
   
    This was written by Lamar Owen:
    
@@ -538,7 +409,7 @@ typedef struct nameData
    Of course, there are many projects that DO include all the files
    necessary to build RPMs from their Official Tarball (TM).
    
-  16) How are CVS branches managed?
+  1.11) How are CVS branches managed?
   
    This was written by Tom Lane:
    
@@ -597,58 +468,194 @@ typedef struct nameData
    tree right away after a major release --- we wait for a dot-release or
    two, so that we won't have to double-patch the first wave of fixes.
    
-  17) How go I get involved in PostgreSQL development?
+                            Technical Questions
+                                      
+  2.1) How do I efficiently access information in tables from the backend code?
   
-   This was written by Lamar Owen:
+   You first need to find the tuples(rows) you are interested in. There
+   are two ways. First, SearchSysCache() and related functions allow you
+   to query the system catalogs. This is the preferred way to access
+   system tables, because the first call to the cache loads the needed
+   rows, and future requests can return the results without accessing the
+   base table. The caches use system table indexes to look up tuples. A
+   list of available caches is located in
+   src/backend/utils/cache/syscache.c.
+   src/backend/utils/cache/lsyscache.c contains many column-specific
+   cache lookup functions.
    
-   2001-06-22
-   What open source development process is used by the PostgreSQL team?
+   The rows returned are cache-owned versions of the heap rows.
+   Therefore, you must not modify or delete the tuple returned by
+   SearchSysCache(). What you should do is release it with
+   ReleaseSysCache() when you are done using it; this informs the cache
+   that it can discard that tuple if necessary. If you neglect to call
+   ReleaseSysCache(), then the cache entry will remain locked in the
+   cache until end of transaction, which is tolerable but not very
+   desirable.
    
-   Read HACKERS for six months (or a full release cycle, whichever is
-   longer). Really. HACKERS _is_the process. The process is not well
-   documented (AFAIK -- it may be somewhere that I am not aware of) --
-   and it changes continually.
-   What development environment (OS, system, compilers, etc) is required
-   to develop code?
+   If you can't use the system cache, you will need to retrieve the data
+   directly from the heap table, using the buffer cache that is shared by
+   all backends. The backend automatically takes care of loading the rows
+   into the buffer cache.
    
-   Developers Corner on the website has links to this information. The
-   distribution tarball itself includes all the extra tools and documents
-   that go beyond a good Unix-like development environment. In general, a
-   modern unix with a modern gcc, GNU make or equivalent, autoconf (of a
-   particular version), and good working knowledge of those tools are
-   required.
-   What areas need support?
+   Open the table with heap_open(). You can then start a table scan with
+   heap_beginscan(), then use heap_getnext() and continue as long as
+   HeapTupleIsValid() returns true. Then do a heap_endscan(). Keys can be
+   assigned to the scan. No indexes are used, so all rows are going to be
+   compared to the keys, and only the valid rows returned.
    
-   The TODO list.
+   You can also use heap_fetch() to fetch rows by block number/offset.
+   While scans automatically lock/unlock rows from the buffer cache, with
+   heap_fetch(), you must pass a Buffer pointer, and ReleaseBuffer() it
+   when completed.
    
-   You've made the first step, by finding and subscribing to HACKERS.
-   Once you find an area to look at in the TODO, and have read the
-   documentation on the internals, etc, then you check out a current
-   CVS,write what you are going to write (keeping your CVS checkout up to
-   date in the process), and make up a patch (as a context diff only) and
-   send to the PATCHES list, prefereably.
+   Once you have the row, you can get data that is common to all tuples,
+   like t_self and t_oid, by merely accessing the HeapTuple structure
+   entries. If you need a table-specific column, you should take the
+   HeapTuple pointer, and use the GETSTRUCT() macro to access the
+   table-specific start of the tuple. You then cast the pointer as a
+   Form_pg_proc pointer if you are accessing the pg_proc table, or
+   Form_pg_type if you are accessing pg_type. You can then access the
+   columns by using a structure pointer:
+((Form_pg_class) GETSTRUCT(tuple))->relnatts
+
+   You must not directly change live tuples in this way. The best way is
+   to use heap_modifytuple() and pass it your original tuple, and the
+   values you want changed. It returns a palloc'ed tuple, which you pass
+   to heap_replace(). You can delete tuples by passing the tuple's t_self
+   to heap_destroy(). You use t_self for heap_update() too. Remember,
+   tuples can be either system cache copies, which may go away after you
+   call ReleaseSysCache(), or read directly from disk buffers, which go
+   away when you heap_getnext(), heap_endscan, or ReleaseBuffer(), in the
+   heap_fetch() case. Or it may be a palloc'ed tuple, that you must
+   pfree() when finished.
    
-   Discussion on the patch typically happens here. If the patch adds a
-   major feature, it would be a good idea to talk about it first on the
-   HACKERS list, in order to increase the chances of it being accepted,
-   as well as toavoid duplication of effort. Note that experienced
-   developers with a proven track record usually get the big jobs -- for
-   more than one reason. Also note that PostgreSQL is highly portable --
-   nonportable code will likely be dismissed out of hand.
+  2.2) Why are table, column, type, function, view names sometimes referenced
+  as Name or NameData, and sometimes as char *?
+  
+   Table, column, type, function, and view names are stored in system
+   tables in columns of type Name. Name is a fixed-length,
+   null-terminated type of NAMEDATALEN bytes. (The default value for
+   NAMEDATALEN is 32 bytes.)
+typedef struct nameData
+    {
+        char        data[NAMEDATALEN];
+    } NameData;
+    typedef NameData *Name;
+
+   Table, column, type, function, and view names that come into the
+   backend via user queries are stored as variable-length,
+   null-terminated character strings.
    
-   Once your contributions get accepted, things move from there.
-   Typically, you would be added as a developer on the list on the
-   website when one of the other developers recommends it. Membership on
-   the steering committee is by invitation only, by the other steering
-   committee members, from what I have gathered watching froma distance.
+   Many functions are called with both types of names, ie. heap_open().
+   Because the Name type is null-terminated, it is safe to pass it to a
+   function expecting a char *. Because there are many cases where
+   on-disk names(Name) are compared to user-supplied names(char *), there
+   are many cases where Name and char * are used interchangeably.
    
-   I make these statements from having watched the process for over two
-   years.
+  2.3) Why do we use Node and List to make data structures?
+  
+   We do this because this allows a consistent way to pass data inside
+   the backend in a flexible way. Every node has a NodeTag which
+   specifies what type of data is inside the Node. Lists are groups of
+   Nodes chained together as a forward-linked list.
    
-   To see a good example of how one goes about this, search the archives
-   for the name 'Tom Lane' and see what his first post consisted of, and
-   where he took things. In particular, note that this hasn't been _that_
-   long ago -- and his bugfixing and general deep knowledge with this
-   codebase is legendary. Take a few days to read after him. And pay
-   special attention to both the sheer quantity as well as the
-   painstaking quality of his work. Both are in high demand.
+   Here are some of the List manipulation commands:
+   
+   lfirst(i)
+          return the data at list element i.
+          
+   lnext(i)
+          return the next list element after i.
+          
+   foreach(i, list)
+          loop through list, assigning each list element to i. It is
+          important to note that i is a List *, not the data in the List
+          element. You need to use lfirst(i) to get at the data. Here is
+          a typical code snipped that loops through a List containing Var
+          *'s and processes each one:
+          
+List *i, *list;
+
+    foreach(i, list)
+    {
+        Var *var = lfirst(i);
+
+        /* process var here */
+    }
+
+   lcons(node, list)
+          add node to the front of list, or create a new list with node
+          if list is NIL.
+          
+   lappend(list, node)
+          add node to the end of list. This is more expensive that lcons.
+          
+   nconc(list1, list2)
+          Concat list2 on to the end of list1.
+          
+   length(list)
+          return the length of the list.
+          
+   nth(i, list)
+          return the i'th element in list.
+          
+   lconsi, ...
+          There are integer versions of these: lconsi, lappendi, nthi.
+          List's containing integers instead of Node pointers are used to
+          hold list of relation object id's and other integer quantities.
+          
+   You can print nodes easily inside gdb. First, to disable output
+   truncation when you use the gdb print command:
+(gdb) set print elements 0
+
+   Instead of printing values in gdb format, you can use the next two
+   commands to print out List, Node, and structure contents in a verbose
+   format that is easier to understand. List's are unrolled into nodes,
+   and nodes are printed in detail. The first prints in a short format,
+   and the second in a long format:
+(gdb) call print(any_pointer)
+    (gdb) call pprint(any_pointer)
+
+   The output appears in the postmaster log file, or on your screen if
+   you are running a backend directly without a postmaster.
+   
+  2.4) I just added a field to a structure. What else should I do?
+  
+   The structures passing around from the parser, rewrite, optimizer, and
+   executor require quite a bit of support. Most structures have support
+   routines in src/backend/nodes used to create, copy, read, and output
+   those structures. Make sure you add support for your new field to
+   these files. Find any other places the structure may need code for
+   your new field. mkid is helpful with this (see above).
+   
+  2.5) Why do we use palloc() and pfree() to allocate memory?
+  
+   palloc() and pfree() are used in place of malloc() and free() because
+   we automatically free all memory allocated when a transaction
+   completes. This makes it easier to make sure we free memory that gets
+   allocated in one place, but only freed much later. There are several
+   contexts that memory can be allocated in, and this controls when the
+   allocated memory is automatically freed by the backend.
+   
+  2.6) What is elog()?
+  
+   elog() is used to send messages to the front-end, and optionally
+   terminate the current query being processed. The first parameter is an
+   elog level of NOTICE, DEBUG, ERROR, or FATAL. NOTICE prints on the
+   user's terminal and the postmaster logs. DEBUG prints only in the
+   postmaster logs. ERROR prints in both places, and terminates the
+   current query, never returning from the call. FATAL terminates the
+   backend process. The remaining parameters of elog are a printf-style
+   set of parameters to print.
+   
+  2.7) What is CommandCounterIncrement()?
+  
+   Normally, transactions can not see the rows they modify. This allows
+   UPDATE foo SET x = x + 1 to work correctly.
+   
+   However, there are cases where a transactions needs to see rows
+   affected in previous parts of the transaction. This is accomplished
+   using a Command Counter. Incrementing the counter allows transactions
+   to be broken into pieces so each piece can see rows modified by
+   previous pieces. CommandCounterIncrement() increments the Command
+   Counter, creating a new part of the transaction.
diff --git a/doc/src/FAQ/FAQ_DEV.html b/doc/src/FAQ/FAQ_DEV.html
index 07f63e3a86a..2d00bdc5cad 100644
--- a/doc/src/FAQ/FAQ_DEV.html
+++ b/doc/src/FAQ/FAQ_DEV.html
@@ -27,39 +27,169 @@
      
 
     <CENTER>
-      <H2>Questions</H2>
+      <H2>General Questions</H2>
     </CENTER>
-    <A href="#1">1</A>) What tools are available for developers?<BR>
-     <A href="#2">2</A>) What books are good for developers?<BR>
-     <A href="#3">3</A>) Why do we use <I>palloc</I>() and
-    <I>pfree</I>() to allocate memory?<BR>
-     <A href="#4">4</A>) Why do we use <I>Node</I> and <I>List</I> to
-    make data structures?<BR>
-     <A href="#5">5</A>) How do I add a feature or fix a bug?<BR>
-     <A href="#6">6</A>) How do I download/update the current source
+     <A href="#1.1">1.1</A>) How do I get involved in PostgreSQL
+    development?<BR>
+     <A href="#1.2">1.2</A>) How do I add a feature or fix a bug?<BR>
+     <A href="#1.3">1.3</A>) How do I download/update the current source
     tree?<BR>
-     <A href="#7">7</A>) How do I test my changes?<BR>
-     <A href="#7">7</A>) I just added a field to a structure. What else
-    should I do?<BR>
-     <A href="#8">8</A>) Why are table, column, type, function, view
+     <A href="#1.4">1.4</A>) How do I test my changes?<BR>
+    <A href="#1.5">1.5</A>) What tools are available for developers?<BR>
+     <A href="#1.6">1.6</A>) What books are good for developers?<BR>
+     <A href="#1.7">1.7</A>) What is configure all about?<BR>
+     <A href="#1.8">1.8</A>) How do I add a new port?<BR>
+     <A href="#1.9">1.9</A>) Why don't we use threads in the backend?<BR>
+     <A href="#1.10">1.10</A>) How are RPM's packaged?<BR>
+     <A href="#1.11">1.11</A>) How are CVS branches handled?<BR>
+
+      <H2>Technical Questions</H2>
+     <A href="#2.1">2.1</A>) How do I efficiently access information in
+    tables from the backend code?<BR>
+     <A href="#2.2">2.2</A>) Why are table, column, type, function, view
     names sometimes referenced as <I>Name</I> or <I>NameData,</I> and
     sometimes as <I>char *?</I><BR>
-     <A href="#9">9</A>) How do I efficiently access information in
-    tables from the backend code?<BR>
-     <A href="#10">10</A>) What is elog()?<BR>
-     <A href="#11">11</A>) What is configure all about?<BR>
-     <A href="#12">12</A>) How do I add a new port?<BR>
-     <A href="#13">13</A>) What is CommandCounterIncrement()?<BR>
-     <A href="#14">14</A>) Why don't we use threads in the backend?<BR>
-     <A href="#15">15</A>) How are RPM's packaged?<BR>
-     <A href="#16">16</A>) How are CVS branches handled?<BR>
-     <A href="#17">17</A>) How do I get involved in PostgreSQL
-    development?<BR>
+     <A href="#2.3">2.3</A>) Why do we use <I>Node</I> and <I>List</I> to
+    make data structures?<BR>
+     <A href="#2.4">2.4</A>) I just added a field to a structure. What else
+    should I do?<BR>
+     <A href="#2.5">2.5</A>) Why do we use <I>palloc</I>() and
+    <I>pfree</I>() to allocate memory?<BR>
+     <A href="#2.6">2.6</A>) What is elog()?<BR>
+     <A href="#2.7">2.7</A>) What is CommandCounterIncrement()?<BR>
      <BR>
      
     <HR>
 
-    <H3><A name="1">1</A>) What tools are available for
+    <CENTER>
+      <H2>General Questions</H2>
+    </CENTER>
+
+    <H3><A name="1.1">1.1</A>) How go I get involved in PostgreSQL
+    development?</H3>
+
+    <P>This was written by Lamar Owen:</P>
+
+    <P>2001-06-22</P>
+
+    <B>What open source development process is used by the PostgreSQL
+    team?</B>
+
+    <P>Read HACKERS for six months (or a full release cycle, whichever
+    is longer). Really. HACKERS _is_the process. The process is not
+    well documented (AFAIK -- it may be somewhere that I am not aware
+    of) -- and it changes continually.</P>
+
+    <B>What development environment (OS, system, compilers, etc) is
+    required to develop code?</B>
+
+    <P><A href="developers.postgresql.org">Developers Corner</A> on the
+    website has links to this information. The distribution tarball
+    itself includes all the extra tools and documents that go beyond a
+    good Unix-like development environment. In general, a modern unix
+    with a modern gcc, GNU make or equivalent, autoconf (of a
+    particular version), and good working knowledge of those tools are
+    required.</P>
+
+    <B>What areas need support?</B>
+
+    <P>The TODO list.</P>
+
+    <P>You've made the first step, by finding and subscribing to
+    HACKERS. Once you find an area to look at in the TODO, and have
+    read the documentation on the internals, etc, then you check out a
+    current CVS,write what you are going to write (keeping your CVS
+    checkout up to date in the process), and make up a patch (as a
+    context diff only) and send to the PATCHES list, prefereably.</P>
+
+    <P>Discussion on the patch typically happens here. If the patch
+    adds a major feature, it would be a good idea to talk about it
+    first on the HACKERS list, in order to increase the chances of it
+    being accepted, as well as toavoid duplication of effort. Note that
+    experienced developers with a proven track record usually get the
+    big jobs -- for more than one reason. Also note that PostgreSQL is
+    highly portable -- nonportable code will likely be dismissed out of
+    hand.</P>
+
+    <P>Once your contributions get accepted, things move from there.
+    Typically, you would be added as a developer on the list on the
+    website when one of the other developers recommends it. Membership
+    on the steering committee is by invitation only, by the other
+    steering committee members, from what I have gathered watching
+    froma distance.</P>
+
+    <P>I make these statements from having watched the process for over
+    two years.</P>
+
+    <P>To see a good example of how one goes about this, search the
+    archives for the name 'Tom Lane' and see what his first post
+    consisted of, and where he took things. In particular, note that
+    this hasn't been _that_ long ago -- and his bugfixing and general
+    deep knowledge with this codebase is legendary. Take a few days to
+    read after him. And pay special attention to both the sheer
+    quantity as well as the painstaking quality of his work. Both are
+    in high demand.</P>
+
+    <H3><A name="1.2">1.2</A>) How do I add a feature or fix a bug?</H3>
+
+    <P>The source code is over 250,000 lines. Many problems/features
+    are isolated to one specific area of the code. Others require
+    knowledge of much of the source. If you are confused about where to
+    start, ask the hackers list, and they will be glad to assess the
+    complexity and give pointers on where to start.</P>
+
+    <P>Another thing to keep in mind is that many fixes and features
+    can be added with surprisingly little code. I often start by adding
+    code, then looking at other areas in the code where similar things
+    are done, and by the time I am finished, the patch is quite small
+    and compact.</P>
+
+    <P>When adding code, keep in mind that it should use the existing
+    facilities in the source, for performance reasons and for
+    simplicity. Often a review of existing code doing similar things is
+    helpful.</P>
+
+    <H3><A name="1.3">1.3</A>) How do I download/update the current source
+    tree?</H3>
+
+    <P>There are several ways to obtain the source tree. Occasional
+    developers can just get the most recent source tree snapshot from
+    ftp.postgresql.org. For regular developers, you can use CVS. CVS
+    allows you to download the source tree, then occasionally update
+    your copy of the source tree with any new changes. Using CVS, you
+    don't have to download the entire source each time, only the
+    changed files. Anonymous CVS does not allows developers to update
+    the remote source tree, though privileged developers can do this.
+    There is a CVS FAQ on our web site that describes how to use remote
+    CVS. You can also use CVSup, which has similarly functionality, and
+    is available from ftp.postgresql.org.</P>
+
+    <P>To update the source tree, there are two ways. You can generate
+    a patch against your current source tree, perhaps using the
+    make_diff tools mentioned above, and send them to the patches list.
+    They will be reviewed, and applied in a timely manner. If the patch
+    is major, and we are in beta testing, the developers may wait for
+    the final release before applying your patches.</P>
+
+    <P>For hard-core developers, Marc(scrappy@postgresql.org) will give
+    you a Unix shell account on postgresql.org, so you can use CVS to
+    update the main source tree, or you can ftp your files into your
+    account, patch, and cvs install the changes directly into the
+    source tree.</P>
+
+    <H3><A name="1.4">1.4</A>) How do I test my changes?</H3>
+
+    <P>First, use <I>psql</I> to make sure it is working as you expect.
+    Then run <I>src/test/regress</I> and get the output of
+    <I>src/test/regress/checkresults</I> with and without your changes,
+    to see that your patch does not change the regression test in
+    unexpected ways. This practice has saved me many times. The
+    regression tests test the code in ways I would never do, and has
+    caught many bugs in my patches. By finding the problems now, you
+    save yourself a lot of debugging later when things are broken, and
+    you can't figure out when it happened.</P>
+
+    <H3><A name="1.5">1.5</A>) What tools are available for
     developers?</H3>
 
     <P>Aside from the User documentation mentioned in the regular FAQ,
@@ -179,7 +309,7 @@
     There is also a script called <I>unused_oids</I> in
     <I>pgsql/src/include/catalog</I> that shows the unused oids.</P>
 
-    <H3><A name="2">2</A>) What books are good for developers?</H3>
+    <H3><A name="1.6">1.6</A>) What books are good for developers?</H3>
 
     <P>I have four good books, <I>An Introduction to Database
     Systems,</I> by C.J. Date, Addison, Wesley, <I>A Guide to the SQL
@@ -192,288 +322,7 @@
     on-line written by Jim Gray at <A href=
     "http://www.benchmarkresources.com">http://www.benchmarkresources.com.</A></P>
 
-    <H3><A name="3">3</A>) Why do we use <I>palloc</I>() and
-    <I>pfree</I>() to allocate memory?</H3>
-
-    <P><I>palloc()</I> and <I>pfree()</I> are used in place of malloc()
-    and free() because we automatically free all memory allocated when
-    a transaction completes. This makes it easier to make sure we free
-    memory that gets allocated in one place, but only freed much later.
-    There are several contexts that memory can be allocated in, and
-    this controls when the allocated memory is automatically freed by
-    the backend.</P>
-
-    <H3><A name="4">4</A>) Why do we use <I>Node</I> and <I>List</I> to
-    make data structures?</H3>
-
-    <P>We do this because this allows a consistent way to pass data
-    inside the backend in a flexible way. Every node has a
-    <I>NodeTag</I> which specifies what type of data is inside the
-    Node. <I>Lists</I> are groups of <I>Nodes chained together as a
-    forward-linked list.</I></P>
-
-    <P>Here are some of the <I>List</I> manipulation commands:</P>
-
-    <BLOCKQUOTE>
-      <DL>
-        <DT>lfirst(i)</DT>
-
-        <DD>return the data at list element <I>i.</I></DD>
-
-        <DT>lnext(i)</DT>
-
-        <DD>return the next list element after <I>i.</I></DD>
-
-        <DT>foreach(i, list)</DT>
-
-        <DD>
-          loop through <I>list,</I> assigning each list element to
-          <I>i.</I> It is important to note that <I>i</I> is a List *,
-          not the data in the <I>List</I> element. You need to use
-          <I>lfirst(i)</I> to get at the data. Here is a typical code
-          snipped that loops through a List containing <I>Var *'s</I>
-          and processes each one: 
-<PRE>
-<CODE>List *i, *list;
-    
-    foreach(i, list)
-    {
-        Var *var = lfirst(i);
-
-        /* process var here */
-    }
-</CODE>
-</PRE>
-        </DD>
-
-        <DT>lcons(node, list)</DT>
-
-        <DD>add <I>node</I> to the front of <I>list,</I> or create a
-        new list with <I>node</I> if <I>list</I> is <I>NIL.</I></DD>
-
-        <DT>lappend(list, node)</DT>
-
-        <DD>add <I>node</I> to the end of <I>list.</I> This is more
-        expensive that lcons.</DD>
-
-        <DT>nconc(list1, list2)</DT>
-
-        <DD>Concat <I>list2</I> on to the end of <I>list1.</I></DD>
-
-        <DT>length(list)</DT>
-
-        <DD>return the length of the <I>list.</I></DD>
-
-        <DT>nth(i, list)</DT>
-
-        <DD>return the <I>i</I>'th element in <I>list.</I></DD>
-
-        <DT>lconsi, ...</DT>
-
-        <DD>There are integer versions of these: <I>lconsi, lappendi,
-        nthi.</I> <I>List's</I> containing integers instead of Node
-        pointers are used to hold list of relation object id's and
-        other integer quantities.</DD>
-      </DL>
-    </BLOCKQUOTE>
-    You can print nodes easily inside <I>gdb.</I> First, to disable
-    output truncation when you use the gdb <I>print</I> command: 
-<PRE>
-<CODE>(gdb) set print elements 0
-</CODE>
-</PRE>
-    Instead of printing values in gdb format, you can use the next two
-    commands to print out List, Node, and structure contents in a
-    verbose format that is easier to understand. List's are unrolled
-    into nodes, and nodes are printed in detail. The first prints in a
-    short format, and the second in a long format: 
-<PRE>
-<CODE>(gdb) call print(any_pointer)
-    (gdb) call pprint(any_pointer)
-</CODE>
-</PRE>
-    The output appears in the postmaster log file, or on your screen if
-    you are running a backend directly without a postmaster. 
-
-    <H3><A name="5">5</A>) How do I add a feature or fix a bug?</H3>
-
-    <P>The source code is over 250,000 lines. Many problems/features
-    are isolated to one specific area of the code. Others require
-    knowledge of much of the source. If you are confused about where to
-    start, ask the hackers list, and they will be glad to assess the
-    complexity and give pointers on where to start.</P>
-
-    <P>Another thing to keep in mind is that many fixes and features
-    can be added with surprisingly little code. I often start by adding
-    code, then looking at other areas in the code where similar things
-    are done, and by the time I am finished, the patch is quite small
-    and compact.</P>
-
-    <P>When adding code, keep in mind that it should use the existing
-    facilities in the source, for performance reasons and for
-    simplicity. Often a review of existing code doing similar things is
-    helpful.</P>
-
-    <H3><A name="6">6</A>) How do I download/update the current source
-    tree?</H3>
-
-    <P>There are several ways to obtain the source tree. Occasional
-    developers can just get the most recent source tree snapshot from
-    ftp.postgresql.org. For regular developers, you can use CVS. CVS
-    allows you to download the source tree, then occasionally update
-    your copy of the source tree with any new changes. Using CVS, you
-    don't have to download the entire source each time, only the
-    changed files. Anonymous CVS does not allows developers to update
-    the remote source tree, though privileged developers can do this.
-    There is a CVS FAQ on our web site that describes how to use remote
-    CVS. You can also use CVSup, which has similarly functionality, and
-    is available from ftp.postgresql.org.</P>
-
-    <P>To update the source tree, there are two ways. You can generate
-    a patch against your current source tree, perhaps using the
-    make_diff tools mentioned above, and send them to the patches list.
-    They will be reviewed, and applied in a timely manner. If the patch
-    is major, and we are in beta testing, the developers may wait for
-    the final release before applying your patches.</P>
-
-    <P>For hard-core developers, Marc(scrappy@postgresql.org) will give
-    you a Unix shell account on postgresql.org, so you can use CVS to
-    update the main source tree, or you can ftp your files into your
-    account, patch, and cvs install the changes directly into the
-    source tree.</P>
-
-    <H3><A name="6">6</A>) How do I test my changes?</H3>
-
-    <P>First, use <I>psql</I> to make sure it is working as you expect.
-    Then run <I>src/test/regress</I> and get the output of
-    <I>src/test/regress/checkresults</I> with and without your changes,
-    to see that your patch does not change the regression test in
-    unexpected ways. This practice has saved me many times. The
-    regression tests test the code in ways I would never do, and has
-    caught many bugs in my patches. By finding the problems now, you
-    save yourself a lot of debugging later when things are broken, and
-    you can't figure out when it happened.</P>
-
-    <H3><A name="7">7</A>) I just added a field to a structure. What
-    else should I do?</H3>
-
-    <P>The structures passing around from the parser, rewrite,
-    optimizer, and executor require quite a bit of support. Most
-    structures have support routines in <I>src/backend/nodes</I> used
-    to create, copy, read, and output those structures. Make sure you
-    add support for your new field to these files. Find any other
-    places the structure may need code for your new field. <I>mkid</I>
-    is helpful with this (see above).</P>
-
-    <H3><A name="8">8</A>) Why are table, column, type, function, view
-    names sometimes referenced as <I>Name</I> or <I>NameData,</I> and
-    sometimes as <I>char *?</I></H3>
-
-    <P>Table, column, type, function, and view names are stored in
-    system tables in columns of type <I>Name.</I> Name is a
-    fixed-length, null-terminated type of <I>NAMEDATALEN</I> bytes.
-    (The default value for NAMEDATALEN is 32 bytes.)</P>
-<PRE>
-<CODE>typedef struct nameData
-    {
-        char        data[NAMEDATALEN];
-    } NameData;
-    typedef NameData *Name;
-</CODE>
-</PRE>
-    Table, column, type, function, and view names that come into the
-    backend via user queries are stored as variable-length,
-    null-terminated character strings. 
-
-    <P>Many functions are called with both types of names, ie.
-    <I>heap_open().</I> Because the Name type is null-terminated, it is
-    safe to pass it to a function expecting a char *. Because there are
-    many cases where on-disk names(Name) are compared to user-supplied
-    names(char *), there are many cases where Name and char * are used
-    interchangeably.</P>
-
-    <H3><A name="9">9</A>) How do I efficiently access information in
-    tables from the backend code?</H3>
-
-    <P>You first need to find the tuples(rows) you are interested in.
-    There are two ways. First, <I>SearchSysCache()</I> and related
-    functions allow you to query the system catalogs. This is the
-    preferred way to access system tables, because the first call to
-    the cache loads the needed rows, and future requests can return the
-    results without accessing the base table. The caches use system
-    table indexes to look up tuples. A list of available caches is
-    located in <I>src/backend/utils/cache/syscache.c.</I>
-    <I>src/backend/utils/cache/lsyscache.c</I> contains many
-    column-specific cache lookup functions.</P>
-
-    <P>The rows returned are cache-owned versions of the heap rows.
-    Therefore, you must not modify or delete the tuple returned by
-    <I>SearchSysCache()</I>. What you <I>should</I> do is release it
-    with <I>ReleaseSysCache()</I> when you are done using it; this
-    informs the cache that it can discard that tuple if necessary. If
-    you neglect to call <I>ReleaseSysCache()</I>, then the cache entry
-    will remain locked in the cache until end of transaction, which is
-    tolerable but not very desirable.</P>
-
-    <P>If you can't use the system cache, you will need to retrieve the
-    data directly from the heap table, using the buffer cache that is
-    shared by all backends. The backend automatically takes care of
-    loading the rows into the buffer cache.</P>
-
-    <P>Open the table with <I>heap_open().</I> You can then start a
-    table scan with <I>heap_beginscan(),</I> then use
-    <I>heap_getnext()</I> and continue as long as
-    <I>HeapTupleIsValid()</I> returns true. Then do a
-    <I>heap_endscan().</I> <I>Keys</I> can be assigned to the
-    <I>scan.</I> No indexes are used, so all rows are going to be
-    compared to the keys, and only the valid rows returned.</P>
-
-    <P>You can also use <I>heap_fetch()</I> to fetch rows by block
-    number/offset. While scans automatically lock/unlock rows from the
-    buffer cache, with <I>heap_fetch(),</I> you must pass a
-    <I>Buffer</I> pointer, and <I>ReleaseBuffer()</I> it when
-    completed.</P>
-
-    <P>Once you have the row, you can get data that is common to all
-    tuples, like <I>t_self</I> and <I>t_oid,</I> by merely accessing
-    the <I>HeapTuple</I> structure entries. If you need a
-    table-specific column, you should take the HeapTuple pointer, and
-    use the <I>GETSTRUCT()</I> macro to access the table-specific start
-    of the tuple. You then cast the pointer as a <I>Form_pg_proc</I>
-    pointer if you are accessing the pg_proc table, or
-    <I>Form_pg_type</I> if you are accessing pg_type. You can then
-    access the columns by using a structure pointer:</P>
-<PRE>
-<CODE>((Form_pg_class) GETSTRUCT(tuple))-&gt;relnatts
-</CODE>
-</PRE>
-    You must not directly change <I>live</I> tuples in this way. The
-    best way is to use <I>heap_modifytuple()</I> and pass it your
-    original tuple, and the values you want changed. It returns a
-    palloc'ed tuple, which you pass to <I>heap_replace().</I> You can
-    delete tuples by passing the tuple's <I>t_self</I> to
-    <I>heap_destroy().</I> You use <I>t_self</I> for
-    <I>heap_update()</I> too. Remember, tuples can be either system
-    cache copies, which may go away after you call
-    <I>ReleaseSysCache()</I>, or read directly from disk buffers, which
-    go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or
-    <I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may
-    be a palloc'ed tuple, that you must <I>pfree()</I> when finished. 
-
-    <H3><A name="10">10</A>) What is elog()?</H3>
-
-    <P><I>elog()</I> is used to send messages to the front-end, and
-    optionally terminate the current query being processed. The first
-    parameter is an elog level of <I>NOTICE,</I> <I>DEBUG,</I>
-    <I>ERROR,</I> or <I>FATAL.</I> <I>NOTICE</I> prints on the user's
-    terminal and the postmaster logs. <I>DEBUG</I> prints only in the
-    postmaster logs. <I>ERROR</I> prints in both places, and terminates
-    the current query, never returning from the call. <I>FATAL</I>
-    terminates the backend process. The remaining parameters of
-    <I>elog</I> are a <I>printf</I>-style set of parameters to
-    print.</P>
-
-    <H3><A name="11">11</A>) What is configure all about?</H3>
+    <H3><A name="1.7">1.7</A>) What is configure all about?</H3>
 
     <P>The files <I>configure</I> and <I>configure.in</I> are part of
     the GNU <I>autoconf</I> package. Configure allows us to test for
@@ -497,7 +346,7 @@
     all files derived by configure are removed, so you see only the
     file contained in the source distribution.</P>
 
-    <H3><A name="12">12</A>) How do I add a new port?</H3>
+    <H3><A name="1.8">1.8</A>) How do I add a new port?</H3>
 
     <P>There are a variety of places that need to be modified to add a
     new port. First, start in the <I>src/template</I> directory. Add an
@@ -516,20 +365,7 @@
     handling. There is a <I>backend/port</I> directory if you need
     special files for your OS.</P>
 
-    <H3><A name="13">13</A>) What is CommandCounterIncrement()?</H3>
-
-    <P>Normally, transactions can not see the rows they modify. This
-    allows <CODE>UPDATE foo SET x = x + 1</CODE> to work correctly.</P>
-
-    <P>However, there are cases where a transactions needs to see rows
-    affected in previous parts of the transaction. This is accomplished
-    using a Command Counter. Incrementing the counter allows
-    transactions to be broken into pieces so each piece can see rows
-    modified by previous pieces. <I>CommandCounterIncrement()</I>
-    increments the Command Counter, creating a new part of the
-    transaction.</P>
-
-    <H3><A name="14">14</A>) Why don't we use threads in the
+    <H3><A name="1.9">1.9</A>) Why don't we use threads in the
     backend?</H3>
 
     <P>There are several reasons threads are not used:</P>
@@ -545,7 +381,7 @@
       <LI>The backend code would be more complex.</LI>
     </UL>
 
-    <H3><A name="15">15</A>) How are RPM's packaged?</H3>
+    <H3><A name="1.10">1.10</A>) How are RPM's packaged?</H3>
 
     <P>This was written by Lamar Owen:</P>
 
@@ -650,7 +486,7 @@
     <P>Of course, there are many projects that DO include all the files
     necessary to build RPMs from their Official Tarball (TM).</P>
 
-    <H3><A name="16">16</A>) How are CVS branches managed?</H3>
+    <H3><A name="1.11">1.11</A>) How are CVS branches managed?</H3>
 
     <P>This was written by Tom Lane:</P>
 
@@ -720,70 +556,244 @@
     dot-release or two, so that we won't have to double-patch the first
     wave of fixes.</P>
 
-    <H3><A name="17">17</A>) How go I get involved in PostgreSQL
-    development?</H3>
+    <CENTER>
+      <H2>Technical Questions</H2>
+    </CENTER>
 
-    <P>This was written by Lamar Owen:</P>
+    <H3><A name="2.1">2.1</A>) How do I efficiently access information in
+    tables from the backend code?</H3>
 
-    <P>2001-06-22</P>
+    <P>You first need to find the tuples(rows) you are interested in.
+    There are two ways. First, <I>SearchSysCache()</I> and related
+    functions allow you to query the system catalogs. This is the
+    preferred way to access system tables, because the first call to
+    the cache loads the needed rows, and future requests can return the
+    results without accessing the base table. The caches use system
+    table indexes to look up tuples. A list of available caches is
+    located in <I>src/backend/utils/cache/syscache.c.</I>
+    <I>src/backend/utils/cache/lsyscache.c</I> contains many
+    column-specific cache lookup functions.</P>
 
-    <B>What open source development process is used by the PostgreSQL
-    team?</B>
+    <P>The rows returned are cache-owned versions of the heap rows.
+    Therefore, you must not modify or delete the tuple returned by
+    <I>SearchSysCache()</I>. What you <I>should</I> do is release it
+    with <I>ReleaseSysCache()</I> when you are done using it; this
+    informs the cache that it can discard that tuple if necessary. If
+    you neglect to call <I>ReleaseSysCache()</I>, then the cache entry
+    will remain locked in the cache until end of transaction, which is
+    tolerable but not very desirable.</P>
 
-    <P>Read HACKERS for six months (or a full release cycle, whichever
-    is longer). Really. HACKERS _is_the process. The process is not
-    well documented (AFAIK -- it may be somewhere that I am not aware
-    of) -- and it changes continually.</P>
+    <P>If you can't use the system cache, you will need to retrieve the
+    data directly from the heap table, using the buffer cache that is
+    shared by all backends. The backend automatically takes care of
+    loading the rows into the buffer cache.</P>
 
-    <B>What development environment (OS, system, compilers, etc) is
-    required to develop code?</B>
+    <P>Open the table with <I>heap_open().</I> You can then start a
+    table scan with <I>heap_beginscan(),</I> then use
+    <I>heap_getnext()</I> and continue as long as
+    <I>HeapTupleIsValid()</I> returns true. Then do a
+    <I>heap_endscan().</I> <I>Keys</I> can be assigned to the
+    <I>scan.</I> No indexes are used, so all rows are going to be
+    compared to the keys, and only the valid rows returned.</P>
 
-    <P><A href="developers.postgresql.org">Developers Corner</A> on the
-    website has links to this information. The distribution tarball
-    itself includes all the extra tools and documents that go beyond a
-    good Unix-like development environment. In general, a modern unix
-    with a modern gcc, GNU make or equivalent, autoconf (of a
-    particular version), and good working knowledge of those tools are
-    required.</P>
+    <P>You can also use <I>heap_fetch()</I> to fetch rows by block
+    number/offset. While scans automatically lock/unlock rows from the
+    buffer cache, with <I>heap_fetch(),</I> you must pass a
+    <I>Buffer</I> pointer, and <I>ReleaseBuffer()</I> it when
+    completed.</P>
 
-    <B>What areas need support?</B>
+    <P>Once you have the row, you can get data that is common to all
+    tuples, like <I>t_self</I> and <I>t_oid,</I> by merely accessing
+    the <I>HeapTuple</I> structure entries. If you need a
+    table-specific column, you should take the HeapTuple pointer, and
+    use the <I>GETSTRUCT()</I> macro to access the table-specific start
+    of the tuple. You then cast the pointer as a <I>Form_pg_proc</I>
+    pointer if you are accessing the pg_proc table, or
+    <I>Form_pg_type</I> if you are accessing pg_type. You can then
+    access the columns by using a structure pointer:</P>
+<PRE>
+<CODE>((Form_pg_class) GETSTRUCT(tuple))-&gt;relnatts
+</CODE>
+</PRE>
+    You must not directly change <I>live</I> tuples in this way. The
+    best way is to use <I>heap_modifytuple()</I> and pass it your
+    original tuple, and the values you want changed. It returns a
+    palloc'ed tuple, which you pass to <I>heap_replace().</I> You can
+    delete tuples by passing the tuple's <I>t_self</I> to
+    <I>heap_destroy().</I> You use <I>t_self</I> for
+    <I>heap_update()</I> too. Remember, tuples can be either system
+    cache copies, which may go away after you call
+    <I>ReleaseSysCache()</I>, or read directly from disk buffers, which
+    go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or
+    <I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may
+    be a palloc'ed tuple, that you must <I>pfree()</I> when finished. 
 
-    <P>The TODO list.</P>
+    <H3><A name="2.2">2.2</A>) Why are table, column, type, function, view
+    names sometimes referenced as <I>Name</I> or <I>NameData,</I> and
+    sometimes as <I>char *?</I></H3>
 
-    <P>You've made the first step, by finding and subscribing to
-    HACKERS. Once you find an area to look at in the TODO, and have
-    read the documentation on the internals, etc, then you check out a
-    current CVS,write what you are going to write (keeping your CVS
-    checkout up to date in the process), and make up a patch (as a
-    context diff only) and send to the PATCHES list, prefereably.</P>
+    <P>Table, column, type, function, and view names are stored in
+    system tables in columns of type <I>Name.</I> Name is a
+    fixed-length, null-terminated type of <I>NAMEDATALEN</I> bytes.
+    (The default value for NAMEDATALEN is 32 bytes.)</P>
+<PRE>
+<CODE>typedef struct nameData
+    {
+        char        data[NAMEDATALEN];
+    } NameData;
+    typedef NameData *Name;
+</CODE>
+</PRE>
+    Table, column, type, function, and view names that come into the
+    backend via user queries are stored as variable-length,
+    null-terminated character strings. 
 
-    <P>Discussion on the patch typically happens here. If the patch
-    adds a major feature, it would be a good idea to talk about it
-    first on the HACKERS list, in order to increase the chances of it
-    being accepted, as well as toavoid duplication of effort. Note that
-    experienced developers with a proven track record usually get the
-    big jobs -- for more than one reason. Also note that PostgreSQL is
-    highly portable -- nonportable code will likely be dismissed out of
-    hand.</P>
+    <P>Many functions are called with both types of names, ie.
+    <I>heap_open().</I> Because the Name type is null-terminated, it is
+    safe to pass it to a function expecting a char *. Because there are
+    many cases where on-disk names(Name) are compared to user-supplied
+    names(char *), there are many cases where Name and char * are used
+    interchangeably.</P>
 
-    <P>Once your contributions get accepted, things move from there.
-    Typically, you would be added as a developer on the list on the
-    website when one of the other developers recommends it. Membership
-    on the steering committee is by invitation only, by the other
-    steering committee members, from what I have gathered watching
-    froma distance.</P>
+    <H3><A name="2.3">2.3</A>) Why do we use <I>Node</I> and <I>List</I> to
+    make data structures?</H3>
 
-    <P>I make these statements from having watched the process for over
-    two years.</P>
+    <P>We do this because this allows a consistent way to pass data
+    inside the backend in a flexible way. Every node has a
+    <I>NodeTag</I> which specifies what type of data is inside the
+    Node. <I>Lists</I> are groups of <I>Nodes chained together as a
+    forward-linked list.</I></P>
+
+    <P>Here are some of the <I>List</I> manipulation commands:</P>
+
+    <BLOCKQUOTE>
+      <DL>
+        <DT>lfirst(i)</DT>
+
+        <DD>return the data at list element <I>i.</I></DD>
+
+        <DT>lnext(i)</DT>
+
+        <DD>return the next list element after <I>i.</I></DD>
+
+        <DT>foreach(i, list)</DT>
+
+        <DD>
+          loop through <I>list,</I> assigning each list element to
+          <I>i.</I> It is important to note that <I>i</I> is a List *,
+          not the data in the <I>List</I> element. You need to use
+          <I>lfirst(i)</I> to get at the data. Here is a typical code
+          snipped that loops through a List containing <I>Var *'s</I>
+          and processes each one: 
+<PRE>
+<CODE>List *i, *list;
+    
+    foreach(i, list)
+    {
+        Var *var = lfirst(i);
+
+        /* process var here */
+    }
+</CODE>
+</PRE>
+        </DD>
+
+        <DT>lcons(node, list)</DT>
+
+        <DD>add <I>node</I> to the front of <I>list,</I> or create a
+        new list with <I>node</I> if <I>list</I> is <I>NIL.</I></DD>
+
+        <DT>lappend(list, node)</DT>
+
+        <DD>add <I>node</I> to the end of <I>list.</I> This is more
+        expensive that lcons.</DD>
+
+        <DT>nconc(list1, list2)</DT>
+
+        <DD>Concat <I>list2</I> on to the end of <I>list1.</I></DD>
+
+        <DT>length(list)</DT>
+
+        <DD>return the length of the <I>list.</I></DD>
+
+        <DT>nth(i, list)</DT>
+
+        <DD>return the <I>i</I>'th element in <I>list.</I></DD>
+
+        <DT>lconsi, ...</DT>
+
+        <DD>There are integer versions of these: <I>lconsi, lappendi,
+        nthi.</I> <I>List's</I> containing integers instead of Node
+        pointers are used to hold list of relation object id's and
+        other integer quantities.</DD>
+      </DL>
+    </BLOCKQUOTE>
+    You can print nodes easily inside <I>gdb.</I> First, to disable
+    output truncation when you use the gdb <I>print</I> command: 
+<PRE>
+<CODE>(gdb) set print elements 0
+</CODE>
+</PRE>
+    Instead of printing values in gdb format, you can use the next two
+    commands to print out List, Node, and structure contents in a
+    verbose format that is easier to understand. List's are unrolled
+    into nodes, and nodes are printed in detail. The first prints in a
+    short format, and the second in a long format: 
+<PRE>
+<CODE>(gdb) call print(any_pointer)
+    (gdb) call pprint(any_pointer)
+</CODE>
+</PRE>
+    The output appears in the postmaster log file, or on your screen if
+    you are running a backend directly without a postmaster. 
+
+    <H3><A name="2.4">2.4</A>) I just added a field to a structure. What
+    else should I do?</H3>
+
+    <P>The structures passing around from the parser, rewrite,
+    optimizer, and executor require quite a bit of support. Most
+    structures have support routines in <I>src/backend/nodes</I> used
+    to create, copy, read, and output those structures. Make sure you
+    add support for your new field to these files. Find any other
+    places the structure may need code for your new field. <I>mkid</I>
+    is helpful with this (see above).</P>
+
+    <H3><A name="2.5">2.5</A>) Why do we use <I>palloc</I>() and
+    <I>pfree</I>() to allocate memory?</H3>
+
+    <P><I>palloc()</I> and <I>pfree()</I> are used in place of malloc()
+    and free() because we automatically free all memory allocated when
+    a transaction completes. This makes it easier to make sure we free
+    memory that gets allocated in one place, but only freed much later.
+    There are several contexts that memory can be allocated in, and
+    this controls when the allocated memory is automatically freed by
+    the backend.</P>
+
+    <H3><A name="2.6">2.6</A>) What is elog()?</H3>
+
+    <P><I>elog()</I> is used to send messages to the front-end, and
+    optionally terminate the current query being processed. The first
+    parameter is an elog level of <I>NOTICE,</I> <I>DEBUG,</I>
+    <I>ERROR,</I> or <I>FATAL.</I> <I>NOTICE</I> prints on the user's
+    terminal and the postmaster logs. <I>DEBUG</I> prints only in the
+    postmaster logs. <I>ERROR</I> prints in both places, and terminates
+    the current query, never returning from the call. <I>FATAL</I>
+    terminates the backend process. The remaining parameters of
+    <I>elog</I> are a <I>printf</I>-style set of parameters to
+    print.</P>
+
+    <H3><A name="2.7">2.7</A>) What is CommandCounterIncrement()?</H3>
+
+    <P>Normally, transactions can not see the rows they modify. This
+    allows <CODE>UPDATE foo SET x = x + 1</CODE> to work correctly.</P>
+
+    <P>However, there are cases where a transactions needs to see rows
+    affected in previous parts of the transaction. This is accomplished
+    using a Command Counter. Incrementing the counter allows
+    transactions to be broken into pieces so each piece can see rows
+    modified by previous pieces. <I>CommandCounterIncrement()</I>
+    increments the Command Counter, creating a new part of the
+    transaction.</P>
 
-    <P>To see a good example of how one goes about this, search the
-    archives for the name 'Tom Lane' and see what his first post
-    consisted of, and where he took things. In particular, note that
-    this hasn't been _that_ long ago -- and his bugfixing and general
-    deep knowledge with this codebase is legendary. Take a few days to
-    read after him. And pay special attention to both the sheer
-    quantity as well as the painstaking quality of his work. Both are
-    in high demand.</P>
   </BODY>
 </HTML>
-