sync with cpython 9e38723a

Author: github-actions[bot]

howto/argparse.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-08-30 18:24+0000\n"
+"POT-Creation-Date: 2024-09-10 00:04+0000\n"
 "PO-Revision-Date: 2023-08-17 22:17+0800\n"
 "Last-Translator: Matt Wang <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -94,17 +94,29 @@ msgstr ""
 msgid "On a Linux machine, this can be done via::"
 msgstr "在 Linux 機器上，這可以透過以下方式完成： ::"
 
+#: ../../howto/instrumentation.rst:42
+msgid "$ yum install systemtap-sdt-devel"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:44
 msgid "or::"
 msgstr "或是： ::"
 
+#: ../../howto/instrumentation.rst:46
+msgid "$ sudo apt-get install systemtap-sdt-dev"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:49
 msgid ""
 "CPython must then be :option:`configured with the --with-dtrace option <--"
 "with-dtrace>`:"
 msgstr ""
 "然後 CPython 必須使用\\ :option:`配置 --with-dtrace 選項 <--with-dtrace>`："
 
+#: ../../howto/instrumentation.rst:52
+msgid "checking for --with-dtrace... yes"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:56
 msgid ""
 "On macOS, you can list available DTrace probes by running a Python process "
@@ -114,6 +126,28 @@ msgstr ""
 "在 macOS 上，你可以透過在後台運行 Python 行程並列出 Python 發布者 (provider) "
 "所提供的所有可用探針，以列出可用的 DTrace 探針： ::"
 
+#: ../../howto/instrumentation.rst:60
+msgid ""
+"$ python3.6 -q &\n"
+"$ sudo dtrace -l -P python$!  # or: dtrace -l -m python3.6\n"
+"\n"
+"   ID   PROVIDER            MODULE                          FUNCTION NAME\n"
+"29564 python18035        python3.6          _PyEval_EvalFrameDefault "
+"function-entry\n"
+"29565 python18035        python3.6             dtrace_function_entry "
+"function-entry\n"
+"29566 python18035        python3.6          _PyEval_EvalFrameDefault "
+"function-return\n"
+"29567 python18035        python3.6            dtrace_function_return "
+"function-return\n"
+"29568 python18035        python3.6                           collect gc-"
+"done\n"
+"29569 python18035        python3.6                           collect gc-"
+"start\n"
+"29570 python18035        python3.6          _PyEval_EvalFrameDefault line\n"
+"29571 python18035        python3.6                 maybe_dtrace_line line"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:73
 msgid ""
 "On Linux, you can verify if the SystemTap static markers are present in the "
@@ -122,6 +156,12 @@ msgstr ""
 "在 Linux 上，你可以透過查看二進位建置檔案中是否包含 \".note.stapsdt\" 部分來"
 "驗證 SystemTap 靜態標記是否存在。"
 
+#: ../../howto/instrumentation.rst:78
+msgid ""
+"$ readelf -S ./python | grep .note.stapsdt\n"
+"[30] .note.stapsdt        NOTE         0000000000000000 00308d78"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:81
 msgid ""
 "If you've built Python as a shared library (with the :option:`--enable-"
@@ -131,10 +171,64 @@ msgstr ""
 "如果你已將 Python 建置為共享函式庫（使用 :option:`--enable-shared` 配置選"
 "項），則需要在共享函式庫中查找。例如： ::"
 
+#: ../../howto/instrumentation.rst:85
+msgid ""
+"$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt\n"
+"[29] .note.stapsdt        NOTE         0000000000000000 00365b68"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:88
 msgid "Sufficiently modern readelf can print the metadata::"
 msgstr "足夠現代化的 readelf 可以印出元資料 (metadata)： ::"
 
