Improve discussion of FOR UPDATE.

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index cad427da3c64d446ca3dcc1286d42c0bdefd9277..0ffc9cecb73a6b0017d74c7d5ad3892ee9d639b6 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
 
 
@@ -368,13 +368,14 @@ where from_item can be:
   
 
   
-   The FOR UPDATE clause allows the SELECT statement to perform 
-   exclusive locking of selected rows.
+   The FOR UPDATE clause causes the SELECT statement to lock the selected
+   rows against concurrent updates.
   
    
   
    You must have SELECT privilege to a table to read its values
    (See the GRANT/REVOKE statements).
+   Use of FOR UPDATE requires UPDATE privilege as well.
   
    
   
@@ -859,19 +860,32 @@ SELECT name FROM distributors ORDER BY code;
    
     FOR UPDATE causes the rows retrieved by the query to be locked as though
     for update.  This prevents them from being modified or deleted by other
-    transactions until the current transaction ends.
+    transactions until the current transaction ends; that is, other
+    transactions that attempt UPDATE, DELETE, or SELECT FOR UPDATE of these
+    rows will be blocked until the current transaction ends.  Also, if an
+    UPDATE, DELETE, or SELECT FOR UPDATE from another transaction has already
+    locked a selected row or rows, SELECT FOR UPDATE will wait for the other
+    transaction to complete, and will then lock and return the updated row
+    (or no row, if the row was deleted).  For further discussion see the
+    concurrency chapter of the User's Guide.
    
 
    
     If specific tables are named in FOR UPDATE, then only rows coming from
-    those tables are locked.
+    those tables are locked; any other tables used in the SELECT are simply
+    read as usual.
    
 
    
     FOR UPDATE cannot be used in contexts where returned rows can't be clearly
     identified with individual table rows; for example it can't be used with
-    aggregation.  FOR UPDATE may also appear before LIMIT for portability with
-    pre-7.3 applications.
+    aggregation.
+   
+
+   
+    FOR UPDATE may appear before LIMIT for compatibility with
+    pre-7.3 applications.  However, it effectively executes after LIMIT,
+    and so that is the recommended place to write it.