# 49.2\. 報告服務器里的錯誤 在服務器代碼里生成的錯誤、警告以及日志信息應該用`ereport` 或者它的兄弟`elog`創建。這個函數的使用已經復雜得需要做些解釋了。 每條消息都有兩個必須的要素：一個嚴重級別(范圍從`DEBUG`到 `PANIC`)和一個主要消息文本。除此之外還有可選的元素， 最常見的就是一個遵循 SQL 標準的 SQLSTATE 習慣的錯誤標識碼。 `ereport`本身只是一個殼函數， 它的存在主要是為了便于讓消息生成看起來像 C 代碼里的函數調用。 `ereport`直接接受的唯一參數是嚴重級別。 主消息文本和任何附加消息元素都是通過在`ereport` 調用里調用輔助函數(比如`errmsg`)生成的。 典型的調用`ereport`的方式看起來可能像下面這樣： ``` ereport(ERROR, (errcode(ERRCODE_DIVISION_BY_ZERO), errmsg("division by zero"))); ``` 這樣就聲明了錯誤嚴重級別`ERROR`(一個普通錯誤)。 `errcode`調用指定一個在`src/include/utils/errcodes.h` 里面使用宏定義的SQLSTATE錯誤代碼。`errmsg`調用提供主要的消息文本。 請注意包圍在輔助函數調用周圍的額外的圓括弧—這么做雖然煩人， 但是語法上是必須的。 然后是一個更復雜的例子： ``` ereport(ERROR, (errcode(ERRCODE_AMBIGUOUS_FUNCTION), errmsg("function %s is not unique", func_signature_string(funcname, nargs, NIL, actual_arg_types)), errhint("Unable to choose a best candidate function. " "You might need to add explicit typecasts."))); ``` 這個例子演示了使用格式化代碼把運行時數值嵌入一個消息文本的用法。 同樣，還提供了一個可選的"暗示"信息。 `ereport`可用的附屬過程有： * `errcode(sqlerrcode)`為該條件聲明 SQLSTATE 錯誤標識符代碼。 如果沒有調用這個過程，并且錯誤嚴重級別是`ERROR`或更高， 那么錯誤標識符缺省是`ERRCODE_INTERNAL_ERROR`， 如果錯誤嚴重級別是`WARNING`則為`ERRCODE_WARNING`， 否則(用于`NOTICE`或者更低級別)為`ERRCODE_SUCCESSFUL_COMPLETION`。 雖然這些缺省都很方便，但是最好還是在省略`errcode()`調用之前三思。 * `errmsg(const char *msg, ...)`聲明主錯誤消息文本， 以及可能的插入其中的運行時數值。插入是使用`sprintf` 風格的格式代碼插入的。除了`sprintf`接受的標準格式代碼， 還接受`%m`用于插入`strerror`為當前`errno` 值返回的錯誤信息。 \[1\] `%m`并不要求在`errmsg`的參數列表里有任何對應的項目。 請注意這個消息字符串在格式代碼得到處理之前將不會通過`gettext` 運行獲取合適的本地化。 * `errmsg_internal(const char *msg, ...)`和`errmsg` 一樣，只是消息字符串將不會包含在國際化消息字典里。這個函數應該用于 "不可能發生"的情況，也就是不值得展開進行翻譯的場合。 * `errmsg_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n, ...)`就像是`errmsg`， 但是支持消息的各種復數形式。`_fmt_singular_`是英語單數形式， `_fmt_plural_`是英語復數形式，`_n_` 是決定使用哪個復數形式的整數值，剩余的參數根據選擇的格式字符串進行格式化。 更多信息請查看[Section 50.2.2](#calibre_link-2012)。 * `errdetail(const char *msg, ...)`提供一個可選的"詳細"信息； 在存在額外的信息，并且很適合放在主消息里面的時候使用這個函數。 消息字符串處理的方法和`errmsg`完全一樣。 * `errdetail_internal(const char *msg, ...)`和`errdetail`一樣， 只是消息字符串將不會包含在國際化消息字典里。這個函數應該用于不值得展開進行翻譯的詳細消息， 比如，因為它們太技術了以至于對大多數用戶來說無用。 * `errdetail_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n, ...)`類似于`errdetail`， 但是支持消息的各種復數形式。更多信息請查閱[Section 50.2.2](#calibre_link-2012)。 * `errdetail_log(const char *msg, ...)`和 `errdetail` 一樣，除了這個字符串只到服務器日志，從不到客戶端。 如果`errdetail`（或它的以上相同的其中之一）和`errdetail_log` 都使用了，那么一個字符串到客戶端，另一個到服務器日志。 這對于過于安全敏感或太大而不能包含進發送到客戶端的報告中的錯誤細節來說是有用的。 * `errhint(const char *msg, ...)`提供一個可選的"暗示"消息； 這個函數用于提供如何修補問題的建議，而不是提供錯誤的事實。 消息字符串處理的方式和`errmsg`一樣。 * `errcontext(const char *msg, ...)`通常不會直接從`ereport` 消息點里直接調用；而是用在`error_context_stack` 回調函數里提供有關錯誤發生的環境的信息，比如，當前的位置是在一個 PL 函數里等等。 消息字符串的處理和`errmsg`完全一樣。和其它輔助函數不同， 這個函數在一次`ereport`調用里可以調用多次； 隨后的調用生成的字符串將帶著各自的換行符連接在原來的字符串上。 * `errposition(int cursorpos)`聲明一個錯誤在查詢字符串里的文本位置。 目前它只是在匯報查詢處理過程中的詞法和語法分析階段檢測到的錯誤有用。 * `errtable(Relation rel)`指定一個關系， 關系名和模式名應該作為輔助字段包含在錯誤報告內。 * `errtablecol(Relation rel, int attnum)`指定一個字段， 該字段的名字、表名和模式名應該作為輔助字段包含在錯誤報告中。 * `errtableconstraint(Relation rel, const char *conname)` 指定一個表約束，該表約束的名字、表名和模式名應該作為輔助字段包含在錯誤報告中。 不管它們是否有一個相關的`pg_constraint`項，索引都應該被認為是約束。 小心地傳遞底層堆關系，不只是索引本身，作為`rel`。 * `errdatatype(Oid datatypeOid)`指定一個數據類型， 它的名字和模式名應該作為輔助字段包含在錯誤報告中。 * `errdomainconstraint(Oid datatypeOid, const char *conname)` 指定一個域約束，該域約束的名字、域名和模式名應該作為附屬字段包含在錯誤報告中。 * `errcode_for_file_access()`是一個便利函數， 它可以為一個文件訪問類的系統調用選擇一個合適的 SQLSTATE 錯誤標識符。 它利用保存下來的`errno`判斷生成哪個錯誤代碼。 通常它應該和主錯誤消息文本里的`%m`結合使用。 * `errcode_for_socket_access()`是一個便利函數， 它可以為一個套接字相關的系統調用選擇一個合適的 SQLSTATE 錯誤標識符。 * `errhidestmt(bool hide_stmt)`可以用來在主日志中指定消息的 `STATEMENT:`部分的消除。如果消息文本早已包括當前語句， 那么這通常是合適的。 > **Note:** `errtable`、`errtablecol`、`errtableconstraint`、 `errdatatype`或`errdomainconstraint` 中最多只有一個函數應該用在一個`ereport`調用中。 這些函數的存在允許應用提取與沒有檢測潛在本地化錯誤消息文本的錯誤條件相關的數據庫對象的名字。 這些函數應該用在應用希望自動錯誤處理的錯誤報告中。自PostgreSQL 9.3起， 完全覆蓋只是為了SQLSTATE class 23中的錯誤而存在（違反完整約束）， 但是有可能會在未來擴展。 還有一個老一些的`elog`函數，仍然在頻繁使用。一個`elog`調用： ``` elog(level, "format string", ...); ``` 完全等效于： ``` ereport(level, (errmsg_internal("format string", ...))); ``` 請注意 SQLSTATE 錯誤代碼總是缺省的，并且消息字符串并沒有翻譯。因此， `elog`應該只用于內部錯誤以及低層的調試日志。 任何普通用戶感興趣的消息都應該通過`ereport`生成。當然， 還有大量內部的"不可能發生"的錯誤檢查使用`elog`； 因為這些信息最好還是表示得簡單些好。 書寫好的錯誤消息的建議可以在[Section 49.3](#calibre_link-1472)找到。 ### Notes \[1\] 也就是說，在到達`ereport`調用的時候當前的數值； 在附屬報告過程里對`errno`的修改將不會影響他。但是如果你在 `errmsg`的參數列表里明確地寫`strerror(errno)`， 這一點就不能保證了，因此，請不要這么做。