+#: ../../howto/instrumentation.rst:90
+msgid ""
+"$ readelf -n ./python\n"
+"\n"
+"Displaying notes found at file offset 0x00000254 with length 0x00000020:\n"
+"    Owner                 Data size          Description\n"
+"    GNU                  0x00000010          NT_GNU_ABI_TAG (ABI version "
+"tag)\n"
+"        OS: Linux, ABI: 2.6.32\n"
+"\n"
+"Displaying notes found at file offset 0x00000274 with length 0x00000024:\n"
+"    Owner                 Data size          Description\n"
+"    GNU                  0x00000014          NT_GNU_BUILD_ID (unique build "
+"ID bitstring)\n"
+"        Build ID: df924a2b08a7e89f6e11251d4602022977af2670\n"
+"\n"
+"Displaying notes found at file offset 0x002d6c30 with length 0x00000144:\n"
+"    Owner                 Data size          Description\n"
+"    stapsdt              0x00000031          NT_STAPSDT (SystemTap probe "
+"descriptors)\n"
+"        Provider: python\n"
+"        Name: gc__start\n"
+"        Location: 0x00000000004371c3, Base: 0x0000000000630ce2, Semaphore: "
+"0x00000000008d6bf6\n"
+"        Arguments: -4@%ebx\n"
+"    stapsdt              0x00000030          NT_STAPSDT (SystemTap probe "
+"descriptors)\n"
+"        Provider: python\n"
+"        Name: gc__done\n"
+"        Location: 0x00000000004374e1, Base: 0x0000000000630ce2, Semaphore: "
+"0x00000000008d6bf8\n"
+"        Arguments: -8@%rax\n"
+"    stapsdt              0x00000045          NT_STAPSDT (SystemTap probe "
+"descriptors)\n"
+"        Provider: python\n"
+"        Name: function__entry\n"
+"        Location: 0x000000000053db6c, Base: 0x0000000000630ce2, Semaphore: "
+"0x00000000008d6be8\n"
+"        Arguments: 8@%rbp 8@%r12 -4@%eax\n"
+"    stapsdt              0x00000046          NT_STAPSDT (SystemTap probe "
+"descriptors)\n"
+"        Provider: python\n"
+"        Name: function__return\n"
+"        Location: 0x000000000053dba8, Base: 0x0000000000630ce2, Semaphore: "
+"0x00000000008d6bea\n"
+"        Arguments: 8@%rbp 8@%r12 -4@%eax"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:125
 msgid ""
 "The above metadata contains information for SystemTap describing how it can "
@@ -158,14 +252,77 @@ msgstr ""
 "以下範例示範 DTrace 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構，僅在名為 "
 "\"start\" 的函式的呼叫內進行追蹤。換句話說，引入時的函式呼叫不會被列出："
 
+#: ../../howto/instrumentation.rst:138
+msgid ""
+"self int indent;\n"
+"\n"
+"python$target:::function-entry\n"
+"/copyinstr(arg1) == \"start\"/\n"
+"{\n"
+"        self->trace = 1;\n"
+"}\n"
+"\n"
+"python$target:::function-entry\n"
+"/self->trace/\n"
+"{\n"
+"        printf(\"%d\\t%*s:\", timestamp, 15, probename);\n"
+"        printf(\"%*s\", self->indent, \"\");\n"
+"        printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), "
+"arg2);\n"
+"        self->indent++;\n"
+"}\n"
+"\n"
+"python$target:::function-return\n"
+"/self->trace/\n"
+"{\n"
+"        self->indent--;\n"
+"        printf(\"%d\\t%*s:\", timestamp, 15, probename);\n"
+"        printf(\"%*s\", self->indent, \"\");\n"
+"        printf(\"%s:%s:%d\\n\", basename(copyinstr(arg0)), copyinstr(arg1), "
+"arg2);\n"
+"}\n"
+"\n"
+"python$target:::function-return\n"
+"/copyinstr(arg1) == \"start\"/\n"
+"{\n"
+"        self->trace = 0;\n"
+"}"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:172 ../../howto/instrumentation.rst:230
 msgid "It can be invoked like this::"
 msgstr "可以這樣呼叫： ::"
 
