-
-
Notifications
You must be signed in to change notification settings - Fork 224
Expand file tree
/
Copy pathremote_debugging.po
More file actions
1325 lines (1191 loc) · 58.1 KB
/
remote_debugging.po
File metadata and controls
1325 lines (1191 loc) · 58.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Python 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-01-22 16:08+0000\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
"tw)\n"
"Language: zh_TW\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: ../../howto/remote_debugging.rst:4
msgid "Remote debugging attachment protocol"
msgstr "遠端偵錯附加協定"
#: ../../howto/remote_debugging.rst:6
msgid ""
"This protocol enables external tools to attach to a running CPython process "
"and execute Python code remotely."
msgstr ""
"此協定使外部工具能夠附加到正在執行的 CPython 行程並遠端執行 Python 程式碼。"
#: ../../howto/remote_debugging.rst:9
msgid ""
"Most platforms require elevated privileges to attach to another Python "
"process."
msgstr "大多數平台上都會需要更高的權限才能附加到另一個 Python 行程。"
#: ../../howto/remote_debugging.rst:12
msgid "Disabling remote debugging"
msgstr "停用遠端偵錯"
#: ../../howto/remote_debugging.rst:14
msgid "To disable remote debugging support, use any of the following:"
msgstr "要停用遠端偵錯支援，請使用以下任一方法："
#: ../../howto/remote_debugging.rst:16
msgid ""
"Set the :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` environment variable to ``1`` "
"before starting the interpreter."
msgstr ""
"在啟動直譯器之前，將 :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` 環境變數設為 ``1``。"
#: ../../howto/remote_debugging.rst:18
msgid "Use the :option:`-X disable_remote_debug` command-line option."
msgstr "使用 :option:`-X disable_remote_debug` 命令列選項。"
#: ../../howto/remote_debugging.rst:19
msgid "Compile Python with the :option:`--without-remote-debug` build flag."
msgstr "使用 :option:`--without-remote-debug` 建置旗標來編譯 Python。"
#: ../../howto/remote_debugging.rst:24
msgid "Permission requirements"
msgstr "權限需求"
#: ../../howto/remote_debugging.rst:26
msgid ""
"Attaching to a running Python process for remote debugging requires elevated "
"privileges on most platforms. The specific requirements and troubleshooting "
"steps depend on your operating system:"
msgstr ""
"在大多數平台上，附加到正在執行的 Python 行程進行遠端偵錯需要更高的權限。具體"
"要求和疑難排解步驟會取決於你的作業系統："
#: ../../howto/remote_debugging.rst:31
msgid "Linux"
msgstr "Linux"
#: ../../howto/remote_debugging.rst:32
msgid ""
"The tracer process must have the ``CAP_SYS_PTRACE`` capability or equivalent "
"privileges. You can only trace processes you own and can signal. Tracing may "
"fail if the process is already being traced, or if it is running with set-"
"user-ID or set-group-ID. Security modules like Yama may further restrict "
"tracing."
msgstr ""
"執行追蹤的行程 (tracer process) 必須具有 ``CAP_SYS_PTRACE`` 功能或同等權限。"
"你只能追蹤你擁有且可以發送訊號的行程。如果行程已經被追蹤，或者它以 set-user-"
"ID 或 set-group-ID 執行，則追蹤可能會失敗。像 Yama 這樣的安全模組可能會進一步"
"限制追蹤。"
#: ../../howto/remote_debugging.rst:38
msgid "To temporarily relax ptrace restrictions (until reboot), run:"
msgstr "要暫時放寬 ptrace 限制（直到重新開機），請執行："
#: ../../howto/remote_debugging.rst:40
msgid "``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``"
msgstr "``echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope``"
#: ../../howto/remote_debugging.rst:44
msgid ""
"Disabling ``ptrace_scope`` reduces system hardening and should only be done "
"in trusted environments."
msgstr ""
"停用 ``ptrace_scope`` 會降低系統安全性，應僅在受信任的環境中執行此操作。"
#: ../../howto/remote_debugging.rst:47
msgid ""
"If running inside a container, use ``--cap-add=SYS_PTRACE`` or ``--"
"privileged``, and run as root if needed."
msgstr ""
"如果在容器內執行，請使用 ``--cap-add=SYS_PTRACE`` 或 ``--privileged``，並在需"
"要時以 root 身分執行。"
#: ../../howto/remote_debugging.rst:50
msgid "Try re-running the command with elevated privileges:"
msgstr "嘗試使用提升後的權限重新執行命令："
#: ../../howto/remote_debugging.rst:52
msgid "``sudo -E !!``"
msgstr "``sudo -E !!``"
#: ../../howto/remote_debugging.rst:56
msgid "macOS"
msgstr "macOS"
#: ../../howto/remote_debugging.rst:57
msgid ""
"To attach to another process, you typically need to run your debugging tool "
"with elevated privileges. This can be done by using ``sudo`` or running as "
"root."
msgstr ""
"要附加到另一個行程，你通常需要以提升過的權限來執行偵錯工具。這可以透過使用 "
"``sudo`` 或以 root 身分執行來完成。"
#: ../../howto/remote_debugging.rst:61
msgid ""
"Even when attaching to processes you own, macOS may block debugging unless "
"the debugger is run with root privileges due to system security restrictions."
msgstr ""
"即使附加到你擁有的行程，macOS 也可能會阻止偵錯，除非偵錯器以 root 權限執行，"
"這是由於系統安全限制。"
#: ../../howto/remote_debugging.rst:66
msgid "Windows"
msgstr "Windows"
#: ../../howto/remote_debugging.rst:67
msgid ""
"To attach to another process, you usually need to run your debugging tool "
"with administrative privileges. Start the command prompt or terminal as "
"Administrator."
msgstr ""
"要附加到另一個行程，你通常需要以系統管理員權限執行偵錯工具。以系統管理員身分"
"啟動命令提示字元或終端機。"
#: ../../howto/remote_debugging.rst:71
msgid ""
"Some processes may still be inaccessible even with Administrator rights, "
"unless you have the ``SeDebugPrivilege`` privilege enabled."
msgstr ""
"即使具有系統管理員權限，某些行程仍可能無法存取，除非你啟用了 "
"``SeDebugPrivilege`` 權限。"
#: ../../howto/remote_debugging.rst:74
msgid ""
"To resolve file or folder access issues, adjust the security permissions:"
msgstr "要解決檔案或資料夾存取問題，請調整安全權限："
#: ../../howto/remote_debugging.rst:76
msgid "Right-click the file or folder and select **Properties**."
msgstr "右鍵點擊檔案或資料夾並選擇 **Properties**。"
#: ../../howto/remote_debugging.rst:77
msgid "Go to the **Security** tab to view users and groups with access."
msgstr "前往 **Security** 分頁以檢視具有存取權限的使用者和群組。"
#: ../../howto/remote_debugging.rst:78
msgid "Click **Edit** to modify permissions."
msgstr "點擊 **Edit** 以修改權限。"
#: ../../howto/remote_debugging.rst:79
msgid "Select your user account."
msgstr "選擇你的使用者帳戶。"
#: ../../howto/remote_debugging.rst:80
msgid "In **Permissions**, check **Read** or **Full control** as needed."
msgstr "在 **Permissions** 中，視需要勾選 **Read** 或 **Full control**。"
#: ../../howto/remote_debugging.rst:81
msgid "Click **Apply**, then **OK** to confirm."
msgstr "點擊 **Apply**，然後點擊 **OK** 來確認。"
#: ../../howto/remote_debugging.rst:86
msgid ""
"Ensure you've satisfied all :ref:`permission-requirements` before proceeding."
msgstr "在繼續之前，請確保你已滿足所有 :ref:`permission-requirements`。"
#: ../../howto/remote_debugging.rst:88
msgid ""
"This section describes the low-level protocol that enables external tools to "
"inject and execute a Python script within a running CPython process."
msgstr ""
"本節描述了低階協定，使外部工具能夠在正在執行的 CPython 行程中注入並執行 "
"Python 腳本。"
#: ../../howto/remote_debugging.rst:91
msgid ""
"This mechanism forms the basis of the :func:`sys.remote_exec` function, "
"which instructs a remote Python process to execute a ``.py`` file. However, "
"this section does not document the usage of that function. Instead, it "
"provides a detailed explanation of the underlying protocol, which takes as "
"input the ``pid`` of a target Python process and the path to a Python source "
"file to be executed. This information supports independent reimplementation "
"of the protocol, regardless of programming language."
msgstr ""
"此機制構成了 :func:`sys.remote_exec` 函式的基礎，該函式指示遠端 Python 行程執"
"行 ``.py`` 檔案。但本節不記錄該函式的用法，而是提供底層協定的詳細說明，該協定"
"以目標 Python 行程的 ``pid`` 和要執行的 Python 原始檔路徑作為輸入。此資訊支援"
"該協定的獨立重新實作，無論使用何種程式語言。"
#: ../../howto/remote_debugging.rst:101
msgid ""
"The execution of the injected script depends on the interpreter reaching a "
"safe evaluation point. As a result, execution may be delayed depending on "
"the runtime state of the target process."
msgstr ""
"注入腳本的執行取決於直譯器是否到達安全執行點 (safe evaluation point)。因此，"
"執行可能會根據目標行程的 runtime 狀態而延遲。"
#: ../../howto/remote_debugging.rst:105
msgid ""
"Once injected, the script is executed by the interpreter within the target "
"process the next time a safe evaluation point is reached. This approach "
"enables remote execution capabilities without modifying the behavior or "
"structure of the running Python application."
msgstr ""
"一旦注入，腳本將在下次到達安全執行點時會由目標行程內的直譯器執行。這種方法使"
"遠端執行功能成為可能，而不需修改正在執行的 Python 應用程式的行為或結構。"
#: ../../howto/remote_debugging.rst:110
msgid ""
"Subsequent sections provide a step-by-step description of the protocol, "
"including techniques for locating interpreter structures in memory, safely "
"accessing internal fields, and triggering code execution. Platform-specific "
"variations are noted where applicable, and example implementations are "
"included to clarify each operation."
msgstr ""
"後續章節提供了協定的逐步描述，包括在記憶體中定位直譯器結構、安全存取內部欄位"
"以及觸發程式碼執行的技術。在適用的情況下會註明平台特有的變化，並包含範例實作"
"以闡明每個操作。"
#: ../../howto/remote_debugging.rst:117
msgid "Locating the PyRuntime structure"
msgstr "定位 PyRuntime 結構"
#: ../../howto/remote_debugging.rst:119
msgid ""
"CPython places the ``PyRuntime`` structure in a dedicated binary section to "
"help external tools find it at runtime. The name and format of this section "
"vary by platform. For example, ``.PyRuntime`` is used on ELF systems, and "
"``__DATA,__PyRuntime`` is used on macOS. Tools can find the offset of this "
"structure by examining the binary on disk."
msgstr ""
"CPython 將 ``PyRuntime`` 結構放置在專用的二進位區段（section）中，以幫助外部"
"工具在 runtime 找到它。此區段的名稱和格式因平台而異。例如，ELF 系統使用 ``."
"PyRuntime``、macOS 使用 ``__DATA,__PyRuntime``。工具可以透過檢查磁碟上的二進"
"位檔案來找到此結構的偏移量。"
#: ../../howto/remote_debugging.rst:125
msgid ""
"The ``PyRuntime`` structure contains CPython’s global interpreter state and "
"provides access to other internal data, including the list of interpreters, "
"thread states, and debugger support fields."
msgstr ""
"``PyRuntime`` 結構包含 CPython 的全域直譯器狀態，並可存取其他內部資料，包括直"
"譯器清單、執行緒狀態和偵錯器支援欄位。"
#: ../../howto/remote_debugging.rst:129
msgid ""
"To work with a remote Python process, a debugger must first find the memory "
"address of the ``PyRuntime`` structure in the target process. This address "
"can’t be hardcoded or calculated from a symbol name, because it depends on "
"where the operating system loaded the binary."
msgstr ""
"要與遠端 Python 行程協作，偵錯器必須首先找到目標行程中 ``PyRuntime`` 結構的記"
"憶體位址。此位址無法寫死或從符號名稱計算出，因為它取決於作業系統載入二進位檔"
"案的位置。"
#: ../../howto/remote_debugging.rst:134
msgid ""
"The method for finding ``PyRuntime`` depends on the platform, but the steps "
"are the same in general:"
msgstr "尋找 ``PyRuntime`` 的方法取決於平台，但步驟大致相同："
#: ../../howto/remote_debugging.rst:137
msgid ""
"Find the base address where the Python binary or shared library was loaded "
"in the target process."
msgstr "找到目標行程中 Python 二進位檔案或共享函式庫被載入的基底位址。"
#: ../../howto/remote_debugging.rst:139
msgid ""
"Use the on-disk binary to locate the offset of the ``.PyRuntime`` section."
msgstr "使用磁碟上的二進位檔案來定位 ``.PyRuntime`` 區段的偏移量。"
#: ../../howto/remote_debugging.rst:140
msgid ""
"Add the section offset to the base address to compute the address in memory."
msgstr "將區段偏移量加到基底位址以計算記憶體中的位址。"
#: ../../howto/remote_debugging.rst:142
msgid ""
"The sections below explain how to do this on each supported platform and "
"include example code."
msgstr "以下各節說明如何在每個支援的平台上執行此操作，並包含範例程式碼。"
#: ../../howto/remote_debugging.rst:146
msgid "Linux (ELF)"
msgstr "Linux (ELF)"
#: ../../howto/remote_debugging.rst:147
msgid "To find the ``PyRuntime`` structure on Linux:"
msgstr "在 Linux 上尋找 ``PyRuntime`` 結構："
#: ../../howto/remote_debugging.rst:149
msgid ""
"Read the process’s memory map (for example, ``/proc/<pid>/maps``) to find "
"the address where the Python executable or ``libpython`` was loaded."
msgstr ""
"讀取行程的記憶體對映（例如 ``/proc/<pid>/maps``）以找到 Python 可執行檔位址"
"或 ``libpython`` 被載入的位址。"
#: ../../howto/remote_debugging.rst:151
msgid ""
"Parse the ELF section headers in the binary to get the offset of the ``."
"PyRuntime`` section."
msgstr "剖析二進位檔案中的 ELF 區段標頭以取得 ``.PyRuntime`` 區段的偏移量。"
#: ../../howto/remote_debugging.rst:153
msgid ""
"Add that offset to the base address from step 1 to get the memory address of "
"``PyRuntime``."
msgstr "將該偏移量加到步驟 1 的基底位址以取得 ``PyRuntime`` 的記憶體位址。"
#: ../../howto/remote_debugging.rst:156 ../../howto/remote_debugging.rst:218
#: ../../howto/remote_debugging.rst:288 ../../howto/remote_debugging.rst:557
msgid "The following is an example implementation::"
msgstr "以下是一個範例實作： ::"
#: ../../howto/remote_debugging.rst:158
msgid ""
"def find_py_runtime_linux(pid: int) -> int:\n"
" # Step 1: Try to find the Python executable in memory\n"
" binary_path, base_address = find_mapped_binary(\n"
" pid, name_contains=\"python\"\n"
" )\n"
"\n"
" # Step 2: Fallback to shared library if executable is not found\n"
" if binary_path is None:\n"
" binary_path, base_address = find_mapped_binary(\n"
" pid, name_contains=\"libpython\"\n"
" )\n"
"\n"
" # Step 3: Parse ELF headers to get .PyRuntime section offset\n"
" section_offset = parse_elf_section_offset(\n"
" binary_path, \".PyRuntime\"\n"
" )\n"
"\n"
" # Step 4: Compute PyRuntime address in memory\n"
" return base_address + section_offset"
msgstr ""
"def find_py_runtime_linux(pid: int) -> int:\n"
" # 步驟 1：嘗試在記憶體中找到 Python 可執行檔\n"
" binary_path, base_address = find_mapped_binary(\n"
" pid, name_contains=\"python\"\n"
" )\n"
"\n"
" # 步驟 2：如果找不到可執行檔，則改用共享函式庫\n"
" if binary_path is None:\n"
" binary_path, base_address = find_mapped_binary(\n"
" pid, name_contains=\"libpython\"\n"
" )\n"
"\n"
" # 步驟 3：剖析 ELF 標頭以取得 .PyRuntime 區段偏移量\n"
" section_offset = parse_elf_section_offset(\n"
" binary_path, \".PyRuntime\"\n"
" )\n"
"\n"
" # 步驟 4：計算 PyRuntime 在記憶體中的位址\n"
" return base_address + section_offset"
#: ../../howto/remote_debugging.rst:179
msgid ""
"On Linux systems, there are two main approaches to read memory from another "
"process. The first is through the ``/proc`` filesystem, specifically by "
"reading from ``/proc/[pid]/mem`` which provides direct access to the "
"process's memory. This requires appropriate permissions - either being the "
"same user as the target process or having root access. The second approach "
"is using the ``process_vm_readv()`` system call which provides a more "
"efficient way to copy memory between processes. While ptrace's "
"``PTRACE_PEEKTEXT`` operation can also be used to read memory, it is "
"significantly slower as it only reads one word at a time and requires "
"multiple context switches between the tracer and tracee processes."
msgstr ""
"在 Linux 系統上，有兩種主要方法可以從另一個行程讀取記憶體。第一種是透過 ``/"
"proc`` 檔案系統，特別是從 ``/proc/[pid]/mem`` 讀取，這提供了對行程記憶體的直"
"接存取。這需要適當的權限 - 要麼與目標行程是同一使用者，要麼就要擁有 root 存取"
"權限。第二種方法是使用 ``process_vm_readv()`` 系統呼叫，它提供了在行程之間複"
"製記憶體的更有效方式。雖然 ptrace 的 ``PTRACE_PEEKTEXT`` 操作也可以用來讀取記"
"憶體，但它明顯較慢，因為它一次只讀取一個字，並且需要追蹤器和被追蹤行程之間的"
"多次情境切換。"
#: ../../howto/remote_debugging.rst:190
msgid ""
"For parsing ELF sections, the process involves reading and interpreting the "
"ELF file format structures from the binary file on disk. The ELF header "
"contains a pointer to the section header table. Each section header contains "
"metadata about a section including its name (stored in a separate string "
"table), offset, and size. To find a specific section like .PyRuntime, you "
"need to walk through these headers and match the section name. The section "
"header then provides the offset where that section exists in the file, which "
"can be used to calculate its runtime address when the binary is loaded into "
"memory."
msgstr ""
"對於剖析 ELF 區段，該過程涉及從磁碟上的二進位檔案讀取並解釋 ELF 檔案格式結"
"構。ELF標頭包含指向區段標頭表的指標。每個區段標頭包含關於區段的中介資料，包括"
"其名稱（儲存在單獨的字串表中）、偏移量和大小。要找到像 .PyRuntime 這樣的特定"
"區段，你需要遍歷這些標頭並匹配區段名稱。然後區段標頭會提供該區段在檔案中存在"
"的偏移量，當二進位檔案載入到記憶體時，可以用它來計算 runtime 位址。"
#: ../../howto/remote_debugging.rst:199
msgid ""
"You can read more about the ELF file format in the `ELF specification "
"<https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_."
msgstr ""
"你可以在 `ELF 規範 <https://en.wikipedia.org/wiki/"
"Executable_and_Linkable_Format>`_\\ 中閱讀更多關於 ELF 檔案格式的資訊。"
#: ../../howto/remote_debugging.rst:204
msgid "macOS (Mach-O)"
msgstr "macOS (Mach-O)"
#: ../../howto/remote_debugging.rst:205
msgid "To find the ``PyRuntime`` structure on macOS:"
msgstr "在 macOS 上找 ``PyRuntime`` 結構："
#: ../../howto/remote_debugging.rst:207
msgid ""
"Call ``task_for_pid()`` to get the ``mach_port_t`` task port for the target "
"process. This handle is needed to read memory using APIs like "
"``mach_vm_read_overwrite`` and ``mach_vm_region``."
msgstr ""
"呼叫 ``task_for_pid()`` 以取得目標行程的 ``mach_port_t`` 任務埠 (task port)。"
"此控制代碼 (handle) 用於使用像 ``mach_vm_read_overwrite`` 和 "
"``mach_vm_region`` 這樣的 API 來讀取記憶體。"
#: ../../howto/remote_debugging.rst:210
msgid ""
"Scan the memory regions to find the one containing the Python executable or "
"``libpython``."
msgstr "掃描記憶體區域以找到包含 Python 可執行檔或 ``libpython`` 的區域。"
#: ../../howto/remote_debugging.rst:212
msgid ""
"Load the binary file from disk and parse the Mach-O headers to find the "
"section named ``PyRuntime`` in the ``__DATA`` segment. On macOS, symbol "
"names are automatically prefixed with an underscore, so the ``PyRuntime`` "
"symbol appears as ``_PyRuntime`` in the symbol table, but the section name "
"is not affected."
msgstr ""
"從磁碟載入二進位檔案並剖析 Mach-O 標頭以找到 ``__DATA`` 程式段（segment）中名"
"為 ``PyRuntime`` 的區段。在 macOS 上，符號名稱會自動加上底線前綴，因此 "
"``PyRuntime`` 符號在符號表中顯示為 ``_PyRuntime``，但區段名稱不受影響。"
#: ../../howto/remote_debugging.rst:220
msgid ""
"def find_py_runtime_macos(pid: int) -> int:\n"
" # Step 1: Get access to the process's memory\n"
" handle = get_memory_access_handle(pid)\n"
"\n"
" # Step 2: Try to find the Python executable in memory\n"
" binary_path, base_address = find_mapped_binary(\n"
" handle, name_contains=\"python\"\n"
" )\n"
"\n"
" # Step 3: Fallback to libpython if the executable is not found\n"
" if binary_path is None:\n"
" binary_path, base_address = find_mapped_binary(\n"
" handle, name_contains=\"libpython\"\n"
" )\n"
"\n"
" # Step 4: Parse Mach-O headers to get __DATA,__PyRuntime section offset\n"
" section_offset = parse_macho_section_offset(\n"
" binary_path, \"__DATA\", \"__PyRuntime\"\n"
" )\n"
"\n"
" # Step 5: Compute the PyRuntime address in memory\n"
" return base_address + section_offset"
msgstr ""
"def find_py_runtime_macos(pid: int) -> int:\n"
" # 步驟 1：取得對行程記憶體的存取權限\n"
" handle = get_memory_access_handle(pid)\n"
"\n"
" # 步驟 2：嘗試在記憶體中找到 Python 可執行檔\n"
" binary_path, base_address = find_mapped_binary(\n"
" handle, name_contains=\"python\"\n"
" )\n"
"\n"
" # 步驟 3：如果找不到可執行檔，則改用 libpython\n"
" if binary_path is None:\n"
" binary_path, base_address = find_mapped_binary(\n"
" handle, name_contains=\"libpython\"\n"
" )\n"
"\n"
" # 步驟 4：剖析 Mach-O 標頭以取得 __DATA,__PyRuntime 區段偏移量\n"
" section_offset = parse_macho_section_offset(\n"
" binary_path, \"__DATA\", \"__PyRuntime\"\n"
" )\n"
"\n"
" # 步驟 5：計算 PyRuntime 在記憶體中的位址\n"
" return base_address + section_offset"
#: ../../howto/remote_debugging.rst:243
msgid ""
"On macOS, accessing another process's memory requires using Mach-O specific "
"APIs and file formats. The first step is obtaining a ``task_port`` handle "
"via ``task_for_pid()``, which provides access to the target process's memory "
"space. This handle enables memory operations through APIs like "
"``mach_vm_read_overwrite()``."
msgstr ""
"在 macOS 上，存取另一個行程的記憶體需要使用 Mach-O 特定的 API 和檔案格式。第"
"一步是透過 ``task_for_pid()`` 取得 ``task_port`` 控制代碼，它提供對目標行程記"
"憶體空間的存取。此控制代碼透過像 ``mach_vm_read_overwrite()`` 這樣的 API 啟用"
"記憶體操作。"
#: ../../howto/remote_debugging.rst:249
msgid ""
"The process memory can be examined using ``mach_vm_region()`` to scan "
"through the virtual memory space, while ``proc_regionfilename()`` helps "
"identify which binary files are loaded at each memory region. When the "
"Python binary or library is found, its Mach-O headers need to be parsed to "
"locate the ``PyRuntime`` structure."
msgstr ""
"可以使用 ``mach_vm_region()`` 掃描虛擬記憶體空間來檢查行程記憶體，而 "
"``proc_regionfilename()`` 幫助識別在每個記憶體區域載入了哪些二進位檔案。當找"
"到 Python 二進位檔案或函式庫時，需要剖析其 Mach-O 標頭以定位 ``PyRuntime`` 結"
"構。"
#: ../../howto/remote_debugging.rst:254
msgid ""
"The Mach-O format organizes code and data into segments and sections. The "
"``PyRuntime`` structure lives in a section named ``__PyRuntime`` within the "
"``__DATA`` segment. The actual runtime address calculation involves finding "
"the ``__TEXT`` segment which serves as the binary's base address, then "
"locating the ``__DATA`` segment containing our target section. The final "
"address is computed by combining the base address with the appropriate "
"section offsets from the Mach-O headers."
msgstr ""
"Mach-O 格式將程式碼和資料組織成程式段和區段。``PyRuntime`` 結構位於 "
"``__DATA`` 程式段內名為 ``__PyRuntime`` 的區段中。實際的 runtime 位址計算涉及"
"找到作為二進位檔案基底位址的 ``__TEXT`` 程式段，然後定位包含我們目標區段的 "
"``__DATA`` 程式段。最終位址是透過將基底位址與來自 Mach-O 標頭的適當區段偏移量"
"組合來計算的。"
#: ../../howto/remote_debugging.rst:262
msgid ""
"Note that accessing another process's memory on macOS typically requires "
"elevated privileges - either root access or special security entitlements "
"granted to the debugging process."
msgstr ""
"請注意，在 macOS 上存取另一個行程的記憶體通常需要提升過後的權限 - 要麼是 "
"root 存取權限，要麼是授予偵錯行程的特殊安全授權。"
#: ../../howto/remote_debugging.rst:268
msgid "Windows (PE)"
msgstr "Windows (PE)"
#: ../../howto/remote_debugging.rst:269
msgid "To find the ``PyRuntime`` structure on Windows:"
msgstr "在 Windows 上找 ``PyRuntime`` 結構："
#: ../../howto/remote_debugging.rst:271
msgid ""
"Use the ToolHelp API to enumerate all modules loaded in the target process. "
"This is done using functions such as `CreateToolhelp32Snapshot <https://"
"learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-"
"createtoolhelp32snapshot>`_, `Module32First <https://learn.microsoft.com/en-"
"us/windows/win32/api/tlhelp32/nf-tlhelp32-module32first>`_, and "
"`Module32Next <https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/"
"nf-tlhelp32-module32next>`_."
msgstr ""
"使用 ToolHelp API 來列舉目標行程中載入的所有模組。這是使用諸如 "
"`CreateToolhelp32Snapshot <https://learn.microsoft.com/en-us/windows/win32/"
"api/tlhelp32/nf-tlhelp32-createtoolhelp32snapshot>`_、`Module32First "
"<https://learn.microsoft.com/en-us/windows/win32/api/tlhelp32/nf-tlhelp32-"
"module32first>`_ 和 `Module32Next <https://learn.microsoft.com/en-us/windows/"
"win32/api/tlhelp32/nf-tlhelp32-module32next>`_ 等函式來完成的。"
#: ../../howto/remote_debugging.rst:278
msgid ""
"Identify the module corresponding to :file:`python.exe` or :file:`python{XY}."
"dll`, where ``X`` and ``Y`` are the major and minor version numbers of the "
"Python version, and record its base address."
msgstr ""
"識別對應於 :file:`python.exe` 或 :file:`python{XY}.dll` 的模組，其中 ``X`` "
"和 ``Y`` 是Python 版本的主要和次要版本號，並記錄其基底位址。"
#: ../../howto/remote_debugging.rst:281
msgid ""
"Locate the ``PyRuntim`` section. Due to the PE format's 8-character limit on "
"section names (defined as ``IMAGE_SIZEOF_SHORT_NAME``), the original name "
"``PyRuntime`` is truncated. This section contains the ``PyRuntime`` "
"structure."
msgstr ""
"定位 ``PyRuntim`` 區段。由於 PE 格式對區段名稱有 8 個字元的限制（定義為 "
"``IMAGE_SIZEOF_SHORT_NAME``），所以原始名稱 ``PyRuntime`` 會被截斷。此區段包"
"含 ``PyRuntime`` 結構。"
#: ../../howto/remote_debugging.rst:285
msgid ""
"Retrieve the section’s relative virtual address (RVA) and add it to the base "
"address of the module."
msgstr ""
"檢索區段的相對虛擬位址 (RVA, relative virtual address) 並將其加到模組的基底位"
"址。"
#: ../../howto/remote_debugging.rst:290
msgid ""
"def find_py_runtime_windows(pid: int) -> int:\n"
" # Step 1: Try to find the Python executable in memory\n"
" binary_path, base_address = find_loaded_module(\n"
" pid, name_contains=\"python\"\n"
" )\n"
"\n"
" # Step 2: Fallback to shared pythonXY.dll if the executable is not\n"
" # found\n"
" if binary_path is None:\n"
" binary_path, base_address = find_loaded_module(\n"
" pid, name_contains=\"python3\"\n"
" )\n"
"\n"
" # Step 3: Parse PE section headers to get the RVA of the PyRuntime\n"
" # section. The section name appears as \"PyRuntim\" due to the\n"
" # 8-character limit defined by the PE format (IMAGE_SIZEOF_SHORT_NAME).\n"
" section_rva = parse_pe_section_offset(binary_path, \"PyRuntim\")\n"
"\n"
" # Step 4: Compute PyRuntime address in memory\n"
" return base_address + section_rva"
msgstr ""
"def find_py_runtime_windows(pid: int) -> int:\n"
" # 步驟 1：嘗試在記憶體中找到 Python 可執行檔\n"
" binary_path, base_address = find_loaded_module(\n"
" pid, name_contains=\"python\"\n"
" )\n"
"\n"
" # 步驟 2：如果找不到可執行檔，則改用共享函式庫 pythonXY.dll\n"
" if binary_path is None:\n"
" binary_path, base_address = find_loaded_module(\n"
" pid, name_contains=\"python3\"\n"
" )\n"
"\n"
" # 步驟 3：剖析 PE 區段標頭以取得 PyRuntime 區段的 RVA。\n"
" # 由於 PE 格式 (IMAGE_SIZEOF_SHORT_NAME) 有8 字元的限制，\n"
" # 區段名稱顯示為 \"PyRuntim\"。\n"
" section_rva = parse_pe_section_offset(binary_path, \"PyRuntim\")\n"
"\n"
" # 步驟 4：計算 PyRuntime 在記憶體中的位址\n"
" return base_address + section_rva"
#: ../../howto/remote_debugging.rst:312
msgid ""
"On Windows, accessing another process's memory requires using the Windows "
"API functions like ``CreateToolhelp32Snapshot()`` and ``Module32First()/"
"Module32Next()`` to enumerate loaded modules. The ``OpenProcess()`` function "
"provides a handle to access the target process's memory space, enabling "
"memory operations through ``ReadProcessMemory()``."
msgstr ""
"在 Windows 上，存取另一個行程的記憶體需要使用像 "
"``CreateToolhelp32Snapshot()`` 和 ``Module32First()/Module32Next()`` 這樣的 "
"Windows API 函式來列舉載入的模組。``OpenProcess()`` 函式提供一個控制代碼來存"
"取目標行程的記憶體空間，並透過 ``ReadProcessMemory()`` 啟用記憶體操作。"
#: ../../howto/remote_debugging.rst:318
msgid ""
"The process memory can be examined by enumerating loaded modules to find the "
"Python binary or DLL. When found, its PE headers need to be parsed to locate "
"the ``PyRuntime`` structure."
msgstr ""
"可以透過列舉載入的模組來檢查行程記憶體，以找到 Python 二進位檔案或 DLL。找到"
"後，需要剖析其 PE 標頭以定位 ``PyRuntime`` 結構。"
#: ../../howto/remote_debugging.rst:322
msgid ""
"The PE format organizes code and data into sections. The ``PyRuntime`` "
"structure lives in a section named \"PyRuntim\" (truncated from "
"\"PyRuntime\" due to PE's 8-character name limit). The actual runtime "
"address calculation involves finding the module's base address from the "
"module entry, then locating our target section in the PE headers. The final "
"address is computed by combining the base address with the section's virtual "
"address from the PE section headers."
msgstr ""
"PE 格式將程式碼和資料組織成區段。``PyRuntime`` 結構位於名為 \"PyRuntim\" 的區"
"段中（由於 PE 的 8 字元名稱限制，從 \"PyRuntime\" 截斷）。實際的 runtime 位址"
"計算涉及從模組項目中找到模組的基底位址，然後在 PE 標頭中定位我們的目標區段。"
"最終位址是透過將基底位址與 PE 區段標頭中的區段虛擬位址組合來計算的。"
#: ../../howto/remote_debugging.rst:329
msgid ""
"Note that accessing another process's memory on Windows typically requires "
"appropriate privileges - either administrative access or the "
"``SeDebugPrivilege`` privilege granted to the debugging process."
msgstr ""
"請注意，在 Windows 上存取另一個行程的記憶體通常需要適當的權限 - 要麼是系統管"
"理員存取權限，要麼是授予偵錯行程的 ``SeDebugPrivilege`` 權限。"
#: ../../howto/remote_debugging.rst:335
msgid "Reading _Py_DebugOffsets"
msgstr "讀取 _Py_DebugOffsets"
#: ../../howto/remote_debugging.rst:337
msgid ""
"Once the address of the ``PyRuntime`` structure has been determined, the "
"next step is to read the ``_Py_DebugOffsets`` structure located at the "
"beginning of the ``PyRuntime`` block."
msgstr ""
"一旦確定了 ``PyRuntime`` 結構的位址，下一步就是讀取位於 ``PyRuntime`` 區塊開"
"頭的 ``_Py_DebugOffsets`` 結構。"
#: ../../howto/remote_debugging.rst:341
msgid ""
"This structure provides version-specific field offsets that are needed to "
"safely read interpreter and thread state memory. These offsets vary between "
"CPython versions and must be checked before use to ensure they are "
"compatible."
msgstr ""
"此結構提供了安全讀取直譯器和執行緒狀態記憶體所需的版本特定欄位偏移量。這些偏"
"移量在不同的 CPython 版本之間有所不同，必須在使用前檢查以確保它們相容。"
#: ../../howto/remote_debugging.rst:345
msgid "To read and check the debug offsets, follow these steps:"
msgstr "要讀取並檢查偵錯偏移量，請按照以下步驟操作："
#: ../../howto/remote_debugging.rst:347
msgid ""
"Read memory from the target process starting at the ``PyRuntime`` address, "
"covering the same number of bytes as the ``_Py_DebugOffsets`` structure. "
"This structure is located at the very start of the ``PyRuntime`` memory "
"block. Its layout is defined in CPython’s internal headers and stays the "
"same within a given minor version, but may change in major versions."
msgstr ""
"從目標行程中的 ``PyRuntime`` 位址開始讀取記憶體，涵蓋與 ``_Py_DebugOffsets`` "
"結構相同的位元組數。此結構位於 ``PyRuntime`` 記憶體區塊的最開始處。其佈局 "
"(layout) 在 CPython 的內部標頭中定義，並在給定的次要版本中維持不變，但在主要"
"版本中可能會更改。"
#: ../../howto/remote_debugging.rst:353
msgid "Check that the structure contains valid data:"
msgstr "檢查結構是否包含有效資料："
#: ../../howto/remote_debugging.rst:355
msgid "The ``cookie`` field must match the expected debug marker."
msgstr "``cookie`` 欄位必須匹配預期的偵錯標記。"
#: ../../howto/remote_debugging.rst:356
msgid ""
"The ``version`` field must match the version of the Python interpreter used "
"by the debugger."
msgstr "``version`` 欄位必須匹配偵錯器使用的 Python 直譯器版本。"
#: ../../howto/remote_debugging.rst:358
msgid ""
"If either the debugger or the target process is using a pre-release version "
"(for example, an alpha, beta, or release candidate), the versions must match "
"exactly."
msgstr ""
"如果偵錯器或目標行程使用的是預發行版本（例如 alpha、beta 或候選版本），版本必"
"須完全匹配。"
#: ../../howto/remote_debugging.rst:361
msgid ""
"The ``free_threaded`` field must have the same value in both the debugger "
"and the target process."
msgstr "``free_threaded`` 欄位在偵錯器和目標行程中必須具有相同的值。"
#: ../../howto/remote_debugging.rst:364
msgid ""
"If the structure is valid, the offsets it contains can be used to locate "
"fields in memory. If any check fails, the debugger should stop the operation "
"to avoid reading memory in the wrong format."
msgstr ""
"如果結構有效，其中包含的偏移量可用於定位記憶體中的欄位。如果任何檢查失敗，偵"
"錯器應停止操作以避免以錯誤的格式讀取記憶體。"
#: ../../howto/remote_debugging.rst:368
msgid ""
"The following is an example implementation that reads and checks "
"``_Py_DebugOffsets``::"
msgstr "以下是一個讀取並檢查 ``_Py_DebugOffsets`` 的範例實作： ::"
#: ../../howto/remote_debugging.rst:371
msgid ""
"def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:\n"
" # Step 1: Read memory from the target process at the PyRuntime address\n"
" data = read_process_memory(\n"
" pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE\n"
" )\n"
"\n"
" # Step 2: Deserialize the raw bytes into a _Py_DebugOffsets structure\n"
" debug_offsets = parse_debug_offsets(data)\n"
"\n"
" # Step 3: Validate the contents of the structure\n"
" if debug_offsets.cookie != EXPECTED_COOKIE:\n"
" raise RuntimeError(\"Invalid or missing debug cookie\")\n"
" if debug_offsets.version != LOCAL_PYTHON_VERSION:\n"
" raise RuntimeError(\n"
" \"Mismatch between caller and target Python versions\"\n"
" )\n"
" if debug_offsets.free_threaded != LOCAL_FREE_THREADED:\n"
" raise RuntimeError(\"Mismatch in free-threaded configuration\")\n"
"\n"
" return debug_offsets"
msgstr ""
"def read_debug_offsets(pid: int, py_runtime_addr: int) -> DebugOffsets:\n"
" # 步驟 1：在 PyRuntime 位址從目標行程讀取記憶體\n"
" data = read_process_memory(\n"
" pid, address=py_runtime_addr, size=DEBUG_OFFSETS_SIZE\n"
" )\n"
"\n"
" # 步驟 2：將原始位元組反序列化為 _Py_DebugOffsets 結構\n"
" debug_offsets = parse_debug_offsets(data)\n"
"\n"
" # 步驟 3：驗證結構的內容\n"
" if debug_offsets.cookie != EXPECTED_COOKIE:\n"
" raise RuntimeError(\"Invalid or missing debug cookie\")\n"
" if debug_offsets.version != LOCAL_PYTHON_VERSION:\n"
" raise RuntimeError(\n"
" \"Mismatch between caller and target Python versions\"\n"
" )\n"
" if debug_offsets.free_threaded != LOCAL_FREE_THREADED:\n"
" raise RuntimeError(\"Mismatch in free-threaded configuration\")\n"
"\n"
" return debug_offsets"
#: ../../howto/remote_debugging.rst:396
msgid "**Process suspension recommended**"
msgstr "**建議暫停行程**"
#: ../../howto/remote_debugging.rst:398
msgid ""
"To avoid race conditions and ensure memory consistency, it is strongly "
"recommended that the target process be suspended before performing any "
"operations that read or write internal interpreter state. The Python runtime "
"may concurrently mutate interpreter data structures—such as creating or "
"destroying threads—during normal execution. This can result in invalid "
"memory reads or writes."
msgstr ""
"為了避免競態條件 (race conditions) 並確保記憶體一致性，強烈建議在執行任何讀取"
"或寫入內部直譯器狀態的操作之前暫停目標行程。Python runtime 可能在正常執行期間"
"同時變更直譯器資料結構 - 例如建立或銷毀執行緒。這可能導致無效的記憶體讀取或寫"
"入。"
#: ../../howto/remote_debugging.rst:405
msgid ""
"A debugger may suspend execution by attaching to the process with ``ptrace`` "
"or by sending a ``SIGSTOP`` signal. Execution should only be resumed after "
"debugger-side memory operations are complete."
msgstr ""
"偵錯器可以透過使用 ``ptrace`` 附加到行程或發送 ``SIGSTOP`` 訊號來暫停執行。只"
"有在偵錯器端的記憶體操作完成後才應恢復執行。"
#: ../../howto/remote_debugging.rst:411
msgid ""
"Some tools, such as profilers or sampling-based debuggers, may operate on a "
"running process without suspension. In such cases, tools must be explicitly "
"designed to handle partially updated or inconsistent memory. For most "
"debugger implementations, suspending the process remains the safest and most "
"robust approach."
msgstr ""
"一些工具，例如分析器 (profilers) 或基於取樣的偵錯器，可能在不暫停的情況下對正"
"在執行的行程進行操作。在這種情況下，工具必須明確設計為能夠處理部分更新或不一"
"致的記憶體。對於大多數偵錯器實作來說，暫停行程仍然是最安全可靠的方法。"
#: ../../howto/remote_debugging.rst:419
msgid "Locating the interpreter and thread state"
msgstr "定位直譯器和執行緒狀態"
#: ../../howto/remote_debugging.rst:421
msgid ""
"Before code can be injected and executed in a remote Python process, the "
"debugger must choose a thread in which to schedule execution. This is "
"necessary because the control fields used to perform remote code injection "
"are located in the ``_PyRemoteDebuggerSupport`` structure, which is embedded "
"in a ``PyThreadState`` object. These fields are modified by the debugger to "
"request execution of injected scripts."
msgstr ""
"在可以於遠端 Python 行程中注入並執行程式碼之前，偵錯器必須選擇一個用於排程執"
"行的執行緒。這是必要的，因為用於執行遠端程式碼注入的控制欄位位於 "
"``_PyRemoteDebuggerSupport`` 結構中，該結構嵌入在 ``PyThreadState`` 物件中。"
"偵錯器會修改這些欄位以請求執行注入的腳本。"
#: ../../howto/remote_debugging.rst:428
msgid ""
"The ``PyThreadState`` structure represents a thread running inside a Python "
"interpreter. It maintains the thread’s evaluation context and contains the "
"fields required for debugger coordination. Locating a valid "
"``PyThreadState`` is therefore a key prerequisite for triggering execution "
"remotely."
msgstr ""
"``PyThreadState`` 結構代表在 Python 直譯器內執行的執行緒。它維護執行緒的求值"
"情境 (evaluation context)，並包含偵錯器協調所需的欄位。因此，定位有效的 "
"``PyThreadState`` 是遠端觸發執行的關鍵前提。"
#: ../../howto/remote_debugging.rst:433
msgid ""
"A thread is typically selected based on its role or ID. In most cases, the "
"main thread is used, but some tools may target a specific thread by its "
"native thread ID. Once the target thread is chosen, the debugger must locate "
"both the interpreter and the associated thread state structures in memory."
msgstr ""
"通常根據執行緒的角色或 ID 來選擇執行緒。在大多數情況下會使用主執行緒，但某些"
"工具可能會透過其原生執行緒 ID 來定位特定執行緒。一旦選擇了目標執行緒，偵錯器"
"必須在記憶體中定位直譯器和相關的執行緒狀態結構。"
#: ../../howto/remote_debugging.rst:438
msgid "The relevant internal structures are defined as follows:"
msgstr "相關的內部結構定義如下："
#: ../../howto/remote_debugging.rst:440
msgid ""
"``PyInterpreterState`` represents an isolated Python interpreter instance. "
"Each interpreter maintains its own set of imported modules, built-in state, "
"and thread state list. Although most Python applications use a single "
"interpreter, CPython supports multiple interpreters in the same process."
msgstr ""
"``PyInterpreterState`` 代表一個隔離的 Python 直譯器實例。每個直譯器維護自己的"
"一組已引入模組、內建狀態和執行緒狀態串列。雖然大多數 Python 應用程式使用單一"
"直譯器，但 CPython 支援在同一行程中使用多個直譯器。"
#: ../../howto/remote_debugging.rst:445
msgid ""
"``PyThreadState`` represents a thread running within an interpreter. It "
"contains execution state and the control fields used by the debugger."
msgstr ""
"``PyThreadState`` 代表在直譯器內運行的執行緒。它包含執行狀態和偵錯器使用的控"
"制欄位。"
#: ../../howto/remote_debugging.rst:448
msgid "To locate a thread:"
msgstr "要定位執行緒："
#: ../../howto/remote_debugging.rst:450
msgid ""
"Use the offset ``runtime_state.interpreters_head`` to obtain the address of "
"the first interpreter in the ``PyRuntime`` structure. This is the entry "
"point to the linked list of active interpreters."
msgstr ""
"使用偏移量 ``runtime_state.interpreters_head`` 來取得 ``PyRuntime`` 結構中第"
"一個直譯器的位址。這是活動直譯器鏈結串列的進入點。"
#: ../../howto/remote_debugging.rst:454
msgid ""
"Use the offset ``interpreter_state.threads_main`` to access the main thread "
"state associated with the selected interpreter. This is typically the most "
"reliable thread to target."
msgstr ""
"使用偏移量 ``interpreter_state.threads_main`` 來存取與所選直譯器相關的主執行"
"緒狀態。這通常是最可靠的目標執行緒。"
#: ../../howto/remote_debugging.rst:458
msgid ""
"Optionally, use the offset ``interpreter_state.threads_head`` to iterate "
"through the linked list of all thread states. Each ``PyThreadState`` "
"structure contains a ``native_thread_id`` field, which may be compared to a "
"target thread ID to find a specific thread."
msgstr ""
"可選地使用偏移量 ``interpreter_state.threads_head`` 來遍歷所有執行緒狀態的鏈"
"結串列。每個 ``PyThreadState`` 結構包含一個 ``native_thread_id`` 欄位，可以將"
"其與目標執行緒 ID 進行比較以找到特定執行緒。"
#: ../../howto/remote_debugging.rst:463
msgid ""
"Once a valid ``PyThreadState`` has been found, its address can be used in "
"later steps of the protocol, such as writing debugger control fields and "
"scheduling execution."
msgstr ""
"一旦找到有效的 ``PyThreadState``，其位址可以在協定的後續步驟中使用，例如寫入"
"偵錯器控制欄位和排程執行。"
#: ../../howto/remote_debugging.rst:467
msgid ""
"The following is an example implementation that locates the main thread "
"state::"
msgstr "以下是一個定位主執行緒狀態的範例實作： ::"
#: ../../howto/remote_debugging.rst:469
msgid ""
"def find_main_thread_state(\n"
" pid: int, py_runtime_addr: int, debug_offsets: DebugOffsets,\n"
") -> int:\n"
" # Step 1: Read interpreters_head from PyRuntime\n"
" interp_head_ptr = (\n"