+#: ../../howto/instrumentation.rst:174
+msgid "$ sudo dtrace -q -s call_stack.d -c \"python3.6 script.py\""
+msgstr ""
+
 #: ../../howto/instrumentation.rst:176 ../../howto/instrumentation.rst:236
 msgid "The output looks like this:"
 msgstr "輸出如下所示："
 
+#: ../../howto/instrumentation.rst:178
+msgid ""
+"156641360502280  function-entry:call_stack.py:start:23\n"
+"156641360518804  function-entry: call_stack.py:function_1:1\n"
+"156641360532797  function-entry:  call_stack.py:function_3:9\n"
+"156641360546807 function-return:  call_stack.py:function_3:10\n"
+"156641360563367 function-return: call_stack.py:function_1:2\n"
+"156641360578365  function-entry: call_stack.py:function_2:5\n"
+"156641360591757  function-entry:  call_stack.py:function_1:1\n"
+"156641360605556  function-entry:   call_stack.py:function_3:9\n"
+"156641360617482 function-return:   call_stack.py:function_3:10\n"
+"156641360629814 function-return:  call_stack.py:function_1:2\n"
+"156641360642285 function-return: call_stack.py:function_2:6\n"
+"156641360656770  function-entry: call_stack.py:function_3:9\n"
+"156641360669707 function-return: call_stack.py:function_3:10\n"
+"156641360687853  function-entry: call_stack.py:function_4:13\n"
+"156641360700719 function-return: call_stack.py:function_4:14\n"
+"156641360719640  function-entry: call_stack.py:function_5:18\n"
+"156641360732567 function-return: call_stack.py:function_5:21\n"
+"156641360747370 function-return:call_stack.py:start:28"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:201
 msgid "Static SystemTap markers"
 msgstr "靜態 SystemTap 標記"
@@ -185,6 +342,44 @@ msgid ""
 "hierarchy of a Python script:"
 msgstr "例如，此 SystemTap 腳本可用於顯示 Python 腳本的呼叫/回傳階層結構："
 
+#: ../../howto/instrumentation.rst:210
+msgid ""
+"probe process(\"python\").mark(\"function__entry\") {\n"
+"     filename = user_string($arg1);\n"
+"     funcname = user_string($arg2);\n"
+"     lineno = $arg3;\n"
+"\n"
+"     printf(\"%s => %s in %s:%d\\\\n\",\n"
+"            thread_indent(1), funcname, filename, lineno);\n"
+"}\n"
+"\n"
+"probe process(\"python\").mark(\"function__return\") {\n"
+"    filename = user_string($arg1);\n"
+"    funcname = user_string($arg2);\n"
+"    lineno = $arg3;\n"
+"\n"
+"    printf(\"%s <= %s in %s:%d\\\\n\",\n"
+"           thread_indent(-1), funcname, filename, lineno);\n"
+"}"
+msgstr ""
+
+#: ../../howto/instrumentation.rst:232
+msgid ""
+"$ stap \\\n"
+"  show-call-hierarchy.stp \\\n"
+"  -c \"./python test.py\""
+msgstr ""
+
+#: ../../howto/instrumentation.rst:238
+msgid ""
+"11408 python(8274):        => __contains__ in Lib/_abcoll.py:362\n"
+"11414 python(8274):         => __getitem__ in Lib/os.py:425\n"
+"11418 python(8274):          => encode in Lib/os.py:490\n"
+"11424 python(8274):          <= encode in Lib/os.py:493\n"
+"11428 python(8274):         <= __getitem__ in Lib/os.py:426\n"
+"11433 python(8274):        <= __contains__ in Lib/_abcoll.py:366"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:247
 msgid "where the columns are:"
 msgstr "其中的行 (column) 是："
@@ -216,10 +411,20 @@ msgstr ""
 "函式庫中，並且探針的帶點路徑 (dotted path) 需要反映這一點。例如，上面範例中的"
 "這一列："
 
+#: ../../howto/instrumentation.rst:259
+msgid "probe process(\"python\").mark(\"function__entry\") {"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:263
 msgid "should instead read:"
 msgstr "應該改為讀取："
 
+#: ../../howto/instrumentation.rst:265
+msgid ""
+"probe process(\"python\").library(\"libpython3.6dm.so.1.0\")."
+"mark(\"function__entry\") {"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:269
 msgid "(assuming a :ref:`debug build <debug-build>` of CPython 3.6)"
 msgstr "（假設 CPython 3.6 的\\ :ref:`除錯建置版本 <debug-build>`）"
@@ -342,6 +547,29 @@ msgstr ""
 msgid "Here is a tapset file, based on a non-shared build of CPython:"
 msgstr "這是一個 tapset 檔案，是基於 CPython 的非共享建置版本："
 
+#: ../../howto/instrumentation.rst:351
+msgid ""
+"/*\n"
+"   Provide a higher-level wrapping around the function__entry and\n"
+"   function__return markers:\n"
+" \\*/\n"
+"probe python.function.entry = process(\"python\").mark(\"function__entry\")\n"
+"{\n"
+"    filename = user_string($arg1);\n"
+"    funcname = user_string($arg2);\n"
+"    lineno = $arg3;\n"
+"    frameptr = $arg4\n"
+"}\n"
+"probe python.function.return = process(\"python\")."
+"mark(\"function__return\")\n"
+"{\n"
+"    filename = user_string($arg1);\n"
+"    funcname = user_string($arg2);\n"
+"    lineno = $arg3;\n"
+"    frameptr = $arg4\n"
+"}"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:372
 msgid ""
 "If this file is installed in SystemTap's tapset directory (e.g. ``/usr/share/"
@@ -381,6 +609,21 @@ msgstr ""
 "此 SystemTap 腳本使用上面的 tapset 來更清晰地實作上面給出的追蹤 Python 函式呼"
 "叫階層結構的範例，而無需直接命名靜態標記："
 
+#: ../../howto/instrumentation.rst:395
+msgid ""
+"probe python.function.entry\n"
+"{\n"
+"  printf(\"%s => %s in %s:%d\\n\",\n"
+"         thread_indent(1), funcname, filename, lineno);\n"
+"}\n"
+"\n"
+"probe python.function.return\n"
+"{\n"
+"  printf(\"%s <= %s in %s:%d\\n\",\n"
+"         thread_indent(-1), funcname, filename, lineno);\n"
+"}"
+msgstr ""
+
 #: ../../howto/instrumentation.rst:410
 msgid ""
 "The following script uses the tapset above to provide a top-like view of all "
@@ -389,3 +632,25 @@ msgid ""
 msgstr ""
 "以下腳本使用上面的 tapset 來提供所有正在運行之 CPython 程式碼的近乎最高層視"
 "角，顯示整個系統中每秒最常被進入的 20 個位元組碼幀 (bytecode frame)："
+
+#: ../../howto/instrumentation.rst:414
+msgid ""
+"global fn_calls;\n"
+"\n"
+"probe python.function.entry\n"
+"{\n"
+"    fn_calls[pid(), filename, funcname, lineno] += 1;\n"
+"}\n"
+"\n"
+"probe timer.ms(1000) {\n"
+"    printf(\"\\033[2J\\033[1;1H\") /* clear screen \\*/\n"
+"    printf(\"%6s %80s %6s %30s %6s\\n\",\n"
+"           \"PID\", \"FILENAME\", \"LINE\", \"FUNCTION\", \"CALLS\")\n"
+"    foreach ([pid, filename, funcname, lineno] in fn_calls- limit 20) {\n"
+"        printf(\"%6d %80s %6d %30s %6d\\n\",\n"
+"            pid, filename, lineno, funcname,\n"
+"            fn_calls[pid, filename, funcname, lineno]);\n"
+"    }\n"
+"    delete fn_calls;\n"
+"}"
+msgstr ""