Compare commits
96 Commits
binutils-m
...
gdb-9.1-mc
Author | SHA1 | Date |
---|---|---|
Alibek Omarov | b021dfea95 | |
Joel Brobecker | 49526e9359 | |
Joel Brobecker | 97bfc9ea88 | |
Joel Brobecker | 899016d49d | |
GDB Administrator | 2c8e4c9fba | |
Iain Buclaw | f49692dff8 | |
Iain Buclaw | ff491e6bfc | |
Tom Tromey | 76f5096cd4 | |
GDB Administrator | 168359c1b5 | |
GDB Administrator | cab7b99a4f | |
GDB Administrator | 6eb28a37e9 | |
GDB Administrator | e0d936418a | |
GDB Administrator | 4d37e9a90b | |
GDB Administrator | 99a0005346 | |
Sergio Durigan Junior | 1aa93c3a9b | |
Eli Zaretskii | 50500ecfef | |
GDB Administrator | 7437a7ef50 | |
GDB Administrator | 1ca56c96a4 | |
GDB Administrator | a11ceee48d | |
GDB Administrator | caeb863eda | |
Hannes Domani | 42cce0e4fc | |
GDB Administrator | 8d197d83a1 | |
GDB Administrator | 85e069727b | |
GDB Administrator | 069022c5b3 | |
GDB Administrator | 99075aaca1 | |
GDB Administrator | 937d3d4a1f | |
GDB Administrator | 0b25a5d915 | |
GDB Administrator | eb886d58a2 | |
GDB Administrator | 832bd9e9c9 | |
GDB Administrator | 283eb89897 | |
GDB Administrator | 0d4f8ed80a | |
GDB Administrator | 62723af4cc | |
Joel Brobecker | 043a001093 | |
GDB Administrator | a3cf234200 | |
GDB Administrator | 7f92ae2824 | |
GDB Administrator | 17524e099d | |
GDB Administrator | 6c54147084 | |
GDB Administrator | 7e36ff586d | |
GDB Administrator | 3e353caee1 | |
GDB Administrator | 55cca6cf13 | |
Christian Biesinger | 975292a976 | |
GDB Administrator | ad5e26527f | |
GDB Administrator | 7e95250e16 | |
GDB Administrator | cd57c637b2 | |
Tom Tromey | 3c473fad8f | |
GDB Administrator | 6b3a34ea87 | |
Andrew Burgess | f7da8e5b9b | |
GDB Administrator | f231cbc17e | |
Eli Zaretskii | 84baa6a515 | |
Joel Brobecker | 6f6d0a0778 | |
Joel Brobecker | b8e46eb9a1 | |
Joel Brobecker | 11bc5fe47f | |
Joel Brobecker | 8b371634b4 | |
Joel Brobecker | a292f79fbd | |
Joel Brobecker | 1458b0f311 | |
Joel Brobecker | e9de78be1c | |
GDB Administrator | e33a4274ee | |
GDB Administrator | 3f83406160 | |
GDB Administrator | 4955678c8c | |
GDB Administrator | bf957be6f3 | |
GDB Administrator | 05989f5ecc | |
GDB Administrator | 7332f2844c | |
GDB Administrator | f9d7b63705 | |
GDB Administrator | af76fcf70f | |
GDB Administrator | c86ec09cd9 | |
GDB Administrator | 0e64a4e283 | |
Christian Biesinger | c0716f3e64 | |
GDB Administrator | 2030d2b12e | |
GDB Administrator | f987988860 | |
GDB Administrator | 8aeb92e18d | |
Eli Zaretskii | b36fbdf11c | |
GDB Administrator | a0f6c91734 | |
GDB Administrator | 34f3d48420 | |
Eli Zaretskii | 5c91fe6ebb | |
Eli Zaretskii | 527178f70a | |
GDB Administrator | 200d296cf3 | |
GDB Administrator | 0c21cc55c7 | |
GDB Administrator | 32e6bcdb5d | |
Tom Tromey | 4ae7258edf | |
Tom Tromey | 1c66314dcb | |
GDB Administrator | f0ee30bfb0 | |
Simon Marchi | be19b69991 | |
GDB Administrator | 1bc50c51fd | |
GDB Administrator | b6778b5b30 | |
Christian Biesinger | 59e99adeed | |
GDB Administrator | 8bad7749dc | |
Andrew Burgess | b547b1310d | |
GDB Administrator | 17a03c954d | |
GDB Administrator | 5d4b673fc6 | |
GDB Administrator | 25d38fd3d5 | |
Joel Brobecker | 3f43467191 | |
Joel Brobecker | 07d5aa38fd | |
Joel Brobecker | b06b54862e | |
Joel Brobecker | 41ec388bf2 | |
Joel Brobecker | 1c47c133d2 | |
Joel Brobecker | c87abc5019 |
14
ChangeLog
14
ChangeLog
|
@ -1,3 +1,17 @@
|
|||
2020-02-01 Sergio Durigan Junior <sergiodj@redhat.com>
|
||||
|
||||
* configure.ac: Don't abort the build if trying to build GDB in tree
|
||||
_and_ invoking with '--enable-src-release-build'.
|
||||
* configure: Regenerate.
|
||||
* src-release.sh (do_proto_toplev): Invoke 'configure' using
|
||||
'--enable-src-release-build'.
|
||||
|
||||
2020-01-17 Joel Brobecker <brobecker@adacore.com>
|
||||
|
||||
* configure.ac: Abort the build with an error if trying to build
|
||||
GDB in tree.
|
||||
* configure: Regenerate.
|
||||
|
||||
2019-10-17 Sergio Durigan Junior <sergiodj@redhat.com>
|
||||
|
||||
* src-release.sh (GDB_SUPPORT_DIRS): Add libctf.
|
||||
|
|
|
@ -1,3 +1,7 @@
|
|||
2019-12-11 Joel Brobecker <brobecker@adacore.com>
|
||||
|
||||
* development.sh (development): Set to false.
|
||||
|
||||
2019-12-11 Alan Modra <amodra@gmail.com>
|
||||
|
||||
* elf32-rx.c (elf32_rx_relax_section): Avoid signed overflow.
|
||||
|
|
|
@ -74,7 +74,7 @@ BFD32_LIBS = \
|
|||
coff-bfd.lo compress.lo corefile.lo elf-properties.lo format.lo \
|
||||
hash.lo init.lo libbfd.lo linker.lo merge.lo opncls.lo reloc.lo \
|
||||
section.lo simple.lo stab-syms.lo stabs.lo syms.lo targets.lo \
|
||||
binary.lo ihex.lo srec.lo tekhex.lo verilog.lo
|
||||
binary.lo ihex.lo srec.lo tekhex.lo verilog.lo eir.lo
|
||||
|
||||
BFD64_LIBS = archive64.lo
|
||||
|
||||
|
@ -83,7 +83,7 @@ BFD32_LIBS_CFILES = \
|
|||
compress.c corefile.c elf-properties.c format.c hash.c \
|
||||
init.c libbfd.c linker.c merge.c opncls.c reloc.c \
|
||||
section.c simple.c stab-syms.c stabs.c syms.c targets.c \
|
||||
binary.c ihex.c srec.c tekhex.c verilog.c
|
||||
binary.c ihex.c srec.c tekhex.c verilog.c eir.c
|
||||
|
||||
BFD64_LIBS_CFILES = archive64.c
|
||||
|
||||
|
@ -104,6 +104,7 @@ ALL_MACHINES = \
|
|||
cpu-d10v.lo \
|
||||
cpu-d30v.lo \
|
||||
cpu-dlx.lo \
|
||||
cpu-e2k.lo \
|
||||
cpu-epiphany.lo \
|
||||
cpu-fr30.lo \
|
||||
cpu-frv.lo \
|
||||
|
@ -190,6 +191,7 @@ ALL_MACHINES_CFILES = \
|
|||
cpu-d10v.c \
|
||||
cpu-d30v.c \
|
||||
cpu-dlx.c \
|
||||
cpu-e2k.c \
|
||||
cpu-epiphany.c \
|
||||
cpu-fr30.c \
|
||||
cpu-frv.c \
|
||||
|
@ -308,6 +310,8 @@ BFD32_BACKENDS = \
|
|||
elf32-d10v.lo \
|
||||
elf32-d30v.lo \
|
||||
elf32-dlx.lo \
|
||||
elf32-e2k.lo \
|
||||
elf32-e2k-pm.lo \
|
||||
elf32-epiphany.lo \
|
||||
elf32-fr30.lo \
|
||||
elf32-frv.lo \
|
||||
|
@ -359,6 +363,7 @@ BFD32_BACKENDS = \
|
|||
elf32-xtensa.lo \
|
||||
elf32.lo \
|
||||
elflink.lo \
|
||||
elfxx-e2k.lo \
|
||||
elfxx-sparc.lo \
|
||||
elfxx-tilegx.lo \
|
||||
i386aout.lo \
|
||||
|
@ -444,6 +449,8 @@ BFD32_BACKENDS_CFILES = \
|
|||
elf32-d10v.c \
|
||||
elf32-d30v.c \
|
||||
elf32-dlx.c \
|
||||
elf32-e2k.c \
|
||||
elf32-e2k-pm.c \
|
||||
elf32-epiphany.c \
|
||||
elf32-fr30.c \
|
||||
elf32-frv.c \
|
||||
|
@ -495,6 +502,7 @@ BFD32_BACKENDS_CFILES = \
|
|||
elf32-xtensa.c \
|
||||
elf32.c \
|
||||
elflink.c \
|
||||
elfxx-e2k.c \
|
||||
elfxx-sparc.c \
|
||||
elfxx-tilegx.c \
|
||||
i386aout.c \
|
||||
|
@ -553,6 +561,7 @@ BFD64_BACKENDS = \
|
|||
elf32-score.lo \
|
||||
elf32-score7.lo \
|
||||
elf64-alpha.lo \
|
||||
elf64-e2k.lo \
|
||||
elf64-gen.lo \
|
||||
elf64-hppa.lo \
|
||||
elf64-ia64.lo \
|
||||
|
@ -594,6 +603,7 @@ BFD64_BACKENDS_CFILES = \
|
|||
elf32-score.c \
|
||||
elf32-score7.c \
|
||||
elf64-alpha.c \
|
||||
elf64-e2k.c \
|
||||
elf64-gen.c \
|
||||
elf64-hppa.c \
|
||||
elf64-ia64-vms.c \
|
||||
|
|
|
@ -186,7 +186,7 @@ am__objects_1 = archive.lo archures.lo bfd.lo bfdio.lo bfdwin.lo \
|
|||
format.lo hash.lo init.lo libbfd.lo linker.lo merge.lo \
|
||||
opncls.lo reloc.lo section.lo simple.lo stab-syms.lo stabs.lo \
|
||||
syms.lo targets.lo binary.lo ihex.lo srec.lo tekhex.lo \
|
||||
verilog.lo
|
||||
verilog.lo eir.lo
|
||||
am_libbfd_la_OBJECTS = $(am__objects_1)
|
||||
libbfd_la_OBJECTS = $(am_libbfd_la_OBJECTS)
|
||||
AM_V_lt = $(am__v_lt_@AM_V@)
|
||||
|
@ -499,7 +499,7 @@ BFD32_LIBS = \
|
|||
coff-bfd.lo compress.lo corefile.lo elf-properties.lo format.lo \
|
||||
hash.lo init.lo libbfd.lo linker.lo merge.lo opncls.lo reloc.lo \
|
||||
section.lo simple.lo stab-syms.lo stabs.lo syms.lo targets.lo \
|
||||
binary.lo ihex.lo srec.lo tekhex.lo verilog.lo
|
||||
binary.lo ihex.lo srec.lo tekhex.lo verilog.lo eir.lo
|
||||
|
||||
BFD64_LIBS = archive64.lo
|
||||
BFD32_LIBS_CFILES = \
|
||||
|
@ -507,7 +507,7 @@ BFD32_LIBS_CFILES = \
|
|||
compress.c corefile.c elf-properties.c format.c hash.c \
|
||||
init.c libbfd.c linker.c merge.c opncls.c reloc.c \
|
||||
section.c simple.c stab-syms.c stabs.c syms.c targets.c \
|
||||
binary.c ihex.c srec.c tekhex.c verilog.c
|
||||
binary.c ihex.c srec.c tekhex.c verilog.c eir.c
|
||||
|
||||
BFD64_LIBS_CFILES = archive64.c
|
||||
|
||||
|
@ -528,6 +528,7 @@ ALL_MACHINES = \
|
|||
cpu-d10v.lo \
|
||||
cpu-d30v.lo \
|
||||
cpu-dlx.lo \
|
||||
cpu-e2k.lo \
|
||||
cpu-epiphany.lo \
|
||||
cpu-fr30.lo \
|
||||
cpu-frv.lo \
|
||||
|
@ -614,6 +615,7 @@ ALL_MACHINES_CFILES = \
|
|||
cpu-d10v.c \
|
||||
cpu-d30v.c \
|
||||
cpu-dlx.c \
|
||||
cpu-e2k.c \
|
||||
cpu-epiphany.c \
|
||||
cpu-fr30.c \
|
||||
cpu-frv.c \
|
||||
|
@ -733,6 +735,8 @@ BFD32_BACKENDS = \
|
|||
elf32-d10v.lo \
|
||||
elf32-d30v.lo \
|
||||
elf32-dlx.lo \
|
||||
elf32-e2k.lo \
|
||||
elf32-e2k-pm.lo \
|
||||
elf32-epiphany.lo \
|
||||
elf32-fr30.lo \
|
||||
elf32-frv.lo \
|
||||
|
@ -784,6 +788,7 @@ BFD32_BACKENDS = \
|
|||
elf32-xtensa.lo \
|
||||
elf32.lo \
|
||||
elflink.lo \
|
||||
elfxx-e2k.lo \
|
||||
elfxx-sparc.lo \
|
||||
elfxx-tilegx.lo \
|
||||
i386aout.lo \
|
||||
|
@ -869,6 +874,8 @@ BFD32_BACKENDS_CFILES = \
|
|||
elf32-d10v.c \
|
||||
elf32-d30v.c \
|
||||
elf32-dlx.c \
|
||||
elf32-e2k.c \
|
||||
elf32-e2k-pm.c \
|
||||
elf32-epiphany.c \
|
||||
elf32-fr30.c \
|
||||
elf32-frv.c \
|
||||
|
@ -920,6 +927,7 @@ BFD32_BACKENDS_CFILES = \
|
|||
elf32-xtensa.c \
|
||||
elf32.c \
|
||||
elflink.c \
|
||||
elfxx-e2k.c \
|
||||
elfxx-sparc.c \
|
||||
elfxx-tilegx.c \
|
||||
i386aout.c \
|
||||
|
@ -979,6 +987,7 @@ BFD64_BACKENDS = \
|
|||
elf32-score.lo \
|
||||
elf32-score7.lo \
|
||||
elf64-alpha.lo \
|
||||
elf64-e2k.lo \
|
||||
elf64-gen.lo \
|
||||
elf64-hppa.lo \
|
||||
elf64-ia64.lo \
|
||||
|
@ -1020,6 +1029,7 @@ BFD64_BACKENDS_CFILES = \
|
|||
elf32-score.c \
|
||||
elf32-score7.c \
|
||||
elf64-alpha.c \
|
||||
elf64-e2k.c \
|
||||
elf64-gen.c \
|
||||
elf64-hppa.c \
|
||||
elf64-ia64-vms.c \
|
||||
|
@ -1346,6 +1356,7 @@ distclean-compile:
|
|||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-d10v.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-d30v.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-dlx.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-e2k.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-epiphany.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-fr30.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/cpu-frv.Plo@am__quote@
|
||||
|
@ -1420,6 +1431,7 @@ distclean-compile:
|
|||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/dwarf2.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ecoff.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/ecofflink.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/eir.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf-attrs.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf-eh-frame.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf-ifunc.Plo@am__quote@
|
||||
|
@ -1443,6 +1455,8 @@ distclean-compile:
|
|||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-d10v.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-d30v.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-dlx.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-e2k-pm.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-e2k.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-epiphany.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-fr30.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf32-frv.Plo@am__quote@
|
||||
|
@ -1500,6 +1514,7 @@ distclean-compile:
|
|||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-aarch64.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-alpha.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-bpf.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-e2k.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-gen.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-hppa.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elf64-ia64-vms.Plo@am__quote@
|
||||
|
@ -1517,6 +1532,7 @@ distclean-compile:
|
|||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elflink.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elfn32-mips.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elfxx-aarch64.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elfxx-e2k.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elfxx-ia64.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elfxx-mips.Plo@am__quote@
|
||||
@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/elfxx-riscv.Plo@am__quote@
|
||||
|
|
|
@ -131,9 +131,15 @@ DESCRIPTION
|
|||
.#define bfd_mach_sparc_v9m 20 {* with OSA2015 and M7 add'ns. *}
|
||||
.#define bfd_mach_sparc_v8plusm8 21 {* with OSA2017 and M8 add'ns. *}
|
||||
.#define bfd_mach_sparc_v9m8 22 {* with OSA2017 and M8 add'ns. *}
|
||||
.#define bfd_mach_sparc_v8plus_r1000 23 {* with r1000 add'ns. *}
|
||||
.#define bfd_mach_sparc_v9_r1000 24 {* with r1000 add'ns. *}
|
||||
.#define bfd_mach_sparc_v8plus_r2000 25 {* with r2000 add'ns. *}
|
||||
.#define bfd_mach_sparc_v9_r2000 26 {* with r2000 add'ns. *}
|
||||
.#define bfd_mach_sparc_v8plus_r2000_plus 27 {* with r2000+ add'ns. *}
|
||||
.#define bfd_mach_sparc_v9_r2000_plus 28 {* with r2000+ add'ns. *}
|
||||
.{* Nonzero if MACH has the v9 instruction set. *}
|
||||
.#define bfd_mach_sparc_v9_p(mach) \
|
||||
. ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9m8 \
|
||||
. ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9_mcst \
|
||||
. && (mach) != bfd_mach_sparc_sparclite_le)
|
||||
.{* Nonzero if MACH is a 64 bit sparc architecture. *}
|
||||
.#define bfd_mach_sparc_64bit_p(mach) \
|
||||
|
@ -144,7 +150,10 @@ DESCRIPTION
|
|||
. && (mach) != bfd_mach_sparc_v8pluse \
|
||||
. && (mach) != bfd_mach_sparc_v8plusv \
|
||||
. && (mach) != bfd_mach_sparc_v8plusm \
|
||||
. && (mach) != bfd_mach_sparc_v8plusm8)
|
||||
. && (mach) != bfd_mach_sparc_v8plusm8 \
|
||||
. && (mach) != bfd_mach_sparc_v8plus_r1000 \
|
||||
. && (mach) != bfd_mach_sparc_v8plus_r2000 \
|
||||
. && (mach) != bfd_mach_sparc_v8plus_r2000_plus)
|
||||
. bfd_arch_spu, {* PowerPC SPU. *}
|
||||
.#define bfd_mach_spu 256
|
||||
. bfd_arch_mips, {* MIPS Rxxxx. *}
|
||||
|
@ -513,6 +522,27 @@ DESCRIPTION
|
|||
. bfd_arch_lm32, {* Lattice Mico32. *}
|
||||
.#define bfd_mach_lm32 1
|
||||
. bfd_arch_microblaze,{* Xilinx MicroBlaze. *}
|
||||
. bfd_arch_e2k, {* MCST E2K. *}
|
||||
.{* It's crucial that the underlying `bfd_mach_e2k*' have the same values as *}
|
||||
.{* the corresponding `E_E2K_MACH_*'s!!! *}
|
||||
.#define bfd_mach_e2k_generic 0
|
||||
.#define bfd_mach_e2k_ev1 1
|
||||
.{* This is interpreted as the common subset of all Elbrus V2 iterations.
|
||||
. Currently it is the same as the common subset of all elbrus-2c+. *}
|
||||
.#define bfd_mach_e2k_ev2 2
|
||||
.#define bfd_mach_e2k_ev3 3
|
||||
.#define bfd_mach_e2k_ev4 4
|
||||
.#define bfd_mach_e2k_ev5 5
|
||||
.#define bfd_mach_e2k_ev6 6
|
||||
.{* Values 16, 17 and 18 used to be reserved for the first three iterations
|
||||
. of `elbrus-v2'. See `include/elf/e2k.h' for why they can't be reused right
|
||||
. now. *}
|
||||
.#define bfd_mach_e2k_8c 19
|
||||
.#define bfd_mach_e2k_1cplus 20
|
||||
.#define bfd_mach_e2k_12c 21
|
||||
.#define bfd_mach_e2k_16c 22
|
||||
.#define bfd_mach_e2k_2c3 23
|
||||
|
||||
. bfd_arch_tilepro, {* Tilera TILEPro. *}
|
||||
. bfd_arch_tilegx, {* Tilera TILE-Gx. *}
|
||||
.#define bfd_mach_tilepro 1
|
||||
|
@ -611,6 +641,7 @@ extern const bfd_arch_info_type bfd_d10v_arch;
|
|||
extern const bfd_arch_info_type bfd_d30v_arch;
|
||||
extern const bfd_arch_info_type bfd_dlx_arch;
|
||||
extern const bfd_arch_info_type bfd_bpf_arch;
|
||||
extern const bfd_arch_info_type bfd_e2k_arch;
|
||||
extern const bfd_arch_info_type bfd_epiphany_arch;
|
||||
extern const bfd_arch_info_type bfd_fr30_arch;
|
||||
extern const bfd_arch_info_type bfd_frv_arch;
|
||||
|
@ -702,6 +733,7 @@ static const bfd_arch_info_type * const bfd_archures_list[] =
|
|||
&bfd_d30v_arch,
|
||||
&bfd_dlx_arch,
|
||||
&bfd_bpf_arch,
|
||||
&bfd_e2k_arch,
|
||||
&bfd_epiphany_arch,
|
||||
&bfd_fr30_arch,
|
||||
&bfd_frv_arch,
|
||||
|
|
116
bfd/bfd-in2.h
116
bfd/bfd-in2.h
|
@ -1514,9 +1514,15 @@ enum bfd_architecture
|
|||
#define bfd_mach_sparc_v9m 20 /* with OSA2015 and M7 add'ns. */
|
||||
#define bfd_mach_sparc_v8plusm8 21 /* with OSA2017 and M8 add'ns. */
|
||||
#define bfd_mach_sparc_v9m8 22 /* with OSA2017 and M8 add'ns. */
|
||||
#define bfd_mach_sparc_v8plus_r1000 23 /* with r1000 add'ns. */
|
||||
#define bfd_mach_sparc_v9_r1000 24 /* with r1000 add'ns. */
|
||||
#define bfd_mach_sparc_v8plus_r2000 25 /* with r2000 add'ns. */
|
||||
#define bfd_mach_sparc_v9_r2000 26 /* with r2000 add'ns. */
|
||||
#define bfd_mach_sparc_v8plus_r2000_plus 27 /* with r2000+ add'ns. */
|
||||
#define bfd_mach_sparc_v9_r2000_plus 28 /* with r2000+ add'ns. */
|
||||
/* Nonzero if MACH has the v9 instruction set. */
|
||||
#define bfd_mach_sparc_v9_p(mach) \
|
||||
((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9m8 \
|
||||
((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9_mcst \
|
||||
&& (mach) != bfd_mach_sparc_sparclite_le)
|
||||
/* Nonzero if MACH is a 64 bit sparc architecture. */
|
||||
#define bfd_mach_sparc_64bit_p(mach) \
|
||||
|
@ -1527,7 +1533,10 @@ enum bfd_architecture
|
|||
&& (mach) != bfd_mach_sparc_v8pluse \
|
||||
&& (mach) != bfd_mach_sparc_v8plusv \
|
||||
&& (mach) != bfd_mach_sparc_v8plusm \
|
||||
&& (mach) != bfd_mach_sparc_v8plusm8)
|
||||
&& (mach) != bfd_mach_sparc_v8plusm8 \
|
||||
&& (mach) != bfd_mach_sparc_v8plus_r1000 \
|
||||
&& (mach) != bfd_mach_sparc_v8plus_r2000 \
|
||||
&& (mach) != bfd_mach_sparc_v8plus_r2000_plus)
|
||||
bfd_arch_spu, /* PowerPC SPU. */
|
||||
#define bfd_mach_spu 256
|
||||
bfd_arch_mips, /* MIPS Rxxxx. */
|
||||
|
@ -1896,6 +1905,26 @@ enum bfd_architecture
|
|||
bfd_arch_lm32, /* Lattice Mico32. */
|
||||
#define bfd_mach_lm32 1
|
||||
bfd_arch_microblaze,/* Xilinx MicroBlaze. */
|
||||
bfd_arch_e2k, /* MCST E2K. */
|
||||
/* It's crucial that the underlying `bfd_mach_e2k*' have the same values as */
|
||||
/* the corresponding `E_E2K_MACH_*'s!!! */
|
||||
#define bfd_mach_e2k_generic 0
|
||||
#define bfd_mach_e2k_ev1 1
|
||||
/* This is interpreted as the common subset of all Elbrus V2 iterations.
|
||||
Currently it is the same as the common subset of all elbrus-2c+. */
|
||||
#define bfd_mach_e2k_ev2 2
|
||||
#define bfd_mach_e2k_ev3 3
|
||||
#define bfd_mach_e2k_ev4 4
|
||||
#define bfd_mach_e2k_ev5 5
|
||||
#define bfd_mach_e2k_ev6 6
|
||||
/* Values 16, 17 and 18 used to be reserved for the first three iterations
|
||||
of `elbrus-v2'. See `include/elf/e2k.h' for why they can't be reused right
|
||||
now. */
|
||||
#define bfd_mach_e2k_8c 19
|
||||
#define bfd_mach_e2k_1cplus 20
|
||||
#define bfd_mach_e2k_12c 21
|
||||
#define bfd_mach_e2k_16c 22
|
||||
#define bfd_mach_e2k_2c3 23
|
||||
bfd_arch_tilepro, /* Tilera TILEPro. */
|
||||
bfd_arch_tilegx, /* Tilera TILE-Gx. */
|
||||
#define bfd_mach_tilepro 1
|
||||
|
@ -6203,6 +6232,89 @@ assembler and not (currently) written to any object files. */
|
|||
|
||||
/* S12Z relocations. */
|
||||
BFD_RELOC_S12Z_OPR,
|
||||
|
||||
/* This one corresponds to R_E2K_64_ABS_LIT. */
|
||||
BFD_RELOC_E2K_64_ABS_LIT,
|
||||
|
||||
/* This one corresponds to R_E2K_DISP. */
|
||||
BFD_RELOC_E2K_DISP,
|
||||
|
||||
/* This one corresponds to R_E2K_GOT. */
|
||||
BFD_RELOC_E2K_GOT,
|
||||
|
||||
/* This one corresponds to R_E2K_TLS_GDMOD. */
|
||||
BFD_RELOC_E2K_TLS_GDMOD,
|
||||
|
||||
/* This one corresponds to R_E2K_TLS_GDREL. */
|
||||
BFD_RELOC_E2K_TLS_GDREL,
|
||||
|
||||
/* This one corresponds to R_E2K_TLS_IE. */
|
||||
BFD_RELOC_E2K_TLS_IE,
|
||||
|
||||
/* This one corresponds to R_E2K_32_TLS_LE. */
|
||||
BFD_RELOC_E2K_32_TLS_LE,
|
||||
|
||||
/* This one corresponds to R_E2K_64_TLS_LE. */
|
||||
BFD_RELOC_E2K_64_TLS_LE,
|
||||
|
||||
/* This one corresponds to R_E2K_TLS_32_DTPREL. */
|
||||
BFD_RELOC_E2K_32_DTPREL,
|
||||
|
||||
/* This one corresponds to R_E2K_TLS_64_DTPREL. */
|
||||
BFD_RELOC_E2K_64_DTPREL,
|
||||
|
||||
/* This one corresponds to R_E2K_PLT. */
|
||||
BFD_RELOC_E2K_PLT,
|
||||
|
||||
/* This one corresponds to R_E2K_GOTPLT. */
|
||||
BFD_RELOC_E2K_GOTPLT,
|
||||
|
||||
/* This one corresponds to R_E2K_ISLOCAL. */
|
||||
BFD_RELOC_E2K_ISLOCAL,
|
||||
|
||||
/* This one corresponds to R_E2K_AP_GOT. */
|
||||
BFD_RELOC_E2K_AP_GOT,
|
||||
|
||||
/* This one corresponds to R_E2K_PL_GOT. */
|
||||
BFD_RELOC_E2K_PL_GOT,
|
||||
|
||||
/* This one corresponds to R_E2K_PREF. */
|
||||
BFD_RELOC_E2K_PREF,
|
||||
|
||||
/* This one corresponds to R_E2K_ISLOCAL32. */
|
||||
BFD_RELOC_E2K_ISLOCAL32,
|
||||
|
||||
/* This one corresponds to R_E2K_GOTOFF64. */
|
||||
BFD_RELOC_E2K_GOTOFF64,
|
||||
|
||||
/* This one corresponds to R_E2K_GOTOFF64_LIT. */
|
||||
BFD_RELOC_E2K_GOTOFF64_LIT,
|
||||
|
||||
/* This one corresponds to R_E2K_AP. */
|
||||
BFD_RELOC_E2K_AP,
|
||||
|
||||
/* This one corresponds to R_E2K_PL. */
|
||||
BFD_RELOC_E2K_PL,
|
||||
|
||||
/* This one corresponds to R_E2K_32_DYNOPT. */
|
||||
BFD_RELOC_E2K_DYNOPT32,
|
||||
|
||||
/* This one corresponds to R_E2K_64_DYNOPT. */
|
||||
BFD_RELOC_E2K_DYNOPT64,
|
||||
|
||||
/* Elvees Elcore relocations. */
|
||||
BFD_RELOC_ELCORE32,
|
||||
BFD_RELOC_ELCORE16NPC,
|
||||
BFD_RELOC_ELCORE16PC,
|
||||
BFD_RELOC_ELCORE16S,
|
||||
BFD_RELOC_ELCORE16,
|
||||
BFD_RELOC_ELCORE5,
|
||||
BFD_RELOC_ELCORE32_FAKE,
|
||||
BFD_RELOC_ELCORE16NPC_FAKE,
|
||||
BFD_RELOC_ELCORE16PC_FAKE,
|
||||
BFD_RELOC_ELCORE16S_FAKE,
|
||||
BFD_RELOC_ELCORE16_FAKE,
|
||||
BFD_RELOC_ELCORE5_FAKE,
|
||||
BFD_RELOC_UNUSED };
|
||||
|
||||
typedef enum bfd_reloc_code_real bfd_reloc_code_real_type;
|
||||
|
|
|
@ -174,6 +174,7 @@ crisv32) targ_archs=bfd_cris_arch ;;
|
|||
crx*) targ_archs=bfd_crx_arch ;;
|
||||
csky*) targ_archs=bfd_csky_arch ;;
|
||||
dlx*) targ_archs=bfd_dlx_arch ;;
|
||||
e2k*) targ_archs=bfd_e2k_arch ;;
|
||||
fido*) targ_archs=bfd_m68k_arch ;;
|
||||
hppa*) targ_archs=bfd_hppa_arch ;;
|
||||
i[3-7]86) targ_archs=bfd_i386_arch ;;
|
||||
|
@ -480,6 +481,18 @@ case "${targ}" in
|
|||
;;
|
||||
#endif
|
||||
|
||||
e2k-*-linux-*)
|
||||
targ_defvec=e2k_elf32_vec
|
||||
targ_selvecs="e2k_pm_elf32_vec"
|
||||
targ64_selvecs="e2k_elf64_vec"
|
||||
want64=true
|
||||
;;
|
||||
|
||||
e2k-*-kpda)
|
||||
targ_defvec=e2k_kpda_elf64_vec
|
||||
want64=true
|
||||
;;
|
||||
|
||||
epiphany-*-*)
|
||||
targ_defvec=epiphany_elf32_vec
|
||||
targ_underscore=yes
|
||||
|
|
|
@ -371,6 +371,9 @@
|
|||
/* Define if we should default to creating read-only plt entries */
|
||||
#undef USE_SECUREPLT
|
||||
|
||||
/* Define if we should use new PM ABI for E2K */
|
||||
#undef NEW_PM_ABI
|
||||
|
||||
/* Enable extensions on AIX 3, Interix. */
|
||||
#ifndef _ALL_SOURCE
|
||||
# undef _ALL_SOURCE
|
||||
|
|
|
@ -830,6 +830,7 @@ enable_targets
|
|||
enable_64_bit_archive
|
||||
with_mmap
|
||||
enable_secureplt
|
||||
enable_new_pm_abi
|
||||
enable_separate_code
|
||||
enable_leading_mingw64_underscores
|
||||
with_separate_debug_dir
|
||||
|
@ -1487,6 +1488,7 @@ Optional Features:
|
|||
--enable-targets alternative target configurations
|
||||
--enable-64-bit-archive force 64-bit archives
|
||||
--enable-secureplt Default to creating read-only plt entries
|
||||
--enable-new-pm-abi Enable new PM ABI on E2K
|
||||
--enable-separate-code enable -z separate-code in ELF linker by default
|
||||
--enable-leading-mingw64-underscores
|
||||
Enable leading underscores on 64 bit mingw targets
|
||||
|
@ -11728,7 +11730,7 @@ else
|
|||
lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
|
||||
lt_status=$lt_dlunknown
|
||||
cat > conftest.$ac_ext <<_LT_EOF
|
||||
#line 11731 "configure"
|
||||
#line 11733 "configure"
|
||||
#include "confdefs.h"
|
||||
|
||||
#if HAVE_DLFCN_H
|
||||
|
@ -11834,7 +11836,7 @@ else
|
|||
lt_dlunknown=0; lt_dlno_uscore=1; lt_dlneed_uscore=2
|
||||
lt_status=$lt_dlunknown
|
||||
cat > conftest.$ac_ext <<_LT_EOF
|
||||
#line 11837 "configure"
|
||||
#line 11839 "configure"
|
||||
#include "confdefs.h"
|
||||
|
||||
#if HAVE_DLFCN_H
|
||||
|
@ -12469,6 +12471,22 @@ $as_echo "#define USE_SECUREPLT 1" >>confdefs.h
|
|||
|
||||
fi
|
||||
|
||||
# Check whether --enable-new-pm-abi was given.
|
||||
if test "${enable_new_pm_abi+set}" = set; then :
|
||||
enableval=$enable_new_pm_abi; case "${enableval}" in
|
||||
yes) new_pm_abi=true ;;
|
||||
no) new_pm_abi=false ;;
|
||||
*) as_fn_error $? "bad value ${enableval} for new-pm-abi option" "$LINENO" 5 ;;
|
||||
esac
|
||||
else
|
||||
new_pm_abi=false
|
||||
fi
|
||||
if test $new_pm_abi = true; then
|
||||
|
||||
$as_echo "#define NEW_PM_ABI 1" >>confdefs.h
|
||||
|
||||
fi
|
||||
|
||||
# Decide if -z separate-code should be enabled in ELF linker by default.
|
||||
ac_default_ld_z_separate_code=unset
|
||||
# Check whether --enable-separate-code was given.
|
||||
|
@ -14731,6 +14749,10 @@ do
|
|||
d10v_elf32_vec) tb="$tb elf32-d10v.lo elf32.lo $elf" ;;
|
||||
d30v_elf32_vec) tb="$tb elf32-d30v.lo elf32.lo $elf" ;;
|
||||
dlx_elf32_be_vec) tb="$tb elf32-dlx.lo elf32.lo $elf" ;;
|
||||
e2k_elf32_vec) tb="$tb elf32-e2k.lo elfxx-e2k.lo elf-ifunc.lo $elf"; want64=true;;
|
||||
e2k_pm_elf32_vec) tb="$tb elf32-e2k-pm.lo elfxx-e2k.lo elf-ifunc.lo $elf";;
|
||||
e2k_elf64_vec) tb="$tb elf64-e2k.lo elfxx-e2k.lo elf-ifunc.lo $elf"; target_size=64;;
|
||||
e2k_kpda_elf64_vec) tb="$tb elf64-e2k-kpda.lo elfxx-e2k.lo elf-ifunc.lo $elf"; target_size=64;;
|
||||
elf32_be_vec) tb="$tb elf32-gen.lo elf32.lo $elf" ;;
|
||||
elf32_le_vec) tb="$tb elf32-gen.lo elf32.lo $elf" ;;
|
||||
elf64_be_vec) tb="$tb elf64-gen.lo elf64.lo $elf"; target_size=64 ;;
|
||||
|
|
|
@ -92,6 +92,18 @@ if test $use_secureplt = true; then
|
|||
[Define if we should default to creating read-only plt entries])
|
||||
fi
|
||||
|
||||
AC_ARG_ENABLE(new-pm-abi,
|
||||
[ --enable-new-pm-abi Enable new PM ABI on E2K],
|
||||
[case "${enableval}" in
|
||||
yes) new_pm_abi=true ;;
|
||||
no) new_pm_abi=false ;;
|
||||
*) AC_MSG_ERROR(bad value ${enableval} for new-pm-abi option) ;;
|
||||
esac],[new_pm_abi=false])dnl
|
||||
if test $new_pm_abi = true; then
|
||||
AC_DEFINE(NEW_PM_ABI, 1,
|
||||
[Define if we should enable new PM ABI])
|
||||
fi
|
||||
|
||||
# Decide if -z separate-code should be enabled in ELF linker by default.
|
||||
ac_default_ld_z_separate_code=unset
|
||||
AC_ARG_ENABLE(separate-code,
|
||||
|
@ -467,6 +479,10 @@ do
|
|||
d10v_elf32_vec) tb="$tb elf32-d10v.lo elf32.lo $elf" ;;
|
||||
d30v_elf32_vec) tb="$tb elf32-d30v.lo elf32.lo $elf" ;;
|
||||
dlx_elf32_be_vec) tb="$tb elf32-dlx.lo elf32.lo $elf" ;;
|
||||
e2k_elf32_vec) tb="$tb elf32-e2k.lo elfxx-e2k.lo elf-ifunc.lo $elf"; want64=true;;
|
||||
e2k_pm_elf32_vec) tb="$tb elf32-e2k-pm.lo elfxx-e2k.lo elf-ifunc.lo $elf";;
|
||||
e2k_elf64_vec) tb="$tb elf64-e2k.lo elfxx-e2k.lo elf-ifunc.lo $elf"; target_size=64;;
|
||||
e2k_kpda_elf64_vec) tb="$tb elf64-e2k-kpda.lo elfxx-e2k.lo elf-ifunc.lo $elf"; target_size=64;;
|
||||
elf32_be_vec) tb="$tb elf32-gen.lo elf32.lo $elf" ;;
|
||||
elf32_le_vec) tb="$tb elf32-gen.lo elf32.lo $elf" ;;
|
||||
elf64_be_vec) tb="$tb elf64-gen.lo elf64.lo $elf"; target_size=64 ;;
|
||||
|
|
|
@ -0,0 +1,394 @@
|
|||
/* BFD support for the E2K architecture.
|
||||
Copyright 1992, 1995, 1996, 1998, 2000, 2002, 2005, 2007
|
||||
Free Software Foundation, Inc.
|
||||
|
||||
This file is part of BFD, the Binary File Descriptor library.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
|
||||
MA 02110-1301, USA. */
|
||||
|
||||
#include "sysdep.h"
|
||||
#include "bfd.h"
|
||||
#include "libbfd.h"
|
||||
|
||||
struct archname_item
|
||||
{
|
||||
const char *str;
|
||||
size_t len;
|
||||
};
|
||||
|
||||
static const char *
|
||||
canonicalize_arch_name (const char *name, int *pmode)
|
||||
{
|
||||
int mode;
|
||||
size_t len;
|
||||
const char *pcolon = strchr (name, ':');
|
||||
|
||||
if (pcolon != NULL)
|
||||
{
|
||||
if ((((pcolon[1] == '3' && pcolon[2] == '2' && (mode = 32))
|
||||
|| (pcolon[1] == '6' && pcolon[2] == '4' && (mode = 64))
|
||||
|| (pcolon[1] == 'p' && pcolon[2] == 'm' && (mode = 128)))
|
||||
&& pcolon[3] == '\0')
|
||||
|| (pcolon[1] == 'a' && pcolon[2] == 'n' && pcolon[3] == 'y'
|
||||
&& pcolon[4] == '\0' && (mode = 256)))
|
||||
len = pcolon - name;
|
||||
else
|
||||
return NULL;
|
||||
}
|
||||
else
|
||||
{
|
||||
mode = 64;
|
||||
len = strlen (name);
|
||||
}
|
||||
|
||||
|
||||
#define STRNCMP(s1, s2, n) \
|
||||
((n == sizeof (s2) - 1 && strncmp (s1, s2, n) == 0) ? 0 : 1)
|
||||
|
||||
if (STRNCMP (name, "e2k", len) == 0
|
||||
|| STRNCMP (name, "elbrus-v2", len) == 0
|
||||
|| STRNCMP (name, "elbrus-2c+", len) == 0
|
||||
|| STRNCMP (name, "elbrus-2cm", len) == 0)
|
||||
name = "elbrus-v2";
|
||||
else if (STRNCMP (name, "elbrus-v3", len) == 0
|
||||
|| STRNCMP (name, "elbrus-4c", len) == 0)
|
||||
name = "elbrus-v3";
|
||||
else if (STRNCMP (name, "elbrus-v4", len) == 0)
|
||||
name = "elbrus-v4";
|
||||
else if (STRNCMP (name, "elbrus-8c", len) == 0)
|
||||
name = "elbrus-8c";
|
||||
else if (STRNCMP (name, "elbrus-1c+", len) == 0)
|
||||
name = "elbrus-1c+";
|
||||
else if (STRNCMP (name, "elbrus-v5", len) == 0
|
||||
|| STRNCMP (name, "elbrus-8c2", len) == 0)
|
||||
name = "elbrus-v5";
|
||||
else if (STRNCMP (name, "elbrus-v6", len) == 0)
|
||||
name = "elbrus-v6";
|
||||
else
|
||||
return NULL;
|
||||
|
||||
#undef STRNCMP
|
||||
|
||||
*pmode = mode;
|
||||
return name;
|
||||
}
|
||||
|
||||
static bfd_boolean
|
||||
e2k_scan (const struct bfd_arch_info *info, const char *string)
|
||||
{
|
||||
static const int modes[] = {64, 32, 128, 256};
|
||||
const char *canon;
|
||||
int mode;
|
||||
|
||||
canon = canonicalize_arch_name (string, &mode);
|
||||
if (canon != NULL
|
||||
&& mode == modes[info->mach % 4]
|
||||
&& strncmp (canon, info->printable_name, strlen (canon)) == 0)
|
||||
return TRUE;
|
||||
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
extern const bfd_arch_info_type bfd_e2k_arch;
|
||||
|
||||
static const bfd_arch_info_type *
|
||||
bfd_e2k_compatible (const bfd_arch_info_type *i, const bfd_arch_info_type *o)
|
||||
{
|
||||
/* FIXME: while reworking this function to make it return the "least common
|
||||
denominator" of I and O a limited amount of code was copy/pasted from
|
||||
`_bfd_e2k_elf_merge_private_bfd_data_1 ()'. Moreover, it was simplified
|
||||
so as not to take EF_E2K_INCOMPAT case into account. The latter means
|
||||
that GDB won't emit a warning (not an error?) on an attempt to execute a
|
||||
forward-incompatible ELF for elbrus-vX on elbrus-v{Y > X} at it'll be the
|
||||
Kernel that will prevent this. To make such a control possible here info
|
||||
on the presence of EF_E2K_INCOMPAT should probably be encoded in `bfd_arch
|
||||
_info_type.mach' along with 32-, 64-bit or PM ABIs. Once this is done, it
|
||||
should be possible to delegate similar activities from `_bfd_e2k_elf_merge
|
||||
_private_bfd_data_1 ()' to this function. */
|
||||
enum
|
||||
{
|
||||
ev1,
|
||||
ev2,
|
||||
ev3,
|
||||
e8c,
|
||||
e1cplus,
|
||||
ev5,
|
||||
e12c,
|
||||
e16c,
|
||||
e2c3,
|
||||
/* The related bit in mask stands for "all future processor models". */
|
||||
ev7
|
||||
};
|
||||
|
||||
#define AT(p) (1L << p)
|
||||
#define AT_ev6 (AT (e12c) | AT (e16c) | AT (e2c3))
|
||||
|
||||
|
||||
/* A reduced version of mask[] from `_bfd_e2k_elf_merge_private_bfd_data_1 ()'
|
||||
without an "incompatible" column. */
|
||||
static const unsigned long mask[] =
|
||||
{
|
||||
[bfd_mach_e2k_generic] = (AT (ev1) | AT (ev2) | AT (ev3) | AT (e8c)
|
||||
| AT (e1cplus) | AT (ev5) | AT_ev6
|
||||
| AT (ev7)),
|
||||
|
||||
[bfd_mach_e2k_ev1] = AT (ev1),
|
||||
|
||||
[bfd_mach_e2k_ev2] = (AT (ev2) | AT (ev3) | AT (e8c) | AT (e1cplus)
|
||||
| AT (ev5) | AT_ev6 | AT (ev7)),
|
||||
|
||||
[bfd_mach_e2k_ev3] = (AT (ev3) | AT (e8c) | AT (e1cplus) | AT (ev5)
|
||||
| AT_ev6 | AT (ev7)),
|
||||
|
||||
[bfd_mach_e2k_ev4] = (AT (e8c) | AT (e1cplus) | AT (ev5) | AT_ev6
|
||||
| AT (ev7)),
|
||||
|
||||
[bfd_mach_e2k_ev5] = (AT (ev5) | AT_ev6 | AT (ev7)),
|
||||
|
||||
[bfd_mach_e2k_ev6] = (AT_ev6 | AT (ev7)),
|
||||
|
||||
[bfd_mach_e2k_8c] = AT (e8c),
|
||||
|
||||
[bfd_mach_e2k_1cplus] = AT (e1cplus),
|
||||
|
||||
[bfd_mach_e2k_12c] = AT (e12c),
|
||||
|
||||
[bfd_mach_e2k_16c] = AT (e16c),
|
||||
|
||||
[bfd_mach_e2k_2c3] = AT (e2c3),
|
||||
};
|
||||
|
||||
unsigned long imach, omach, remind;
|
||||
unsigned int j;
|
||||
|
||||
|
||||
if (i->arch != o->arch)
|
||||
return NULL;
|
||||
|
||||
imach = i->mach;
|
||||
omach = o->mach;
|
||||
|
||||
/* Check whether input and output BFDs have the same ABI. 3 stands for
|
||||
"any ABI will do" and is currently used when assigning bfd_arch_info
|
||||
to TARGET_DESC in gdb as there is probably no way to determine which
|
||||
mode the inferior is started in. */
|
||||
if (imach % 4 != 3 && omach % 4 != 3 && imach % 4 != omach % 4)
|
||||
return NULL;
|
||||
|
||||
remind = (imach % 4 != 3) ? imach % 4 : omach % 4;
|
||||
|
||||
imach /= 4;
|
||||
omach /= 4;
|
||||
|
||||
imach = mask[imach];
|
||||
omach = mask[omach];
|
||||
|
||||
omach = omach & imach;
|
||||
if (omach != 0)
|
||||
{
|
||||
for (j = 0; j < sizeof (mask) / sizeof (mask[0]); j++)
|
||||
{
|
||||
if (omach == mask[j])
|
||||
return bfd_lookup_arch (o->arch, 4 * j + remind);
|
||||
}
|
||||
}
|
||||
|
||||
return NULL;
|
||||
}
|
||||
|
||||
|
||||
#define BITS_ADDR_64 64
|
||||
#define BITS_ADDR_32 32
|
||||
#define BITS_ADDR_pm 32
|
||||
/* This is a formal definition as we are unaware of "BITS_ADDR" when "any"
|
||||
bfd_arch_info_type is used. */
|
||||
#define BITS_ADDR_any 64
|
||||
|
||||
#define MACH_64(mach) (4 * (mach))
|
||||
#define MACH_32(mach) (4 * (mach) + 1)
|
||||
#define MACH_pm(mach) (4 * (mach) + 2)
|
||||
#define MACH_any(mach) (4 * (mach) + 3)
|
||||
|
||||
#define PRINT_PREFIX_64 "64-bit ABI for "
|
||||
#define PRINT_PREFIX_32 "32-bit ABI for "
|
||||
#define PRINT_PREFIX_PM "Protected ABI for "
|
||||
|
||||
|
||||
|
||||
#define N(ARCH, MODE, PRINT, DEFAULT, NEXT) \
|
||||
{ \
|
||||
/* We believe that E2k has 32 bits in a word for all architectures \
|
||||
in all supported ABIs. I wonder whether it's actually so from \
|
||||
the point of view of binutils. */ \
|
||||
32, \
|
||||
/* Number of bits in an address */ \
|
||||
BITS_ADDR_##MODE, \
|
||||
/* We have 8 bits in a byte everywhere. */ \
|
||||
8, \
|
||||
bfd_arch_e2k, \
|
||||
/* Get an actual machine number used inside binutils while \
|
||||
performing further checks. */ \
|
||||
MACH_##MODE (ARCH), \
|
||||
"e2k", \
|
||||
PRINT ":" #MODE, \
|
||||
/* Section alignment power. This should probably be \
|
||||
revisited. */ \
|
||||
4, \
|
||||
DEFAULT, \
|
||||
bfd_e2k_compatible, \
|
||||
e2k_scan, \
|
||||
bfd_arch_default_fill, \
|
||||
NEXT, \
|
||||
0 /* Maximum offset of a reloc from the start of an insn. */ \
|
||||
}
|
||||
|
||||
/* These indices are used to refer to the next arch_info entry. I_generic_64
|
||||
is not needed here since the corresponding entry is defined apart. */
|
||||
enum
|
||||
{
|
||||
I_generic_64 = -1,
|
||||
I_generic_32,
|
||||
I_generic_pm,
|
||||
I_generic_any,
|
||||
|
||||
I_ev1_64,
|
||||
I_ev1_32,
|
||||
I_ev1_pm,
|
||||
I_ev1_any,
|
||||
|
||||
I_ev2_64,
|
||||
I_ev2_32,
|
||||
I_ev2_pm,
|
||||
I_ev2_any,
|
||||
|
||||
I_ev3_64,
|
||||
I_ev3_32,
|
||||
I_ev3_pm,
|
||||
I_ev3_any,
|
||||
|
||||
I_ev4_64,
|
||||
I_ev4_32,
|
||||
I_ev4_pm,
|
||||
I_ev4_any,
|
||||
|
||||
I_ev5_64,
|
||||
I_ev5_32,
|
||||
I_ev5_pm,
|
||||
I_ev5_any,
|
||||
|
||||
I_ev6_64,
|
||||
I_ev6_32,
|
||||
I_ev6_pm,
|
||||
I_ev6_any,
|
||||
|
||||
I_8c_64,
|
||||
I_8c_32,
|
||||
I_8c_pm,
|
||||
I_8c_any,
|
||||
|
||||
I_1cplus_64,
|
||||
I_1cplus_32,
|
||||
I_1cplus_pm,
|
||||
I_1cplus_any,
|
||||
|
||||
I_12c_64,
|
||||
I_12c_32,
|
||||
I_12c_pm,
|
||||
I_12c_any,
|
||||
|
||||
I_16c_64,
|
||||
I_16c_32,
|
||||
I_16c_pm,
|
||||
I_16c_any,
|
||||
|
||||
I_2c3_64,
|
||||
I_2c3_32,
|
||||
I_2c3_pm,
|
||||
I_2c3_any
|
||||
};
|
||||
|
||||
#define NN(index) (&arch_info_struct[(index) + 1])
|
||||
|
||||
#define FIRST_TRIP(mach, name) \
|
||||
N (bfd_mach_e2k_##mach, 32, name, FALSE, NN (I_##mach##_32)), \
|
||||
N (bfd_mach_e2k_##mach, pm, name, FALSE, NN (I_##mach##_pm)), \
|
||||
N (bfd_mach_e2k_##mach, any, name, FALSE, NN (I_##mach##_any))
|
||||
|
||||
#define TRIP(mach, name) \
|
||||
N (bfd_mach_e2k_##mach, 64, name, FALSE, NN (I_##mach##_64)), \
|
||||
N (bfd_mach_e2k_##mach, 32, name, FALSE, NN (I_##mach##_32)), \
|
||||
N (bfd_mach_e2k_##mach, pm, name, FALSE, NN (I_##mach##_pm))
|
||||
|
||||
#define QUAD(mach, name) \
|
||||
TRIP (mach, name), \
|
||||
N (bfd_mach_e2k_##mach, any, name, FALSE, NN (I_##mach##_any))
|
||||
|
||||
#define LAST_QUAD(mach, name) \
|
||||
TRIP (mach, name), \
|
||||
N (bfd_mach_e2k_##mach, any, name, FALSE, NULL)
|
||||
|
||||
|
||||
|
||||
|
||||
const bfd_arch_info_type arch_info_struct[] =
|
||||
{
|
||||
/* The two remaining generic entries. */
|
||||
FIRST_TRIP (generic, "generic"),
|
||||
|
||||
/* `elbrus-v1' entries. */
|
||||
QUAD (ev1, "elbrus-v1"),
|
||||
|
||||
/* `elbrus-v2' entries. */
|
||||
QUAD (ev2, "elbrus-v2"),
|
||||
|
||||
/* `elbrus-v3' entries. */
|
||||
QUAD (ev3, "elbrus-v3"),
|
||||
|
||||
/* `elbrus-v4' entries. */
|
||||
QUAD (ev4, "elbrus-v4"),
|
||||
|
||||
/* `elbrus-v5' entries. */
|
||||
QUAD (ev5, "elbrus-v5"),
|
||||
|
||||
/* `elbrus-v6' entries. */
|
||||
QUAD (ev6, "elbrus-v6"),
|
||||
|
||||
/* Entries, describing the specific `elbrus-8c' processor also known as
|
||||
Processor-1 (elbrus-v4). */
|
||||
QUAD (8c, "elbrus-8c"),
|
||||
|
||||
/* Entries, describing the specific `elbrus-1c+' processor also known as
|
||||
Processor-2 (elbrus-v4). */
|
||||
QUAD (1cplus, "elbrus-1c+"),
|
||||
|
||||
/* Entries, describing the specific `elbrus-12c' processor of elbrus-v6
|
||||
series. */
|
||||
QUAD (12c, "elbrus-12c"),
|
||||
|
||||
/* Entries, describing the specific `elbrus-16c' processor of elbrus-v6
|
||||
series. */
|
||||
QUAD (16c, "elbrus-16c"),
|
||||
|
||||
/* Entries, describing the specific `elbrus-2c3' processor of elbrus-v6
|
||||
series. */
|
||||
LAST_QUAD (2c3, "elbrus-2c3")
|
||||
};
|
||||
|
||||
/* I don't remember for sure what DEFAULT actually means here. We should
|
||||
probably only one default arch, however. Let it be a 64-bit elbrus
|
||||
generic arch. */
|
||||
const bfd_arch_info_type bfd_e2k_arch =
|
||||
N (bfd_mach_e2k_generic, 64, "generic", TRUE, NN (I_generic_64));
|
|
@ -62,7 +62,13 @@ static const bfd_arch_info_type arch_info_struct[] =
|
|||
N (32, bfd_mach_sparc_v8plusm, "sparc:v8plusm", FALSE, arch_info_struct + 18),
|
||||
N (64, bfd_mach_sparc_v9m, "sparc:v9m", FALSE, arch_info_struct + 19),
|
||||
N (32, bfd_mach_sparc_v8plusm8, "sparc:v8plusm8", FALSE, arch_info_struct + 20),
|
||||
N (64, bfd_mach_sparc_v9m8, "sparc:v9m8", FALSE, NULL)
|
||||
N (64, bfd_mach_sparc_v9m8, "sparc:v9m8", FALSE, arch_info_struct + 21),
|
||||
N (32, bfd_mach_sparc_v8plus_r1000, "sparc:v8plus_r1000", FALSE, arch_info_struct + 22),
|
||||
N (64, bfd_mach_sparc_v9_r1000, "sparc:r1000", FALSE, arch_info_struct + 23),
|
||||
N (32, bfd_mach_sparc_v8plus_r2000, "sparc:v8plus_r2000", FALSE, arch_info_struct + 24),
|
||||
N (64, bfd_mach_sparc_v9_r2000, "sparc:r2000", FALSE, arch_info_struct + 25),
|
||||
N (32, bfd_mach_sparc_v8plus_r2000_plus, "sparc:v8plus_r2000_plus", FALSE, arch_info_struct + 26),
|
||||
N (64, bfd_mach_sparc_v9_r2000_plus, "sparc:r2000_plus", FALSE, NULL),
|
||||
};
|
||||
|
||||
const bfd_arch_info_type bfd_sparc_arch =
|
||||
|
|
|
@ -16,7 +16,7 @@
|
|||
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
# Controls whether to enable development-mode features by default.
|
||||
development=true
|
||||
development=false
|
||||
|
||||
# Indicate whether this is a release branch.
|
||||
experimental=true
|
||||
|
|
|
@ -0,0 +1,102 @@
|
|||
/* BFD back-end for objects containing EIR.
|
||||
Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
|
||||
2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
||||
Written by Ian Lance Taylor, Cygnus Support, <ian@cygnus.com>
|
||||
|
||||
This file is part of BFD, the Binary File Descriptor library.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
|
||||
MA 02110-1301, USA. */
|
||||
|
||||
#include "sysdep.h"
|
||||
#include "bfd.h"
|
||||
#include "libbfd.h"
|
||||
|
||||
#define eir_set_arch_mach _bfd_generic_set_arch_mach
|
||||
|
||||
static bfd_boolean
|
||||
eir_set_section_contents (bfd *abfd,
|
||||
asection *sec,
|
||||
const void *data,
|
||||
file_ptr offset,
|
||||
bfd_size_type size)
|
||||
{
|
||||
static file_ptr crnt_pos;
|
||||
file_ptr mask;
|
||||
|
||||
if (size == 0 || (strcmp (sec->name, ".pack_pure_eir") != 0
|
||||
&& strcmp (sec->name, ".pack_mixed_eir") != 0))
|
||||
return TRUE;
|
||||
|
||||
mask = (1 << sec->alignment_power) - 1;
|
||||
crnt_pos = (crnt_pos + mask) & ~mask;
|
||||
sec->filepos = crnt_pos;
|
||||
crnt_pos += size;
|
||||
|
||||
return _bfd_generic_set_section_contents (abfd, sec, data, offset, size);
|
||||
}
|
||||
|
||||
const bfd_target eir_vec =
|
||||
{
|
||||
"eir", /* name */
|
||||
bfd_target_unknown_flavour, /* flavour */
|
||||
BFD_ENDIAN_UNKNOWN, /* byteorder */
|
||||
BFD_ENDIAN_UNKNOWN, /* header_byteorder */
|
||||
EXEC_P, /* object_flags */
|
||||
(SEC_ALLOC | SEC_LOAD | SEC_READONLY | SEC_CODE | SEC_DATA
|
||||
| SEC_ROM | SEC_HAS_CONTENTS), /* section_flags */
|
||||
0, /* symbol_leading_char */
|
||||
' ', /* ar_pad_char */
|
||||
16, /* ar_max_namelen */
|
||||
255, /* match priority. */
|
||||
bfd_getb64, bfd_getb_signed_64, bfd_putb64,
|
||||
bfd_getb32, bfd_getb_signed_32, bfd_putb32,
|
||||
bfd_getb16, bfd_getb_signed_16, bfd_putb16, /* data */
|
||||
bfd_getb64, bfd_getb_signed_64, bfd_putb64,
|
||||
bfd_getb32, bfd_getb_signed_32, bfd_putb32,
|
||||
bfd_getb16, bfd_getb_signed_16, bfd_putb16, /* hdrs */
|
||||
{ /* bfd_check_format */
|
||||
_bfd_dummy_target,
|
||||
_bfd_dummy_target,
|
||||
_bfd_dummy_target,
|
||||
_bfd_dummy_target,
|
||||
},
|
||||
{ /* bfd_set_format */
|
||||
_bfd_bool_bfd_false_error,
|
||||
_bfd_bool_bfd_true,
|
||||
_bfd_bool_bfd_false_error,
|
||||
_bfd_bool_bfd_false_error,
|
||||
},
|
||||
{ /* bfd_write_contents */
|
||||
_bfd_bool_bfd_false_error,
|
||||
_bfd_bool_bfd_true,
|
||||
_bfd_bool_bfd_false_error,
|
||||
_bfd_bool_bfd_false_error,
|
||||
},
|
||||
|
||||
BFD_JUMP_TABLE_GENERIC (_bfd_generic),
|
||||
BFD_JUMP_TABLE_COPY (_bfd_generic),
|
||||
BFD_JUMP_TABLE_CORE (_bfd_nocore),
|
||||
BFD_JUMP_TABLE_ARCHIVE (_bfd_noarchive),
|
||||
BFD_JUMP_TABLE_SYMBOLS (_bfd_nosymbols),
|
||||
BFD_JUMP_TABLE_RELOCS (_bfd_norelocs),
|
||||
BFD_JUMP_TABLE_WRITE (eir),
|
||||
BFD_JUMP_TABLE_LINK (_bfd_nolink),
|
||||
BFD_JUMP_TABLE_DYNAMIC (_bfd_nodynamic),
|
||||
|
||||
NULL,
|
||||
|
||||
NULL
|
||||
};
|
|
@ -519,6 +519,7 @@ enum elf_target_id
|
|||
TILEGX_ELF_DATA,
|
||||
TILEPRO_ELF_DATA,
|
||||
RISCV_ELF_DATA,
|
||||
E2K_ELF_DATA,
|
||||
GENERIC_ELF_DATA
|
||||
};
|
||||
|
||||
|
@ -1603,6 +1604,8 @@ struct elf_backend_data
|
|||
/* True if the 64-bit Linux PRPSINFO structure's `pr_uid' and `pr_gid'
|
||||
members use a 16-bit data type. */
|
||||
unsigned linux_prpsinfo64_ugid16 : 1;
|
||||
|
||||
bfd_vma r_none_info;
|
||||
};
|
||||
|
||||
/* Information about reloc sections associated with a bfd_elf_section_data
|
||||
|
@ -2820,6 +2823,12 @@ extern bfd_boolean _bfd_elf_allocate_ifunc_dyn_relocs
|
|||
struct elf_dyn_relocs **, bfd_boolean *, unsigned int,
|
||||
unsigned int, unsigned int, bfd_boolean);
|
||||
|
||||
/* Leave it in place since E2K needs it. */
|
||||
extern long _bfd_elf_ifunc_get_synthetic_symtab
|
||||
(bfd *, long, asymbol **, long, asymbol **, asymbol **, asection *,
|
||||
int, void *,
|
||||
bfd_vma *(*) (bfd *, asymbol **, asection *, asection *, int, void *));
|
||||
|
||||
extern void elf_append_rela (bfd *, asection *, Elf_Internal_Rela *);
|
||||
extern void elf_append_rel (bfd *, asection *, Elf_Internal_Rela *);
|
||||
|
||||
|
|
|
@ -142,6 +142,10 @@ read_sleb128 (bfd_byte **iter, bfd_byte *end, bfd_signed_vma *value)
|
|||
static
|
||||
int get_DW_EH_PE_width (int encoding, int ptr_size)
|
||||
{
|
||||
/* For the sake of E2K Protected Mode. */
|
||||
if (encoding == DW_EH_PE_aligned)
|
||||
return 16;
|
||||
|
||||
/* DW_EH_PE_ values of 0x60 and 0x70 weren't defined at the time .eh_frame
|
||||
was added to bfd. */
|
||||
if ((encoding & 0x60) == 0x60)
|
||||
|
@ -998,6 +1002,15 @@ _bfd_elf_parse_eh_frame (bfd *abfd, struct bfd_link_info *info,
|
|||
CIE instructions. */
|
||||
|| (set_loc_count && this_inf->cie))
|
||||
goto free_no_table;
|
||||
|
||||
/* Prevent e2k-linux-ld from adjusting the size of entries (are only CIEs
|
||||
adjusted this way?) and thus ensure that the 16 byte alignment of all
|
||||
subsequent CIEs and FDEs is preserved in such a primitive way . . . */
|
||||
if (((elf_elfheader (abfd)->e_flags & 32 /* EF_E2K_PM */)
|
||||
== 32 /* EF_E2K_PM */)
|
||||
&& strcmp (abfd->xvec->name, "elf32-e2k-pm") == 0)
|
||||
insns_end = end;
|
||||
|
||||
this_inf->size -= end - insns_end;
|
||||
if (insns_end != end && this_inf->cie)
|
||||
{
|
||||
|
|
170
bfd/elf-ifunc.c
170
bfd/elf-ifunc.c
|
@ -359,3 +359,173 @@ keep:
|
|||
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
/* Leave the underlying function in place since E2K needs it. */
|
||||
|
||||
/* Similar to _bfd_elf_get_synthetic_symtab, optimized for unsorted PLT
|
||||
entries. PLT is the PLT section. PLT_SYM_VAL is a function pointer
|
||||
which returns an array of PLT entry symbol values. */
|
||||
|
||||
long
|
||||
_bfd_elf_ifunc_get_synthetic_symtab
|
||||
(bfd *abfd, long symcount ATTRIBUTE_UNUSED,
|
||||
asymbol **syms ATTRIBUTE_UNUSED, long dynsymcount, asymbol **dynsyms,
|
||||
asymbol **ret, asection *plt,
|
||||
int kind,
|
||||
void *dummy,
|
||||
bfd_vma *(*get_plt_sym_val) (bfd *, asymbol **, asection *, asection *,
|
||||
int, void *))
|
||||
{
|
||||
const struct elf_backend_data *bed = get_elf_backend_data (abfd);
|
||||
asection *relplt;
|
||||
asymbol *s;
|
||||
const char *relplt_name;
|
||||
bfd_boolean (*slurp_relocs) (bfd *, asection *, asymbol **, bfd_boolean);
|
||||
arelent *p;
|
||||
long count, i, n;
|
||||
size_t size;
|
||||
Elf_Internal_Shdr *hdr;
|
||||
char *names;
|
||||
bfd_vma *plt_sym_val;
|
||||
const char *plt_sfx;
|
||||
size_t plt_sfx_sz;
|
||||
|
||||
switch (kind)
|
||||
{
|
||||
case 0:
|
||||
plt_sfx = "@plt";
|
||||
plt_sfx_sz = sizeof ("@plt");
|
||||
break;
|
||||
case 1:
|
||||
plt_sfx = "@secondary_plt";
|
||||
plt_sfx_sz = sizeof ("@secondary_plt");
|
||||
break;
|
||||
case 2:
|
||||
plt_sfx = "@plt.got";
|
||||
plt_sfx_sz = sizeof ("@plt.got");
|
||||
break;
|
||||
default:
|
||||
return -1;
|
||||
}
|
||||
|
||||
*ret = NULL;
|
||||
|
||||
if (plt == NULL)
|
||||
return 0;
|
||||
|
||||
if ((abfd->flags & (DYNAMIC | EXEC_P)) == 0)
|
||||
return 0;
|
||||
|
||||
if (dynsymcount <= 0)
|
||||
return 0;
|
||||
|
||||
/* When looking for primary and secondary PLT entries one should iterate
|
||||
over `.rela.plt', whereas for `.plt.got' entries (recall that they are
|
||||
created for functions a pointer to which should be resolved in a non-lazy
|
||||
way (in a shared library?)) - over `.rela.dyn'. */
|
||||
if (kind == 0 || kind == 1)
|
||||
{
|
||||
relplt_name = bed->relplt_name;
|
||||
if (relplt_name == NULL)
|
||||
relplt_name = bed->rela_plts_and_copies_p ? ".rela.plt" : ".rel.plt";
|
||||
relplt = bfd_get_section_by_name (abfd, relplt_name);
|
||||
}
|
||||
else
|
||||
{
|
||||
/* FIXME: currently this function is called with `kind == 2' for E2K
|
||||
only. How should I properly choose between `.rel{,a}.dyn' on other
|
||||
platforms? */
|
||||
relplt_name = ".rela.dyn";
|
||||
|
||||
/* FIXME: is it worthwhile to iterate over a potentially huge `.rela.dyn'
|
||||
for just a few relocations related to `.plt.got' entries? There are a
|
||||
couple of such entries in libc.so . . . */
|
||||
relplt = bfd_get_section_by_name (abfd, relplt_name);
|
||||
}
|
||||
|
||||
if (relplt == NULL)
|
||||
return 0;
|
||||
|
||||
hdr = &elf_section_data (relplt)->this_hdr;
|
||||
if (hdr->sh_link != elf_dynsymtab (abfd)
|
||||
|| (hdr->sh_type != SHT_REL && hdr->sh_type != SHT_RELA))
|
||||
return 0;
|
||||
|
||||
slurp_relocs = get_elf_backend_data (abfd)->s->slurp_reloc_table;
|
||||
if (! (*slurp_relocs) (abfd, relplt, dynsyms, TRUE))
|
||||
return -1;
|
||||
|
||||
count = relplt->size / hdr->sh_entsize;
|
||||
size = count * sizeof (asymbol);
|
||||
p = relplt->relocation;
|
||||
for (i = 0; i < count; i++, p += bed->s->int_rels_per_ext_rel)
|
||||
{
|
||||
size += strlen ((*p->sym_ptr_ptr)->name) + plt_sfx_sz;
|
||||
if (p->addend != 0)
|
||||
{
|
||||
#ifdef BFD64
|
||||
size += sizeof ("+0x") - 1 + 8 + 8 * (bed->s->elfclass == ELFCLASS64);
|
||||
#else
|
||||
size += sizeof ("+0x") - 1 + 8;
|
||||
#endif
|
||||
}
|
||||
}
|
||||
|
||||
plt_sym_val = get_plt_sym_val (abfd, dynsyms, plt, relplt, kind, dummy);
|
||||
if (plt_sym_val == NULL)
|
||||
return -1;
|
||||
|
||||
s = *ret = (asymbol *) bfd_malloc (size);
|
||||
if (s == NULL)
|
||||
{
|
||||
free (plt_sym_val);
|
||||
return -1;
|
||||
}
|
||||
|
||||
names = (char *) (s + count);
|
||||
p = relplt->relocation;
|
||||
n = 0;
|
||||
for (i = 0; i < count; i++, p += bed->s->int_rels_per_ext_rel)
|
||||
{
|
||||
size_t len;
|
||||
bfd_vma addr;
|
||||
|
||||
addr = plt_sym_val[i];
|
||||
if (addr == (bfd_vma) -1)
|
||||
continue;
|
||||
|
||||
*s = **p->sym_ptr_ptr;
|
||||
/* Undefined syms won't have BSF_LOCAL or BSF_GLOBAL set. Since
|
||||
we are defining a symbol, ensure one of them is set. */
|
||||
if ((s->flags & BSF_LOCAL) == 0)
|
||||
s->flags |= BSF_GLOBAL;
|
||||
s->flags |= BSF_SYNTHETIC;
|
||||
s->section = plt;
|
||||
s->value = addr - plt->vma;
|
||||
s->name = names;
|
||||
s->udata.p = NULL;
|
||||
len = strlen ((*p->sym_ptr_ptr)->name);
|
||||
memcpy (names, (*p->sym_ptr_ptr)->name, len);
|
||||
names += len;
|
||||
if (p->addend != 0)
|
||||
{
|
||||
char buf[30], *a;
|
||||
|
||||
memcpy (names, "+0x", sizeof ("+0x") - 1);
|
||||
names += sizeof ("+0x") - 1;
|
||||
bfd_sprintf_vma (abfd, buf, p->addend);
|
||||
for (a = buf; *a == '0'; ++a)
|
||||
;
|
||||
len = strlen (a);
|
||||
memcpy (names, a, len);
|
||||
names += len;
|
||||
}
|
||||
memcpy (names, plt_sfx, plt_sfx_sz);
|
||||
names += plt_sfx_sz;
|
||||
++s, ++n;
|
||||
}
|
||||
|
||||
free (plt_sym_val);
|
||||
|
||||
return n;
|
||||
}
|
||||
|
|
|
@ -0,0 +1,130 @@
|
|||
#include "sysdep.h"
|
||||
#include "bfd.h"
|
||||
#include "libbfd.h"
|
||||
#include "elf-bfd.h"
|
||||
#include "elf/e2k.h"
|
||||
#include "elfxx-e2k.h"
|
||||
|
||||
static bfd_boolean
|
||||
segment_executable (struct elf_segment_map *seg)
|
||||
{
|
||||
if (seg->p_flags_valid)
|
||||
return (seg->p_flags & PF_X) != 0;
|
||||
else
|
||||
{
|
||||
/* The p_flags value has not been computed yet,
|
||||
so we have to look through the sections. */
|
||||
unsigned int i;
|
||||
for (i = 0; i < seg->count; ++i)
|
||||
if (seg->sections[i]->flags & SEC_CODE)
|
||||
return TRUE;
|
||||
}
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
/* Determine if this segment is eligible to receive the file and program
|
||||
headers. It must be read-only and non-executable.
|
||||
Its first section must start far enough past the page boundary to
|
||||
allow space for the headers. */
|
||||
static bfd_boolean
|
||||
segment_eligible_for_headers (struct elf_segment_map *seg,
|
||||
bfd_vma minpagesize, bfd_vma sizeof_headers)
|
||||
{
|
||||
unsigned int i;
|
||||
if (seg->count == 0 || seg->sections[0]->lma % minpagesize < sizeof_headers)
|
||||
return FALSE;
|
||||
for (i = 0; i < seg->count; ++i)
|
||||
{
|
||||
if ((seg->sections[i]->flags & (SEC_CODE|SEC_READONLY)) != SEC_READONLY)
|
||||
return FALSE;
|
||||
}
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
|
||||
static bfd_boolean
|
||||
_bfd_e2k_pm_elf_modify_segment_map (bfd *abfd, struct bfd_link_info *info)
|
||||
{
|
||||
const struct elf_backend_data *const bed = get_elf_backend_data (abfd);
|
||||
struct elf_segment_map **m = &elf_seg_map (abfd);
|
||||
struct elf_segment_map **first_load = NULL;
|
||||
struct elf_segment_map **last_load = NULL;
|
||||
bfd_boolean moved_headers = FALSE;
|
||||
int sizeof_headers;
|
||||
|
||||
sizeof_headers = bfd_sizeof_headers (abfd, info);
|
||||
|
||||
while (*m != NULL)
|
||||
{
|
||||
struct elf_segment_map *seg = *m;
|
||||
|
||||
if (seg->p_type == PT_LOAD)
|
||||
{
|
||||
bfd_boolean executable = segment_executable (seg);
|
||||
|
||||
/* First, we're just finding the earliest PT_LOAD.
|
||||
By the normal rules, this will be the lowest-addressed one.
|
||||
We only have anything interesting to do if it's executable. */
|
||||
last_load = m;
|
||||
if (first_load == NULL)
|
||||
{
|
||||
if (!executable)
|
||||
goto next;
|
||||
first_load = m;
|
||||
}
|
||||
/* Now that we've noted the first PT_LOAD, we're looking for
|
||||
the first non-executable PT_LOAD with a nonempty p_filesz. */
|
||||
else if (!moved_headers
|
||||
&& segment_eligible_for_headers (seg, bed->minpagesize,
|
||||
sizeof_headers))
|
||||
{
|
||||
/* This is the one we were looking for!
|
||||
|
||||
First, clear the flags on previous segments that
|
||||
say they include the file header and phdrs. */
|
||||
struct elf_segment_map *prevseg;
|
||||
for (prevseg = *first_load;
|
||||
prevseg != seg;
|
||||
prevseg = prevseg->next)
|
||||
if (prevseg->p_type == PT_LOAD)
|
||||
{
|
||||
prevseg->includes_filehdr = 0;
|
||||
prevseg->includes_phdrs = 0;
|
||||
}
|
||||
|
||||
/* This segment will include those headers instead. */
|
||||
seg->includes_filehdr = 1;
|
||||
seg->includes_phdrs = 1;
|
||||
|
||||
moved_headers = TRUE;
|
||||
}
|
||||
}
|
||||
|
||||
next:
|
||||
m = &seg->next;
|
||||
}
|
||||
|
||||
if (first_load != last_load && moved_headers)
|
||||
{
|
||||
/* Now swap the first and last PT_LOAD segments'
|
||||
positions in segment_map. */
|
||||
struct elf_segment_map *first = *first_load;
|
||||
struct elf_segment_map *last = *last_load;
|
||||
*first_load = first->next;
|
||||
first->next = last->next;
|
||||
last->next = first;
|
||||
}
|
||||
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
#define elf_backend_modify_segment_map _bfd_e2k_pm_elf_modify_segment_map
|
||||
|
||||
/* The first Elf32_Addr GOT entry containing link-time "address" of `_DYNAMIC'
|
||||
is followed by two 16 bytes long appropriately aligned descriptors containing
|
||||
`struct link_map *' and `&_dl_fixup ()'. */
|
||||
#define elf_backend_got_header_size 48
|
||||
#define TARGET_LITTLE_SYM e2k_pm_elf32_vec
|
||||
#define TARGET_LITTLE_NAME "elf32-e2k-pm"
|
||||
|
||||
#include "elf32-e2k.c"
|
|
@ -0,0 +1,202 @@
|
|||
/* E2K-specific support for 32-bit ELF
|
||||
Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
|
||||
2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
||||
|
||||
This file is part of BFD, the Binary File Descriptor library.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
|
||||
MA 02110-1301, USA. */
|
||||
|
||||
#if ! defined TARGET_LITTLE_SYM
|
||||
|
||||
#include "sysdep.h"
|
||||
#include "bfd.h"
|
||||
#include "libbfd.h"
|
||||
#include "elf-bfd.h"
|
||||
#include "elf/e2k.h"
|
||||
#include "elfxx-e2k.h"
|
||||
|
||||
#endif
|
||||
|
||||
|
||||
static int
|
||||
elf32_e2k_write_out_phdrs (bfd *abfd,
|
||||
const Elf_Internal_Phdr *phdr,
|
||||
unsigned int count)
|
||||
{
|
||||
/* There is no point in hacking VMA's unless we are creating an executable
|
||||
containing DSP-specific segments. Otherwise we may very well set wrong
|
||||
VMA's when creating non-trivial ELF files (e.g. Kernels, BIOSes and so
|
||||
on) which may have segments with `VMA != LMA'. Later when creating binary
|
||||
images OBJCOPY may very well figure out wrong LMAs for the corresponding
|
||||
sections since it'll be unable to find appropriate segments containing
|
||||
them and set `LMA = VMA' (see `_bfd_elf_make_section_from_shdr ()'). This
|
||||
may very well lead to binary images having HUGE sizes (see Bug #67966). */
|
||||
if (!e2k_dsp_linux_mode)
|
||||
return bfd_elf32_write_out_phdrs (abfd, phdr, count);
|
||||
|
||||
while (count--)
|
||||
{
|
||||
Elf32_External_Phdr extphdr;
|
||||
|
||||
if (phdr->p_vaddr != phdr->p_paddr)
|
||||
{
|
||||
Elf_Internal_Phdr fake;
|
||||
memcpy (&fake, phdr, sizeof (fake));
|
||||
fake.p_vaddr = phdr->p_paddr;
|
||||
bfd_elf32_swap_phdr_out (abfd, &fake, &extphdr);
|
||||
}
|
||||
else
|
||||
bfd_elf32_swap_phdr_out (abfd, phdr, &extphdr);
|
||||
|
||||
|
||||
if (bfd_bwrite (&extphdr, sizeof (Elf32_External_Phdr), abfd)
|
||||
!= sizeof (Elf32_External_Phdr))
|
||||
return -1;
|
||||
|
||||
phdr++;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
|
||||
/* All fields are set to their default values from
|
||||
`elfcode.h' except `write_out_phdrs' which shoud
|
||||
fool the Kernel in case of DSP segments. */
|
||||
static const struct elf_size_info elf32_e2k_size_info = {
|
||||
sizeof (Elf32_External_Ehdr),
|
||||
sizeof (Elf32_External_Phdr),
|
||||
sizeof (Elf32_External_Shdr),
|
||||
sizeof (Elf32_External_Rel),
|
||||
sizeof (Elf32_External_Rela),
|
||||
sizeof (Elf32_External_Sym),
|
||||
sizeof (Elf32_External_Dyn),
|
||||
sizeof (Elf_External_Note),
|
||||
4,
|
||||
1,
|
||||
32, 2,
|
||||
1, 1,
|
||||
elf32_e2k_write_out_phdrs,
|
||||
bfd_elf32_write_shdrs_and_ehdr,
|
||||
bfd_elf32_checksum_contents,
|
||||
bfd_elf32_write_relocs,
|
||||
bfd_elf32_swap_symbol_in,
|
||||
bfd_elf32_swap_symbol_out,
|
||||
bfd_elf32_slurp_reloc_table,
|
||||
bfd_elf32_slurp_symbol_table,
|
||||
bfd_elf32_swap_dyn_in,
|
||||
bfd_elf32_swap_dyn_out,
|
||||
bfd_elf32_swap_reloc_in,
|
||||
bfd_elf32_swap_reloc_out,
|
||||
bfd_elf32_swap_reloca_in,
|
||||
bfd_elf32_swap_reloca_out
|
||||
};
|
||||
|
||||
|
||||
|
||||
#define bfd_elf32_bfd_link_add_symbols _bfd_e2k_elf_link_add_symbols
|
||||
#define bfd_elf32_bfd_reloc_type_lookup _bfd_e2k_elf_reloc_type_lookup
|
||||
#define bfd_elf32_bfd_reloc_name_lookup _bfd_e2k_elf_reloc_name_lookup
|
||||
#define bfd_elf32_bfd_merge_private_bfd_data _bfd_e2k_elf_merge_private_bfd_data
|
||||
#define bfd_elf32_mkobject _bfd_e2k_elf_mkobject
|
||||
#define bfd_elf32_bfd_link_hash_table_create _bfd_e2k_elf_link_hash_table_create
|
||||
#define bfd_elf32_bfd_final_link _bfd_e2k_elf_final_link
|
||||
#define bfd_elf32_get_synthetic_symtab _bfd_e2k_elf_get_synthetic_symtab
|
||||
#define bfd_elf32_write_object_contents _bfd_e2k_elf_write_object_contents
|
||||
#define bfd_elf32_bfd_copy_private_bfd_data _bfd_e2k_elf_copy_private_bfd_data
|
||||
|
||||
#define elf_info_to_howto _bfd_e2k_elf_info_to_howto
|
||||
|
||||
#define elf_backend_add_symbol_hook _bfd_e2k_elf_add_symbol_hook
|
||||
#define elf_backend_special_sections _bfd_e2k_elf_special_sections
|
||||
#define elf_backend_common_definition _bfd_e2k_elf_common_definition
|
||||
#define elf_backend_merge_symbol_attribute _bfd_e2k_elf_merge_symbol_attribute
|
||||
#define elf_backend_grok_prstatus _bfd_e2k_elf_grok_prstatus
|
||||
#define elf_backend_write_core_note _bfd_e2k_elf_write_core_note
|
||||
|
||||
|
||||
#define elf_backend_create_dynamic_sections _bfd_e2k_elf_create_dynamic_sections
|
||||
#define elf_backend_copy_indirect_symbol _bfd_e2k_elf_copy_indirect_symbol
|
||||
#define elf_backend_check_directives _bfd_e2k_elf_check_directives
|
||||
#define elf_backend_check_relocs _bfd_e2k_elf_check_relocs
|
||||
#define elf_backend_gc_sweep_hook _bfd_e2k_elf_gc_sweep_hook
|
||||
#define elf_backend_adjust_dynamic_symbol _bfd_e2k_elf_adjust_dynamic_symbol
|
||||
#define elf_backend_size_dynamic_sections _bfd_e2k_elf_size_dynamic_sections
|
||||
#define elf_backend_action_discarded _bfd_e2k_elf_action_discarded
|
||||
#define elf_backend_relocate_section _bfd_e2k_elf_relocate_section
|
||||
#define elf_backend_finish_dynamic_symbol _bfd_e2k_elf_finish_dynamic_symbol
|
||||
#define elf_backend_reloc_type_class _bfd_e2k_elf_reloc_type_class
|
||||
#define elf_backend_finish_dynamic_sections _bfd_e2k_elf_finish_dynamic_sections
|
||||
#define elf_backend_init_file_header _bfd_e2k_elf_init_file_header
|
||||
#define elf_backend_ignore_discarded_relocs _bfd_e2k_elf_ignore_discarded_relocs
|
||||
#define elf_backend_hide_symbol _bfd_e2k_elf_hide_symbol
|
||||
#define elf_backend_object_p _bfd_e2k_elf_object_p
|
||||
#define elf_backend_setup_gnu_properties _bfd_e2k_elf_link_setup_gnu_properties
|
||||
|
||||
/* Make tests employing `gc-sections' option PASS. I wonder if any backend-
|
||||
specific support is required. TODO: place here actual names of the tests. */
|
||||
#define elf_backend_can_gc_sections 1
|
||||
#define elf_backend_want_got_sym 1
|
||||
/* I want got.refcount start from `0', not from `-1'
|
||||
(see _bfd_elf_link_hash_table_init). */
|
||||
#define elf_backend_can_refcount 1
|
||||
|
||||
#define elf_backend_want_got_plt 1
|
||||
#define elf_backend_plt_readonly 1
|
||||
|
||||
/* This is required to ensure that addends of rela-relocations against section
|
||||
symbols are adjusted correctly during the relocatable linkage in
|
||||
`elf_link_input_bfd ()'. */
|
||||
#define elf_backend_rela_normal 1
|
||||
|
||||
#define elf_backend_plt_alignment 3
|
||||
|
||||
#define elf_backend_size_info elf32_e2k_size_info
|
||||
|
||||
#define elf_backend_extern_protected_data 1
|
||||
|
||||
#define elf_backend_r_none_info R_E2K_NONE
|
||||
|
||||
/* Let `bfd_elf_size_dynamic_sections ()' treat a missing PT_GNU_STACK as an
|
||||
unexecutable one to be in line with the Kernel and glibc. */
|
||||
#define elf_backend_default_execstack 0
|
||||
|
||||
|
||||
#define ELF_ARCH bfd_arch_e2k
|
||||
|
||||
#define ELF_MACHINE_CODE EM_MCST_ELBRUS
|
||||
|
||||
/* This is the value we initially used. */
|
||||
#define ELF_MACHINE_ALT1 EM_E2K_OLD
|
||||
|
||||
#define ELF_MAXPAGESIZE 0x1000
|
||||
|
||||
#ifndef elf_backend_got_header_size
|
||||
/* The first entry in `.got' is reserved for the `_DYNAMIC' link-time
|
||||
address. */
|
||||
# define elf_backend_got_header_size 12
|
||||
#endif
|
||||
|
||||
#ifndef TARGET_LITTLE_SYM
|
||||
#define TARGET_LITTLE_SYM e2k_elf32_vec
|
||||
#endif
|
||||
|
||||
#ifndef TARGET_LITTLE_NAME
|
||||
#define TARGET_LITTLE_NAME "elf32-e2k"
|
||||
#endif
|
||||
|
||||
|
||||
#include "elf32-target.h"
|
|
@ -75,6 +75,13 @@ elf32_sparc_merge_private_bfd_data (bfd *ibfd, struct bfd_link_info *info)
|
|||
/* FIXME: This should not be static. */
|
||||
static unsigned long previous_ibfd_e_flags = (unsigned long) -1;
|
||||
|
||||
/* No matter whether the output BFD is ELF or not, check magic in the input
|
||||
one provided that it is. */
|
||||
if (bfd_get_flavour (ibfd) == bfd_target_elf_flavour
|
||||
&& ! _bfd_sparc_elf_check_magic (ibfd))
|
||||
return FALSE;
|
||||
|
||||
|
||||
if (bfd_get_flavour (ibfd) != bfd_target_elf_flavour
|
||||
|| bfd_get_flavour (obfd) != bfd_target_elf_flavour)
|
||||
return TRUE;
|
||||
|
@ -147,6 +154,17 @@ sparc_final_write_processing (bfd *abfd)
|
|||
elf_elfheader (abfd)->e_flags |= EF_SPARC_32PLUS | EF_SPARC_SUN_US1
|
||||
| EF_SPARC_SUN_US3;
|
||||
break;
|
||||
/* I cannot understand why in 32-bit mode the same functionality as in
|
||||
(sparc_elf_final_processing (), tc-sparc.c) is DUPLICATED here. In fact
|
||||
we set the same value of `e_flags' both there and here. */
|
||||
case bfd_mach_sparc_v8plus_r1000 :
|
||||
case bfd_mach_sparc_v8plus_r2000 :
|
||||
case bfd_mach_sparc_v8plus_r2000_plus :
|
||||
elf_elfheader (abfd)->e_machine = EM_SPARC32PLUS;
|
||||
elf_elfheader (abfd)->e_flags &=~ EF_SPARC_32PLUS_MASK;
|
||||
elf_elfheader (abfd)->e_flags |= (EF_SPARC_32PLUS | EF_SPARC_SUN_US1
|
||||
| EF_SPARC_SUN_US3 | EF_SPARC_MCST);
|
||||
break;
|
||||
case bfd_mach_sparc_sparclite_le :
|
||||
elf_elfheader (abfd)->e_flags |= EF_SPARC_LEDATA;
|
||||
break;
|
||||
|
@ -269,6 +287,18 @@ elf32_sparc_reloc_type_class (const struct bfd_link_info *info,
|
|||
|
||||
#define elf_backend_linux_prpsinfo32_ugid16 TRUE
|
||||
|
||||
/* EIR-specific hacks. */
|
||||
#define bfd_elf32_bfd_link_add_symbols _bfd_sparc_elf_link_add_symbols
|
||||
#define bfd_elf32_bfd_final_link _bfd_sparc_elf_final_link
|
||||
#define elf_backend_ignore_discarded_relocs _bfd_sparc_elf_ignore_discarded_relocs
|
||||
#define elf_backend_hide_symbol _bfd_sparc_elf_hide_symbol
|
||||
#define bfd_elf32_write_object_contents _bfd_sparc_elf_write_object_contents
|
||||
|
||||
/* Let `.magic' section be `SHT_NOTE'. */
|
||||
#define elf_backend_special_sections _bfd_sparc_elf_special_sections
|
||||
|
||||
#define elf_backend_extern_protected_data 1
|
||||
|
||||
#include "elf32-target.h"
|
||||
|
||||
/* Solaris 2. */
|
||||
|
|
|
@ -0,0 +1,34 @@
|
|||
/* Signalize that elf64-e2k.c shouldn't set up bfd target vector for us.
|
||||
We'll do it ourselves after redefining a few macros. */
|
||||
#define TARGET_KPDA
|
||||
#include "elf64-e2k.c"
|
||||
#undef TARGET_KPDA
|
||||
|
||||
#if 0
|
||||
static void
|
||||
_bfd_e2k_kpda_elf64_post_process_headers (bfd *abfd,
|
||||
struct bfd_link_info *link_info)
|
||||
{
|
||||
Elf_Internal_Ehdr *i_ehdrp;
|
||||
|
||||
i_ehdrp = elf_elfheader (abfd);
|
||||
i_ehdrp->e_ident[EI_OSABI] = ELFOSABI_KPDA;
|
||||
|
||||
_bfd_elf_post_process_headers (abfd, link_info);
|
||||
}
|
||||
|
||||
#undef elf_backend_post_process_headers
|
||||
#define elf_backend_post_process_headers _bfd_e2k_kpda_elf64_post_process_headers
|
||||
|
||||
#endif /* 0 */
|
||||
|
||||
#undef TARGET_LITTLE_SYM
|
||||
#define TARGET_LITTLE_SYM e2k_kpda_elf64_vec
|
||||
|
||||
#undef TARGET_LITTLE_NAME
|
||||
#define TARGET_LITTLE_NAME "elf64-e2k-kpda"
|
||||
|
||||
#define ELF_OSABI ELFOSABI_KPDA
|
||||
|
||||
/* Now set up the target vector. */
|
||||
#include "elf64-target.h"
|
|
@ -0,0 +1,191 @@
|
|||
/* E2K-specific support for 32-bit ELF
|
||||
Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
|
||||
2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
|
||||
|
||||
This file is part of BFD, the Binary File Descriptor library.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
|
||||
MA 02110-1301, USA. */
|
||||
|
||||
#include "sysdep.h"
|
||||
#include "bfd.h"
|
||||
#include "libbfd.h"
|
||||
#include "elf-bfd.h"
|
||||
#include "elf/e2k.h"
|
||||
#include "elfxx-e2k.h"
|
||||
|
||||
|
||||
static int
|
||||
elf64_e2k_write_out_phdrs (bfd *abfd,
|
||||
const Elf_Internal_Phdr *phdr,
|
||||
unsigned int count)
|
||||
{
|
||||
/* See a more detailed comment in `elf32-e2k.c'. */
|
||||
if (!e2k_dsp_linux_mode)
|
||||
return bfd_elf64_write_out_phdrs (abfd, phdr, count);
|
||||
|
||||
while (count--)
|
||||
{
|
||||
Elf64_External_Phdr extphdr;
|
||||
|
||||
if (phdr->p_vaddr != phdr->p_paddr)
|
||||
{
|
||||
Elf_Internal_Phdr fake;
|
||||
memcpy (&fake, phdr, sizeof (fake));
|
||||
fake.p_vaddr = phdr->p_paddr;
|
||||
bfd_elf64_swap_phdr_out (abfd, &fake, &extphdr);
|
||||
}
|
||||
else
|
||||
bfd_elf64_swap_phdr_out (abfd, phdr, &extphdr);
|
||||
|
||||
|
||||
if (bfd_bwrite (&extphdr, sizeof (Elf64_External_Phdr), abfd)
|
||||
!= sizeof (Elf64_External_Phdr))
|
||||
return -1;
|
||||
|
||||
phdr++;
|
||||
}
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
|
||||
/* All fields are set to their default values from
|
||||
`elfcode.h' except `write_out_phdrs' which shoud
|
||||
fool the Kernel in case of DSP segments. */
|
||||
static const struct elf_size_info elf64_e2k_size_info = {
|
||||
sizeof (Elf64_External_Ehdr),
|
||||
sizeof (Elf64_External_Phdr),
|
||||
sizeof (Elf64_External_Shdr),
|
||||
sizeof (Elf64_External_Rel),
|
||||
sizeof (Elf64_External_Rela),
|
||||
sizeof (Elf64_External_Sym),
|
||||
sizeof (Elf64_External_Dyn),
|
||||
sizeof (Elf_External_Note),
|
||||
4,
|
||||
1,
|
||||
64, 3,
|
||||
2, 1,
|
||||
elf64_e2k_write_out_phdrs,
|
||||
bfd_elf64_write_shdrs_and_ehdr,
|
||||
bfd_elf64_checksum_contents,
|
||||
bfd_elf64_write_relocs,
|
||||
bfd_elf64_swap_symbol_in,
|
||||
bfd_elf64_swap_symbol_out,
|
||||
bfd_elf64_slurp_reloc_table,
|
||||
bfd_elf64_slurp_symbol_table,
|
||||
bfd_elf64_swap_dyn_in,
|
||||
bfd_elf64_swap_dyn_out,
|
||||
bfd_elf64_swap_reloc_in,
|
||||
bfd_elf64_swap_reloc_out,
|
||||
bfd_elf64_swap_reloca_in,
|
||||
bfd_elf64_swap_reloca_out
|
||||
};
|
||||
|
||||
|
||||
|
||||
#define bfd_elf64_bfd_link_add_symbols _bfd_e2k_elf_link_add_symbols
|
||||
#define bfd_elf64_bfd_reloc_type_lookup _bfd_e2k_elf_reloc_type_lookup
|
||||
#define bfd_elf64_bfd_reloc_name_lookup _bfd_e2k_elf_reloc_name_lookup
|
||||
#define bfd_elf64_bfd_merge_private_bfd_data _bfd_e2k_elf_merge_private_bfd_data
|
||||
#define bfd_elf64_mkobject _bfd_e2k_elf_mkobject
|
||||
#define bfd_elf64_bfd_link_hash_table_create _bfd_e2k_elf_link_hash_table_create
|
||||
#define bfd_elf64_bfd_final_link _bfd_e2k_elf_final_link
|
||||
#define bfd_elf64_get_synthetic_symtab _bfd_e2k_elf_get_synthetic_symtab
|
||||
#define bfd_elf64_write_object_contents _bfd_e2k_elf_write_object_contents
|
||||
#define bfd_elf64_bfd_copy_private_bfd_data _bfd_e2k_elf_copy_private_bfd_data
|
||||
|
||||
|
||||
#define elf_info_to_howto _bfd_e2k_elf_info_to_howto
|
||||
|
||||
#define elf_backend_add_symbol_hook _bfd_e2k_elf_add_symbol_hook
|
||||
#define elf_backend_special_sections _bfd_e2k_elf_special_sections
|
||||
#define elf_backend_common_definition _bfd_e2k_elf_common_definition
|
||||
#define elf_backend_merge_symbol_attribute _bfd_e2k_elf_merge_symbol_attribute
|
||||
#define elf_backend_grok_prstatus _bfd_e2k_elf_grok_prstatus
|
||||
#define elf_backend_write_core_note _bfd_e2k_elf_write_core_note
|
||||
|
||||
|
||||
/* This one is required in order to create `{,.rela}.plt' and . . .
|
||||
Typically backends have their own `create_dynamic_sections' method which
|
||||
calls `_bfd_elf_create_dynamic_sections ()'. */
|
||||
#define elf_backend_create_dynamic_sections _bfd_e2k_elf_create_dynamic_sections
|
||||
|
||||
#define elf_backend_copy_indirect_symbol _bfd_e2k_elf_copy_indirect_symbol
|
||||
#define elf_backend_check_directives _bfd_e2k_elf_check_directives
|
||||
#define elf_backend_check_relocs _bfd_e2k_elf_check_relocs
|
||||
#define elf_backend_gc_sweep_hook _bfd_e2k_elf_gc_sweep_hook
|
||||
#define elf_backend_adjust_dynamic_symbol _bfd_e2k_elf_adjust_dynamic_symbol
|
||||
#define elf_backend_size_dynamic_sections _bfd_e2k_elf_size_dynamic_sections
|
||||
#define elf_backend_action_discarded _bfd_e2k_elf_action_discarded
|
||||
#define elf_backend_relocate_section _bfd_e2k_elf_relocate_section
|
||||
#define elf_backend_finish_dynamic_symbol _bfd_e2k_elf_finish_dynamic_symbol
|
||||
#define elf_backend_reloc_type_class _bfd_e2k_elf_reloc_type_class
|
||||
#define elf_backend_finish_dynamic_sections _bfd_e2k_elf_finish_dynamic_sections
|
||||
#define elf_backend_init_file_header _bfd_e2k_elf_init_file_header
|
||||
#define elf_backend_ignore_discarded_relocs _bfd_e2k_elf_ignore_discarded_relocs
|
||||
#define elf_backend_hide_symbol _bfd_e2k_elf_hide_symbol
|
||||
#define elf_backend_object_p _bfd_e2k_elf_object_p
|
||||
#define elf_backend_setup_gnu_properties _bfd_e2k_elf_link_setup_gnu_properties
|
||||
|
||||
/* Make tests employing `gc-sections' option PASS. I wonder if any backend-
|
||||
specific support is required. TODO: place here actual names of the tests. */
|
||||
#define elf_backend_can_gc_sections 1
|
||||
#define elf_backend_want_got_sym 1
|
||||
/* I want got.refcount start from `0', not from `-1'
|
||||
(see _bfd_elf_link_hash_table_init). */
|
||||
#define elf_backend_can_refcount 1
|
||||
|
||||
#define elf_backend_want_got_plt 1
|
||||
#define elf_backend_plt_readonly 1
|
||||
|
||||
/* The first entry in `.got' is reserved for the `_DYNAMIC' link-time
|
||||
address. */
|
||||
#define elf_backend_got_header_size 24
|
||||
|
||||
/* This is required to ensure that addends of rela-relocations against section
|
||||
symbols are adjusted correctly during the relocatable linkage in
|
||||
`elf_link_input_bfd ()'. */
|
||||
#define elf_backend_rela_normal 1
|
||||
|
||||
#define elf_backend_plt_alignment 3
|
||||
|
||||
#define elf_backend_size_info elf64_e2k_size_info
|
||||
|
||||
#define elf_backend_extern_protected_data 1
|
||||
|
||||
#define elf_backend_r_none_info R_E2K_NONE
|
||||
|
||||
/* Let `bfd_elf_size_dynamic_sections ()' treat a missing PT_GNU_STACK as an
|
||||
unexecutable one to be in line with the Kernel and glibc. */
|
||||
#define elf_backend_default_execstack 0
|
||||
|
||||
|
||||
#define TARGET_LITTLE_SYM e2k_elf64_vec
|
||||
#define TARGET_LITTLE_NAME "elf64-e2k"
|
||||
#define ELF_ARCH bfd_arch_e2k
|
||||
|
||||
#define ELF_MACHINE_CODE EM_MCST_ELBRUS
|
||||
|
||||
/* This is the value we initially used. */
|
||||
#define ELF_MACHINE_ALT1 EM_E2K_OLD
|
||||
|
||||
#define ELF_MAXPAGESIZE 0x1000
|
||||
|
||||
/* Don't rush to set up BFD target vector if we are included on behalf of KPDA
|
||||
target: some of the above definitions are going to be altered by it. */
|
||||
#ifndef TARGET_KPDA
|
||||
#include "elf64-target.h"
|
||||
#endif /* ! TARGET_KPDA */
|
|
@ -662,6 +662,12 @@ elf64_sparc_merge_private_bfd_data (bfd *ibfd, struct bfd_link_info *info)
|
|||
flagword new_flags, old_flags;
|
||||
int new_mm, old_mm;
|
||||
|
||||
/* No matter whether the output BFD is ELF or not, check magic in the input
|
||||
one provided that it is. */
|
||||
if (bfd_get_flavour (ibfd) == bfd_target_elf_flavour
|
||||
&& ! _bfd_sparc_elf_check_magic (ibfd))
|
||||
return FALSE;
|
||||
|
||||
if (bfd_get_flavour (ibfd) != bfd_target_elf_flavour
|
||||
|| bfd_get_flavour (obfd) != bfd_target_elf_flavour)
|
||||
return TRUE;
|
||||
|
@ -682,8 +688,10 @@ elf64_sparc_merge_private_bfd_data (bfd *ibfd, struct bfd_link_info *info)
|
|||
{
|
||||
error = FALSE;
|
||||
|
||||
/* MCST extensions should be considered Sun- rather than HAL-compatible.
|
||||
See the code below. */
|
||||
#define EF_SPARC_ISA_EXTENSIONS \
|
||||
(EF_SPARC_SUN_US1 | EF_SPARC_SUN_US3 | EF_SPARC_HAL_R1)
|
||||
(EF_SPARC_SUN_US1 | EF_SPARC_SUN_US3 | EF_SPARC_MCST | EF_SPARC_HAL_R1)
|
||||
|
||||
if ((ibfd->flags & DYNAMIC) != 0)
|
||||
{
|
||||
|
@ -699,12 +707,14 @@ elf64_sparc_merge_private_bfd_data (bfd *ibfd, struct bfd_link_info *info)
|
|||
/* Choose the highest architecture requirements. */
|
||||
old_flags |= (new_flags & EF_SPARC_ISA_EXTENSIONS);
|
||||
new_flags |= (old_flags & EF_SPARC_ISA_EXTENSIONS);
|
||||
if ((old_flags & (EF_SPARC_SUN_US1 | EF_SPARC_SUN_US3))
|
||||
if ((old_flags & (EF_SPARC_SUN_US1 | EF_SPARC_SUN_US3
|
||||
| EF_SPARC_MCST))
|
||||
&& (old_flags & EF_SPARC_HAL_R1))
|
||||
{
|
||||
error = TRUE;
|
||||
_bfd_error_handler
|
||||
(_("%pB: linking UltraSPARC specific with HAL specific code"),
|
||||
(_("%pB: linking either UltraSPARC or MCST specific "
|
||||
"with HAL specific code"),
|
||||
ibfd);
|
||||
}
|
||||
/* Choose the most restrictive memory ordering. */
|
||||
|
@ -975,6 +985,18 @@ const struct elf_size_info elf64_sparc_size_info =
|
|||
/* Section 5.2.4 of the ABI specifies a 256-byte boundary for the table. */
|
||||
#define elf_backend_plt_alignment 8
|
||||
|
||||
/* EIR-specific hacks. */
|
||||
#define bfd_elf64_bfd_link_add_symbols _bfd_sparc_elf_link_add_symbols
|
||||
#define bfd_elf64_bfd_final_link _bfd_sparc_elf_final_link
|
||||
#define elf_backend_ignore_discarded_relocs _bfd_sparc_elf_ignore_discarded_relocs
|
||||
#define elf_backend_hide_symbol _bfd_sparc_elf_hide_symbol
|
||||
#define bfd_elf64_write_object_contents _bfd_sparc_elf_write_object_contents
|
||||
|
||||
/* Let `.magic' section be `SHT_NOTE'. */
|
||||
#define elf_backend_special_sections _bfd_sparc_elf_special_sections
|
||||
|
||||
#define elf_backend_extern_protected_data 1
|
||||
|
||||
#include "elf64-target.h"
|
||||
|
||||
/* FreeBSD support */
|
||||
|
|
|
@ -1906,26 +1906,23 @@ _bfd_elf_add_default_symbol (bfd *abfd,
|
|||
|
||||
if (hi->def_regular || ELF_COMMON_DEF_P (hi))
|
||||
{
|
||||
struct bfd_elf_version_tree *vertree = hi->verinfo.vertree;
|
||||
|
||||
/* If the undecorated symbol will have a version added by a
|
||||
script different to H, then don't indirect to/from the
|
||||
undecorated symbol. This isn't ideal because we may not yet
|
||||
have seen symbol versions, if given by a script on the
|
||||
command line rather than via --version-script. */
|
||||
if (hi->verinfo.vertree == NULL && info->version_info != NULL)
|
||||
if (vertree == NULL && info->version_info != NULL)
|
||||
{
|
||||
bfd_boolean hide;
|
||||
|
||||
hi->verinfo.vertree
|
||||
vertree
|
||||
= bfd_find_version_for_sym (info->version_info,
|
||||
hi->root.root.string, &hide);
|
||||
if (hi->verinfo.vertree != NULL && hide)
|
||||
{
|
||||
(*bed->elf_backend_hide_symbol) (info, hi, TRUE);
|
||||
goto nondefault;
|
||||
}
|
||||
}
|
||||
if (hi->verinfo.vertree != NULL
|
||||
&& strcmp (p + 1 + (p[1] == '@'), hi->verinfo.vertree->name) != 0)
|
||||
if (vertree != NULL
|
||||
&& strcmp (p + 1 + (p[1] == '@'), vertree->name) != 0)
|
||||
goto nondefault;
|
||||
}
|
||||
|
||||
|
@ -9379,6 +9376,12 @@ elf_link_sort_relocs (bfd *abfd, struct bfd_link_info *info, asection **psec)
|
|||
free (sort);
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* FIXME: currently there's an unresolved issue on Sparc making me
|
||||
occasionally allocate excessive space in `.rela.got', which is why
|
||||
'>=' is temporarely used here instead of '=='. */
|
||||
BFD_ASSERT (o->size >= o->reloc_count * ext_size);
|
||||
|
||||
erel = o->contents;
|
||||
erelend = o->contents + o->size;
|
||||
p = sort + o->output_offset * opb / ext_size * sort_elt;
|
||||
|
@ -10799,7 +10802,16 @@ elf_link_input_bfd (struct elf_final_link_info *flinfo, bfd *input_bfd)
|
|||
|
||||
/* We need to reverse-copy input .ctors/.dtors sections if
|
||||
they are placed in .init_array/.finit_array for output. */
|
||||
if (o->size > address_size
|
||||
if (
|
||||
#if 1
|
||||
/* However, there's no point in doing so in E2K Protected
|
||||
Mode. */
|
||||
(((elf_elfheader (input_bfd)->e_flags & 32 /* EF_E2K_PM */)
|
||||
!= 32 /* EF_E2K_PM */)
|
||||
|| strcmp (input_bfd->xvec->name, "elf32-e2k-pm") != 0)
|
||||
&&
|
||||
#endif /* 0 */
|
||||
o->size > address_size
|
||||
&& ((strncmp (o->name, ".ctors", 6) == 0
|
||||
&& strcmp (o->output_section->name,
|
||||
".init_array") == 0)
|
||||
|
@ -11062,7 +11074,14 @@ elf_link_input_bfd (struct elf_final_link_info *flinfo, bfd *input_bfd)
|
|||
bfd_elf_discard_info rely on reloc offsets
|
||||
being ordered. */
|
||||
irela->r_offset = last_offset;
|
||||
irela->r_info = 0;
|
||||
/* FIXME: I suppose that the original code setting
|
||||
`r_info' to 0 is sure to lead for an invalid result not
|
||||
only for E2K but for all targets with `R_xxx_NONE
|
||||
!= 0'. Moreover, it discards my attempts to setup
|
||||
R_E2K_NONE instead of an original relocation against a
|
||||
symbol coming from a discarded section in `_bfd_e2k_elf
|
||||
_relocate_section ()'. */
|
||||
irela->r_info = bed->r_none_info;
|
||||
irela->r_addend = 0;
|
||||
continue;
|
||||
}
|
||||
|
@ -14620,9 +14639,13 @@ _bfd_elf_copy_link_hash_symbol_type (bfd *abfd,
|
|||
void
|
||||
elf_append_rela (bfd *abfd, asection *s, Elf_Internal_Rela *rel)
|
||||
{
|
||||
static const char zero_rel[sizeof (Elf_Internal_Rela)];
|
||||
const struct elf_backend_data *bed = get_elf_backend_data (abfd);
|
||||
bfd_byte *loc = s->contents + (s->reloc_count++ * bed->s->sizeof_rela);
|
||||
BFD_ASSERT (loc + bed->s->sizeof_rela <= s->contents + s->size);
|
||||
|
||||
BFD_ASSERT (memcmp (rel, zero_rel, sizeof (zero_rel)) != 0);
|
||||
|
||||
bed->s->swap_reloca_out (abfd, rel, loc);
|
||||
}
|
||||
|
||||
|
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,305 @@
|
|||
/* E2k ELF specific backend routines.
|
||||
Copyright 2005, 2006, 2007, 2009 Free Software Foundation, Inc.
|
||||
|
||||
This file is part of BFD, the Binary File Descriptor library.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
|
||||
MA 02110-1301, USA. */
|
||||
|
||||
|
||||
/* E2K ELF linker hash table */
|
||||
|
||||
struct export_pl_list
|
||||
{
|
||||
struct export_pl_list *next;
|
||||
struct elf_link_hash_entry *h;
|
||||
};
|
||||
|
||||
struct _bfd_e2k_elf_link_hash_table
|
||||
{
|
||||
struct elf_link_hash_table elf;
|
||||
|
||||
/* Short-cuts to get to dynamic linker sections. */
|
||||
asection *sdynbss;
|
||||
asection *srelbss;
|
||||
|
||||
/* A section containing code performing static initialization of pointers
|
||||
in Protected Mode. */
|
||||
asection *selfinit;
|
||||
bfd_vma selfinit_off;
|
||||
|
||||
/* A set of PLs which should be made accessible to ld.so in Protected
|
||||
Mode. */
|
||||
asection *export_pl;
|
||||
struct export_pl_list *export_pl_list;
|
||||
|
||||
/* Small local sym cache. For example, it's used when we need local
|
||||
symbols to account for dynamic relocs against them (see
|
||||
check_relocs ()). Does this cache actually save any resources? */
|
||||
struct sym_cache sym_cache;
|
||||
|
||||
void (* put_word) (bfd *, bfd_vma, void *);
|
||||
bfd_vma (* r_info) (bfd_vma, bfd_vma);
|
||||
|
||||
/* Adjust offset of the corresponding dynamic relocation in a lazy PLT
|
||||
entry as soon as this offset is known. */
|
||||
void (* adjust_plt_lazy_entry_reloc_offset)
|
||||
(bfd *,
|
||||
struct _bfd_e2k_elf_link_hash_table *htab,
|
||||
asection *,
|
||||
bfd_vma,
|
||||
bfd_vma);
|
||||
|
||||
unsigned int word_align_power;
|
||||
|
||||
/* Interestingly enough, unlike Sparc i386 holds `plt_entry_size'
|
||||
in elf_backend_arch_data rather than in the hash table. Moreover, only
|
||||
i386 makes use of `elf_backend_arch_data' at present . . . */
|
||||
|
||||
|
||||
/* PLTGOT header, its size and offsets at which it should be adjusted at
|
||||
link time. */
|
||||
const unsigned int *plt_got_header;
|
||||
unsigned int plt_got_header_nop_offset;
|
||||
unsigned int plt_got_link_map_ld_offset;
|
||||
unsigned int plt_got_dl_fixup_ld_offset;
|
||||
unsigned int plt_got_header_size;
|
||||
|
||||
|
||||
const unsigned int *plt_got_primary_entry;
|
||||
unsigned int plt_got_entry_nop_offset;
|
||||
unsigned int plt_got_target_ld_offset;
|
||||
unsigned int plt_got_primary_entry_size;
|
||||
|
||||
const unsigned int *plt_got_secondary_entry;
|
||||
unsigned int plt_got_reloc_arg_offset;
|
||||
unsigned int plt_got_disp_offset;
|
||||
unsigned int plt_got_secondary_entry_size;
|
||||
|
||||
int bytes_per_word;
|
||||
|
||||
/* Stores `sizeof (Elfxx_External_Sym)'. */
|
||||
int bytes_per_sym;
|
||||
|
||||
int bytes_per_rela;
|
||||
int abs_reloc;
|
||||
int abs_lit_reloc;
|
||||
int copy_reloc;
|
||||
int relative_reloc;
|
||||
int relative_lit_reloc;
|
||||
int dtpmod_reloc;
|
||||
int dtpoff_reloc;
|
||||
int tpoff_reloc;
|
||||
int jmp_slot_reloc;
|
||||
int irelative_reloc;
|
||||
|
||||
/* Ancient semantics value is stored here depending on the output file's
|
||||
ABI. Used when producing an old-style output ELF. */
|
||||
int ancient_semantics;
|
||||
|
||||
/* Throw them away from our hash table so that we don't need to duplicate
|
||||
these fields in PM hash table and then decide which hash table should
|
||||
be used within common code. */
|
||||
#if 0
|
||||
/* `--e2k-ipd' option may take values 0, 1 and 2 only. */
|
||||
int e2k_ipd:2;
|
||||
int e2k_is_x86app:1;
|
||||
int e2k_is_4mpages:1;
|
||||
#endif /* 0 */
|
||||
|
||||
/* `relaxed_e2k_machine_check' is required when merging private bfd data
|
||||
where link_info is not available. Therefore it's not present here.
|
||||
|
||||
Probably `output_new_e_machine' may be set when link_info does not exist
|
||||
at all. Therefore, it's absent here as well. This issue is to be
|
||||
revisited. */
|
||||
|
||||
bfd_boolean have_dsp_output;
|
||||
bfd_boolean dsp_non_empty_data[16];
|
||||
bfd_boolean dsp_non_empty_rodata[16];
|
||||
|
||||
/* Offset of a GOT entry holding runtime index of the module being linked
|
||||
(OBFD). To specify this module a runtime relocation against the dynamic
|
||||
symbol #0, which is local by its nature, is used. */
|
||||
bfd_vma gdmod_zero_off;
|
||||
|
||||
/* The numbers of primary and secondary PLT entries in the current link. */
|
||||
bfd_vma primary_plt_num;
|
||||
bfd_vma secondary_plt_num;
|
||||
};
|
||||
|
||||
/* This variable should be accessible from multiple modules. Moreover, it
|
||||
shouldn't be associated with LINK_INFO since its value may be required when
|
||||
no LINK_INFO exists at all, e.g. when writing out Program Headers and
|
||||
deciding whether to hack VMA's or not. */
|
||||
extern bfd_boolean e2k_dsp_linux_mode;
|
||||
|
||||
|
||||
/* Get the E2k ELF linker hash table from a link_info structure. */
|
||||
|
||||
#define _bfd_e2k_elf_hash_table(p) \
|
||||
(elf_hash_table_id ((struct elf_link_hash_table *) ((p)->hash)) \
|
||||
== E2K_ELF_DATA ? ((struct _bfd_e2k_elf_link_hash_table *) ((p)->hash)) : NULL)
|
||||
|
||||
|
||||
|
||||
/* Methods of struct bfd_target */
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_link_add_symbols
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern reloc_howto_type * _bfd_e2k_elf_reloc_type_lookup
|
||||
(bfd *, bfd_reloc_code_real_type);
|
||||
|
||||
extern reloc_howto_type * _bfd_e2k_elf_reloc_name_lookup
|
||||
(bfd *, const char *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_merge_private_bfd_data_1
|
||||
(bfd *, bfd *, bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_merge_private_bfd_data
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_mkobject
|
||||
(bfd *);
|
||||
|
||||
extern struct bfd_link_hash_table * _bfd_e2k_elf_link_hash_table_create
|
||||
(bfd *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_create_dynamic_sections
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_final_link
|
||||
(bfd *abfd, struct bfd_link_info *info);
|
||||
|
||||
|
||||
/* Methods of struct elf_backend_data */
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_info_to_howto
|
||||
(bfd *, arelent *, Elf_Internal_Rela *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_add_symbol_hook
|
||||
(bfd *, struct bfd_link_info *, Elf_Internal_Sym *, const char **,
|
||||
flagword *, asection **, bfd_vma *);
|
||||
|
||||
|
||||
extern void _bfd_e2k_elf_copy_indirect_symbol (struct bfd_link_info *,
|
||||
struct elf_link_hash_entry *,
|
||||
struct elf_link_hash_entry *);
|
||||
|
||||
extern bfd_boolean
|
||||
_bfd_e2k_elf_check_directives (bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_check_relocs
|
||||
(bfd *, struct bfd_link_info *,
|
||||
asection *, const Elf_Internal_Rela *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_gc_sweep_hook
|
||||
(bfd *abfd,
|
||||
struct bfd_link_info *info,
|
||||
asection *sec,
|
||||
const Elf_Internal_Rela *relocs);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_adjust_dynamic_symbol
|
||||
(struct bfd_link_info *, struct elf_link_hash_entry *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_size_dynamic_sections
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern unsigned int _bfd_e2k_elf_action_discarded
|
||||
(asection *);
|
||||
|
||||
extern bfd_boolean simulating_mode;
|
||||
|
||||
extern int simulate_relocate_section (bfd *input_bfd,
|
||||
asection *input_section,
|
||||
bfd_byte *contents,
|
||||
Elf_Internal_Rela *relocs);
|
||||
|
||||
extern int _bfd_e2k_elf_relocate_section
|
||||
(bfd *, struct bfd_link_info *, bfd *,
|
||||
asection *, bfd_byte *, Elf_Internal_Rela *,
|
||||
Elf_Internal_Sym *, asection **);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_finish_dynamic_symbol
|
||||
(bfd *, struct bfd_link_info *,
|
||||
struct elf_link_hash_entry *, Elf_Internal_Sym *sym);
|
||||
|
||||
extern enum elf_reloc_type_class
|
||||
_bfd_e2k_elf_reloc_type_class (const struct bfd_link_info *,
|
||||
const asection *,
|
||||
const Elf_Internal_Rela *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_finish_dynamic_sections
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_init_file_header_1
|
||||
(bfd *, struct bfd_link_info *, bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_init_file_header
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_ignore_discarded_relocs
|
||||
(asection *);
|
||||
|
||||
extern void _bfd_e2k_elf_hide_symbol_1
|
||||
(struct bfd_link_info *,
|
||||
struct elf_link_hash_entry *,
|
||||
bfd_boolean,
|
||||
bfd_boolean);
|
||||
|
||||
extern void _bfd_e2k_elf_hide_symbol
|
||||
(struct bfd_link_info *,
|
||||
struct elf_link_hash_entry *,
|
||||
bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_write_object_contents
|
||||
(bfd *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_copy_private_bfd_data_1
|
||||
(bfd *, bfd *, bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_copy_private_bfd_data
|
||||
(bfd *, bfd *);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_object_p_1
|
||||
(bfd *, bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_object_p
|
||||
(bfd *);
|
||||
|
||||
extern bfd * _bfd_e2k_elf_link_setup_gnu_properties
|
||||
(struct bfd_link_info *);
|
||||
|
||||
extern long _bfd_e2k_elf_get_synthetic_symtab
|
||||
(bfd *, long, asymbol **, long, asymbol **, asymbol **);
|
||||
|
||||
extern void _bfd_e2k_elf_after_parse (int);
|
||||
|
||||
extern void _bfd_e2k_elf_after_open (int, int, int, bfd_boolean, bfd_boolean,
|
||||
bfd_boolean, bfd_boolean, bfd_boolean);
|
||||
|
||||
extern const struct bfd_elf_special_section _bfd_e2k_elf_special_sections[];
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_common_definition (Elf_Internal_Sym *);
|
||||
|
||||
extern void _bfd_e2k_elf_merge_symbol_attribute (struct elf_link_hash_entry *,
|
||||
const Elf_Internal_Sym *,
|
||||
bfd_boolean,
|
||||
bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_e2k_elf_grok_prstatus (bfd *, Elf_Internal_Note *);
|
||||
|
||||
extern char * _bfd_e2k_elf_write_core_note (bfd *, char *, int *, int, ...);
|
|
@ -0,0 +1,190 @@
|
|||
#define MYHOWTO(C, R,S,B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \
|
||||
[C] = HOWTO(C, R,S,B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC)
|
||||
|
||||
MYHOWTO (R_ELCORE_NONE, /* type */
|
||||
0, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
32, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_dont, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_NONE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0, /* src_mask */
|
||||
0, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
/* relocation for I5 */
|
||||
MYHOWTO (R_ELCORE_I5, /* type */
|
||||
2, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
5, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
27, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I5", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0xf8000000, /* src_mask */
|
||||
0xf8000000, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
/* relocation for I5 */
|
||||
MYHOWTO (R_ELCORE_I5_FAKE, /* type */
|
||||
0, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
5, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
27, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I5_FAKE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0xf8000000, /* src_mask */
|
||||
0xf8000000, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
|
||||
MYHOWTO (R_ELCORE_I16, /* type */
|
||||
2, /* rightshift */
|
||||
1, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
0, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I16", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x0000ffff, /* src_mask */
|
||||
0x0000ffff, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_I16_FAKE, /* type */
|
||||
0, /* rightshift */
|
||||
1, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
0, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I16_FAKE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x0000ffff, /* src_mask */
|
||||
0x0000ffff, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_I16PC, /* type */
|
||||
2, /* rightshift */
|
||||
1, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
0, /* bitsize */
|
||||
TRUE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I16PC", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x0000ffff, /* src_mask */
|
||||
0x0000ffff, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_I16PC_FAKE, /* type */
|
||||
0, /* rightshift */
|
||||
1, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
0, /* bitsize */
|
||||
TRUE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I16PC_FAKE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x0000ffff, /* src_mask */
|
||||
0x0000ffff, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_S16, /* type */
|
||||
2, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
16, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
11, /* bitpos */
|
||||
complain_overflow_dont, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_S16", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x07fff800, /* src_mask */
|
||||
0x07fff800, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_S16_FAKE, /* type */
|
||||
0, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
16, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
11, /* bitpos */
|
||||
complain_overflow_dont, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_S16_FAKE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x07fff800, /* src_mask */
|
||||
0x07fff800, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_S16PC, /* type */
|
||||
2, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
16, /* bitsize */
|
||||
TRUE, /* pc_relative */
|
||||
11, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_S16PC", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x07fff800, /* src_mask */
|
||||
0x07fff800, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_S16PC_FAKE, /* type */
|
||||
0, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
16, /* bitsize */
|
||||
TRUE, /* pc_relative */
|
||||
11, /* bitpos */
|
||||
complain_overflow_bitfield, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_S16PC_FAKE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0x07fff800, /* src_mask */
|
||||
0x07fff800, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
/* A standard 32 bit relocation. */
|
||||
MYHOWTO (R_ELCORE_I32, /* type */
|
||||
2, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
32, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_dont, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I32", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0xffffffff, /* src_mask */
|
||||
0xffffffff, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
MYHOWTO (R_ELCORE_I32_FAKE, /* type */
|
||||
0, /* rightshift */
|
||||
2, /* size (0 = byte, 1 = short, 2 = long) */
|
||||
32, /* bitsize */
|
||||
FALSE, /* pc_relative */
|
||||
0, /* bitpos */
|
||||
complain_overflow_dont, /* complain_on_overflow */
|
||||
bfd_elf_generic_reloc, /* special_function */
|
||||
"R_ELCORE_I32_FAKE", /* name */
|
||||
FALSE, /* partial_inplace */
|
||||
0xffffffff, /* src_mask */
|
||||
0xffffffff, /* dst_mask */
|
||||
FALSE), /* pcrel_offset */
|
||||
|
||||
#undef MYHOWTO
|
|
@ -2345,6 +2345,16 @@ allocate_dynrelocs (struct elf_link_hash_entry *h, void * inf)
|
|||
return FALSE;
|
||||
}
|
||||
}
|
||||
|
||||
/* Input relocations in `.rela.xxx' sections against ifunctions defined
|
||||
in regular object files are not copied to the output file (see how
|
||||
they are treated in relocate_section () below). Therefore, avoid
|
||||
allocating redundant space for them below. The failure to recognize
|
||||
this issue turned out to be the reason for Bugs #81941 and #88486. */
|
||||
if (eh->dyn_relocs != NULL
|
||||
&& h->type == STT_GNU_IFUNC
|
||||
&& h->def_regular)
|
||||
eh->dyn_relocs = NULL;
|
||||
}
|
||||
else
|
||||
{
|
||||
|
@ -2502,6 +2512,20 @@ _bfd_sparc_elf_size_dynamic_sections (bfd *output_bfd,
|
|||
{
|
||||
struct elf_dyn_relocs *p;
|
||||
|
||||
/* Don't allocate space for dynamic relocations not only if the
|
||||
section to which they are applied is discarded (condition in the
|
||||
loop a few lines below takes care of that), but also if the section
|
||||
"against" which they are resolved is. This lets me resolve an issue
|
||||
when LD manages without creation of dynamic relocations against
|
||||
discarded `.gnu.linkonce'-sections within kept `.eh_frame's (as you
|
||||
remember the contents of the latter is modified somehow to
|
||||
eliminate the need for dynamic relocations then): allocation of
|
||||
redundant space would lead to an assertion failure described in
|
||||
Bug #79553. For a more detailed example see the commit. */
|
||||
if (!bfd_is_abs_section (s)
|
||||
&& bfd_is_abs_section (s->output_section))
|
||||
continue;
|
||||
|
||||
for (p = elf_section_data (s)->local_dynrel; p != NULL; p = p->next)
|
||||
{
|
||||
if (!bfd_is_abs_section (p->sec)
|
||||
|
@ -4844,20 +4868,29 @@ _bfd_sparc_elf_finish_dynamic_sections (bfd *output_bfd, struct bfd_link_info *i
|
|||
? 0 : htab->plt_entry_size);
|
||||
}
|
||||
|
||||
/* Set the first entry in the global offset table to the address of
|
||||
the dynamic section. */
|
||||
if (htab->elf.sgot && htab->elf.sgot->size > 0)
|
||||
{
|
||||
bfd_vma val = (sdyn ?
|
||||
sdyn->output_section->vma + sdyn->output_offset :
|
||||
0);
|
||||
|
||||
SPARC_ELF_PUT_WORD (htab, output_bfd, val, htab->elf.sgot->contents);
|
||||
}
|
||||
|
||||
if (htab->elf.sgot)
|
||||
elf_section_data (htab->elf.sgot->output_section)->this_hdr.sh_entsize =
|
||||
SPARC_ELF_WORD_BYTES (htab);
|
||||
{
|
||||
if (bfd_is_abs_section (htab->elf.sgot->output_section))
|
||||
{
|
||||
_bfd_error_handler
|
||||
(_("discarded output section: `%pA'"), htab->elf.sgot);
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
/* Set the first entry in the global offset table to the address of
|
||||
the dynamic section. */
|
||||
if (htab->elf.sgot->size > 0)
|
||||
{
|
||||
bfd_vma val = (sdyn ?
|
||||
sdyn->output_section->vma + sdyn->output_offset :
|
||||
0);
|
||||
|
||||
SPARC_ELF_PUT_WORD (htab, output_bfd, val, htab->elf.sgot->contents);
|
||||
}
|
||||
|
||||
elf_section_data (htab->elf.sgot->output_section)->this_hdr.sh_entsize =
|
||||
SPARC_ELF_WORD_BYTES (htab);
|
||||
}
|
||||
|
||||
/* Fill PLT and GOT entries for local STT_GNU_IFUNC symbols. */
|
||||
htab_traverse (htab->loc_hash_table, finish_local_dynamic_symbol, info);
|
||||
|
@ -4912,11 +4945,23 @@ _bfd_sparc_elf_object_p (bfd *abfd)
|
|||
| ELF_SPARC_HWCAP2_RLE
|
||||
| ELF_SPARC_HWCAP2_SHA3);
|
||||
|
||||
unsigned int r2000_hwcaps_mask = ELF_SPARC_HWCAP_SAPPHIRE;
|
||||
unsigned int r2000_plus_hwcaps2_mask = ELF_SPARC_HWCAP2_SAPPHIRE_PLUS;
|
||||
|
||||
if (ABI_64_P (abfd))
|
||||
{
|
||||
unsigned long mach = bfd_mach_sparc_v9;
|
||||
|
||||
if (hwcaps2->i & m8_hwcaps2_mask)
|
||||
if (elf_elfheader (abfd)->e_flags & EF_SPARC_MCST)
|
||||
{
|
||||
if (hwcaps2->i & r2000_plus_hwcaps2_mask)
|
||||
mach = bfd_mach_sparc_v9_r2000_plus;
|
||||
else if (hwcaps->i & r2000_hwcaps_mask)
|
||||
mach = bfd_mach_sparc_v9_r2000;
|
||||
else
|
||||
mach = bfd_mach_sparc_v9_r1000;
|
||||
}
|
||||
else if (hwcaps2->i & m8_hwcaps2_mask)
|
||||
mach = bfd_mach_sparc_v9m8;
|
||||
else if (hwcaps2->i & v9m_hwcaps2_mask)
|
||||
mach = bfd_mach_sparc_v9m;
|
||||
|
@ -4938,7 +4983,20 @@ _bfd_sparc_elf_object_p (bfd *abfd)
|
|||
{
|
||||
if (elf_elfheader (abfd)->e_machine == EM_SPARC32PLUS)
|
||||
{
|
||||
if (hwcaps2->i & m8_hwcaps2_mask)
|
||||
if (elf_elfheader (abfd)->e_flags & EF_SPARC_MCST)
|
||||
{
|
||||
if (hwcaps2->i & r2000_plus_hwcaps2_mask)
|
||||
return
|
||||
bfd_default_set_arch_mach (abfd, bfd_arch_sparc,
|
||||
bfd_mach_sparc_v8plus_r2000_plus);
|
||||
else if (hwcaps->i & r2000_hwcaps_mask)
|
||||
return bfd_default_set_arch_mach (abfd, bfd_arch_sparc,
|
||||
bfd_mach_sparc_v8plus_r2000);
|
||||
else
|
||||
return bfd_default_set_arch_mach (abfd, bfd_arch_sparc,
|
||||
bfd_mach_sparc_v8plus_r1000);
|
||||
}
|
||||
else if (hwcaps2->i & m8_hwcaps2_mask)
|
||||
return bfd_default_set_arch_mach (abfd, bfd_arch_sparc,
|
||||
bfd_mach_sparc_v8plusm8);
|
||||
else if (hwcaps2->i & v9m_hwcaps2_mask)
|
||||
|
@ -5040,3 +5098,380 @@ _bfd_sparc_elf_merge_private_bfd_data (bfd *ibfd, struct bfd_link_info *info)
|
|||
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
|
||||
/* EIR specific methods. */
|
||||
|
||||
static int link_mixed_eir_phase;
|
||||
static bfd_boolean met_eir_section;
|
||||
static bfd_boolean eir_in_this_bfd;
|
||||
|
||||
void
|
||||
_bfd_sparc_elf_after_parse (int phase)
|
||||
{
|
||||
link_mixed_eir_phase = phase;
|
||||
}
|
||||
|
||||
static void
|
||||
search_eir (bfd *abfd ATTRIBUTE_UNUSED, asection *sect, void *obj ATTRIBUTE_UNUSED)
|
||||
{
|
||||
if (strcmp (sect->name, ".pack_pure_eir") == 0
|
||||
|| strcmp (sect->name, ".pack_mixed_eir") == 0)
|
||||
{
|
||||
met_eir_section = TRUE;
|
||||
eir_in_this_bfd = TRUE;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
static void
|
||||
discard_unsuitable_section (bfd *abfd ATTRIBUTE_UNUSED, asection *sect, void *obj ATTRIBUTE_UNUSED)
|
||||
{
|
||||
|
||||
if ((link_mixed_eir_phase == 1 && met_eir_section)
|
||||
|| (link_mixed_eir_phase == 3
|
||||
&& (!(met_eir_section && !eir_in_this_bfd)
|
||||
|| abfd->my_archive)))
|
||||
{
|
||||
/* SEC_DEBUGGING is required to fool lang_gc_sections in ldlang.c */
|
||||
sect->flags |= (SEC_EXCLUDE | SEC_DEBUGGING);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
static void
|
||||
search_pure_eir (bfd *abfd, asection *sec, void *no_pure_eir)
|
||||
{
|
||||
if (strcmp (sec->name, ".pack_pure_eir") == 0)
|
||||
{
|
||||
*((bfd_boolean *) no_pure_eir) = FALSE;
|
||||
_bfd_error_handler ("%pB with '.pack_pure_eir' is illegal during "
|
||||
"non-relocatable linkage", abfd);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
bfd_boolean
|
||||
_bfd_sparc_elf_link_add_symbols (bfd *abfd, struct bfd_link_info *info)
|
||||
{
|
||||
bfd_boolean ret;
|
||||
|
||||
/* Check for the absence of `.pack_pure_eir' sections during
|
||||
non-relocatable linkage (see Bug #41413). */
|
||||
if (bfd_get_format (abfd) == bfd_object && info
|
||||
&& !bfd_link_relocatable (info))
|
||||
{
|
||||
bfd_boolean no_pure_eir = TRUE;
|
||||
bfd_map_over_sections (abfd, search_pure_eir, &no_pure_eir);
|
||||
|
||||
if (! no_pure_eir)
|
||||
return FALSE;
|
||||
|
||||
}
|
||||
|
||||
ret = bfd_elf_link_add_symbols (abfd, info);
|
||||
|
||||
/* COMMON sections are created while COMMON symbols are being
|
||||
read rather than while parsing input file's section headers.
|
||||
Therefore, a call to `bfd_elf_link_add_symbols ()' should
|
||||
precede the following, provided that we need to be able to
|
||||
discard COMMON sections. And we actually need this (see
|
||||
Bug #57962). */
|
||||
if ((link_mixed_eir_phase == 1
|
||||
|| link_mixed_eir_phase == 3)
|
||||
&& bfd_get_format (abfd) == bfd_object)
|
||||
{
|
||||
eir_in_this_bfd = FALSE;
|
||||
bfd_map_over_sections (abfd, search_eir, NULL);
|
||||
bfd_map_over_sections (abfd, discard_unsuitable_section, NULL);
|
||||
}
|
||||
|
||||
return ret;
|
||||
}
|
||||
|
||||
bfd_boolean
|
||||
_bfd_sparc_elf_final_link (bfd *abfd, struct bfd_link_info *info)
|
||||
{
|
||||
/* There is nothing to be done here if we are going to output
|
||||
a binary file when linking EIR (see Bug #59012, Comment # ). */
|
||||
if (link_mixed_eir_phase == 2)
|
||||
return TRUE;
|
||||
|
||||
return bfd_elf_final_link (abfd, info);
|
||||
}
|
||||
|
||||
bfd_boolean
|
||||
_bfd_sparc_elf_ignore_discarded_relocs (asection *sec)
|
||||
{
|
||||
bfd *abfd;
|
||||
size_t locsymcount;
|
||||
Elf_Internal_Shdr *symtab_hdr;
|
||||
Elf_Internal_Rela *internal_relocs;
|
||||
Elf_Internal_Rela *rel, *relend;
|
||||
struct elf_link_hash_entry **sym_hashes;
|
||||
const struct elf_backend_data *bed;
|
||||
int r_sym_shift;
|
||||
|
||||
if (link_mixed_eir_phase != 1
|
||||
&& link_mixed_eir_phase !=3)
|
||||
return FALSE;
|
||||
|
||||
abfd = sec->owner;
|
||||
symtab_hdr = &elf_tdata (abfd)->symtab_hdr;
|
||||
locsymcount = symtab_hdr->sh_info;
|
||||
|
||||
bed = get_elf_backend_data (abfd);
|
||||
|
||||
internal_relocs = _bfd_elf_link_read_relocs (abfd, sec, NULL, NULL, FALSE);
|
||||
rel = internal_relocs;
|
||||
relend = rel + sec->reloc_count * bed->s->int_rels_per_ext_rel;
|
||||
|
||||
r_sym_shift = (bed->s->arch_size == 32) ? 8 : 32;
|
||||
|
||||
|
||||
sym_hashes = elf_sym_hashes (abfd);
|
||||
for ( ; rel < relend; rel++)
|
||||
{
|
||||
unsigned long r_symndx = rel->r_info >> r_sym_shift;
|
||||
struct elf_link_hash_entry *h = NULL;
|
||||
|
||||
if (r_symndx == STN_UNDEF)
|
||||
continue;
|
||||
|
||||
if (r_symndx >= locsymcount)
|
||||
{
|
||||
h = sym_hashes[r_symndx - locsymcount];
|
||||
|
||||
while (h->root.type == bfd_link_hash_indirect
|
||||
|| h->root.type == bfd_link_hash_warning)
|
||||
h = (struct elf_link_hash_entry *) h->root.u.i.link;
|
||||
|
||||
if (((h->root.type == bfd_link_hash_defined
|
||||
|| h->root.type == bfd_link_hash_defweak)
|
||||
&& discarded_section (h->root.u.def.section))
|
||||
/* Don't forget about common symbols. Their sections may
|
||||
very well be discarded as well. */
|
||||
|| (h->root.type == bfd_link_hash_common
|
||||
&& discarded_section (h->root.u.c.p->section)))
|
||||
#if 0
|
||||
/* I don't have legal access to this (link) info . . . */
|
||||
&& (h->root.u.def.next || . . .)
|
||||
#endif /* 0 */
|
||||
{
|
||||
/* Stupidly make it undefined. Is it going to work? */
|
||||
h->root.type = bfd_link_hash_undefined;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* free (internal_relocs); */
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
void
|
||||
_bfd_sparc_elf_hide_symbol (struct bfd_link_info *info,
|
||||
struct elf_link_hash_entry *h,
|
||||
bfd_boolean force_local)
|
||||
{
|
||||
/* I don't want to hide (make local) symbols from unsuitable
|
||||
(SEC_EXCLUDE | SEC_DEBUGGING) sections
|
||||
(see discard_unsuitable_section () before) in EIR linkage
|
||||
mode. Prevent the code in `elf_link_add_object_symbols ()'
|
||||
from achieving this. Interestingly enough, there is no attempt
|
||||
to hide these symbols in binutils-2.21. */
|
||||
|
||||
if (link_mixed_eir_phase != 1 && link_mixed_eir_phase != 3)
|
||||
_bfd_elf_link_hash_hide_symbol (info, h, force_local);
|
||||
}
|
||||
|
||||
struct write_eir_info
|
||||
{
|
||||
bfd_size_type max_size;
|
||||
bfd_byte *contents;
|
||||
/* This is set to FALSE if `_bfd_e2k_write_eir_contens ()' fails
|
||||
for any section. */
|
||||
bfd_boolean res;
|
||||
};
|
||||
|
||||
static void
|
||||
write_eir_contents (bfd *abfd ATTRIBUTE_UNUSED,
|
||||
asection *s,
|
||||
void *param)
|
||||
{
|
||||
static bfd_vma s_offset;
|
||||
bfd_vma next_s_offset;
|
||||
bfd_vma mask;
|
||||
struct bfd_link_order *p;
|
||||
struct write_eir_info *wei;
|
||||
|
||||
/* There is nothing to do for non-EIR sections. */
|
||||
if (strcmp (s->name, ".pack_pure_eir") != 0
|
||||
&& strcmp (s->name, ".pack_mixed_eir") != 0)
|
||||
return;
|
||||
|
||||
wei = (struct write_eir_info *) param;
|
||||
/* If we've already failed, there is no point in continuing. */
|
||||
if (wei->res == FALSE)
|
||||
return;
|
||||
|
||||
mask = (1 << s->alignment_power) - 1;
|
||||
s_offset = (s_offset + mask) & ~mask;
|
||||
next_s_offset = s_offset;
|
||||
|
||||
for (p = s->map_head.link_order; p != NULL; p = p->next)
|
||||
{
|
||||
asection *i;
|
||||
|
||||
if (p->type != bfd_indirect_link_order)
|
||||
continue;
|
||||
|
||||
i = p->u.indirect.section;
|
||||
|
||||
if (i->size > 0)
|
||||
{
|
||||
if (i->size > wei->max_size)
|
||||
{
|
||||
wei->max_size = i->size;
|
||||
wei->contents = (bfd_byte *) bfd_realloc (wei->contents,
|
||||
wei->max_size);
|
||||
}
|
||||
|
||||
if (s_offset + i->output_offset + i->size > next_s_offset)
|
||||
next_s_offset = s_offset + i->output_offset + i->size;
|
||||
|
||||
if (! bfd_get_section_contents (i->owner, i, wei->contents,
|
||||
0, i->size)
|
||||
|| bfd_seek (abfd, s_offset + i->output_offset, SEEK_SET) != 0
|
||||
|| bfd_bwrite (wei->contents, i->size, abfd) != i->size)
|
||||
{
|
||||
wei->res = FALSE;
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* Setting initial `s_offset' value for the next invocation. */
|
||||
s_offset = next_s_offset;
|
||||
}
|
||||
|
||||
|
||||
/* This function gets called when BFD is being closed. Avoid calling
|
||||
an ELF-specific method (which outputs strtab, . . .) when a raw
|
||||
binary for EIR is required. */
|
||||
bfd_boolean
|
||||
_bfd_sparc_elf_write_object_contents (bfd *abfd)
|
||||
{
|
||||
struct write_eir_info wei;
|
||||
|
||||
if (link_mixed_eir_phase != 2)
|
||||
return _bfd_elf_write_object_contents (abfd);
|
||||
|
||||
wei.max_size = 0;
|
||||
wei.contents = NULL;
|
||||
wei.res = TRUE;
|
||||
|
||||
/* Calculating positions of EIR sections and setting their contents. */
|
||||
bfd_map_over_sections (abfd, write_eir_contents, &wei);
|
||||
|
||||
if (wei.contents)
|
||||
free (wei.contents);
|
||||
|
||||
return wei.res;
|
||||
}
|
||||
|
||||
|
||||
/* This is a helper of `_bfd_sparc_elf_check_magic () below. */
|
||||
static bfd_boolean
|
||||
check_magic (bfd *abfd, asection *magic_sec)
|
||||
{
|
||||
char *magic = getenv ("MAGIC");
|
||||
size_t magic_size;
|
||||
char *data;
|
||||
bfd_boolean res = FALSE;
|
||||
|
||||
BFD_ASSERT (magic);
|
||||
magic_size = strlen (magic) + 1;
|
||||
|
||||
data = xmalloc (magic_sec->size);
|
||||
if (! bfd_get_section_contents (abfd, magic_sec, data, 0, magic_sec->size))
|
||||
{
|
||||
_bfd_error_handler (_("%pB: cannot read contents of section %pA\n"),
|
||||
abfd, magic_sec);
|
||||
}
|
||||
|
||||
if (magic_sec->size == (12 + ((sizeof ("MCST") + 3) & 0xfffffffc)
|
||||
+ ((magic_size + 3) & 0xfffffffc))
|
||||
&& bfd_get_32 (abfd, data) == sizeof ("MCST")
|
||||
&& bfd_get_32 (abfd, data + 4) == magic_size
|
||||
&& bfd_get_32 (abfd, data + 8) == NT_MAGIC
|
||||
&& data[12 + sizeof ("MCST") - 1] == '\0'
|
||||
&& data[12 + ((sizeof ("MCST") + 3) & 0xfffffffc)
|
||||
+ magic_size - 1] == '\0'
|
||||
&& strncmp (data + 12, "MCST", sizeof ("MCST") - 1) == 0
|
||||
&& strncmp (data + 12 + ((sizeof ("MCST") + 3) & 0xfffffffc), magic,
|
||||
magic_size - 1) == 0)
|
||||
res = TRUE;
|
||||
|
||||
free (data);
|
||||
return res;
|
||||
}
|
||||
|
||||
|
||||
/* This function is required to implement MCST-specific MAGIC checks
|
||||
(see Bug #67430). It gets called from `elf{32,64}_sparc_merge_private_bfd
|
||||
_data ()' so that they don't have a chance to `return TRUE' without
|
||||
performing this test (see their code just after the call to this function
|
||||
for how it may happen).
|
||||
|
||||
FIXME: this function replicates the analogous part of
|
||||
`_bfd_e2k_elf_merge_private_bfd_data_1 ()' in `elfxx-e2k.c'. Get rid of this
|
||||
awful Copy/Paste by placing them in some common (for E2K and Sparc) source
|
||||
file. Its`check_magic ()' helper and EIR-specific functions should probably
|
||||
go there as well. */
|
||||
|
||||
bfd_boolean
|
||||
_bfd_sparc_elf_check_magic (bfd *ibfd)
|
||||
{
|
||||
if (! getenv ("MAGIC"))
|
||||
return TRUE;
|
||||
|
||||
asection *magic_sec;
|
||||
static bfd_boolean first_ibfd_saved = TRUE;
|
||||
bfd_boolean res, first_ibfd = first_ibfd_saved;
|
||||
|
||||
/* Next time `first_ibfd' will be set to FALSE. */
|
||||
first_ibfd_saved = FALSE;
|
||||
|
||||
magic_sec = bfd_get_section_by_name (ibfd, ".magic");
|
||||
if (magic_sec == NULL)
|
||||
{
|
||||
_bfd_error_handler (_("Input object %pB doesn't have a .magic "
|
||||
"section"), ibfd);
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
res = check_magic (ibfd, magic_sec);
|
||||
/* Exclude this section from output no matter what `check_magic ()'
|
||||
returned, though it's not absolutely necessary if it failed: we are
|
||||
not going to have any output in this case. */
|
||||
if (! first_ibfd)
|
||||
{
|
||||
magic_sec->flags |= SEC_EXCLUDE;
|
||||
magic_sec->size = 0;
|
||||
}
|
||||
|
||||
if (! res)
|
||||
{
|
||||
_bfd_error_handler (_("Input object %pB contains wrong MAGIC "),
|
||||
ibfd);
|
||||
return FALSE;
|
||||
}
|
||||
|
||||
return TRUE;
|
||||
}
|
||||
|
||||
const struct bfd_elf_special_section _bfd_sparc_elf_special_sections[] =
|
||||
{
|
||||
{ STRING_COMMA_LEN (".magic"), 0, SHT_NOTE, 0 },
|
||||
{ NULL, 0, 0, 0, 0 }
|
||||
};
|
||||
|
|
|
@ -144,3 +144,27 @@ extern bfd_vma _bfd_sparc_elf_plt_sym_val
|
|||
(bfd_vma, const asection *, const arelent *);
|
||||
extern bfd_boolean _bfd_sparc_elf_merge_private_bfd_data
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
|
||||
/* EIR specific methods. */
|
||||
|
||||
extern bfd_boolean _bfd_sparc_elf_link_add_symbols
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_sparc_elf_final_link
|
||||
(bfd *, struct bfd_link_info *);
|
||||
|
||||
extern bfd_boolean _bfd_sparc_elf_ignore_discarded_relocs
|
||||
(asection *);
|
||||
|
||||
extern void _bfd_sparc_elf_hide_symbol
|
||||
(struct bfd_link_info *, struct elf_link_hash_entry *,
|
||||
bfd_boolean);
|
||||
|
||||
extern bfd_boolean _bfd_sparc_elf_write_object_contents (bfd *);
|
||||
|
||||
extern void _bfd_sparc_elf_after_parse (int);
|
||||
|
||||
extern bfd_boolean _bfd_sparc_elf_check_magic (bfd *ibfd);
|
||||
|
||||
extern const struct bfd_elf_special_section _bfd_sparc_elf_special_sections[];
|
||||
|
|
|
@ -84,7 +84,16 @@
|
|||
#define bfd_elfNN_set_section_contents _bfd_elf_set_section_contents
|
||||
#endif
|
||||
#define bfd_elfNN_sizeof_headers _bfd_elf_sizeof_headers
|
||||
|
||||
/* We should be able to override this method if output file format
|
||||
is not ELF as it happens in case of EIR linkage (see Bug #59012,
|
||||
Comment # ). Take into account that calling `bfd_elf_final_link'
|
||||
is inappropriate in this case either, since it also performs some
|
||||
ELF-specific output. */
|
||||
#ifndef bfd_elfNN_write_object_contents
|
||||
#define bfd_elfNN_write_object_contents _bfd_elf_write_object_contents
|
||||
#endif
|
||||
|
||||
#define bfd_elfNN_write_corefile_contents _bfd_elf_write_corefile_contents
|
||||
|
||||
#define bfd_elfNN_get_section_contents_in_window \
|
||||
|
@ -769,6 +778,10 @@
|
|||
#define elf_backend_cant_unwind_opcode 0
|
||||
#endif
|
||||
|
||||
#ifndef elf_backend_r_none_info
|
||||
#define elf_backend_r_none_info 0
|
||||
#endif
|
||||
|
||||
#ifndef elf_match_priority
|
||||
#define elf_match_priority \
|
||||
(ELF_ARCH == bfd_arch_unknown ? 2 : ELF_OSABI == ELFOSABI_NONE ? 1 : 0)
|
||||
|
@ -924,7 +937,8 @@ static struct elf_backend_data elfNN_bed =
|
|||
elf_backend_extern_protected_data,
|
||||
elf_backend_always_renumber_dynsyms,
|
||||
elf_backend_linux_prpsinfo32_ugid16,
|
||||
elf_backend_linux_prpsinfo64_ugid16
|
||||
elf_backend_linux_prpsinfo64_ugid16,
|
||||
elf_backend_r_none_info
|
||||
};
|
||||
|
||||
/* Forward declaration for use when initialising alternative_target field. */
|
||||
|
|
|
@ -0,0 +1,21 @@
|
|||
/* Copyright 2007 Free Software Foundation, Inc.
|
||||
|
||||
This file is part of BFD, the Binary File Descriptor library.
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, write to the Free Software
|
||||
Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
|
||||
MA 02110-1301, USA. */
|
||||
|
||||
/* Other architectures place here some definitions regarding to
|
||||
core file handling. */
|
35
bfd/libbfd.h
35
bfd/libbfd.h
|
@ -3328,6 +3328,41 @@ static const char *const bfd_reloc_code_real_names[] = { "@@uninitialized@@",
|
|||
"BFD_RELOC_CKCORE_PCREL_BLOOP_IMM4BY4",
|
||||
"BFD_RELOC_CKCORE_PCREL_BLOOP_IMM12BY4",
|
||||
"BFD_RELOC_S12Z_OPR",
|
||||
"BFD_RELOC_E2K_64_ABS_LIT",
|
||||
"BFD_RELOC_E2K_DISP",
|
||||
"BFD_RELOC_E2K_GOT",
|
||||
"BFD_RELOC_E2K_TLS_GDMOD",
|
||||
"BFD_RELOC_E2K_TLS_GDREL",
|
||||
"BFD_RELOC_E2K_TLS_IE",
|
||||
"BFD_RELOC_E2K_32_TLS_LE",
|
||||
"BFD_RELOC_E2K_64_TLS_LE",
|
||||
"BFD_RELOC_E2K_32_DTPREL",
|
||||
"BFD_RELOC_E2K_64_DTPREL",
|
||||
"BFD_RELOC_E2K_PLT",
|
||||
"BFD_RELOC_E2K_GOTPLT",
|
||||
"BFD_RELOC_E2K_ISLOCAL",
|
||||
"BFD_RELOC_E2K_AP_GOT",
|
||||
"BFD_RELOC_E2K_PL_GOT",
|
||||
"BFD_RELOC_E2K_PREF",
|
||||
"BFD_RELOC_E2K_ISLOCAL32",
|
||||
"BFD_RELOC_E2K_GOTOFF64",
|
||||
"BFD_RELOC_E2K_GOTOFF64_LIT",
|
||||
"BFD_RELOC_E2K_AP",
|
||||
"BFD_RELOC_E2K_PL",
|
||||
"BFD_RELOC_E2K_DYNOPT32",
|
||||
"BFD_RELOC_E2K_DYNOPT64",
|
||||
"BFD_RELOC_ELCORE32",
|
||||
"BFD_RELOC_ELCORE16NPC",
|
||||
"BFD_RELOC_ELCORE16PC",
|
||||
"BFD_RELOC_ELCORE16S",
|
||||
"BFD_RELOC_ELCORE16",
|
||||
"BFD_RELOC_ELCORE5",
|
||||
"BFD_RELOC_ELCORE32_FAKE",
|
||||
"BFD_RELOC_ELCORE16NPC_FAKE",
|
||||
"BFD_RELOC_ELCORE16PC_FAKE",
|
||||
"BFD_RELOC_ELCORE16S_FAKE",
|
||||
"BFD_RELOC_ELCORE16_FAKE",
|
||||
"BFD_RELOC_ELCORE5_FAKE",
|
||||
"@@overflow: BFD_RELOC_UNUSED@@",
|
||||
};
|
||||
#endif
|
||||
|
|
120
bfd/reloc.c
120
bfd/reloc.c
|
@ -8081,6 +8081,126 @@ ENUM
|
|||
ENUMDOC
|
||||
S12Z relocations.
|
||||
|
||||
ENUM
|
||||
BFD_RELOC_E2K_64_ABS_LIT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_64_ABS_LIT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_DISP
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_DISP.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_GOT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_GOT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_TLS_GDMOD
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_TLS_GDMOD.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_TLS_GDREL
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_TLS_GDREL.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_TLS_IE
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_TLS_IE.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_32_TLS_LE
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_32_TLS_LE.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_64_TLS_LE
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_64_TLS_LE.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_32_DTPREL
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_TLS_32_DTPREL.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_64_DTPREL
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_TLS_64_DTPREL.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_PLT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_PLT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_GOTPLT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_GOTPLT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_ISLOCAL
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_ISLOCAL.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_AP_GOT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_AP_GOT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_PL_GOT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_PL_GOT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_PREF
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_PREF.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_ISLOCAL32
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_ISLOCAL32.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_GOTOFF64
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_GOTOFF64.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_GOTOFF64_LIT
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_GOTOFF64_LIT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_AP
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_AP.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_PL
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_PL.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_DYNOPT32
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_32_DYNOPT.
|
||||
ENUM
|
||||
BFD_RELOC_E2K_DYNOPT64
|
||||
ENUMDOC
|
||||
This one corresponds to R_E2K_64_DYNOPT.
|
||||
|
||||
ENUM
|
||||
BFD_RELOC_ELCORE32
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16NPC
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16PC
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16S
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE5
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE32_FAKE
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16NPC_FAKE
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16PC_FAKE
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16S_FAKE
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE16_FAKE
|
||||
ENUMX
|
||||
BFD_RELOC_ELCORE5_FAKE
|
||||
ENUMDOC
|
||||
Elvees Elcore relocations.
|
||||
|
||||
ENDSENUM
|
||||
BFD_RELOC_UNUSED
|
||||
CODE_FRAGMENT
|
||||
|
|
|
@ -706,6 +706,12 @@ extern const bfd_target csky_elf32_le_vec;
|
|||
extern const bfd_target d10v_elf32_vec;
|
||||
extern const bfd_target d30v_elf32_vec;
|
||||
extern const bfd_target dlx_elf32_be_vec;
|
||||
extern const bfd_target e2k_elf32_vec;
|
||||
extern const bfd_target e2k_elf64_vec;
|
||||
extern const bfd_target e2k_pm_elf32_vec;
|
||||
extern const bfd_target e2k_kpda_elf64_vec;
|
||||
extern const bfd_target elcore_elf32_vec;
|
||||
extern const bfd_target elcore_elf64_vec;
|
||||
extern const bfd_target elf32_be_vec;
|
||||
extern const bfd_target elf32_le_vec;
|
||||
extern const bfd_target elf64_be_vec;
|
||||
|
@ -941,6 +947,7 @@ extern const bfd_target verilog_vec;
|
|||
extern const bfd_target tekhex_vec;
|
||||
extern const bfd_target binary_vec;
|
||||
extern const bfd_target ihex_vec;
|
||||
extern const bfd_target eir_vec;
|
||||
|
||||
/* All of the xvecs for core files. */
|
||||
extern const bfd_target core_aix386_vec;
|
||||
|
@ -1043,6 +1050,12 @@ static const bfd_target * const _bfd_target_vector[] =
|
|||
|
||||
&dlx_elf32_be_vec,
|
||||
|
||||
&e2k_elf32_vec,
|
||||
&e2k_elf64_vec,
|
||||
&e2k_pm_elf32_vec,
|
||||
&elcore_elf32_vec,
|
||||
&elcore_elf64_vec,
|
||||
|
||||
/* This, and other vectors, may not be used in any *.mt configuration.
|
||||
But that does not mean they are unnecessary. If configured with
|
||||
--enable-targets=all, objdump or gdb should be able to examine
|
||||
|
@ -1370,6 +1383,8 @@ static const bfd_target * const _bfd_target_vector[] =
|
|||
&binary_vec,
|
||||
/* Likewise for ihex. */
|
||||
&ihex_vec,
|
||||
/* Likewise for EIR. */
|
||||
&eir_vec,
|
||||
|
||||
#if BFD_SUPPORTS_PLUGINS
|
||||
&plugin_vec,
|
||||
|
|
|
@ -16,7 +16,7 @@
|
|||
|
||||
In releases, the date is not included in either version strings or
|
||||
sonames. */
|
||||
#define BFD_VERSION_DATE 20191211
|
||||
#define BFD_VERSION_DATE 20200213
|
||||
#define BFD_VERSION @bfd_version@
|
||||
#define BFD_VERSION_STRING @bfd_version_package@ @bfd_version_string@
|
||||
#define REPORT_BUGS_TO @report_bugs_to@
|
||||
|
|
|
@ -960,7 +960,7 @@ EOF
|
|||
echo "$UNAME_MACHINE"-axis-linux-"$LIBC"
|
||||
exit ;;
|
||||
e2k:Linux:*:*)
|
||||
echo "$UNAME_MACHINE"-unknown-linux-"$LIBC"
|
||||
echo "$UNAME_MACHINE"-mcst-linux-"$LIBC"
|
||||
exit ;;
|
||||
frv:Linux:*:*)
|
||||
echo "$UNAME_MACHINE"-unknown-linux-"$LIBC"
|
||||
|
|
|
@ -943,6 +943,10 @@ EOF
|
|||
cpu=x86_64
|
||||
vendor=pc
|
||||
;;
|
||||
e2k | e2k64 | e2k32 | e2k128)
|
||||
cpu=$basic_machine
|
||||
vendor=mcst
|
||||
;;
|
||||
# Recognize the basic CPU types without company name.
|
||||
*)
|
||||
cpu=$basic_machine
|
||||
|
@ -1176,7 +1180,7 @@ case $cpu-$vendor in
|
|||
| c[123]* | c30 | [cjt]90 | c4x \
|
||||
| c8051 | clipper | craynv | csky | cydra \
|
||||
| d10v | d30v | dlx | dsp16xx \
|
||||
| e2k | elxsi | epiphany \
|
||||
| e2k | e2k64 | e2k32 | e2k128 | elxsi | epiphany \
|
||||
| f30[01] | f700 | fido | fr30 | frv | ft32 | fx80 \
|
||||
| h8300 | h8500 \
|
||||
| hppa | hppa1.[01] | hppa2.0 | hppa2.0[nw] | hppa64 \
|
||||
|
@ -1512,6 +1516,8 @@ case $os in
|
|||
;;
|
||||
ios)
|
||||
;;
|
||||
kpda)
|
||||
;;
|
||||
none)
|
||||
;;
|
||||
*-eabi)
|
||||
|
|
|
@ -2279,6 +2279,23 @@ ac_compiler_gnu=$ac_cv_c_compiler_gnu
|
|||
|
||||
|
||||
|
||||
if test x"${enable_gdb}" != x"no" -a x"${enable_src_release_build}" != x"yes"; then
|
||||
# For this branch, we do not support building GDB in-tree.
|
||||
# Try to detect whether we are in this situation or not by
|
||||
# searching for a couple of known files in the source directory.
|
||||
if test -f gnulib/update-gnulib.sh -a -f gdb/ChangeLog; then
|
||||
as_fn_error $? "GDB must be configured and built in a directory separate from its sources.
|
||||
|
||||
To do so, create a dedicated directory for your GDB build and invoke
|
||||
the configure script from that directory:
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ <full path to your sources>/gdb-VERSION/configure [etc...]
|
||||
$ make" "$LINENO" 5
|
||||
fi
|
||||
fi
|
||||
|
||||
progname=$0
|
||||
# if PWD already has a value, it is probably wrong.
|
||||
if test -n "$PWD" ; then PWD=`${PWDCMD-pwd}`; fi
|
||||
|
@ -3019,7 +3036,7 @@ case "${ENABLE_GOLD}" in
|
|||
# Check for target supported by gold.
|
||||
case "${target}" in
|
||||
i?86-*-* | x86_64-*-* | sparc*-*-* | powerpc*-*-* | arm*-*-* \
|
||||
| aarch64*-*-* | tilegx*-*-* | mips*-*-* | s390*-*-*)
|
||||
| aarch64*-*-* | tilegx*-*-* | mips*-*-* | s390*-*-* | e2k-*)
|
||||
configdirs="$configdirs gold"
|
||||
if test x${ENABLE_GOLD} = xdefault; then
|
||||
default_ld=gold
|
||||
|
|
19
configure.ac
19
configure.ac
|
@ -33,6 +33,23 @@ m4_include([config/isl.m4])
|
|||
AC_INIT(move-if-change)
|
||||
AC_DISABLE_OPTION_CHECKING
|
||||
|
||||
if test x"${enable_gdb}" != x"no" -a x"${enable_src_release_build}" != x"yes"; then
|
||||
# For this branch, we do not support building GDB in-tree.
|
||||
# Try to detect whether we are in this situation or not by
|
||||
# searching for a couple of known files in the source directory.
|
||||
if test -f gnulib/update-gnulib.sh -a -f gdb/ChangeLog; then
|
||||
AC_MSG_ERROR([GDB must be configured and built in a directory separate from its sources.
|
||||
|
||||
To do so, create a dedicated directory for your GDB build and invoke
|
||||
the configure script from that directory:
|
||||
|
||||
$ mkdir build
|
||||
$ cd build
|
||||
$ <full path to your sources>/gdb-VERSION/configure [[etc...]]
|
||||
$ make])
|
||||
fi
|
||||
fi
|
||||
|
||||
progname=$0
|
||||
# if PWD already has a value, it is probably wrong.
|
||||
if test -n "$PWD" ; then PWD=`${PWDCMD-pwd}`; fi
|
||||
|
@ -349,7 +366,7 @@ case "${ENABLE_GOLD}" in
|
|||
# Check for target supported by gold.
|
||||
case "${target}" in
|
||||
i?86-*-* | x86_64-*-* | sparc*-*-* | powerpc*-*-* | arm*-*-* \
|
||||
| aarch64*-*-* | tilegx*-*-* | mips*-*-* | s390*-*-*)
|
||||
| aarch64*-*-* | tilegx*-*-* | mips*-*-* | s390*-*-* | e2k-*)
|
||||
configdirs="$configdirs gold"
|
||||
if test x${ENABLE_GOLD} = xdefault; then
|
||||
default_ld=gold
|
||||
|
|
|
@ -0,0 +1,42 @@
|
|||
´.purify
|
||||
autom4te.cache
|
||||
config.log
|
||||
config.cache
|
||||
config.status
|
||||
config.status.lineno
|
||||
db_home
|
||||
Makefile
|
||||
buildno
|
||||
python
|
||||
build
|
||||
Makefile.pre
|
||||
platform
|
||||
pybuilddir.txt
|
||||
pyconfig.h
|
||||
libpython*.a
|
||||
libpython*.so*
|
||||
python.exe
|
||||
python-gdb.py
|
||||
reflog.txt
|
||||
tags
|
||||
TAGS
|
||||
.gdb_history
|
||||
Doc/tools/sphinx
|
||||
Doc/tools/jinja
|
||||
Doc/tools/jinja2
|
||||
Doc/tools/pygments
|
||||
Doc/tools/docutils
|
||||
Misc/python.pc
|
||||
Modules/Setup
|
||||
Modules/Setup.config
|
||||
Modules/Setup.local
|
||||
Modules/config.c
|
||||
Modules/ld_so_aix
|
||||
Parser/pgen
|
||||
Lib/test/data/*
|
||||
Lib/lib2to3/Grammar*.pickle
|
||||
Lib/lib2to3/PatternGrammar*.pickle
|
||||
__pycache__
|
||||
.coverage
|
||||
coverage/*
|
||||
htmlcov/*
|
|
@ -0,0 +1,73 @@
|
|||
*.cover
|
||||
*.o
|
||||
*.orig
|
||||
*.pyc
|
||||
*.pyd
|
||||
*.pyo
|
||||
*.rej
|
||||
*.swp
|
||||
*~
|
||||
.gdb_history
|
||||
Doc/build/
|
||||
Doc/tools/docutils/
|
||||
Doc/tools/jinja/
|
||||
Doc/tools/jinja2/
|
||||
Doc/tools/pygments/
|
||||
Doc/tools/sphinx/
|
||||
Lib/lib2to3/*.pickle
|
||||
Lib/test/data/*
|
||||
Lib/_sysconfigdata.py
|
||||
Lib/plat-mac/errors.rsrc.df.rsrc
|
||||
Makefile
|
||||
Makefile.pre
|
||||
Misc/python.pc
|
||||
Misc/python-config.sh
|
||||
Modules/Setup
|
||||
Modules/Setup.config
|
||||
Modules/Setup.local
|
||||
Modules/config.c
|
||||
Modules/ld_so_aix
|
||||
Modules/_freeze_importlib
|
||||
Modules/_testembed
|
||||
PCbuild/*.bsc
|
||||
PCbuild/*.dll
|
||||
PCbuild/*.exe
|
||||
PCbuild/*.exp
|
||||
PCbuild/*.lib
|
||||
PCbuild/*.ncb
|
||||
PCbuild/*.o
|
||||
PCbuild/*.pdb
|
||||
PCbuild/Win32-temp-*
|
||||
PCbuild/amd64/
|
||||
.purify
|
||||
Parser/pgen
|
||||
__pycache__
|
||||
autom4te.cache
|
||||
build/
|
||||
buildno
|
||||
config.cache
|
||||
config.log
|
||||
config.status
|
||||
config.status.lineno
|
||||
core
|
||||
db_home
|
||||
config.log
|
||||
config.status
|
||||
libpython*.a
|
||||
libpython*.so*
|
||||
platform
|
||||
pybuilddir.txt
|
||||
pyconfig.h
|
||||
python
|
||||
python-config
|
||||
python-config.py
|
||||
python.exe
|
||||
python-gdb.py
|
||||
python.exe-gdb.py
|
||||
reflog.txt
|
||||
.svn/
|
||||
tags
|
||||
TAGS
|
||||
.coverage
|
||||
coverage/
|
||||
htmlcov/
|
|
@ -0,0 +1,49 @@
|
|||
[patterns]
|
||||
|
||||
# Non human-editable files are binary
|
||||
|
||||
**.dsp = BIN
|
||||
**.dsw = BIN
|
||||
**.mk = BIN
|
||||
**.sln = BIN
|
||||
**.vcproj = BIN
|
||||
**.vsprops = BIN
|
||||
|
||||
**.aif = BIN
|
||||
**.aifc = BIN
|
||||
**.aiff = BIN
|
||||
**.au = BIN
|
||||
**.bmp = BIN
|
||||
**.db = BIN
|
||||
**.exe = BIN
|
||||
**.icns = BIN
|
||||
**.gif = BIN
|
||||
**.ico = BIN
|
||||
**.info = BIN
|
||||
**.jpg = BIN
|
||||
**.pck = BIN
|
||||
**.png = BIN
|
||||
**.psd = BIN
|
||||
**.tar = BIN
|
||||
**.wav = BIN
|
||||
**.whl = BIN
|
||||
**.xar = BIN
|
||||
**.zip = BIN
|
||||
|
||||
Lib/test/cjkencodings/* = BIN
|
||||
Lib/test/decimaltestdata/*.decTest = BIN
|
||||
Lib/test/sndhdrdata/sndhdr.* = BIN
|
||||
Lib/test/test_email/data/msg_26.txt = BIN
|
||||
Lib/test/xmltestdata/* = BIN
|
||||
|
||||
Lib/venv/scripts/nt/* = BIN
|
||||
|
||||
Lib/test/coding20731.py = BIN
|
||||
|
||||
# All other files (which presumably are human-editable) are "native".
|
||||
# This must be the last rule!
|
||||
|
||||
** = native
|
||||
|
||||
[repository]
|
||||
native = LF
|
|
@ -0,0 +1,99 @@
|
|||
.gdb_history
|
||||
.purify
|
||||
.svn/
|
||||
^.idea/
|
||||
.DS_Store
|
||||
Makefile$
|
||||
Makefile.pre$
|
||||
TAGS$
|
||||
autom4te.cache$
|
||||
^build/
|
||||
^Doc/build/
|
||||
buildno$
|
||||
config.cache
|
||||
config.log
|
||||
config.status
|
||||
config.status.lineno
|
||||
db_home
|
||||
platform$
|
||||
pyconfig.h$
|
||||
python$
|
||||
python.exe$
|
||||
python-config$
|
||||
python-config.py$
|
||||
reflog.txt$
|
||||
tags$
|
||||
Lib/plat-mac/errors.rsrc.df.rsrc
|
||||
Misc/python.pc
|
||||
Misc/python-config.sh$
|
||||
Modules/Setup$
|
||||
Modules/Setup.config
|
||||
Modules/Setup.local
|
||||
Modules/config.c
|
||||
Modules/ld_so_aix$
|
||||
Parser/pgen$
|
||||
^lcov-report/
|
||||
^core
|
||||
^python-gdb.py
|
||||
^python.exe-gdb.py
|
||||
^pybuilddir.txt
|
||||
|
||||
syntax: glob
|
||||
libpython*.a
|
||||
libpython*.so*
|
||||
*.swp
|
||||
*.o
|
||||
*.pyc
|
||||
*.pyo
|
||||
*.pyd
|
||||
*.cover
|
||||
*~
|
||||
Lib/lib2to3/*.pickle
|
||||
Lib/test/data/*
|
||||
Misc/*.wpu
|
||||
PC/python_nt*.h
|
||||
PC/pythonnt_rc*.h
|
||||
PC/*.obj
|
||||
PC/*.exe
|
||||
PC/*/*.exe
|
||||
PC/*/*.exp
|
||||
PC/*/*.lib
|
||||
PC/*/*.bsc
|
||||
PC/*/*.dll
|
||||
PC/*/*.pdb
|
||||
PC/*/*.user
|
||||
PC/*/*.ncb
|
||||
PC/*/*.suo
|
||||
PC/*/Win32-temp-*
|
||||
PC/*/x64-temp-*
|
||||
PC/*/amd64
|
||||
PCbuild/*.exe
|
||||
PCbuild/*.dll
|
||||
PCbuild/*.pdb
|
||||
PCbuild/*.lib
|
||||
PCbuild/*.exp
|
||||
PCbuild/*.o
|
||||
PCbuild/*.ncb
|
||||
PCbuild/*.bsc
|
||||
PCbuild/*.user
|
||||
PCbuild/*.suo
|
||||
PCbuild/*.*sdf
|
||||
PCbuild/Win32-temp-*
|
||||
PCbuild/x64-temp-*
|
||||
PCbuild/*-pgi
|
||||
PCbuild/*-pgo
|
||||
PCbuild/amd64
|
||||
PCbuild/ipch
|
||||
Tools/unicode/build/
|
||||
Tools/unicode/MAPPINGS/
|
||||
BuildLog.htm
|
||||
__pycache__
|
||||
Modules/_freeze_importlib
|
||||
Modules/_testembed
|
||||
.coverage
|
||||
coverage/
|
||||
htmlcov/
|
||||
*.gcda
|
||||
*.gcno
|
||||
*.gcov
|
||||
coverage.info
|
|
@ -0,0 +1,136 @@
|
|||
64cc5439e10a6fdf984effaf0141e94fa4cc1004 v0.9.8
|
||||
78a7ed6953025e7ecdde9585099b01a6ae40b76a v0.9.9
|
||||
b15b8cc9b8d10e0352a0b8b7e8d51fa309db6df3 v1.0.1
|
||||
0326b5d61445ee3a8d3de28119f9652cb72d2e3f v1.0.2
|
||||
832615ec07646e310c85316b8ba6bc9b17ad3547 v1.1
|
||||
9895475d18c7b5f32adaf78f71886ae041e4d10c v1.1.1
|
||||
16eb4c51ee97169046340998e850a63c65225b0a v1.2b1
|
||||
b45c688756d04fb84d4a0d518fc3d7e3cb25fa8d v1.2b2
|
||||
9e82daf7605bad7976a9abc997cb5e0abe434078 v1.2b3
|
||||
065e31cf5862e27521cf5725b003aed211f091b2 v1.2b4
|
||||
e72257e655454d569468da8b1189e0ec336f3536 v1.2
|
||||
e63d83f8275853aaaa3d1972cb86564505e65583 v1.3b1
|
||||
7d743c865a9aa6bde8b603e32e0542031bba3c33 v1.3
|
||||
4fc85c82cc222554ae6b9c0b87776ed5f2b70c6e v1.4b1
|
||||
129f1299d4e97e884bbbbdd00baf101d178973e6 v1.4b2
|
||||
44a82ac654a4175569deed8e8a94b0cc8edee08d v1.4b3
|
||||
db49494c93dc73de06d5721c74eab533a947a92c v1.4
|
||||
062aed8a4ce2c91c81b80e29f02faff1cf5a761b v1.5a1
|
||||
c9498ac988372575cf7028b86395b900c9b0a840 v1.5a2
|
||||
dc5c968ec992aab3d40a7189df0c443d1c7a1a68 v1.5a3
|
||||
746654a0af680c7d9b814b210a026eb91bec9533 v1.5a4
|
||||
8ff58b5730f06be08fbbdc2bf592226f7a736201 v1.5b1
|
||||
eb78658d819fb0af09a8e6f9bedcb670805ed5f6 v1.5b2
|
||||
84461011a1a0ab402e352f06748f29fb5b5559e5 v1.5
|
||||
44aba4d26b01fbae0403efe654f9fd0347606732 v1.5.1
|
||||
fed63ccbe6dc3ac663bfe97a2f7006b1b28568f9 v1.5.2a1
|
||||
21d71f2e27248a0f4e393d0fc321ecf9b89321d2 v1.5.2a2
|
||||
f08c7a2a56f80741f5f192fd0ebe0b0967a203cf v1.5.2b1
|
||||
8fe7ec4b4fc1518fcac89e6bf674fbbce16150a9 v1.5.2b2
|
||||
39fb0dcc83dc375c1565ba65dbce0ed59b1359c9 v1.5.2c1
|
||||
61c91c7f101bab3149adfcd5646ae40e048de712 v1.5.2
|
||||
605eb9326ffe1fd1e43f40e2338d6652ab449fdf v1.6a1
|
||||
011bee8fd9f7f4da457ec71596484fb0882c0614 v1.6a2
|
||||
35c4fc1414a59888614b9be784a25f233ba67984 v2.0b1
|
||||
55bba197d4870cdae62aeca00e20240a756b84f8 v2.0b2
|
||||
e276329cce036a5f9e9d3451256dca5984e543dc v2.0c1
|
||||
2fa4e35083e02342ca014bf5bfba46aecb816c31 v2.0
|
||||
b60831eeab5a06dd3c5e8297a99e39297aa8794b v2.1a1
|
||||
b382f1f07ec6b2c95551658b30c6139eeb32077a v2.1a2
|
||||
d0c830db5e68edd4aaa3401216e610c9ff145826 v2.1b1
|
||||
b59a536ae1ef3774fd85c17f623e8926b7b6c095 v2.1b2
|
||||
d611276e9ad53b5d32d1e8065e1d811c32f7d96f v2.1c1
|
||||
ff065e674af6c9ab895bd9eff7d9e9039a376c7d v2.1c2
|
||||
020e95d8180d7943fe54701e1db0a7d7d87e2b1e v2.1
|
||||
08796a137f1ada2462f7a3177306df5f67a767e1 v2.2a3
|
||||
d054c29647f90bccb8345bd779bca1eecf2dd7f2 v2.3c1
|
||||
fce5c9e9abc722394cb2e909b7e2a39080d4448e v2.3c2
|
||||
92ca658fd420095b6284c9ce6e9082a80285ec9c v2.4a1
|
||||
055fc6955f3c6522bfeb7ed4c671c97d5baaaac2 v2.4a2
|
||||
186b72550e53533ef6175f6411f932c1298193d7 v2.4a3
|
||||
53cff04283855adf88ed0c0fd3698827ca843637 v2.4b1
|
||||
7e387a9dcc79954a77695adef8b593da35be1214 v2.4b2
|
||||
ff80d8bbef6e13426c8a85d7f9d837b8f8f89834 v2.4c1
|
||||
f31e18d313c7a4fc66914b2d27e130a0f72c0b69 v2.4
|
||||
cd3f783cd08a16781e236c0b9cb5717d1d995fa9 v3.0a1
|
||||
65e82140e281bf26f2e22eda05a7f9956c420f8b v3.0a2
|
||||
df15827f34881b9af0936350813ced5c123c8230 v3.0a3
|
||||
15f773f7300e372c56a21d59fe49ca26955a6477 v3.0a4
|
||||
e35935475153377d6727d64e6c52f72c3b84015b v3.0a5
|
||||
a335c4d643b1cfe14197a9ef195c9b2804f608fc v3.0b1
|
||||
16ec4bb14a68ea428acf09ebf0c92981da2646f3 v3.0b2
|
||||
509e30a7968e01be329ec121540b3e755fc4e566 v3.0b3
|
||||
507ede9c7f7f475dfafbd4a52c22d767d10a2bc0 v3.0rc1
|
||||
8fae465a39627b590385462e6095eb63af45240a v3.0rc2
|
||||
e83a60c69d53f5551a306e77a6d38e9b11485496 v3.0rc3
|
||||
bc1ce368986e45b1faf96f93995df46bcd75e7b8 v3.1a1
|
||||
ee430e5075db2adf8124e6b94916a89ca41d3171 v3.1a2
|
||||
b63020797f9678adaf4d2c3e26574a9eef2ef028 v3.1b1
|
||||
4353fd0843cb31b356adc50f93d220e2e7255ef2 v3.1rc1
|
||||
0b87e438e1b53e3f812cad963a7fdb65d198ba2f v3.1rc2
|
||||
a69a031ac1402dede8b1ef80096436bca6d371f3 v3.1
|
||||
35efb1054ec6ceca72017a587263cb6a9257340b v3.1.1rc1
|
||||
8b9c0f573ab29c41c6c5fdcca82a1fe0ff5355af v3.1.1
|
||||
149b8b87514d10416b598884db5f74651f625b38 v3.1.2rc1
|
||||
960efa327c5d9c18df995437b0ac550cb89c9f85 v3.1.2
|
||||
d18e9d71f369d8211f6ac87252c6d3211f9bd09f v3.1.3rc1
|
||||
a4f75773c0060cee38b0bb651a7aba6f56b0e996 v3.1.3
|
||||
32fcb9e94985cb19ce37ba9543f091c0dbe9d7dd v3.1.4rc1
|
||||
c918ec9f3a76d6afedfbb5d455004de880443a3d v3.1.4
|
||||
ee26aca3219cf4bb0b93352e83edcc9cb28c7802 v3.1.5rc1
|
||||
75db2bc69fc9a3e4801e94e3e19801cb096208d8 v3.1.5rc2
|
||||
7395330e495ec3316862ca1f6ce0aaf7bdf6785b v3.1.5
|
||||
b37b7834757492d009b99cf0ca4d42d2153d7fac v3.2a1
|
||||
56d4373cecb73c8b45126ba7b045b3c7b3f94b0b v3.2a2
|
||||
da012d9a2c23d144e399d2e01a55b8a83ad94573 v3.2a3
|
||||
d92a5b850f5e56808bedc01723906ed64c5e6e2e v3.2a4
|
||||
b635cea94195780c8716e236479af319bcc26253 v3.2b1
|
||||
e3af5f3a7904c0d5343ec9633ea66e7acfd23a66 v3.2b2
|
||||
865d5b24bf28ca41b536befc326407c03e74a4d5 v3.2rc1
|
||||
acf3e24dd0d0dfd1e20c907d696d3da965a8f56f v3.2rc2
|
||||
18c1f52896501c7ee13b038454a39acb45a87979 v3.2rc3
|
||||
a222a015e28d8ae9af3899258dc6c15c3d40add0 v3.2
|
||||
8ffac2337a3323323d02153ac919fd1483176652 v3.2.1b1
|
||||
cfa9364997c7f2e67b9cbb45c3a5fa3bba4e4999 v3.2.1rc1
|
||||
5df549718fb4841ff521fe051f6b54f290fad5d8 v3.2.1rc2
|
||||
ac1f7e5c05104d557d5acd922e95625ba5d1fe10 v3.2.1
|
||||
c860feaa348d663e598986894ee4680480577e15 v3.2.2rc1
|
||||
137e45f15c0bd262c9ad4c032d97425bc0589456 v3.2.2
|
||||
7085403daf439adb3f9e70ef13f6bedb1c447376 v3.2.3rc1
|
||||
428f05cb7277e1d42bb9dd8d1af6b6270ebc6112 v3.2.3rc2
|
||||
3d0686d90f55a78f96d9403da2c52dc2411419d0 v3.2.3
|
||||
b2cb7bc1edb8493c0a78f9331eae3e8fba6a881d v3.2.4rc1
|
||||
1e10bdeabe3de02f038a63c001911561ac1d13a7 v3.2.4
|
||||
cef745775b6583446572cffad704100983db2bea v3.2.5
|
||||
f1a9a6505731714f0e157453ff850e3b71615c45 v3.3.0a1
|
||||
2f69db52d6de306cdaef0a0cc00cc823fb350b01 v3.3.0a2
|
||||
0b53b70a40a00013505eb35e3660057b62be77be v3.3.0a3
|
||||
7c51388a3aa7ce76a8541bbbdfc05d2d259a162c v3.3.0a4
|
||||
e15c554cd43eb23bc0a528a4e8741da9bbec9607 v3.3.0b1
|
||||
4972a8f1b2aa3d7cdd64dc96aa7fa112fe1ea343 v3.3.0b2
|
||||
8bb5c7bc46ba43804480f3e328e1fa956672c885 v3.3.0rc1
|
||||
88a0792e8ba3e4916b24c7e7a522c277d326d66e v3.3.0rc2
|
||||
c191d21cefafb3832c45570e84854e309aa62eaa v3.3.0rc3
|
||||
bd8afb90ebf28ba4edc901d4a235f75e7bbc79fd v3.3.0
|
||||
92c2cfb924055ce68c4f78f836dcfe688437ceb8 v3.3.1rc1
|
||||
d9893d13c6289aa03d33559ec67f97dcbf5c9e3c v3.3.1
|
||||
d047928ae3f6314a13b6137051315453d0ae89b6 v3.3.2
|
||||
fd53c500f8b80f54f3ecedec9da2e8c7e52a6888 v3.3.3rc1
|
||||
d32442c0e60dfbd71234e807d3d1dedd227495a9 v3.3.3rc2
|
||||
c3896275c0f61b2510a6c7e6c458a750359a91b8 v3.3.3
|
||||
fa92f5f940c6c0d839d7f0611e4b717606504a3c v3.3.4rc1
|
||||
7ff62415e4263c432c8acf6e424224209211eadb v3.3.4
|
||||
9ec811df548ed154a9bf9815383a916d6df31b98 v3.3.5rc1
|
||||
ca5635efe090f78806188ac2758f9948596aa8b2 v3.3.5rc2
|
||||
62cf4e77f78564714e7ea3d4bf1479ca1fbd0758 v3.3.5
|
||||
46535f65e7f3bcdcf176f36d34bc1fed719ffd2b v3.4.0a1
|
||||
9265a2168e2cb2a84785d8717792acc661e6b692 v3.4.0a2
|
||||
dd9cdf90a5073510877e9dd5112f8e6cf20d5e89 v3.4.0a3
|
||||
e245b0d7209bb6d0e19316e1e2af1aa9c2139104 v3.4.0a4
|
||||
3405dc9a6afaa0a06dd1f6f182ec5c998dce6f5f v3.4.0b1
|
||||
ba32913eb13ec545a46dd0ce18035b6c416f0d78 v3.4.0b2
|
||||
a97ce3ecc96af79bd2e1ac66ce48d9138e0ca749 v3.4.0b3
|
||||
5e088cea8660677969113741c1313d570d977e02 v3.4.0rc1
|
||||
a300712ed38c9a242b736c44e806caea25a6dc05 v3.4.0rc2
|
||||
8a81cdab3e9d521daaef989fade94b16455fc3b8 v3.4.0rc3
|
||||
04f714765c13824c3bc2835d7b008908862e083a v3.4.0
|
|
@ -0,0 +1,15 @@
|
|||
# -*- Makefile -*-
|
||||
# Define dependencies of generated files that are checked into hg.
|
||||
# The syntax of this file uses make rule dependencies, without actions
|
||||
|
||||
Python/importlib.h: Lib/importlib/_bootstrap.py Modules/_freeze_importlib.c
|
||||
|
||||
Include/Python-ast.h: Parser/Python.asdl Parser/asdl.py Parser/asdl_c.py
|
||||
Python/Python-ast.c: Include/Python-ast.h
|
||||
|
||||
Python/opcode_targets.h: Python/makeopcodetargets.py Lib/opcode.py
|
||||
|
||||
Objects/typeslots.inc: Include/typeslots.h Objects/typeslots.py
|
||||
|
||||
Include/graminit.h: Grammar/Grammar Parser/acceler.c Parser/grammar1.c Parser/listnode.c Parser/node.c Parser/parser.c Parser/bitset.c Parser/metagrammar.c Parser/firstsets.c Parser/grammar.c Parser/pgen.c Objects/obmalloc.c Python/dynamic_annotations.c Python/mysnprintf.c Python/pyctype.c Parser/tokenizer_pgen.c Parser/printgrammar.c Parser/parsetok_pgen.c Parser/pgenmain.c
|
||||
Python/graminit.c: Include/graminit.h Grammar/Grammar Parser/acceler.c Parser/grammar1.c Parser/listnode.c Parser/node.c Parser/parser.c Parser/bitset.c Parser/metagrammar.c Parser/firstsets.c Parser/grammar.c Parser/pgen.c Objects/obmalloc.c Python/dynamic_annotations.c Python/mysnprintf.c Python/pyctype.c Parser/tokenizer_pgen.c Parser/printgrammar.c Parser/parsetok_pgen.c Parser/pgenmain.c
|
|
@ -0,0 +1,129 @@
|
|||
Python Documentation README
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This directory contains the reStructuredText (reST) sources to the Python
|
||||
documentation. You don't need to build them yourself, prebuilt versions are
|
||||
available at <http://docs.python.org/download/>.
|
||||
|
||||
Documentation on the authoring Python documentation, including information about
|
||||
both style and markup, is available in the "Documenting Python" chapter of the
|
||||
developers guide <http://docs.python.org/devguide/documenting.html>.
|
||||
|
||||
|
||||
Building the docs
|
||||
=================
|
||||
|
||||
You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset
|
||||
used to build the docs. It is not included in this tree, but maintained
|
||||
separately and available from PyPI <http://pypi.python.org/pypi/Sphinx>.
|
||||
|
||||
|
||||
Using make
|
||||
----------
|
||||
|
||||
A Makefile has been prepared so that on Unix, provided you have installed
|
||||
Sphinx, you can just run ::
|
||||
|
||||
make html
|
||||
|
||||
to build the HTML output files. To view the generated HTML, point your favorite
|
||||
browser at the top-level index `build/html/index.html` after running "make".
|
||||
|
||||
On Windows, we try to emulate the Makefile as closely as possible with a
|
||||
``make.bat`` file.
|
||||
|
||||
To use a Python interpreter that's not called ``python``, use the standard
|
||||
way to set Makefile variables, using e.g. ::
|
||||
|
||||
make html PYTHON=/usr/bin/python2.5
|
||||
|
||||
Available make targets are:
|
||||
|
||||
* "html", which builds standalone HTML files for offline viewing.
|
||||
|
||||
* "htmlhelp", which builds HTML files and a HTML Help project file usable to
|
||||
convert them into a single Compiled HTML (.chm) file -- these are popular
|
||||
under Microsoft Windows, but very handy on every platform.
|
||||
|
||||
To create the CHM file, you need to run the Microsoft HTML Help Workshop over
|
||||
the generated project (.hhp) file.
|
||||
|
||||
* "latex", which builds LaTeX source files as input to "pdflatex" to produce
|
||||
PDF documents.
|
||||
|
||||
* "text", which builds a plain text file for each source file.
|
||||
|
||||
* "epub", which builds an EPUB document, suitable to be viewed on e-book
|
||||
readers.
|
||||
|
||||
* "linkcheck", which checks all external references to see whether they are
|
||||
broken, redirected or malformed, and outputs this information to stdout as
|
||||
well as a plain-text (.txt) file.
|
||||
|
||||
* "changes", which builds an overview over all versionadded/versionchanged/
|
||||
deprecated items in the current version. This is meant as a help for the
|
||||
writer of the "What's New" document.
|
||||
|
||||
* "coverage", which builds a coverage overview for standard library modules and
|
||||
C API.
|
||||
|
||||
* "pydoc-topics", which builds a Python module containing a dictionary with
|
||||
plain text documentation for the labels defined in
|
||||
`tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic and
|
||||
keyword help.
|
||||
|
||||
* "suspicious", which checks the parsed markup for text that looks like
|
||||
malformed and thus unconverted reST.
|
||||
|
||||
|
||||
Without make
|
||||
------------
|
||||
|
||||
Install the Sphinx package and its dependencies from PyPI.
|
||||
|
||||
Then, from the ``Docs`` directory, run ::
|
||||
|
||||
sphinx-build -b<builder> . build/<builder>
|
||||
|
||||
where ``<builder>`` is one of html, text, latex, or htmlhelp (for explanations
|
||||
see the make targets above).
|
||||
|
||||
|
||||
Contributing
|
||||
============
|
||||
|
||||
Bugs in the content should be reported to the Python bug tracker at
|
||||
http://bugs.python.org.
|
||||
|
||||
Bugs in the toolset should be reported in the Sphinx bug tracker at
|
||||
http://www.bitbucket.org/birkenfeld/sphinx/issues/.
|
||||
|
||||
You can also send a mail to the Python Documentation Team at docs@python.org,
|
||||
and we will process your request as soon as possible.
|
||||
|
||||
If you want to help the Documentation Team, you are always welcome. Just send
|
||||
a mail to docs@python.org.
|
||||
|
||||
|
||||
Copyright notice
|
||||
================
|
||||
|
||||
The Python source is copyrighted, but you can freely use and copy it
|
||||
as long as you don't change or remove the copyright notice:
|
||||
|
||||
----------------------------------------------------------------------
|
||||
Copyright (c) 2000-2014 Python Software Foundation.
|
||||
All rights reserved.
|
||||
|
||||
Copyright (c) 2000 BeOpen.com.
|
||||
All rights reserved.
|
||||
|
||||
Copyright (c) 1995-2000 Corporation for National Research Initiatives.
|
||||
All rights reserved.
|
||||
|
||||
Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
|
||||
All rights reserved.
|
||||
|
||||
See the file "license.rst" for information on usage and redistribution
|
||||
of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
----------------------------------------------------------------------
|
|
@ -0,0 +1,39 @@
|
|||
=====================
|
||||
About these documents
|
||||
=====================
|
||||
|
||||
|
||||
These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
|
||||
document processor specifically written for the Python documentation.
|
||||
|
||||
.. _reStructuredText: http://docutils.sf.net/rst.html
|
||||
.. _Sphinx: http://sphinx-doc.org/
|
||||
|
||||
.. In the online version of these documents, you can submit comments and suggest
|
||||
changes directly on the documentation pages.
|
||||
|
||||
Development of the documentation and its toolchain is an entirely volunteer
|
||||
effort, just like Python itself. If you want to contribute, please take a
|
||||
look at the :ref:`reporting-bugs` page for information on how to do so. New
|
||||
volunteers are always welcome!
|
||||
|
||||
Many thanks go to:
|
||||
|
||||
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
|
||||
and writer of much of the content;
|
||||
* the `Docutils <http://docutils.sf.net/>`_ project for creating
|
||||
reStructuredText and the Docutils suite;
|
||||
* Fredrik Lundh for his `Alternative Python Reference
|
||||
<http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
|
||||
ideas.
|
||||
|
||||
|
||||
Contributors to the Python Documentation
|
||||
----------------------------------------
|
||||
|
||||
Many people have contributed to the Python language, the Python standard
|
||||
library, and the Python documentation. See :source:`Misc/ACKS` in the Python
|
||||
source distribution for a partial list of contributors.
|
||||
|
||||
It is only with the input and contributions of the Python community
|
||||
that Python has such wonderful documentation -- Thank You!
|
|
@ -0,0 +1,87 @@
|
|||
.. _reporting-bugs:
|
||||
|
||||
**************
|
||||
Reporting Bugs
|
||||
**************
|
||||
|
||||
Python is a mature programming language which has established a reputation for
|
||||
stability. In order to maintain this reputation, the developers would like to
|
||||
know of any deficiencies you find in Python.
|
||||
|
||||
|
||||
Documentation bugs
|
||||
==================
|
||||
|
||||
If you find a bug in this documentation or would like to propose an improvement,
|
||||
please submit a bug report on the :ref:`tracker <using-the-tracker>`. If you
|
||||
have a suggestion how to fix it, include that as well.
|
||||
|
||||
If you're short on time, you can also email your bug report to docs@python.org.
|
||||
'docs@' is a mailing list run by volunteers; your request will be noticed,
|
||||
though it may take a while to be processed.
|
||||
|
||||
.. seealso::
|
||||
`Documentation bugs`_ on the Python issue tracker
|
||||
|
||||
.. _using-the-tracker:
|
||||
|
||||
Using the Python issue tracker
|
||||
==============================
|
||||
|
||||
Bug reports for Python itself should be submitted via the Python Bug Tracker
|
||||
(http://bugs.python.org/). The bug tracker offers a Web form which allows
|
||||
pertinent information to be entered and submitted to the developers.
|
||||
|
||||
The first step in filing a report is to determine whether the problem has
|
||||
already been reported. The advantage in doing so, aside from saving the
|
||||
developers time, is that you learn what has been done to fix it; it may be that
|
||||
the problem has already been fixed for the next release, or additional
|
||||
information is needed (in which case you are welcome to provide it if you can!).
|
||||
To do this, search the bug database using the search box on the top of the page.
|
||||
|
||||
If the problem you're reporting is not already in the bug tracker, go back to
|
||||
the Python Bug Tracker and log in. If you don't already have a tracker account,
|
||||
select the "Register" link or, if you use OpenID, one of the OpenID provider
|
||||
logos in the sidebar. It is not possible to submit a bug report anonymously.
|
||||
|
||||
Being now logged in, you can submit a bug. Select the "Create New" link in the
|
||||
sidebar to open the bug reporting form.
|
||||
|
||||
The submission form has a number of fields. For the "Title" field, enter a
|
||||
*very* short description of the problem; less than ten words is good. In the
|
||||
"Type" field, select the type of your problem; also select the "Component" and
|
||||
"Versions" to which the bug relates.
|
||||
|
||||
In the "Comment" field, describe the problem in detail, including what you
|
||||
expected to happen and what did happen. Be sure to include whether any
|
||||
extension modules were involved, and what hardware and software platform you
|
||||
were using (including version information as appropriate).
|
||||
|
||||
Each bug report will be assigned to a developer who will determine what needs to
|
||||
be done to correct the problem. You will receive an update each time action is
|
||||
taken on the bug.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
`How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
|
||||
Article which goes into some detail about how to create a useful bug report.
|
||||
This describes what kind of information is useful and why it is useful.
|
||||
|
||||
`Bug Writing Guidelines <http://developer.mozilla.org/en/docs/Bug_writing_guidelines>`_
|
||||
Information about writing a good bug report. Some of this is specific to the
|
||||
Mozilla project, but describes general good practices.
|
||||
|
||||
|
||||
Getting started contributing to Python yourself
|
||||
===============================================
|
||||
|
||||
Beyond just reporting bugs that you find, you are also welcome to submit
|
||||
patches to fix them. You can find more information on how to get started
|
||||
patching Python in the `Python Developer's Guide`_. If you have questions,
|
||||
the `core-mentorship mailing list`_ is a friendly place to get answers to
|
||||
any and all questions pertaining to the process of fixing issues in Python.
|
||||
|
||||
.. _Documentation bugs: http://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity
|
||||
.. _Python Developer's Guide: http://docs.python.org/devguide/
|
||||
.. _core-mentorship mailing list: https://mail.python.org/mailman/listinfo/core-mentorship/
|
|
@ -0,0 +1,26 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _abstract:
|
||||
|
||||
**********************
|
||||
Abstract Objects Layer
|
||||
**********************
|
||||
|
||||
The functions in this chapter interact with Python objects regardless of their
|
||||
type, or with wide classes of object types (e.g. all numerical types, or all
|
||||
sequence types). When used on object types for which they do not apply, they
|
||||
will raise a Python exception.
|
||||
|
||||
It is not possible to use these functions on objects that are not properly
|
||||
initialized, such as a list object that has been created by :c:func:`PyList_New`,
|
||||
but whose items have not been set to some non-\ ``NULL`` value yet.
|
||||
|
||||
.. toctree::
|
||||
|
||||
object.rst
|
||||
number.rst
|
||||
sequence.rst
|
||||
mapping.rst
|
||||
iter.rst
|
||||
buffer.rst
|
||||
objbuffer.rst
|
|
@ -0,0 +1,71 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _allocating-objects:
|
||||
|
||||
Allocating Objects on the Heap
|
||||
==============================
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
|
||||
|
||||
|
||||
.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
|
||||
|
||||
Initialize a newly-allocated object *op* with its type and initial
|
||||
reference. Returns the initialized object. If *type* indicates that the
|
||||
object participates in the cyclic garbage detector, it is added to the
|
||||
detector's set of observed objects. Other fields of the object are not
|
||||
affected.
|
||||
|
||||
|
||||
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
|
||||
|
||||
This does everything :c:func:`PyObject_Init` does, and also initializes the
|
||||
length information for a variable-size object.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
|
||||
|
||||
Allocate a new Python object using the C structure type *TYPE* and the
|
||||
Python type object *type*. Fields not defined by the Python object header
|
||||
are not initialized; the object's reference count will be one. The size of
|
||||
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
|
||||
the type object.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
|
||||
|
||||
Allocate a new Python object using the C structure type *TYPE* and the
|
||||
Python type object *type*. Fields not defined by the Python object header
|
||||
are not initialized. The allocated memory allows for the *TYPE* structure
|
||||
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
|
||||
*type*. This is useful for implementing objects like tuples, which are
|
||||
able to determine their size at construction time. Embedding the array of
|
||||
fields into the same allocation decreases the number of allocations,
|
||||
improving the memory management efficiency.
|
||||
|
||||
|
||||
.. c:function:: void PyObject_Del(PyObject *op)
|
||||
|
||||
Releases memory allocated to an object using :c:func:`PyObject_New` or
|
||||
:c:func:`PyObject_NewVar`. This is normally called from the
|
||||
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
|
||||
the object should not be accessed after this call as the memory is no
|
||||
longer a valid Python object.
|
||||
|
||||
|
||||
.. c:var:: PyObject _Py_NoneStruct
|
||||
|
||||
Object which is visible in Python as ``None``. This should only be accessed
|
||||
using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
|
||||
object.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:c:func:`PyModule_Create`
|
||||
To allocate and create extension modules.
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _apiabiversion:
|
||||
|
||||
***********************
|
||||
API and ABI Versioning
|
||||
***********************
|
||||
|
||||
``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
|
||||
|
||||
For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
|
||||
version information can be found by treating it as a 32 bit number in
|
||||
the following manner:
|
||||
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| Bytes | Bits (big endian order) | Meaning |
|
||||
+=======+=========================+================================================+
|
||||
| ``1`` | ``1-8`` | ``PY_MAJOR_VERSION`` (the ``3`` in |
|
||||
| | | ``3.4.1a2``) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| ``2`` | ``9-16`` | ``PY_MINOR_VERSION`` (the ``4`` in |
|
||||
| | | ``3.4.1a2``) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| ``3`` | ``17-24`` | ``PY_MICRO_VERSION`` (the ``1`` in |
|
||||
| | | ``3.4.1a2``) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| ``4`` | ``25-28`` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, |
|
||||
| | | ``0xB`` for beta, ``0xC`` for release |
|
||||
| | | candidate and ``0xF`` for final), in this |
|
||||
| | | case it is alpha. |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
| | ``29-32`` | ``PY_RELEASE_SERIAL`` (the ``2`` in |
|
||||
| | | ``3.4.1a2``, zero for final releases) |
|
||||
+-------+-------------------------+------------------------------------------------+
|
||||
|
||||
Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
|
||||
|
||||
All the given macros are defined in :source:`Include/patchlevel.h`.
|
||||
|
|
@ -0,0 +1,640 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _arg-parsing:
|
||||
|
||||
Parsing arguments and building values
|
||||
=====================================
|
||||
|
||||
These functions are useful when creating your own extensions functions and
|
||||
methods. Additional information and examples are available in
|
||||
:ref:`extending-index`.
|
||||
|
||||
The first three of these functions described, :c:func:`PyArg_ParseTuple`,
|
||||
:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use *format
|
||||
strings* which are used to tell the function about the expected arguments. The
|
||||
format strings use the same syntax for each of these functions.
|
||||
|
||||
-----------------
|
||||
Parsing arguments
|
||||
-----------------
|
||||
|
||||
A format string consists of zero or more "format units." A format unit
|
||||
describes one Python object; it is usually a single character or a parenthesized
|
||||
sequence of format units. With a few exceptions, a format unit that is not a
|
||||
parenthesized sequence normally corresponds to a single address argument to
|
||||
these functions. In the following description, the quoted form is the format
|
||||
unit; the entry in (round) parentheses is the Python object type that matches
|
||||
the format unit; and the entry in [square] brackets is the type of the C
|
||||
variable(s) whose address should be passed.
|
||||
|
||||
Strings and buffers
|
||||
-------------------
|
||||
|
||||
These formats allow to access an object as a contiguous chunk of memory.
|
||||
You don't have to provide raw storage for the returned unicode or bytes
|
||||
area. Also, you won't have to release any memory yourself, except with the
|
||||
``es``, ``es#``, ``et`` and ``et#`` formats.
|
||||
|
||||
However, when a :c:type:`Py_buffer` structure gets filled, the underlying
|
||||
buffer is locked so that the caller can subsequently use the buffer even
|
||||
inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data
|
||||
being resized or destroyed. As a result, **you have to call**
|
||||
:c:func:`PyBuffer_Release` after you have finished processing the data (or
|
||||
in any early abort case).
|
||||
|
||||
Unless otherwise stated, buffers are not NUL-terminated.
|
||||
|
||||
.. note::
|
||||
|
||||
For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
|
||||
the length argument (int or :c:type:`Py_ssize_t`) is controlled by
|
||||
defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
|
||||
:file:`Python.h`. If the macro was defined, length is a
|
||||
:c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
|
||||
in a future Python version to only support :c:type:`Py_ssize_t` and
|
||||
drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
|
||||
|
||||
|
||||
``s`` (:class:`str`) [const char \*]
|
||||
Convert a Unicode object to a C pointer to a character string.
|
||||
A pointer to an existing string is stored in the character pointer
|
||||
variable whose address you pass. The C string is NUL-terminated.
|
||||
The Python string must not contain embedded NUL bytes; if it does,
|
||||
a :exc:`TypeError` exception is raised. Unicode objects are converted
|
||||
to C strings using ``'utf-8'`` encoding. If this conversion fails, a
|
||||
:exc:`UnicodeError` is raised.
|
||||
|
||||
.. note::
|
||||
This format does not accept bytes-like objects. If you want to accept
|
||||
filesystem paths and convert them to C character strings, it is
|
||||
preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter`
|
||||
as *converter*.
|
||||
|
||||
``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
|
||||
This format accepts Unicode objects as well as :term:`bytes-like object`\ s.
|
||||
It fills a :c:type:`Py_buffer` structure provided by the caller.
|
||||
In this case the resulting C string may contain embedded NUL bytes.
|
||||
Unicode objects are converted to C strings using ``'utf-8'`` encoding.
|
||||
|
||||
``s#`` (:class:`str`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :c:type:`Py_ssize_t`]
|
||||
Like ``s*``, except that it doesn't accept mutable buffer-like objects
|
||||
such as :class:`bytearray`. The result is stored into two C variables,
|
||||
the first one a pointer to a C string, the second one its length.
|
||||
The string may contain embedded null bytes. Unicode objects are converted
|
||||
to C strings using ``'utf-8'`` encoding.
|
||||
|
||||
``z`` (:class:`str` or ``None``) [const char \*]
|
||||
Like ``s``, but the Python object may also be ``None``, in which case the C
|
||||
pointer is set to *NULL*.
|
||||
|
||||
``z*`` (:class:`str`, :class:`bytes`, :class:`bytearray`, buffer compatible object or ``None``) [Py_buffer]
|
||||
Like ``s*``, but the Python object may also be ``None``, in which case the
|
||||
``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*.
|
||||
|
||||
``z#`` (:class:`str`, :class:`bytes`, read-only buffer compatible object or ``None``) [const char \*, int]
|
||||
Like ``s#``, but the Python object may also be ``None``, in which case the C
|
||||
pointer is set to *NULL*.
|
||||
|
||||
``y`` (:class:`bytes`) [const char \*]
|
||||
This format converts a bytes-like object to a C pointer to a character
|
||||
string; it does not accept Unicode objects. The bytes buffer must not
|
||||
contain embedded NUL bytes; if it does, a :exc:`TypeError`
|
||||
exception is raised.
|
||||
|
||||
``y*`` (:class:`bytes`, :class:`bytearray` or :term:`bytes-like object`) [Py_buffer]
|
||||
This variant on ``s*`` doesn't accept Unicode objects, only
|
||||
:term:`bytes-like object`\ s. **This is the recommended way to accept
|
||||
binary data.**
|
||||
|
||||
``y#`` (:class:`bytes`) [const char \*, int]
|
||||
This variant on ``s#`` doesn't accept Unicode objects, only :term:`bytes-like
|
||||
object`\ s.
|
||||
|
||||
``S`` (:class:`bytes`) [PyBytesObject \*]
|
||||
Requires that the Python object is a :class:`bytes` object, without
|
||||
attempting any conversion. Raises :exc:`TypeError` if the object is not
|
||||
a bytes object. The C variable may also be declared as :c:type:`PyObject\*`.
|
||||
|
||||
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
|
||||
Requires that the Python object is a :class:`bytearray` object, without
|
||||
attempting any conversion. Raises :exc:`TypeError` if the object is not
|
||||
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
|
||||
|
||||
``u`` (:class:`str`) [Py_UNICODE \*]
|
||||
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
|
||||
Unicode characters. You must pass the address of a :c:type:`Py_UNICODE`
|
||||
pointer variable, which will be filled with the pointer to an existing
|
||||
Unicode buffer. Please note that the width of a :c:type:`Py_UNICODE`
|
||||
character depends on compilation options (it is either 16 or 32 bits).
|
||||
The Python string must not contain embedded NUL characters; if it does,
|
||||
a :exc:`TypeError` exception is raised.
|
||||
|
||||
.. note::
|
||||
Since ``u`` doesn't give you back the length of the string, and it
|
||||
may contain embedded NUL characters, it is recommended to use ``u#``
|
||||
or ``U`` instead.
|
||||
|
||||
``u#`` (:class:`str`) [Py_UNICODE \*, int]
|
||||
This variant on ``u`` stores into two C variables, the first one a pointer to a
|
||||
Unicode data buffer, the second one its length.
|
||||
|
||||
``Z`` (:class:`str` or ``None``) [Py_UNICODE \*]
|
||||
Like ``u``, but the Python object may also be ``None``, in which case the
|
||||
:c:type:`Py_UNICODE` pointer is set to *NULL*.
|
||||
|
||||
``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
|
||||
Like ``u#``, but the Python object may also be ``None``, in which case the
|
||||
:c:type:`Py_UNICODE` pointer is set to *NULL*.
|
||||
|
||||
``U`` (:class:`str`) [PyObject \*]
|
||||
Requires that the Python object is a Unicode object, without attempting
|
||||
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
|
||||
object. The C variable may also be declared as :c:type:`PyObject\*`.
|
||||
|
||||
``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer]
|
||||
This format accepts any object which implements the read-write buffer
|
||||
interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
|
||||
The buffer may contain embedded null bytes. The caller have to call
|
||||
:c:func:`PyBuffer_Release` when it is done with the buffer.
|
||||
|
||||
``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
|
||||
This variant on ``s`` is used for encoding Unicode into a character buffer.
|
||||
It only works for encoded data without embedded NUL bytes.
|
||||
|
||||
This format requires two arguments. The first is only used as input, and
|
||||
must be a :c:type:`const char\*` which points to the name of an encoding as a
|
||||
NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
|
||||
An exception is raised if the named encoding is not known to Python. The
|
||||
second argument must be a :c:type:`char\*\*`; the value of the pointer it
|
||||
references will be set to a buffer with the contents of the argument text.
|
||||
The text will be encoded in the encoding specified by the first argument.
|
||||
|
||||
:c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
|
||||
encoded data into this buffer and adjust *\*buffer* to reference the newly
|
||||
allocated storage. The caller is responsible for calling :c:func:`PyMem_Free` to
|
||||
free the allocated buffer after use.
|
||||
|
||||
``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
|
||||
Same as ``es`` except that byte string objects are passed through without
|
||||
recoding them. Instead, the implementation assumes that the byte string object uses
|
||||
the encoding passed in as parameter.
|
||||
|
||||
``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
|
||||
This variant on ``s#`` is used for encoding Unicode into a character buffer.
|
||||
Unlike the ``es`` format, this variant allows input data which contains NUL
|
||||
characters.
|
||||
|
||||
It requires three arguments. The first is only used as input, and must be a
|
||||
:c:type:`const char\*` which points to the name of an encoding as a
|
||||
NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
|
||||
An exception is raised if the named encoding is not known to Python. The
|
||||
second argument must be a :c:type:`char\*\*`; the value of the pointer it
|
||||
references will be set to a buffer with the contents of the argument text.
|
||||
The text will be encoded in the encoding specified by the first argument.
|
||||
The third argument must be a pointer to an integer; the referenced integer
|
||||
will be set to the number of bytes in the output buffer.
|
||||
|
||||
There are two modes of operation:
|
||||
|
||||
If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
|
||||
the needed size, copy the encoded data into this buffer and set *\*buffer* to
|
||||
reference the newly allocated storage. The caller is responsible for calling
|
||||
:c:func:`PyMem_Free` to free the allocated buffer after usage.
|
||||
|
||||
If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
|
||||
:c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the
|
||||
initial value of *\*buffer_length* as the buffer size. It will then copy the
|
||||
encoded data into the buffer and NUL-terminate it. If the buffer is not large
|
||||
enough, a :exc:`ValueError` will be set.
|
||||
|
||||
In both cases, *\*buffer_length* is set to the length of the encoded data
|
||||
without the trailing NUL byte.
|
||||
|
||||
``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
|
||||
Same as ``es#`` except that byte string objects are passed through without recoding
|
||||
them. Instead, the implementation assumes that the byte string object uses the
|
||||
encoding passed in as parameter.
|
||||
|
||||
Numbers
|
||||
-------
|
||||
|
||||
``b`` (:class:`int`) [unsigned char]
|
||||
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
|
||||
:c:type:`unsigned char`.
|
||||
|
||||
``B`` (:class:`int`) [unsigned char]
|
||||
Convert a Python integer to a tiny int without overflow checking, stored in a C
|
||||
:c:type:`unsigned char`.
|
||||
|
||||
``h`` (:class:`int`) [short int]
|
||||
Convert a Python integer to a C :c:type:`short int`.
|
||||
|
||||
``H`` (:class:`int`) [unsigned short int]
|
||||
Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
|
||||
checking.
|
||||
|
||||
``i`` (:class:`int`) [int]
|
||||
Convert a Python integer to a plain C :c:type:`int`.
|
||||
|
||||
``I`` (:class:`int`) [unsigned int]
|
||||
Convert a Python integer to a C :c:type:`unsigned int`, without overflow
|
||||
checking.
|
||||
|
||||
``l`` (:class:`int`) [long int]
|
||||
Convert a Python integer to a C :c:type:`long int`.
|
||||
|
||||
``k`` (:class:`int`) [unsigned long]
|
||||
Convert a Python integer to a C :c:type:`unsigned long` without
|
||||
overflow checking.
|
||||
|
||||
``L`` (:class:`int`) [PY_LONG_LONG]
|
||||
Convert a Python integer to a C :c:type:`long long`. This format is only
|
||||
available on platforms that support :c:type:`long long` (or :c:type:`_int64` on
|
||||
Windows).
|
||||
|
||||
``K`` (:class:`int`) [unsigned PY_LONG_LONG]
|
||||
Convert a Python integer to a C :c:type:`unsigned long long`
|
||||
without overflow checking. This format is only available on platforms that
|
||||
support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on Windows).
|
||||
|
||||
``n`` (:class:`int`) [Py_ssize_t]
|
||||
Convert a Python integer to a C :c:type:`Py_ssize_t`.
|
||||
|
||||
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
|
||||
Convert a Python byte, represented as a :class:`bytes` or
|
||||
:class:`bytearray` object of length 1, to a C :c:type:`char`.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Allow :class:`bytearray` objects.
|
||||
|
||||
``C`` (:class:`str` of length 1) [int]
|
||||
Convert a Python character, represented as a :class:`str` object of
|
||||
length 1, to a C :c:type:`int`.
|
||||
|
||||
``f`` (:class:`float`) [float]
|
||||
Convert a Python floating point number to a C :c:type:`float`.
|
||||
|
||||
``d`` (:class:`float`) [double]
|
||||
Convert a Python floating point number to a C :c:type:`double`.
|
||||
|
||||
``D`` (:class:`complex`) [Py_complex]
|
||||
Convert a Python complex number to a C :c:type:`Py_complex` structure.
|
||||
|
||||
Other objects
|
||||
-------------
|
||||
|
||||
``O`` (object) [PyObject \*]
|
||||
Store a Python object (without any conversion) in a C object pointer. The C
|
||||
program thus receives the actual object that was passed. The object's reference
|
||||
count is not increased. The pointer stored is not *NULL*.
|
||||
|
||||
``O!`` (object) [*typeobject*, PyObject \*]
|
||||
Store a Python object in a C object pointer. This is similar to ``O``, but
|
||||
takes two C arguments: the first is the address of a Python type object, the
|
||||
second is the address of the C variable (of type :c:type:`PyObject\*`) into which
|
||||
the object pointer is stored. If the Python object does not have the required
|
||||
type, :exc:`TypeError` is raised.
|
||||
|
||||
.. _o_ampersand:
|
||||
|
||||
``O&`` (object) [*converter*, *anything*]
|
||||
Convert a Python object to a C variable through a *converter* function. This
|
||||
takes two arguments: the first is a function, the second is the address of a C
|
||||
variable (of arbitrary type), converted to :c:type:`void \*`. The *converter*
|
||||
function in turn is called as follows::
|
||||
|
||||
status = converter(object, address);
|
||||
|
||||
where *object* is the Python object to be converted and *address* is the
|
||||
:c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
|
||||
The returned *status* should be ``1`` for a successful conversion and ``0`` if
|
||||
the conversion has failed. When the conversion fails, the *converter* function
|
||||
should raise an exception and leave the content of *address* unmodified.
|
||||
|
||||
If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
|
||||
second time if the argument parsing eventually fails, giving the converter a
|
||||
chance to release any memory that it had already allocated. In this second
|
||||
call, the *object* parameter will be NULL; *address* will have the same value
|
||||
as in the original call.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
``Py_CLEANUP_SUPPORTED`` was added.
|
||||
|
||||
``p`` (:class:`bool`) [int]
|
||||
Tests the value passed in for truth (a boolean **p**\redicate) and converts
|
||||
the result to its equivalent C true/false integer value.
|
||||
Sets the int to 1 if the expression was true and 0 if it was false.
|
||||
This accepts any valid Python value. See :ref:`truth` for more
|
||||
information about how Python tests values for truth.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
``(items)`` (:class:`tuple`) [*matching-items*]
|
||||
The object must be a Python sequence whose length is the number of format units
|
||||
in *items*. The C arguments must correspond to the individual format units in
|
||||
*items*. Format units for sequences may be nested.
|
||||
|
||||
It is possible to pass "long" integers (integers whose value exceeds the
|
||||
platform's :const:`LONG_MAX`) however no proper range checking is done --- the
|
||||
most significant bits are silently truncated when the receiving field is too
|
||||
small to receive the value (actually, the semantics are inherited from downcasts
|
||||
in C --- your mileage may vary).
|
||||
|
||||
A few other characters have a meaning in a format string. These may not occur
|
||||
inside nested parentheses. They are:
|
||||
|
||||
``|``
|
||||
Indicates that the remaining arguments in the Python argument list are optional.
|
||||
The C variables corresponding to optional arguments should be initialized to
|
||||
their default value --- when an optional argument is not specified,
|
||||
:c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding C
|
||||
variable(s).
|
||||
|
||||
``$``
|
||||
:c:func:`PyArg_ParseTupleAndKeywords` only:
|
||||
Indicates that the remaining arguments in the Python argument list are
|
||||
keyword-only. Currently, all keyword-only arguments must also be optional
|
||||
arguments, so ``|`` must always be specified before ``$`` in the format
|
||||
string.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
``:``
|
||||
The list of format units ends here; the string after the colon is used as the
|
||||
function name in error messages (the "associated value" of the exception that
|
||||
:c:func:`PyArg_ParseTuple` raises).
|
||||
|
||||
``;``
|
||||
The list of format units ends here; the string after the semicolon is used as
|
||||
the error message *instead* of the default error message. ``:`` and ``;``
|
||||
mutually exclude each other.
|
||||
|
||||
Note that any Python object references which are provided to the caller are
|
||||
*borrowed* references; do not decrement their reference count!
|
||||
|
||||
Additional arguments passed to these functions must be addresses of variables
|
||||
whose type is determined by the format string; these are used to store values
|
||||
from the input tuple. There are a few cases, as described in the list of format
|
||||
units above, where these parameters are used as input values; they should match
|
||||
what is specified for the corresponding format unit in that case.
|
||||
|
||||
For the conversion to succeed, the *arg* object must match the format
|
||||
and the format must be exhausted. On success, the
|
||||
:c:func:`PyArg_Parse\*` functions return true, otherwise they return
|
||||
false and raise an appropriate exception. When the
|
||||
:c:func:`PyArg_Parse\*` functions fail due to conversion failure in one
|
||||
of the format units, the variables at the addresses corresponding to that
|
||||
and the following format units are left untouched.
|
||||
|
||||
API Functions
|
||||
-------------
|
||||
|
||||
.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
|
||||
|
||||
Parse the parameters of a function that takes only positional parameters into
|
||||
local variables. Returns true on success; on failure, it returns false and
|
||||
raises the appropriate exception.
|
||||
|
||||
|
||||
.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
|
||||
|
||||
Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list rather
|
||||
than a variable number of arguments.
|
||||
|
||||
|
||||
.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
|
||||
|
||||
Parse the parameters of a function that takes both positional and keyword
|
||||
parameters into local variables. Returns true on success; on failure, it
|
||||
returns false and raises the appropriate exception.
|
||||
|
||||
|
||||
.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
|
||||
|
||||
Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
|
||||
va_list rather than a variable number of arguments.
|
||||
|
||||
|
||||
.. c:function:: int PyArg_ValidateKeywordArguments(PyObject *)
|
||||
|
||||
Ensure that the keys in the keywords argument dictionary are strings. This
|
||||
is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since the
|
||||
latter already does this check.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. XXX deprecated, will be removed
|
||||
.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
|
||||
|
||||
Function used to deconstruct the argument lists of "old-style" functions ---
|
||||
these are functions which use the :const:`METH_OLDARGS` parameter parsing
|
||||
method. This is not recommended for use in parameter parsing in new code, and
|
||||
most code in the standard interpreter has been modified to no longer use this
|
||||
for that purpose. It does remain a convenient way to decompose other tuples,
|
||||
however, and may continue to be used for that purpose.
|
||||
|
||||
|
||||
.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
|
||||
|
||||
A simpler form of parameter retrieval which does not use a format string to
|
||||
specify the types of the arguments. Functions which use this method to retrieve
|
||||
their parameters should be declared as :const:`METH_VARARGS` in function or
|
||||
method tables. The tuple containing the actual parameters should be passed as
|
||||
*args*; it must actually be a tuple. The length of the tuple must be at least
|
||||
*min* and no more than *max*; *min* and *max* may be equal. Additional
|
||||
arguments must be passed to the function, each of which should be a pointer to a
|
||||
:c:type:`PyObject\*` variable; these will be filled in with the values from
|
||||
*args*; they will contain borrowed references. The variables which correspond
|
||||
to optional parameters not given by *args* will not be filled in; these should
|
||||
be initialized by the caller. This function returns true on success and false if
|
||||
*args* is not a tuple or contains the wrong number of elements; an exception
|
||||
will be set if there was a failure.
|
||||
|
||||
This is an example of the use of this function, taken from the sources for the
|
||||
:mod:`_weakref` helper module for weak references::
|
||||
|
||||
static PyObject *
|
||||
weakref_ref(PyObject *self, PyObject *args)
|
||||
{
|
||||
PyObject *object;
|
||||
PyObject *callback = NULL;
|
||||
PyObject *result = NULL;
|
||||
|
||||
if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
|
||||
result = PyWeakref_NewRef(object, callback);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
The call to :c:func:`PyArg_UnpackTuple` in this example is entirely equivalent to
|
||||
this call to :c:func:`PyArg_ParseTuple`::
|
||||
|
||||
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
|
||||
|
||||
|
||||
---------------
|
||||
Building values
|
||||
---------------
|
||||
|
||||
.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
|
||||
|
||||
Create a new value based on a format string similar to those accepted by the
|
||||
:c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns
|
||||
the value or *NULL* in the case of an error; an exception will be raised if
|
||||
*NULL* is returned.
|
||||
|
||||
:c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple only if
|
||||
its format string contains two or more format units. If the format string is
|
||||
empty, it returns ``None``; if it contains exactly one format unit, it returns
|
||||
whatever object is described by that format unit. To force it to return a tuple
|
||||
of size 0 or one, parenthesize the format string.
|
||||
|
||||
When memory buffers are passed as parameters to supply data to build objects, as
|
||||
for the ``s`` and ``s#`` formats, the required data is copied. Buffers provided
|
||||
by the caller are never referenced by the objects created by
|
||||
:c:func:`Py_BuildValue`. In other words, if your code invokes :c:func:`malloc`
|
||||
and passes the allocated memory to :c:func:`Py_BuildValue`, your code is
|
||||
responsible for calling :c:func:`free` for that memory once
|
||||
:c:func:`Py_BuildValue` returns.
|
||||
|
||||
In the following description, the quoted form is the format unit; the entry in
|
||||
(round) parentheses is the Python object type that the format unit will return;
|
||||
and the entry in [square] brackets is the type of the C value(s) to be passed.
|
||||
|
||||
The characters space, tab, colon and comma are ignored in format strings (but
|
||||
not within format units such as ``s#``). This can be used to make long format
|
||||
strings a tad more readable.
|
||||
|
||||
``s`` (:class:`str` or ``None``) [char \*]
|
||||
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
|
||||
encoding. If the C string pointer is *NULL*, ``None`` is used.
|
||||
|
||||
``s#`` (:class:`str` or ``None``) [char \*, int]
|
||||
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
|
||||
encoding. If the C string pointer is *NULL*, the length is ignored and
|
||||
``None`` is returned.
|
||||
|
||||
``y`` (:class:`bytes`) [char \*]
|
||||
This converts a C string to a Python :class:`bytes` object. If the C
|
||||
string pointer is *NULL*, ``None`` is returned.
|
||||
|
||||
``y#`` (:class:`bytes`) [char \*, int]
|
||||
This converts a C string and its lengths to a Python object. If the C
|
||||
string pointer is *NULL*, ``None`` is returned.
|
||||
|
||||
``z`` (:class:`str` or ``None``) [char \*]
|
||||
Same as ``s``.
|
||||
|
||||
``z#`` (:class:`str` or ``None``) [char \*, int]
|
||||
Same as ``s#``.
|
||||
|
||||
``u`` (:class:`str`) [Py_UNICODE \*]
|
||||
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
|
||||
Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned.
|
||||
|
||||
``u#`` (:class:`str`) [Py_UNICODE \*, int]
|
||||
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
|
||||
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
|
||||
and ``None`` is returned.
|
||||
|
||||
``U`` (:class:`str` or ``None``) [char \*]
|
||||
Same as ``s``.
|
||||
|
||||
``U#`` (:class:`str` or ``None``) [char \*, int]
|
||||
Same as ``s#``.
|
||||
|
||||
``i`` (:class:`int`) [int]
|
||||
Convert a plain C :c:type:`int` to a Python integer object.
|
||||
|
||||
``b`` (:class:`int`) [char]
|
||||
Convert a plain C :c:type:`char` to a Python integer object.
|
||||
|
||||
``h`` (:class:`int`) [short int]
|
||||
Convert a plain C :c:type:`short int` to a Python integer object.
|
||||
|
||||
``l`` (:class:`int`) [long int]
|
||||
Convert a C :c:type:`long int` to a Python integer object.
|
||||
|
||||
``B`` (:class:`int`) [unsigned char]
|
||||
Convert a C :c:type:`unsigned char` to a Python integer object.
|
||||
|
||||
``H`` (:class:`int`) [unsigned short int]
|
||||
Convert a C :c:type:`unsigned short int` to a Python integer object.
|
||||
|
||||
``I`` (:class:`int`) [unsigned int]
|
||||
Convert a C :c:type:`unsigned int` to a Python integer object.
|
||||
|
||||
``k`` (:class:`int`) [unsigned long]
|
||||
Convert a C :c:type:`unsigned long` to a Python integer object.
|
||||
|
||||
``L`` (:class:`int`) [PY_LONG_LONG]
|
||||
Convert a C :c:type:`long long` to a Python integer object. Only available
|
||||
on platforms that support :c:type:`long long` (or :c:type:`_int64` on
|
||||
Windows).
|
||||
|
||||
``K`` (:class:`int`) [unsigned PY_LONG_LONG]
|
||||
Convert a C :c:type:`unsigned long long` to a Python integer object. Only
|
||||
available on platforms that support :c:type:`unsigned long long` (or
|
||||
:c:type:`unsigned _int64` on Windows).
|
||||
|
||||
``n`` (:class:`int`) [Py_ssize_t]
|
||||
Convert a C :c:type:`Py_ssize_t` to a Python integer.
|
||||
|
||||
``c`` (:class:`bytes` of length 1) [char]
|
||||
Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
|
||||
length 1.
|
||||
|
||||
``C`` (:class:`str` of length 1) [int]
|
||||
Convert a C :c:type:`int` representing a character to Python :class:`str`
|
||||
object of length 1.
|
||||
|
||||
``d`` (:class:`float`) [double]
|
||||
Convert a C :c:type:`double` to a Python floating point number.
|
||||
|
||||
``f`` (:class:`float`) [float]
|
||||
Convert a C :c:type:`float` to a Python floating point number.
|
||||
|
||||
``D`` (:class:`complex`) [Py_complex \*]
|
||||
Convert a C :c:type:`Py_complex` structure to a Python complex number.
|
||||
|
||||
``O`` (object) [PyObject \*]
|
||||
Pass a Python object untouched (except for its reference count, which is
|
||||
incremented by one). If the object passed in is a *NULL* pointer, it is assumed
|
||||
that this was caused because the call producing the argument found an error and
|
||||
set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't
|
||||
raise an exception. If no exception has been raised yet, :exc:`SystemError` is
|
||||
set.
|
||||
|
||||
``S`` (object) [PyObject \*]
|
||||
Same as ``O``.
|
||||
|
||||
``N`` (object) [PyObject \*]
|
||||
Same as ``O``, except it doesn't increment the reference count on the object.
|
||||
Useful when the object is created by a call to an object constructor in the
|
||||
argument list.
|
||||
|
||||
``O&`` (object) [*converter*, *anything*]
|
||||
Convert *anything* to a Python object through a *converter* function. The
|
||||
function is called with *anything* (which should be compatible with :c:type:`void
|
||||
\*`) as its argument and should return a "new" Python object, or *NULL* if an
|
||||
error occurred.
|
||||
|
||||
``(items)`` (:class:`tuple`) [*matching-items*]
|
||||
Convert a sequence of C values to a Python tuple with the same number of items.
|
||||
|
||||
``[items]`` (:class:`list`) [*matching-items*]
|
||||
Convert a sequence of C values to a Python list with the same number of items.
|
||||
|
||||
``{items}`` (:class:`dict`) [*matching-items*]
|
||||
Convert a sequence of C values to a Python dictionary. Each pair of consecutive
|
||||
C values adds one item to the dictionary, serving as key and value,
|
||||
respectively.
|
||||
|
||||
If there is an error in the format string, the :exc:`SystemError` exception is
|
||||
set and *NULL* returned.
|
||||
|
||||
.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
|
||||
|
||||
Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list
|
||||
rather than a variable number of arguments.
|
|
@ -0,0 +1,46 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _boolobjects:
|
||||
|
||||
Boolean Objects
|
||||
---------------
|
||||
|
||||
Booleans in Python are implemented as a subclass of integers. There are only
|
||||
two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal
|
||||
creation and deletion functions don't apply to booleans. The following macros
|
||||
are available, however.
|
||||
|
||||
|
||||
.. c:function:: int PyBool_Check(PyObject *o)
|
||||
|
||||
Return true if *o* is of type :c:data:`PyBool_Type`.
|
||||
|
||||
|
||||
.. c:var:: PyObject* Py_False
|
||||
|
||||
The Python ``False`` object. This object has no methods. It needs to be
|
||||
treated just like any other object with respect to reference counts.
|
||||
|
||||
|
||||
.. c:var:: PyObject* Py_True
|
||||
|
||||
The Python ``True`` object. This object has no methods. It needs to be treated
|
||||
just like any other object with respect to reference counts.
|
||||
|
||||
|
||||
.. c:macro:: Py_RETURN_FALSE
|
||||
|
||||
Return :const:`Py_False` from a function, properly incrementing its reference
|
||||
count.
|
||||
|
||||
|
||||
.. c:macro:: Py_RETURN_TRUE
|
||||
|
||||
Return :const:`Py_True` from a function, properly incrementing its reference
|
||||
count.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBool_FromLong(long v)
|
||||
|
||||
Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
|
||||
truth value of *v*.
|
|
@ -0,0 +1,496 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. index::
|
||||
single: buffer protocol
|
||||
single: buffer interface; (see buffer protocol)
|
||||
single: buffer object; (see buffer protocol)
|
||||
|
||||
.. _bufferobjects:
|
||||
|
||||
Buffer Protocol
|
||||
---------------
|
||||
|
||||
.. sectionauthor:: Greg Stein <gstein@lyra.org>
|
||||
.. sectionauthor:: Benjamin Peterson
|
||||
.. sectionauthor:: Stefan Krah
|
||||
|
||||
|
||||
Certain objects available in Python wrap access to an underlying memory
|
||||
array or *buffer*. Such objects include the built-in :class:`bytes` and
|
||||
:class:`bytearray`, and some extension types like :class:`array.array`.
|
||||
Third-party libraries may define their own types for special purposes, such
|
||||
as image processing or numeric analysis.
|
||||
|
||||
While each of these types have their own semantics, they share the common
|
||||
characteristic of being backed by a possibly large memory buffer. It is
|
||||
then desirable, in some situations, to access that buffer directly and
|
||||
without intermediate copying.
|
||||
|
||||
Python provides such a facility at the C level in the form of the :ref:`buffer
|
||||
protocol <bufferobjects>`. This protocol has two sides:
|
||||
|
||||
.. index:: single: PyBufferProcs
|
||||
|
||||
- on the producer side, a type can export a "buffer interface" which allows
|
||||
objects of that type to expose information about their underlying buffer.
|
||||
This interface is described in the section :ref:`buffer-structs`;
|
||||
|
||||
- on the consumer side, several means are available to obtain a pointer to
|
||||
the raw underlying data of an object (for example a method parameter).
|
||||
|
||||
Simple objects such as :class:`bytes` and :class:`bytearray` expose their
|
||||
underlying buffer in byte-oriented form. Other forms are possible; for example,
|
||||
the elements exposed by a :class:`array.array` can be multi-byte values.
|
||||
|
||||
An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
|
||||
method of file objects: any object that can export a series of bytes through
|
||||
the buffer interface can be written to a file. While :meth:`write` only
|
||||
needs read-only access to the internal contents of the object passed to it,
|
||||
other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
|
||||
to the contents of their argument. The buffer interface allows objects to
|
||||
selectively allow or reject exporting of read-write and read-only buffers.
|
||||
|
||||
There are two ways for a consumer of the buffer interface to acquire a buffer
|
||||
over a target object:
|
||||
|
||||
* call :c:func:`PyObject_GetBuffer` with the right parameters;
|
||||
|
||||
* call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
|
||||
``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
|
||||
|
||||
In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
|
||||
isn't needed anymore. Failure to do so could lead to various issues such as
|
||||
resource leaks.
|
||||
|
||||
|
||||
.. _buffer-structure:
|
||||
|
||||
Buffer structure
|
||||
================
|
||||
|
||||
Buffer structures (or simply "buffers") are useful as a way to expose the
|
||||
binary data from another object to the Python programmer. They can also be
|
||||
used as a zero-copy slicing mechanism. Using their ability to reference a
|
||||
block of memory, it is possible to expose any data to the Python programmer
|
||||
quite easily. The memory could be a large, constant array in a C extension,
|
||||
it could be a raw block of memory for manipulation before passing to an
|
||||
operating system library, or it could be used to pass around structured data
|
||||
in its native, in-memory format.
|
||||
|
||||
Contrary to most data types exposed by the Python interpreter, buffers
|
||||
are not :c:type:`PyObject` pointers but rather simple C structures. This
|
||||
allows them to be created and copied very simply. When a generic wrapper
|
||||
around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
|
||||
can be created.
|
||||
|
||||
For short instructions how to write an exporting object, see
|
||||
:ref:`Buffer Object Structures <buffer-structs>`. For obtaining
|
||||
a buffer, see :c:func:`PyObject_GetBuffer`.
|
||||
|
||||
.. c:type:: Py_buffer
|
||||
|
||||
.. c:member:: void \*obj
|
||||
|
||||
A new reference to the exporting object. The reference is owned by
|
||||
the consumer and automatically decremented and set to *NULL* by
|
||||
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
|
||||
value of any standard C-API function.
|
||||
|
||||
As a special case, for *temporary* buffers that are wrapped by
|
||||
:c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
|
||||
this field is *NULL*. In general, exporting objects MUST NOT
|
||||
use this scheme.
|
||||
|
||||
.. c:member:: void \*buf
|
||||
|
||||
A pointer to the start of the logical structure described by the buffer
|
||||
fields. This can be any location within the underlying physical memory
|
||||
block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
|
||||
the value may point to the end of the memory block.
|
||||
|
||||
For contiguous arrays, the value points to the beginning of the memory
|
||||
block.
|
||||
|
||||
.. c:member:: Py_ssize_t len
|
||||
|
||||
``product(shape) * itemsize``. For contiguous arrays, this is the length
|
||||
of the underlying memory block. For non-contiguous arrays, it is the length
|
||||
that the logical structure would have if it were copied to a contiguous
|
||||
representation.
|
||||
|
||||
Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid
|
||||
if the buffer has been obtained by a request that guarantees contiguity. In
|
||||
most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:`PyBUF_WRITABLE`.
|
||||
|
||||
.. c:member:: int readonly
|
||||
|
||||
An indicator of whether the buffer is read-only. This field is controlled
|
||||
by the :c:macro:`PyBUF_WRITABLE` flag.
|
||||
|
||||
.. c:member:: Py_ssize_t itemsize
|
||||
|
||||
Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
|
||||
called on non-NULL :c:member:`~Py_buffer.format` values.
|
||||
|
||||
Important exception: If a consumer requests a buffer without the
|
||||
:c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_Buffer.format` will
|
||||
be set to *NULL*, but :c:member:`~Py_buffer.itemsize` still has
|
||||
the value for the original format.
|
||||
|
||||
If :c:member:`~Py_Buffer.shape` is present, the equality
|
||||
``product(shape) * itemsize == len`` still holds and the consumer
|
||||
can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
|
||||
|
||||
If :c:member:`~Py_Buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
|
||||
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
|
||||
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
|
||||
|
||||
.. c:member:: const char \*format
|
||||
|
||||
A *NUL* terminated string in :mod:`struct` module style syntax describing
|
||||
the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
|
||||
is assumed.
|
||||
|
||||
This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
|
||||
|
||||
.. c:member:: int ndim
|
||||
|
||||
The number of dimensions the memory represents as an n-dimensional array.
|
||||
If it is 0, :c:member:`~Py_Buffer.buf` points to a single item representing
|
||||
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
|
||||
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
|
||||
|
||||
The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
|
||||
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
|
||||
buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
|
||||
|
||||
.. c:member:: Py_ssize_t \*shape
|
||||
|
||||
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
|
||||
indicating the shape of the memory as an n-dimensional array. Note that
|
||||
``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to
|
||||
:c:member:`~Py_buffer.len`.
|
||||
|
||||
Shape values are restricted to ``shape[n] >= 0``. The case
|
||||
``shape[n] == 0`` requires special attention. See `complex arrays`_
|
||||
for further information.
|
||||
|
||||
The shape array is read-only for the consumer.
|
||||
|
||||
.. c:member:: Py_ssize_t \*strides
|
||||
|
||||
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
|
||||
giving the number of bytes to skip to get to a new element in each
|
||||
dimension.
|
||||
|
||||
Stride values can be any integer. For regular arrays, strides are
|
||||
usually positive, but a consumer MUST be able to handle the case
|
||||
``strides[n] <= 0``. See `complex arrays`_ for further information.
|
||||
|
||||
The strides array is read-only for the consumer.
|
||||
|
||||
.. c:member:: Py_ssize_t \*suboffsets
|
||||
|
||||
An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
|
||||
If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
|
||||
pointers and the suboffset value dictates how many bytes to add to each
|
||||
pointer after de-referencing. A suboffset value that is negative
|
||||
indicates that no de-referencing should occur (striding in a contiguous
|
||||
memory block).
|
||||
|
||||
This type of array representation is used by the Python Imaging Library
|
||||
(PIL). See `complex arrays`_ for further information how to access elements
|
||||
of such an array.
|
||||
|
||||
The suboffsets array is read-only for the consumer.
|
||||
|
||||
.. c:member:: void \*internal
|
||||
|
||||
This is for use internally by the exporting object. For example, this
|
||||
might be re-cast as an integer by the exporter and used to store flags
|
||||
about whether or not the shape, strides, and suboffsets arrays must be
|
||||
freed when the buffer is released. The consumer MUST NOT alter this
|
||||
value.
|
||||
|
||||
.. _buffer-request-types:
|
||||
|
||||
Buffer request types
|
||||
====================
|
||||
|
||||
Buffers are usually obtained by sending a buffer request to an exporting
|
||||
object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
|
||||
structure of the memory can vary drastically, the consumer uses the *flags*
|
||||
argument to specify the exact buffer type it can handle.
|
||||
|
||||
All :c:data:`Py_buffer` fields are unambiguously defined by the request
|
||||
type.
|
||||
|
||||
request-independent fields
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The following fields are not influenced by *flags* and must always be filled in
|
||||
with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
|
||||
:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
|
||||
|
||||
|
||||
readonly, format
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. c:macro:: PyBUF_WRITABLE
|
||||
|
||||
Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
|
||||
MUST provide a writable buffer or else report failure. Otherwise, the
|
||||
exporter MAY provide either a read-only or writable buffer, but the choice
|
||||
MUST be consistent for all consumers.
|
||||
|
||||
.. c:macro:: PyBUF_FORMAT
|
||||
|
||||
Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
|
||||
be filled in correctly. Otherwise, this field MUST be *NULL*.
|
||||
|
||||
|
||||
:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
|
||||
Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
|
||||
can be used as a stand-alone flag to request a simple writable buffer.
|
||||
|
||||
:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
|
||||
The latter already implies format ``B`` (unsigned bytes).
|
||||
|
||||
|
||||
shape, strides, suboffsets
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The flags that control the logical structure of the memory are listed
|
||||
in decreasing order of complexity. Note that each flag contains all bits
|
||||
of the flags below it.
|
||||
|
||||
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
|
||||
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| Request | shape | strides | suboffsets |
|
||||
+=============================+=======+=========+============+
|
||||
| .. c:macro:: PyBUF_INDIRECT | yes | yes | if needed |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| .. c:macro:: PyBUF_STRIDES | yes | yes | NULL |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| .. c:macro:: PyBUF_ND | yes | NULL | NULL |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
| .. c:macro:: PyBUF_SIMPLE | NULL | NULL | NULL |
|
||||
+-----------------------------+-------+---------+------------+
|
||||
|
||||
|
||||
contiguity requests
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
C or Fortran contiguity can be explicitly requested, with and without stride
|
||||
information. Without stride information, the buffer must be C-contiguous.
|
||||
|
||||
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
|
||||
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| Request | shape | strides | suboffsets | contig |
|
||||
+===================================+=======+=========+============+========+
|
||||
| .. c:macro:: PyBUF_C_CONTIGUOUS | yes | yes | NULL | C |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| .. c:macro:: PyBUF_F_CONTIGUOUS | yes | yes | NULL | F |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| .. c:macro:: PyBUF_ANY_CONTIGUOUS | yes | yes | NULL | C or F |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
| .. c:macro:: PyBUF_ND | yes | NULL | NULL | C |
|
||||
+-----------------------------------+-------+---------+------------+--------+
|
||||
|
||||
|
||||
compound requests
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
All possible requests are fully defined by some combination of the flags in
|
||||
the previous section. For convenience, the buffer protocol provides frequently
|
||||
used combinations as single flags.
|
||||
|
||||
In the following table *U* stands for undefined contiguity. The consumer would
|
||||
have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
|
||||
|
||||
.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
|
||||
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| Request | shape | strides | suboffsets | contig | readonly | format |
|
||||
+===============================+=======+=========+============+========+==========+========+
|
||||
| .. c:macro:: PyBUF_FULL | yes | yes | if needed | U | 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_FULL_RO | yes | yes | if needed | U | 1 or 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_RECORDS | yes | yes | NULL | U | 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_RECORDS_RO | yes | yes | NULL | U | 1 or 0 | yes |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_STRIDED | yes | yes | NULL | U | 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_STRIDED_RO | yes | yes | NULL | U | 1 or 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_CONTIG | yes | NULL | NULL | C | 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
| .. c:macro:: PyBUF_CONTIG_RO | yes | NULL | NULL | C | 1 or 0 | NULL |
|
||||
+-------------------------------+-------+---------+------------+--------+----------+--------+
|
||||
|
||||
|
||||
Complex arrays
|
||||
==============
|
||||
|
||||
NumPy-style: shape and strides
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.itemsize`,
|
||||
:c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides`.
|
||||
|
||||
If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
|
||||
interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
|
||||
both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
|
||||
|
||||
If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
|
||||
a standard n-dimensional C-array. Otherwise, the consumer must access an
|
||||
n-dimensional array as follows:
|
||||
|
||||
``ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1]``
|
||||
``item = *((typeof(item) *)ptr);``
|
||||
|
||||
|
||||
As noted above, :c:member:`~Py_buffer.buf` can point to any location within
|
||||
the actual memory block. An exporter can check the validity of a buffer with
|
||||
this function:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
|
||||
"""Verify that the parameters represent a valid array within
|
||||
the bounds of the allocated memory:
|
||||
char *mem: start of the physical memory block
|
||||
memlen: length of the physical memory block
|
||||
offset: (char *)buf - mem
|
||||
"""
|
||||
if offset % itemsize:
|
||||
return False
|
||||
if offset < 0 or offset+itemsize > memlen:
|
||||
return False
|
||||
if any(v % itemsize for v in strides):
|
||||
return False
|
||||
|
||||
if ndim <= 0:
|
||||
return ndim == 0 and not shape and not strides
|
||||
if 0 in shape:
|
||||
return True
|
||||
|
||||
imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
|
||||
if strides[j] <= 0)
|
||||
imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
|
||||
if strides[j] > 0)
|
||||
|
||||
return 0 <= offset+imin and offset+imax+itemsize <= memlen
|
||||
|
||||
|
||||
PIL-style: shape, strides and suboffsets
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the regular items, PIL-style arrays can contain pointers
|
||||
that must be followed in order to get to the next element in a dimension.
|
||||
For example, the regular three-dimensional C-array ``char v[2][2][3]`` can
|
||||
also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
|
||||
``char (*v[2])[2][3]``. In suboffsets representation, those two pointers
|
||||
can be embedded at the start of :c:member:`~Py_buffer.buf`, pointing
|
||||
to two ``char x[2][3]`` arrays that can be located anywhere in memory.
|
||||
|
||||
|
||||
Here is a function that returns a pointer to the element in an N-D array
|
||||
pointed to by an N-dimensional index when there are both non-NULL strides
|
||||
and suboffsets::
|
||||
|
||||
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
|
||||
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
|
||||
char *pointer = (char*)buf;
|
||||
int i;
|
||||
for (i = 0; i < ndim; i++) {
|
||||
pointer += strides[i] * indices[i];
|
||||
if (suboffsets[i] >=0 ) {
|
||||
pointer = *((char**)pointer) + suboffsets[i];
|
||||
}
|
||||
}
|
||||
return (void*)pointer;
|
||||
}
|
||||
|
||||
|
||||
Buffer-related functions
|
||||
========================
|
||||
|
||||
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
|
||||
|
||||
Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is
|
||||
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
|
||||
succeed.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
|
||||
|
||||
Send a request to *exporter* to fill in *view* as specified by *flags*.
|
||||
If the exporter cannot provide a buffer of the exact type, it MUST raise
|
||||
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
|
||||
return -1.
|
||||
|
||||
On success, fill in *view*, set :c:member:`view->obj` to a new reference
|
||||
to *exporter* and return 0. In the case of chained buffer providers
|
||||
that redirect requests to a single object, :c:member:`view->obj` MAY
|
||||
refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
|
||||
|
||||
Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
|
||||
to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:`free`.
|
||||
Thus, after the consumer is done with the buffer, :c:func:`PyBuffer_Release`
|
||||
must be called exactly once.
|
||||
|
||||
|
||||
.. c:function:: void PyBuffer_Release(Py_buffer *view)
|
||||
|
||||
Release the buffer *view* and decrement the reference count for
|
||||
:c:member:`view->obj`. This function MUST be called when the buffer
|
||||
is no longer being used, otherwise reference leaks may occur.
|
||||
|
||||
It is an error to call this function on a buffer that was not obtained via
|
||||
:c:func:`PyObject_GetBuffer`.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
|
||||
|
||||
Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
|
||||
This function is not yet implemented.
|
||||
|
||||
|
||||
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
|
||||
|
||||
Return 1 if the memory defined by the *view* is C-style (*order* is
|
||||
``'C'``) or Fortran-style (*order* is ``'F'``) contiguous or either one
|
||||
(*order* is ``'A'``). Return 0 otherwise.
|
||||
|
||||
|
||||
.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
|
||||
|
||||
Fill the *strides* array with byte-strides of a contiguous (C-style if
|
||||
*order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
|
||||
given shape with the given number of bytes per element.
|
||||
|
||||
|
||||
.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
|
||||
|
||||
Handle buffer requests for an exporter that wants to expose *buf* of size *len*
|
||||
with writability set according to *readonly*. *buf* is interpreted as a sequence
|
||||
of unsigned bytes.
|
||||
|
||||
The *flags* argument indicates the request type. This function always fills in
|
||||
*view* as specified by flags, unless *buf* has been designated as read-only
|
||||
and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
|
||||
|
||||
On success, set :c:member:`view->obj` to a new reference to *exporter* and
|
||||
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
|
||||
:c:member:`view->obj` to *NULL* and return -1;
|
||||
|
||||
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
|
||||
*exporter* MUST be set to the exporting object. Otherwise, *exporter* MUST
|
||||
be NULL.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,86 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _bytearrayobjects:
|
||||
|
||||
Byte Array Objects
|
||||
------------------
|
||||
|
||||
.. index:: object: bytearray
|
||||
|
||||
|
||||
.. c:type:: PyByteArrayObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python bytearray object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyByteArray_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
|
||||
it is the same object as :class:`bytearray` in the Python layer.
|
||||
|
||||
|
||||
Type check macros
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. c:function:: int PyByteArray_Check(PyObject *o)
|
||||
|
||||
Return true if the object *o* is a bytearray object or an instance of a
|
||||
subtype of the bytearray type.
|
||||
|
||||
|
||||
.. c:function:: int PyByteArray_CheckExact(PyObject *o)
|
||||
|
||||
Return true if the object *o* is a bytearray object, but not an instance of a
|
||||
subtype of the bytearray type.
|
||||
|
||||
|
||||
Direct API functions
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
|
||||
|
||||
Return a new bytearray object from any object, *o*, that implements the
|
||||
:ref:`buffer protocol <bufferobjects>`.
|
||||
|
||||
.. XXX expand about the buffer protocol, at least somewhere
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
|
||||
|
||||
Create a new bytearray object from *string* and its length, *len*. On
|
||||
failure, *NULL* is returned.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
|
||||
|
||||
Concat bytearrays *a* and *b* and return a new bytearray with the result.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
|
||||
|
||||
Return the size of *bytearray* after checking for a *NULL* pointer.
|
||||
|
||||
|
||||
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
|
||||
|
||||
Return the contents of *bytearray* as a char array after checking for a
|
||||
*NULL* pointer.
|
||||
|
||||
|
||||
.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
|
||||
|
||||
Resize the internal buffer of *bytearray* to *len*.
|
||||
|
||||
Macros
|
||||
^^^^^^
|
||||
|
||||
These macros trade safety for speed and they don't check pointers.
|
||||
|
||||
.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
|
||||
|
||||
Macro version of :c:func:`PyByteArray_AsString`.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
|
||||
|
||||
Macro version of :c:func:`PyByteArray_Size`.
|
|
@ -0,0 +1,194 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _bytesobjects:
|
||||
|
||||
Bytes Objects
|
||||
-------------
|
||||
|
||||
These functions raise :exc:`TypeError` when expecting a bytes parameter and are
|
||||
called with a non-bytes parameter.
|
||||
|
||||
.. index:: object: bytes
|
||||
|
||||
|
||||
.. c:type:: PyBytesObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python bytes object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyBytes_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
|
||||
is the same object as :class:`bytes` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyBytes_Check(PyObject *o)
|
||||
|
||||
Return true if the object *o* is a bytes object or an instance of a subtype
|
||||
of the bytes type.
|
||||
|
||||
|
||||
.. c:function:: int PyBytes_CheckExact(PyObject *o)
|
||||
|
||||
Return true if the object *o* is a bytes object, but not an instance of a
|
||||
subtype of the bytes type.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromString(const char *v)
|
||||
|
||||
Return a new bytes object with a copy of the string *v* as value on success,
|
||||
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
|
||||
checked.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
|
||||
|
||||
Return a new bytes object with a copy of the string *v* as value and length
|
||||
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of
|
||||
the bytes object are uninitialized.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
|
||||
|
||||
Take a C :c:func:`printf`\ -style *format* string and a variable number of
|
||||
arguments, calculate the size of the resulting Python bytes object and return
|
||||
a bytes object with the values formatted into it. The variable arguments
|
||||
must be C types and must correspond exactly to the format characters in the
|
||||
*format* string. The following format characters are allowed:
|
||||
|
||||
.. % XXX: This should be exactly the same as the table in PyErr_Format.
|
||||
.. % One should just refer to the other.
|
||||
.. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
|
||||
.. % because not all compilers support the %z width modifier -- we fake it
|
||||
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
|
||||
|
||||
.. tabularcolumns:: |l|l|L|
|
||||
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| Format Characters | Type | Comment |
|
||||
+===================+===============+================================+
|
||||
| :attr:`%%` | *n/a* | The literal % character. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%c` | int | A single character, |
|
||||
| | | represented as an C int. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%d` | int | Exactly equivalent to |
|
||||
| | | ``printf("%d")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%u` | unsigned int | Exactly equivalent to |
|
||||
| | | ``printf("%u")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%ld` | long | Exactly equivalent to |
|
||||
| | | ``printf("%ld")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%lu` | unsigned long | Exactly equivalent to |
|
||||
| | | ``printf("%lu")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
|
||||
| | | ``printf("%zd")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%zu` | size_t | Exactly equivalent to |
|
||||
| | | ``printf("%zu")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%i` | int | Exactly equivalent to |
|
||||
| | | ``printf("%i")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%x` | int | Exactly equivalent to |
|
||||
| | | ``printf("%x")``. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%s` | char\* | A null-terminated C character |
|
||||
| | | array. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
| :attr:`%p` | void\* | The hex representation of a C |
|
||||
| | | pointer. Mostly equivalent to |
|
||||
| | | ``printf("%p")`` except that |
|
||||
| | | it is guaranteed to start with |
|
||||
| | | the literal ``0x`` regardless |
|
||||
| | | of what the platform's |
|
||||
| | | ``printf`` yields. |
|
||||
+-------------------+---------------+--------------------------------+
|
||||
|
||||
An unrecognized format character causes all the rest of the format string to be
|
||||
copied as-is to the result string, and any extra arguments discarded.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
|
||||
|
||||
Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
|
||||
arguments.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
|
||||
|
||||
Return the bytes representation of object *o* that implements the buffer
|
||||
protocol.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
|
||||
|
||||
Return the length of the bytes in bytes object *o*.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
|
||||
|
||||
Macro form of :c:func:`PyBytes_Size` but without error checking.
|
||||
|
||||
|
||||
.. c:function:: char* PyBytes_AsString(PyObject *o)
|
||||
|
||||
Return a NUL-terminated representation of the contents of *o*. The pointer
|
||||
refers to the internal buffer of *o*, not a copy. The data must not be
|
||||
modified in any way, unless the string was just created using
|
||||
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
|
||||
*o* is not a string object at all, :c:func:`PyBytes_AsString` returns *NULL*
|
||||
and raises :exc:`TypeError`.
|
||||
|
||||
|
||||
.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
|
||||
|
||||
Macro form of :c:func:`PyBytes_AsString` but without error checking.
|
||||
|
||||
|
||||
.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
|
||||
|
||||
Return a NUL-terminated representation of the contents of the object *obj*
|
||||
through the output variables *buffer* and *length*.
|
||||
|
||||
If *length* is *NULL*, the resulting buffer may not contain NUL characters;
|
||||
if it does, the function returns ``-1`` and a :exc:`TypeError` is raised.
|
||||
|
||||
The buffer refers to an internal string buffer of *obj*, not a copy. The data
|
||||
must not be modified in any way, unless the string was just created using
|
||||
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
|
||||
*string* is not a string object at all, :c:func:`PyBytes_AsStringAndSize`
|
||||
returns ``-1`` and raises :exc:`TypeError`.
|
||||
|
||||
|
||||
.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
|
||||
|
||||
Create a new bytes object in *\*bytes* containing the contents of *newpart*
|
||||
appended to *bytes*; the caller will own the new reference. The reference to
|
||||
the old value of *bytes* will be stolen. If the new string cannot be
|
||||
created, the old reference to *bytes* will still be discarded and the value
|
||||
of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
|
||||
|
||||
|
||||
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
|
||||
|
||||
Create a new string object in *\*bytes* containing the contents of *newpart*
|
||||
appended to *bytes*. This version decrements the reference count of
|
||||
*newpart*.
|
||||
|
||||
|
||||
.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
|
||||
|
||||
A way to resize a bytes object even though it is "immutable". Only use this
|
||||
to build up a brand new bytes object; don't use this if the bytes may already
|
||||
be known in other parts of the code. It is an error to call this function if
|
||||
the refcount on the input bytes object is not one. Pass the address of an
|
||||
existing bytes object as an lvalue (it may be written into), and the new size
|
||||
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
|
||||
returned; the address in *\*bytes* may differ from its input value. If the
|
||||
reallocation fails, the original bytes object at *\*bytes* is deallocated,
|
||||
*\*bytes* is set to *NULL*, a memory exception is set, and ``-1`` is
|
||||
returned.
|
|
@ -0,0 +1,150 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _capsules:
|
||||
|
||||
Capsules
|
||||
--------
|
||||
|
||||
.. index:: object: Capsule
|
||||
|
||||
Refer to :ref:`using-capsules` for more information on using these objects.
|
||||
|
||||
|
||||
.. c:type:: PyCapsule
|
||||
|
||||
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
|
||||
extension modules who need to pass an opaque value (as a :c:type:`void\*`
|
||||
pointer) through Python code to other C code. It is often used to make a C
|
||||
function pointer defined in one module available to other modules, so the
|
||||
regular import mechanism can be used to access C APIs defined in dynamically
|
||||
loaded modules.
|
||||
|
||||
.. c:type:: PyCapsule_Destructor
|
||||
|
||||
The type of a destructor callback for a capsule. Defined as::
|
||||
|
||||
typedef void (*PyCapsule_Destructor)(PyObject *);
|
||||
|
||||
See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
|
||||
callbacks.
|
||||
|
||||
|
||||
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyCapsule`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
|
||||
|
||||
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*
|
||||
argument may not be *NULL*.
|
||||
|
||||
On failure, set an exception and return *NULL*.
|
||||
|
||||
The *name* string may either be *NULL* or a pointer to a valid C string. If
|
||||
non-*NULL*, this string must outlive the capsule. (Though it is permitted to
|
||||
free it inside the *destructor*.)
|
||||
|
||||
If the *destructor* argument is not *NULL*, it will be called with the
|
||||
capsule as its argument when it is destroyed.
|
||||
|
||||
If this capsule will be stored as an attribute of a module, the *name* should
|
||||
be specified as ``modulename.attributename``. This will enable other modules
|
||||
to import the capsule using :c:func:`PyCapsule_Import`.
|
||||
|
||||
|
||||
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
|
||||
|
||||
Retrieve the *pointer* stored in the capsule. On failure, set an exception
|
||||
and return *NULL*.
|
||||
|
||||
The *name* parameter must compare exactly to the name stored in the capsule.
|
||||
If the name stored in the capsule is *NULL*, the *name* passed in must also
|
||||
be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule
|
||||
names.
|
||||
|
||||
|
||||
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
|
||||
|
||||
Return the current destructor stored in the capsule. On failure, set an
|
||||
exception and return *NULL*.
|
||||
|
||||
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
|
||||
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
|
||||
:c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
|
||||
|
||||
Return the current context stored in the capsule. On failure, set an
|
||||
exception and return *NULL*.
|
||||
|
||||
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
|
||||
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
|
||||
:c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
|
||||
|
||||
Return the current name stored in the capsule. On failure, set an exception
|
||||
and return *NULL*.
|
||||
|
||||
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
|
||||
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
|
||||
:c:func:`PyErr_Occurred` to disambiguate.
|
||||
|
||||
|
||||
.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
|
||||
|
||||
Import a pointer to a C object from a capsule attribute in a module. The
|
||||
*name* parameter should specify the full name to the attribute, as in
|
||||
``module.attribute``. The *name* stored in the capsule must match this
|
||||
string exactly. If *no_block* is true, import the module without blocking
|
||||
(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
|
||||
import the module conventionally (using :c:func:`PyImport_ImportModule`).
|
||||
|
||||
Return the capsule's internal *pointer* on success. On failure, set an
|
||||
exception and return *NULL*. However, if :c:func:`PyCapsule_Import` failed to
|
||||
import the module, and *no_block* was true, no exception is set.
|
||||
|
||||
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
|
||||
|
||||
Determines whether or not *capsule* is a valid capsule. A valid capsule is
|
||||
non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
|
||||
stored in it, and its internal name matches the *name* parameter. (See
|
||||
:c:func:`PyCapsule_GetPointer` for information on how capsule names are
|
||||
compared.)
|
||||
|
||||
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
|
||||
any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
|
||||
guaranteed to succeed.
|
||||
|
||||
Return a nonzero value if the object is valid and matches the name passed in.
|
||||
Return 0 otherwise. This function will not fail.
|
||||
|
||||
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
|
||||
|
||||
Set the context pointer inside *capsule* to *context*.
|
||||
|
||||
Return 0 on success. Return nonzero and set an exception on failure.
|
||||
|
||||
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
|
||||
|
||||
Set the destructor inside *capsule* to *destructor*.
|
||||
|
||||
Return 0 on success. Return nonzero and set an exception on failure.
|
||||
|
||||
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
|
||||
|
||||
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
|
||||
outlive the capsule. If the previous *name* stored in the capsule was not
|
||||
*NULL*, no attempt is made to free it.
|
||||
|
||||
Return 0 on success. Return nonzero and set an exception on failure.
|
||||
|
||||
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
|
||||
|
||||
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
|
||||
*NULL*.
|
||||
|
||||
Return 0 on success. Return nonzero and set an exception on failure.
|
|
@ -0,0 +1,62 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _cell-objects:
|
||||
|
||||
Cell Objects
|
||||
------------
|
||||
|
||||
"Cell" objects are used to implement variables referenced by multiple scopes.
|
||||
For each such variable, a cell object is created to store the value; the local
|
||||
variables of each stack frame that references the value contains a reference to
|
||||
the cells from outer scopes which also use that variable. When the value is
|
||||
accessed, the value contained in the cell is used instead of the cell object
|
||||
itself. This de-referencing of the cell object requires support from the
|
||||
generated byte-code; these are not automatically de-referenced when accessed.
|
||||
Cell objects are not likely to be useful elsewhere.
|
||||
|
||||
|
||||
.. c:type:: PyCellObject
|
||||
|
||||
The C structure used for cell objects.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyCell_Type
|
||||
|
||||
The type object corresponding to cell objects.
|
||||
|
||||
|
||||
.. c:function:: int PyCell_Check(ob)
|
||||
|
||||
Return true if *ob* is a cell object; *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyCell_New(PyObject *ob)
|
||||
|
||||
Create and return a new cell object containing the value *ob*. The parameter may
|
||||
be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyCell_Get(PyObject *cell)
|
||||
|
||||
Return the contents of the cell *cell*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyCell_GET(PyObject *cell)
|
||||
|
||||
Return the contents of the cell *cell*, but without checking that *cell* is
|
||||
non-*NULL* and a cell object.
|
||||
|
||||
|
||||
.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
|
||||
|
||||
Set the contents of the cell object *cell* to *value*. This releases the
|
||||
reference to any current content of the cell. *value* may be *NULL*. *cell*
|
||||
must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
|
||||
success, ``0`` will be returned.
|
||||
|
||||
|
||||
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
|
||||
|
||||
Sets the value of the cell object *cell* to *value*. No reference counts are
|
||||
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
|
||||
be a cell object.
|
|
@ -0,0 +1,50 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _codeobjects:
|
||||
|
||||
Code Objects
|
||||
------------
|
||||
|
||||
.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
|
||||
|
||||
|
||||
.. index::
|
||||
object: code
|
||||
|
||||
Code objects are a low-level detail of the CPython implementation.
|
||||
Each one represents a chunk of executable code that hasn't yet been
|
||||
bound into a function.
|
||||
|
||||
.. c:type:: PyCodeObject
|
||||
|
||||
The C structure of the objects used to describe code objects. The
|
||||
fields of this type are subject to change at any time.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyCode_Type
|
||||
|
||||
This is an instance of :c:type:`PyTypeObject` representing the Python
|
||||
:class:`code` type.
|
||||
|
||||
|
||||
.. c:function:: int PyCode_Check(PyObject *co)
|
||||
|
||||
Return true if *co* is a :class:`code` object
|
||||
|
||||
.. c:function:: int PyCode_GetNumFree(PyCodeObject *co)
|
||||
|
||||
Return the number of free variables in *co*.
|
||||
|
||||
.. c:function:: PyCodeObject* PyCode_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
|
||||
|
||||
Return a new code object. If you need a dummy code object to
|
||||
create a frame, use :c:func:`PyCode_NewEmpty` instead. Calling
|
||||
:c:func:`PyCode_New` directly can bind you to a precise Python
|
||||
version since the definition of the bytecode changes often.
|
||||
|
||||
|
||||
.. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
|
||||
|
||||
Return a new empty code object with the specified filename,
|
||||
function name, and first line number. It is illegal to
|
||||
:func:`exec` or :func:`eval` the resulting code object.
|
|
@ -0,0 +1,118 @@
|
|||
.. _codec-registry:
|
||||
|
||||
Codec registry and support functions
|
||||
====================================
|
||||
|
||||
.. c:function:: int PyCodec_Register(PyObject *search_function)
|
||||
|
||||
Register a new codec search function.
|
||||
|
||||
As side effect, this tries to load the :mod:`encodings` package, if not yet
|
||||
done, to make sure that it is always first in the list of search functions.
|
||||
|
||||
.. c:function:: int PyCodec_KnownEncoding(const char *encoding)
|
||||
|
||||
Return ``1`` or ``0`` depending on whether there is a registered codec for
|
||||
the given *encoding*.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
|
||||
|
||||
Generic codec based encoding API.
|
||||
|
||||
*object* is passed through the encoder function found for the given
|
||||
*encoding* using the error handling method defined by *errors*. *errors* may
|
||||
be *NULL* to use the default method defined for the codec. Raises a
|
||||
:exc:`LookupError` if no encoder can be found.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
|
||||
|
||||
Generic codec based decoding API.
|
||||
|
||||
*object* is passed through the decoder function found for the given
|
||||
*encoding* using the error handling method defined by *errors*. *errors* may
|
||||
be *NULL* to use the default method defined for the codec. Raises a
|
||||
:exc:`LookupError` if no encoder can be found.
|
||||
|
||||
|
||||
Codec lookup API
|
||||
----------------
|
||||
|
||||
In the following functions, the *encoding* string is looked up converted to all
|
||||
lower-case characters, which makes encodings looked up through this mechanism
|
||||
effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set
|
||||
and *NULL* returned.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_Encoder(const char *encoding)
|
||||
|
||||
Get an encoder function for the given *encoding*.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_Decoder(const char *encoding)
|
||||
|
||||
Get a decoder function for the given *encoding*.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
|
||||
|
||||
Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
|
||||
|
||||
Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
|
||||
|
||||
Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
|
||||
|
||||
Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
|
||||
|
||||
|
||||
Registry API for Unicode encoding error handlers
|
||||
------------------------------------------------
|
||||
|
||||
.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error)
|
||||
|
||||
Register the error handling callback function *error* under the given *name*.
|
||||
This callback function will be called by a codec when it encounters
|
||||
unencodable characters/undecodable bytes and *name* is specified as the error
|
||||
parameter in the call to the encode/decode function.
|
||||
|
||||
The callback gets a single argument, an instance of
|
||||
:exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
|
||||
:exc:`UnicodeTranslateError` that holds information about the problematic
|
||||
sequence of characters or bytes and their offset in the original string (see
|
||||
:ref:`unicodeexceptions` for functions to extract this information). The
|
||||
callback must either raise the given exception, or return a two-item tuple
|
||||
containing the replacement for the problematic sequence, and an integer
|
||||
giving the offset in the original string at which encoding/decoding should be
|
||||
resumed.
|
||||
|
||||
Return ``0`` on success, ``-1`` on error.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_LookupError(const char *name)
|
||||
|
||||
Lookup the error handling callback function registered under *name*. As a
|
||||
special case *NULL* can be passed, in which case the error handling callback
|
||||
for "strict" will be returned.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)
|
||||
|
||||
Raise *exc* as an exception.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
|
||||
|
||||
Ignore the unicode error, skipping the faulty input.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
|
||||
|
||||
Replace the unicode encode error with ``?`` or ``U+FFFD``.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
|
||||
|
||||
Replace the unicode encode error with XML character references.
|
||||
|
||||
.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
|
||||
|
||||
Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
|
||||
``\U``).
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _complexobjects:
|
||||
|
||||
Complex Number Objects
|
||||
----------------------
|
||||
|
||||
.. index:: object: complex number
|
||||
|
||||
Python's complex number objects are implemented as two distinct types when
|
||||
viewed from the C API: one is the Python object exposed to Python programs, and
|
||||
the other is a C structure which represents the actual complex number value.
|
||||
The API provides functions for working with both.
|
||||
|
||||
|
||||
Complex Numbers as C Structures
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Note that the functions which accept these structures as parameters and return
|
||||
them as results do so *by value* rather than dereferencing them through
|
||||
pointers. This is consistent throughout the API.
|
||||
|
||||
|
||||
.. c:type:: Py_complex
|
||||
|
||||
The C structure which corresponds to the value portion of a Python complex
|
||||
number object. Most of the functions for dealing with complex number objects
|
||||
use structures of this type as input or output values, as appropriate. It is
|
||||
defined as::
|
||||
|
||||
typedef struct {
|
||||
double real;
|
||||
double imag;
|
||||
} Py_complex;
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
|
||||
|
||||
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
|
||||
|
||||
Return the difference between two complex numbers, using the C
|
||||
:c:type:`Py_complex` representation.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_neg(Py_complex complex)
|
||||
|
||||
Return the negation of the complex number *complex*, using the C
|
||||
:c:type:`Py_complex` representation.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
|
||||
|
||||
Return the product of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
|
||||
|
||||
Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
If *divisor* is null, this method returns zero and sets
|
||||
:c:data:`errno` to :c:data:`EDOM`.
|
||||
|
||||
|
||||
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
|
||||
|
||||
Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
|
||||
representation.
|
||||
|
||||
If *num* is null and *exp* is not a positive real number,
|
||||
this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
|
||||
|
||||
|
||||
Complex Numbers as Python Objects
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
.. c:type:: PyComplexObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python complex number object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyComplex_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python complex number
|
||||
type. It is the same object as :class:`complex` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyComplex_Check(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
|
||||
:c:type:`PyComplexObject`.
|
||||
|
||||
|
||||
.. c:function:: int PyComplex_CheckExact(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
|
||||
:c:type:`PyComplexObject`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
|
||||
|
||||
Create a new Python complex number object from a C :c:type:`Py_complex` value.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
|
||||
|
||||
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
|
||||
|
||||
|
||||
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
|
||||
|
||||
Return the real part of *op* as a C :c:type:`double`.
|
||||
|
||||
|
||||
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
|
||||
|
||||
Return the imaginary part of *op* as a C :c:type:`double`.
|
||||
|
||||
|
||||
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
|
||||
|
||||
Return the :c:type:`Py_complex` value of the complex number *op*.
|
||||
|
||||
If *op* is not a Python complex number object but has a :meth:`__complex__`
|
||||
method, this method will first be called to convert *op* to a Python complex
|
||||
number object. Upon failure, this method returns ``-1.0`` as a real value.
|
|
@ -0,0 +1,116 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
|
||||
.. _concrete:
|
||||
|
||||
**********************
|
||||
Concrete Objects Layer
|
||||
**********************
|
||||
|
||||
The functions in this chapter are specific to certain Python object types.
|
||||
Passing them an object of the wrong type is not a good idea; if you receive an
|
||||
object from a Python program and you are not sure that it has the right type,
|
||||
you must perform a type check first; for example, to check that an object is a
|
||||
dictionary, use :c:func:`PyDict_Check`. The chapter is structured like the
|
||||
"family tree" of Python object types.
|
||||
|
||||
.. warning::
|
||||
|
||||
While the functions described in this chapter carefully check the type of the
|
||||
objects which are passed in, many of them do not check for *NULL* being passed
|
||||
instead of a valid object. Allowing *NULL* to be passed in can cause memory
|
||||
access violations and immediate termination of the interpreter.
|
||||
|
||||
|
||||
.. _fundamental:
|
||||
|
||||
Fundamental Objects
|
||||
===================
|
||||
|
||||
This section describes Python type objects and the singleton object ``None``.
|
||||
|
||||
.. toctree::
|
||||
|
||||
type.rst
|
||||
none.rst
|
||||
|
||||
|
||||
.. _numericobjects:
|
||||
|
||||
Numeric Objects
|
||||
===============
|
||||
|
||||
.. index:: object: numeric
|
||||
|
||||
.. toctree::
|
||||
|
||||
long.rst
|
||||
bool.rst
|
||||
float.rst
|
||||
complex.rst
|
||||
|
||||
|
||||
.. _sequenceobjects:
|
||||
|
||||
Sequence Objects
|
||||
================
|
||||
|
||||
.. index:: object: sequence
|
||||
|
||||
Generic operations on sequence objects were discussed in the previous chapter;
|
||||
this section deals with the specific kinds of sequence objects that are
|
||||
intrinsic to the Python language.
|
||||
|
||||
.. XXX sort out unicode, str, bytes and bytearray
|
||||
|
||||
.. toctree::
|
||||
|
||||
bytes.rst
|
||||
bytearray.rst
|
||||
unicode.rst
|
||||
tuple.rst
|
||||
list.rst
|
||||
|
||||
|
||||
.. _mapobjects:
|
||||
|
||||
Container Objects
|
||||
=================
|
||||
|
||||
.. index:: object: mapping
|
||||
|
||||
.. toctree::
|
||||
|
||||
dict.rst
|
||||
set.rst
|
||||
|
||||
|
||||
.. _otherobjects:
|
||||
|
||||
Function Objects
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
|
||||
function.rst
|
||||
method.rst
|
||||
cell.rst
|
||||
code.rst
|
||||
|
||||
|
||||
Other Objects
|
||||
=============
|
||||
|
||||
.. toctree::
|
||||
|
||||
file.rst
|
||||
module.rst
|
||||
iterator.rst
|
||||
descriptor.rst
|
||||
slice.rst
|
||||
memoryview.rst
|
||||
weakref.rst
|
||||
capsule.rst
|
||||
gen.rst
|
||||
datetime.rst
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _string-conversion:
|
||||
|
||||
String conversion and formatting
|
||||
================================
|
||||
|
||||
Functions for number conversion and formatted string output.
|
||||
|
||||
|
||||
.. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
|
||||
|
||||
Output not more than *size* bytes to *str* according to the format string
|
||||
*format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
|
||||
|
||||
|
||||
.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
|
||||
|
||||
Output not more than *size* bytes to *str* according to the format string
|
||||
*format* and the variable argument list *va*. Unix man page
|
||||
:manpage:`vsnprintf(2)`.
|
||||
|
||||
:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
|
||||
functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
|
||||
guarantee consistent behavior in corner cases, which the Standard C functions do
|
||||
not.
|
||||
|
||||
The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
|
||||
never write more than *size* bytes (including the trailing ``'\0'``) into str.
|
||||
Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
|
||||
NULL``.
|
||||
|
||||
If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
|
||||
avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
|
||||
*Py_FatalError*.
|
||||
|
||||
The return value (*rv*) for these functions should be interpreted as follows:
|
||||
|
||||
* When ``0 <= rv < size``, the output conversion was successful and *rv*
|
||||
characters were written to *str* (excluding the trailing ``'\0'`` byte at
|
||||
*str*[*rv*]).
|
||||
|
||||
* When ``rv >= size``, the output conversion was truncated and a buffer with
|
||||
``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
|
||||
in this case.
|
||||
|
||||
* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
|
||||
this case too, but the rest of *str* is undefined. The exact cause of the error
|
||||
depends on the underlying platform.
|
||||
|
||||
The following functions provide locale-independent string to number conversions.
|
||||
|
||||
|
||||
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
|
||||
|
||||
Convert a string ``s`` to a :c:type:`double`, raising a Python
|
||||
exception on failure. The set of accepted strings corresponds to
|
||||
the set of strings accepted by Python's :func:`float` constructor,
|
||||
except that ``s`` must not have leading or trailing whitespace.
|
||||
The conversion is independent of the current locale.
|
||||
|
||||
If ``endptr`` is ``NULL``, convert the whole string. Raise
|
||||
ValueError and return ``-1.0`` if the string is not a valid
|
||||
representation of a floating-point number.
|
||||
|
||||
If endptr is not ``NULL``, convert as much of the string as
|
||||
possible and set ``*endptr`` to point to the first unconverted
|
||||
character. If no initial segment of the string is the valid
|
||||
representation of a floating-point number, set ``*endptr`` to point
|
||||
to the beginning of the string, raise ValueError, and return
|
||||
``-1.0``.
|
||||
|
||||
If ``s`` represents a value that is too large to store in a float
|
||||
(for example, ``"1e500"`` is such a string on many platforms) then
|
||||
if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
|
||||
an appropriate sign) and don't set any exception. Otherwise,
|
||||
``overflow_exception`` must point to a Python exception object;
|
||||
raise that exception and return ``-1.0``. In both cases, set
|
||||
``*endptr`` to point to the first character after the converted value.
|
||||
|
||||
If any other error occurs during the conversion (for example an
|
||||
out-of-memory error), set the appropriate Python exception and
|
||||
return ``-1.0``.
|
||||
|
||||
.. versionadded:: 3.1
|
||||
|
||||
|
||||
.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
|
||||
|
||||
Convert a :c:type:`double` *val* to a string using supplied
|
||||
*format_code*, *precision*, and *flags*.
|
||||
|
||||
*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
|
||||
``'g'``, ``'G'`` or ``'r'``. For ``'r'``, the supplied *precision*
|
||||
must be 0 and is ignored. The ``'r'`` format code specifies the
|
||||
standard :func:`repr` format.
|
||||
|
||||
*flags* can be zero or more of the values *Py_DTSF_SIGN*,
|
||||
*Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
|
||||
|
||||
* *Py_DTSF_SIGN* means to always precede the returned string with a sign
|
||||
character, even if *val* is non-negative.
|
||||
|
||||
* *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
|
||||
like an integer.
|
||||
|
||||
* *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the
|
||||
documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
|
||||
details.
|
||||
|
||||
If *ptype* is non-NULL, then the value it points to will be set to one of
|
||||
*Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
|
||||
*val* is a finite number, an infinite number, or not a number, respectively.
|
||||
|
||||
The return value is a pointer to *buffer* with the converted string or
|
||||
*NULL* if the conversion failed. The caller is responsible for freeing the
|
||||
returned string by calling :c:func:`PyMem_Free`.
|
||||
|
||||
.. versionadded:: 3.1
|
||||
|
||||
|
||||
.. c:function:: int PyOS_stricmp(char *s1, char *s2)
|
||||
|
||||
Case insensitive comparison of strings. The function works almost
|
||||
identically to :c:func:`strcmp` except that it ignores the case.
|
||||
|
||||
|
||||
.. c:function:: int PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
|
||||
|
||||
Case insensitive comparison of strings. The function works almost
|
||||
identically to :c:func:`strncmp` except that it ignores the case.
|
|
@ -0,0 +1,209 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _datetimeobjects:
|
||||
|
||||
DateTime Objects
|
||||
----------------
|
||||
|
||||
Various date and time objects are supplied by the :mod:`datetime` module.
|
||||
Before using any of these functions, the header file :file:`datetime.h` must be
|
||||
included in your source (note that this is not included by :file:`Python.h`),
|
||||
and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
|
||||
the module initialisation function. The macro puts a pointer to a C structure
|
||||
into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
|
||||
macros.
|
||||
|
||||
Type-check macros:
|
||||
|
||||
.. c:function:: int PyDate_Check(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
|
||||
:c:data:`PyDateTime_DateType`. *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyDate_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_Check(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
|
||||
:c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
|
||||
be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyTime_Check(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
|
||||
:c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyTime_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyDelta_Check(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
|
||||
:c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyDelta_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyTZInfo_Check(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
|
||||
:c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
|
||||
|
||||
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
|
||||
*NULL*.
|
||||
|
||||
|
||||
Macros to create objects:
|
||||
|
||||
.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
|
||||
|
||||
Return a ``datetime.date`` object with the specified year, month and day.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
|
||||
|
||||
Return a ``datetime.datetime`` object with the specified year, month, day, hour,
|
||||
minute, second and microsecond.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
|
||||
|
||||
Return a ``datetime.time`` object with the specified hour, minute, second and
|
||||
microsecond.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
|
||||
|
||||
Return a ``datetime.timedelta`` object representing the given number of days,
|
||||
seconds and microseconds. Normalization is performed so that the resulting
|
||||
number of microseconds and seconds lie in the ranges documented for
|
||||
``datetime.timedelta`` objects.
|
||||
|
||||
|
||||
Macros to extract fields from date objects. The argument must be an instance of
|
||||
:c:data:`PyDateTime_Date`, including subclasses (such as
|
||||
:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is
|
||||
not checked:
|
||||
|
||||
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
|
||||
|
||||
Return the year, as a positive int.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
|
||||
|
||||
Return the month, as an int from 1 through 12.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
|
||||
|
||||
Return the day, as an int from 1 through 31.
|
||||
|
||||
|
||||
Macros to extract fields from datetime objects. The argument must be an
|
||||
instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
|
||||
must not be *NULL*, and the type is not checked:
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
|
||||
|
||||
Return the hour, as an int from 0 through 23.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
|
||||
|
||||
Return the minute, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
|
||||
|
||||
Return the second, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
|
||||
|
||||
Return the microsecond, as an int from 0 through 999999.
|
||||
|
||||
|
||||
Macros to extract fields from time objects. The argument must be an instance of
|
||||
:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
|
||||
and the type is not checked:
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
|
||||
|
||||
Return the hour, as an int from 0 through 23.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
|
||||
|
||||
Return the minute, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
|
||||
|
||||
Return the second, as an int from 0 through 59.
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
|
||||
|
||||
Return the microsecond, as an int from 0 through 999999.
|
||||
|
||||
|
||||
Macros to extract fields from time delta objects. The argument must be an
|
||||
instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
|
||||
not be *NULL*, and the type is not checked:
|
||||
|
||||
.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
|
||||
|
||||
Return the number of days, as an int from -999999999 to 999999999.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
|
||||
|
||||
Return the number of seconds, as an int from 0 through 86399.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: int PyDateTime_DELTA_GET_MICROSECOND(PyDateTime_Delta *o)
|
||||
|
||||
Return the number of microseconds, as an int from 0 through 999999.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
Macros for the convenience of modules implementing the DB API:
|
||||
|
||||
.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
|
||||
|
||||
Create and return a new ``datetime.datetime`` object given an argument tuple
|
||||
suitable for passing to ``datetime.datetime.fromtimestamp()``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
|
||||
|
||||
Create and return a new ``datetime.date`` object given an argument tuple
|
||||
suitable for passing to ``datetime.date.fromtimestamp()``.
|
|
@ -0,0 +1,40 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _descriptor-objects:
|
||||
|
||||
Descriptor Objects
|
||||
------------------
|
||||
|
||||
"Descriptors" are objects that describe some attribute of an object. They are
|
||||
found in the dictionary of type objects.
|
||||
|
||||
.. XXX document these!
|
||||
|
||||
.. c:var:: PyTypeObject PyProperty_Type
|
||||
|
||||
The type object for the built-in descriptor types.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
|
||||
|
||||
|
||||
.. c:function:: int PyDescr_IsData(PyObject *descr)
|
||||
|
||||
Return true if the descriptor objects *descr* describes a data attribute, or
|
||||
false if it describes a method. *descr* must be a descriptor object; there is
|
||||
no error checking.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
|
|
@ -0,0 +1,230 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _dictobjects:
|
||||
|
||||
Dictionary Objects
|
||||
------------------
|
||||
|
||||
.. index:: object: dictionary
|
||||
|
||||
|
||||
.. c:type:: PyDictObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python dictionary object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyDict_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python dictionary
|
||||
type. This is the same object as :class:`dict` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a dict object or an instance of a subtype of the dict
|
||||
type.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a dict object, but not an instance of a subtype of
|
||||
the dict type.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_New()
|
||||
|
||||
Return a new empty dictionary, or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
|
||||
|
||||
Return a :class:`types.MappingProxyType` object for a mapping which
|
||||
enforces read-only behavior. This is normally used to create a view to
|
||||
prevent modification of the dictionary for non-dynamic class types.
|
||||
|
||||
|
||||
.. c:function:: void PyDict_Clear(PyObject *p)
|
||||
|
||||
Empty an existing dictionary of all key-value pairs.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
|
||||
|
||||
Determine if dictionary *p* contains *key*. If an item in *p* is matches
|
||||
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
|
||||
This is equivalent to the Python expression ``key in p``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Copy(PyObject *p)
|
||||
|
||||
Return a new dictionary that contains the same key-value pairs as *p*.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
|
||||
|
||||
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
|
||||
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
|
||||
``0`` on success or ``-1`` on failure.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
|
||||
|
||||
.. index:: single: PyUnicode_FromString()
|
||||
|
||||
Insert *value* into the dictionary *p* using *key* as a key. *key* should
|
||||
be a :c:type:`char\*`. The key object is created using
|
||||
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
|
||||
failure.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
|
||||
|
||||
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
|
||||
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
|
||||
on failure.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
|
||||
|
||||
Remove the entry in dictionary *p* which has a key specified by the string
|
||||
*key*. Return ``0`` on success or ``-1`` on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
|
||||
|
||||
Return the object from dictionary *p* which has a key *key*. Return *NULL*
|
||||
if the key *key* is not present, but *without* setting an exception.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
|
||||
|
||||
Variant of :c:func:`PyDict_GetItem` that does not suppress
|
||||
exceptions. Return *NULL* **with** an exception set if an exception
|
||||
occurred. Return *NULL* **without** an exception set if the key
|
||||
wasn't present.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
|
||||
|
||||
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
|
||||
:c:type:`char\*`, rather than a :c:type:`PyObject\*`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)
|
||||
|
||||
This is the same as the Python-level :meth:`dict.setdefault`. If present, it
|
||||
returns the value corresponding to *key* from the dictionary *p*. If the key
|
||||
is not in the dict, it is inserted with value *defaultobj* and *defaultobj*
|
||||
is returned. This function evaluates the hash function of *key* only once,
|
||||
instead of evaluating it independently for the lookup and the insertion.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Items(PyObject *p)
|
||||
|
||||
Return a :c:type:`PyListObject` containing all the items from the dictionary.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Keys(PyObject *p)
|
||||
|
||||
Return a :c:type:`PyListObject` containing all the keys from the dictionary.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyDict_Values(PyObject *p)
|
||||
|
||||
Return a :c:type:`PyListObject` containing all the values from the dictionary
|
||||
*p*.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Return the number of items in the dictionary. This is equivalent to
|
||||
``len(p)`` on a dictionary.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
|
||||
|
||||
Iterate over all key-value pairs in the dictionary *p*. The
|
||||
:c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
|
||||
prior to the first call to this function to start the iteration; the
|
||||
function returns true for each pair in the dictionary, and false once all
|
||||
pairs have been reported. The parameters *pkey* and *pvalue* should either
|
||||
point to :c:type:`PyObject\*` variables that will be filled in with each key
|
||||
and value, respectively, or may be *NULL*. Any references returned through
|
||||
them are borrowed. *ppos* should not be altered during iteration. Its
|
||||
value represents offsets within the internal dictionary structure, and
|
||||
since the structure is sparse, the offsets are not consecutive.
|
||||
|
||||
For example::
|
||||
|
||||
PyObject *key, *value;
|
||||
Py_ssize_t pos = 0;
|
||||
|
||||
while (PyDict_Next(self->dict, &pos, &key, &value)) {
|
||||
/* do something interesting with the values... */
|
||||
...
|
||||
}
|
||||
|
||||
The dictionary *p* should not be mutated during iteration. It is safe to
|
||||
modify the values of the keys as you iterate over the dictionary, but only
|
||||
so long as the set of keys does not change. For example::
|
||||
|
||||
PyObject *key, *value;
|
||||
Py_ssize_t pos = 0;
|
||||
|
||||
while (PyDict_Next(self->dict, &pos, &key, &value)) {
|
||||
long i = PyLong_AsLong(value);
|
||||
if (i == -1 && PyErr_Occurred()) {
|
||||
return -1;
|
||||
}
|
||||
PyObject *o = PyLong_FromLong(i + 1);
|
||||
if (o == NULL)
|
||||
return -1;
|
||||
if (PyDict_SetItem(self->dict, key, o) < 0) {
|
||||
Py_DECREF(o);
|
||||
return -1;
|
||||
}
|
||||
Py_DECREF(o);
|
||||
}
|
||||
|
||||
|
||||
.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
|
||||
|
||||
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
|
||||
*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
|
||||
and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
|
||||
will be replaced if a matching key is found in *b*, otherwise pairs will
|
||||
only be added if there is not a matching key in *a*. Return ``0`` on
|
||||
success or ``-1`` if an exception was raised.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
|
||||
|
||||
This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
|
||||
``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
|
||||
back to the iterating over a sequence of key value pairs if the second
|
||||
argument has no "keys" attribute. Return ``0`` on success or ``-1`` if an
|
||||
exception was raised.
|
||||
|
||||
|
||||
.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
|
||||
|
||||
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
|
||||
*seq2* must be an iterable object producing iterable objects of length 2,
|
||||
viewed as key-value pairs. In case of duplicate keys, the last wins if
|
||||
*override* is true, else the first wins. Return ``0`` on success or ``-1``
|
||||
if an exception was raised. Equivalent Python (except for the return
|
||||
value)::
|
||||
|
||||
def PyDict_MergeFromSeq2(a, seq2, override):
|
||||
for key, value in seq2:
|
||||
if override or key not in a:
|
||||
a[key] = value
|
||||
|
||||
|
||||
.. c:function:: int PyDict_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
.. versionadded:: 3.3
|
|
@ -0,0 +1,850 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
|
||||
.. _exceptionhandling:
|
||||
|
||||
******************
|
||||
Exception Handling
|
||||
******************
|
||||
|
||||
The functions described in this chapter will let you handle and raise Python
|
||||
exceptions. It is important to understand some of the basics of Python
|
||||
exception handling. It works somewhat like the Unix :c:data:`errno` variable:
|
||||
there is a global indicator (per thread) of the last error that occurred. Most
|
||||
functions don't clear this on success, but will set it to indicate the cause of
|
||||
the error on failure. Most functions also return an error indicator, usually
|
||||
*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
|
||||
integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
|
||||
``0`` for failure).
|
||||
|
||||
When a function must fail because some function it called failed, it generally
|
||||
doesn't set the error indicator; the function it called already set it. It is
|
||||
responsible for either handling the error and clearing the exception or
|
||||
returning after cleaning up any resources it holds (such as object references or
|
||||
memory allocations); it should *not* continue normally if it is not prepared to
|
||||
handle the error. If returning due to an error, it is important to indicate to
|
||||
the caller that an error has been set. If the error is not handled or carefully
|
||||
propagated, additional calls into the Python/C API may not behave as intended
|
||||
and may fail in mysterious ways.
|
||||
|
||||
The error indicator consists of three Python objects corresponding to the result
|
||||
of ``sys.exc_info()``. API functions exist to interact with the error indicator
|
||||
in various ways. There is a separate error indicator for each thread.
|
||||
|
||||
.. XXX Order of these should be more thoughtful.
|
||||
Either alphabetical or some kind of structure.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
|
||||
|
||||
Print a standard traceback to ``sys.stderr`` and clear the error indicator.
|
||||
Call this function only when the error indicator is set. (Otherwise it will
|
||||
cause a fatal error!)
|
||||
|
||||
If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
|
||||
:data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
|
||||
type, value and traceback of the printed exception, respectively.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_Print()
|
||||
|
||||
Alias for ``PyErr_PrintEx(1)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_Occurred()
|
||||
|
||||
Test whether the error indicator is set. If set, return the exception *type*
|
||||
(the first argument to the last call to one of the :c:func:`PyErr_Set\*`
|
||||
functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not
|
||||
own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
|
||||
it.
|
||||
|
||||
.. note::
|
||||
|
||||
Do not compare the return value to a specific exception; use
|
||||
:c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
|
||||
easily fail since the exception may be an instance instead of a class, in the
|
||||
case of a class exception, or it may the a subclass of the expected exception.)
|
||||
|
||||
|
||||
.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
|
||||
|
||||
Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
|
||||
should only be called when an exception is actually set; a memory access
|
||||
violation will occur if no exception has been raised.
|
||||
|
||||
|
||||
.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
|
||||
|
||||
Return true if the *given* exception matches the exception in *exc*. If
|
||||
*exc* is a class object, this also returns true when *given* is an instance
|
||||
of a subclass. If *exc* is a tuple, all exceptions in the tuple (and
|
||||
recursively in subtuples) are searched for a match.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
|
||||
|
||||
Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
|
||||
can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
|
||||
not an instance of the same class. This function can be used to instantiate
|
||||
the class in that case. If the values are already normalized, nothing happens.
|
||||
The delayed normalization is implemented to improve performance.
|
||||
|
||||
.. note::
|
||||
|
||||
This function *does not* implicitly set the ``__traceback__``
|
||||
attribute on the exception value. If setting the traceback
|
||||
appropriately is desired, the following additional snippet is needed::
|
||||
|
||||
if (tb != NULL) {
|
||||
PyException_SetTraceback(val, tb);
|
||||
}
|
||||
|
||||
|
||||
.. c:function:: void PyErr_Clear()
|
||||
|
||||
Clear the error indicator. If the error indicator is not set, there is no
|
||||
effect.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
|
||||
|
||||
Retrieve the error indicator into three variables whose addresses are passed.
|
||||
If the error indicator is not set, set all three variables to *NULL*. If it is
|
||||
set, it will be cleared and you own a reference to each object retrieved. The
|
||||
value and traceback object may be *NULL* even when the type object is not.
|
||||
|
||||
.. note::
|
||||
|
||||
This function is normally only used by code that needs to handle exceptions or
|
||||
by code that needs to save and restore the error indicator temporarily.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
|
||||
|
||||
Set the error indicator from the three objects. If the error indicator is
|
||||
already set, it is cleared first. If the objects are *NULL*, the error
|
||||
indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
|
||||
traceback. The exception type should be a class. Do not pass an invalid
|
||||
exception type or value. (Violating these rules will cause subtle problems
|
||||
later.) This call takes away a reference to each object: you must own a
|
||||
reference to each object before the call and after the call you no longer own
|
||||
these references. (If you don't understand this, don't use this function. I
|
||||
warned you.)
|
||||
|
||||
.. note::
|
||||
|
||||
This function is normally only used by code that needs to save and restore the
|
||||
error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
|
||||
exception state.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
|
||||
|
||||
Retrieve the exception info, as known from ``sys.exc_info()``. This refers
|
||||
to an exception that was already caught, not to an exception that was
|
||||
freshly raised. Returns new references for the three objects, any of which
|
||||
may be *NULL*. Does not modify the exception info state.
|
||||
|
||||
.. note::
|
||||
|
||||
This function is not normally used by code that wants to handle exceptions.
|
||||
Rather, it can be used when code needs to save and restore the exception
|
||||
state temporarily. Use :c:func:`PyErr_SetExcInfo` to restore or clear the
|
||||
exception state.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)
|
||||
|
||||
Set the exception info, as known from ``sys.exc_info()``. This refers
|
||||
to an exception that was already caught, not to an exception that was
|
||||
freshly raised. This function steals the references of the arguments.
|
||||
To clear the exception state, pass *NULL* for all three arguments.
|
||||
For general rules about the three arguments, see :c:func:`PyErr_Restore`.
|
||||
|
||||
.. note::
|
||||
|
||||
This function is not normally used by code that wants to handle exceptions.
|
||||
Rather, it can be used when code needs to save and restore the exception
|
||||
state temporarily. Use :c:func:`PyErr_GetExcInfo` to read the exception
|
||||
state.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
|
||||
|
||||
This is the most common way to set the error indicator. The first argument
|
||||
specifies the exception type; it is normally one of the standard exceptions,
|
||||
e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
|
||||
The second argument is an error message; it is decoded from ``'utf-8``'.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
|
||||
|
||||
This function is similar to :c:func:`PyErr_SetString` but lets you specify an
|
||||
arbitrary Python object for the "value" of the exception.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
|
||||
|
||||
This function sets the error indicator and returns *NULL*. *exception*
|
||||
should be a Python exception class. The *format* and subsequent
|
||||
parameters help format the error message; they have the same meaning and
|
||||
values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoded
|
||||
string.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SetNone(PyObject *type)
|
||||
|
||||
This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
|
||||
|
||||
|
||||
.. c:function:: int PyErr_BadArgument()
|
||||
|
||||
This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
|
||||
*message* indicates that a built-in operation was invoked with an illegal
|
||||
argument. It is mostly for internal use.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_NoMemory()
|
||||
|
||||
This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
|
||||
so an object allocation function can write ``return PyErr_NoMemory();`` when it
|
||||
runs out of memory.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
|
||||
|
||||
.. index:: single: strerror()
|
||||
|
||||
This is a convenience function to raise an exception when a C library function
|
||||
has returned an error and set the C variable :c:data:`errno`. It constructs a
|
||||
tuple object whose first item is the integer :c:data:`errno` value and whose
|
||||
second item is the corresponding error message (gotten from :c:func:`strerror`),
|
||||
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
|
||||
:c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
|
||||
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
|
||||
leaves it set to that. The function always returns *NULL*, so a wrapper
|
||||
function around a system call can write ``return PyErr_SetFromErrno(type);``
|
||||
when the system call returns an error.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
|
||||
*filenameObject* is not *NULL*, it is passed to the constructor of *type* as
|
||||
a third parameter. In the case of :exc:`OSError` exception,
|
||||
this is used to define the :attr:`filename` attribute of the
|
||||
exception instance.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but takes a second
|
||||
filename object, for raising errors when a function that takes two filenames
|
||||
fails.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
|
||||
is given as a C string. *filename* is decoded from the filesystem encoding
|
||||
(:func:`os.fsdecode`).
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
|
||||
|
||||
This is a convenience function to raise :exc:`WindowsError`. If called with
|
||||
*ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
|
||||
is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
|
||||
the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
|
||||
then it constructs a tuple object whose first item is the *ierr* value and whose
|
||||
second item is the corresponding error message (gotten from
|
||||
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
|
||||
object)``. This function always returns *NULL*. Availability: Windows.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
|
||||
specifying the exception type to be raised. Availability: Windows.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
|
||||
filename is given as a C string. *filename* is decoded from the filesystem
|
||||
encoding (:func:`os.fsdecode`). Availability: Windows.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
|
||||
additional parameter specifying the exception type to be raised.
|
||||
Availability: Windows.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
|
||||
|
||||
Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
|
||||
but accepts a second filename object.
|
||||
Availability: Windows.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
|
||||
|
||||
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
|
||||
parameter specifying the exception type to be raised. Availability: Windows.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
|
||||
|
||||
This is a convenience function to raise :exc:`ImportError`. *msg* will be
|
||||
set as the exception's message string. *name* and *path*, both of which can
|
||||
be ``NULL``, will be set as the :exc:`ImportError`'s respective ``name``
|
||||
and ``path`` attributes.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)
|
||||
|
||||
Set file, line, and offset information for the current exception. If the
|
||||
current exception is not a :exc:`SyntaxError`, then it sets additional
|
||||
attributes, which make the exception printing subsystem think the exception
|
||||
is a :exc:`SyntaxError`.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SyntaxLocationEx(char *filename, int lineno, int col_offset)
|
||||
|
||||
Like :c:func:`PyErr_SyntaxLocationObject`, but *filename* is a byte string
|
||||
decoded from the filesystem encoding (:func:`os.fsdecode`).
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SyntaxLocation(char *filename, int lineno)
|
||||
|
||||
Like :c:func:`PyErr_SyntaxLocationEx`, but the col_offset parameter is
|
||||
omitted.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_BadInternalCall()
|
||||
|
||||
This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
|
||||
where *message* indicates that an internal operation (e.g. a Python/C API
|
||||
function) was invoked with an illegal argument. It is mostly for internal
|
||||
use.
|
||||
|
||||
|
||||
.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level)
|
||||
|
||||
Issue a warning message. The *category* argument is a warning category (see
|
||||
below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* is a
|
||||
positive number giving a number of stack frames; the warning will be issued from
|
||||
the currently executing line of code in that stack frame. A *stack_level* of 1
|
||||
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
|
||||
and so forth.
|
||||
|
||||
This function normally prints a warning message to *sys.stderr*; however, it is
|
||||
also possible that the user has specified that warnings are to be turned into
|
||||
errors, and in that case this will raise an exception. It is also possible that
|
||||
the function raises an exception because of a problem with the warning machinery
|
||||
(the implementation imports the :mod:`warnings` module to do the heavy lifting).
|
||||
The return value is ``0`` if no exception is raised, or ``-1`` if an exception
|
||||
is raised. (It is not possible to determine whether a warning message is
|
||||
actually printed, nor what the reason is for the exception; this is
|
||||
intentional.) If an exception is raised, the caller should do its normal
|
||||
exception handling (for example, :c:func:`Py_DECREF` owned references and return
|
||||
an error value).
|
||||
|
||||
Warning categories must be subclasses of :c:data:`Warning`; the default warning
|
||||
category is :c:data:`RuntimeWarning`. The standard Python warning categories are
|
||||
available as global variables whose names are ``PyExc_`` followed by the Python
|
||||
exception name. These have the type :c:type:`PyObject\*`; they are all class
|
||||
objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`,
|
||||
:c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`,
|
||||
:c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and
|
||||
:c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of
|
||||
:c:data:`PyExc_Exception`; the other warning categories are subclasses of
|
||||
:c:data:`PyExc_Warning`.
|
||||
|
||||
For information about warning control, see the documentation for the
|
||||
:mod:`warnings` module and the :option:`-W` option in the command line
|
||||
documentation. There is no C API for warning control.
|
||||
|
||||
|
||||
.. c:function:: int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)
|
||||
|
||||
Issue a warning message with explicit control over all warning attributes. This
|
||||
is a straightforward wrapper around the Python function
|
||||
:func:`warnings.warn_explicit`, see there for more information. The *module*
|
||||
and *registry* arguments may be set to *NULL* to get the default effect
|
||||
described there.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
|
||||
|
||||
Similar to :c:func:`PyErr_WarnExplicitObject` except that *message* and
|
||||
*module* are UTF-8 encoded strings, and *filename* is decoded from the
|
||||
filesystem encoding (:func:`os.fsdecode`).
|
||||
|
||||
|
||||
.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
|
||||
|
||||
Function similar to :c:func:`PyErr_WarnEx`, but use
|
||||
:c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
|
||||
an ASCII-encoded string.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. c:function:: int PyErr_CheckSignals()
|
||||
|
||||
.. index::
|
||||
module: signal
|
||||
single: SIGINT
|
||||
single: KeyboardInterrupt (built-in exception)
|
||||
|
||||
This function interacts with Python's signal handling. It checks whether a
|
||||
signal has been sent to the processes and if so, invokes the corresponding
|
||||
signal handler. If the :mod:`signal` module is supported, this can invoke a
|
||||
signal handler written in Python. In all cases, the default effect for
|
||||
:const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
|
||||
exception is raised the error indicator is set and the function returns ``-1``;
|
||||
otherwise the function returns ``0``. The error indicator may or may not be
|
||||
cleared if it was previously set.
|
||||
|
||||
|
||||
.. c:function:: void PyErr_SetInterrupt()
|
||||
|
||||
.. index::
|
||||
single: SIGINT
|
||||
single: KeyboardInterrupt (built-in exception)
|
||||
|
||||
This function simulates the effect of a :const:`SIGINT` signal arriving --- the
|
||||
next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
|
||||
be raised. It may be called without holding the interpreter lock.
|
||||
|
||||
.. % XXX This was described as obsolete, but is used in
|
||||
.. % _thread.interrupt_main() (used from IDLE), so it's still needed.
|
||||
|
||||
|
||||
.. c:function:: int PySignal_SetWakeupFd(int fd)
|
||||
|
||||
This utility function specifies a file descriptor to which a ``'\0'`` byte will
|
||||
be written whenever a signal is received. It returns the previous such file
|
||||
descriptor. The value ``-1`` disables the feature; this is the initial state.
|
||||
This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
|
||||
error checking. *fd* should be a valid file descriptor. The function should
|
||||
only be called from the main thread.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
|
||||
|
||||
This utility function creates and returns a new exception class. The *name*
|
||||
argument must be the name of the new exception, a C string of the form
|
||||
``module.classname``. The *base* and *dict* arguments are normally *NULL*.
|
||||
This creates a class object derived from :exc:`Exception` (accessible in C as
|
||||
:c:data:`PyExc_Exception`).
|
||||
|
||||
The :attr:`__module__` attribute of the new class is set to the first part (up
|
||||
to the last dot) of the *name* argument, and the class name is set to the last
|
||||
part (after the last dot). The *base* argument can be used to specify alternate
|
||||
base classes; it can either be only one class or a tuple of classes. The *dict*
|
||||
argument can be used to specify a dictionary of class variables and methods.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
|
||||
|
||||
Same as :c:func:`PyErr_NewException`, except that the new exception class can
|
||||
easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
|
||||
docstring for the exception class.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
|
||||
|
||||
This utility function prints a warning message to ``sys.stderr`` when an
|
||||
exception has been set but it is impossible for the interpreter to actually
|
||||
raise the exception. It is used, for example, when an exception occurs in an
|
||||
:meth:`__del__` method.
|
||||
|
||||
The function is called with a single argument *obj* that identifies the context
|
||||
in which the unraisable exception occurred. The repr of *obj* will be printed in
|
||||
the warning message.
|
||||
|
||||
|
||||
Exception Objects
|
||||
=================
|
||||
|
||||
.. c:function:: PyObject* PyException_GetTraceback(PyObject *ex)
|
||||
|
||||
Return the traceback associated with the exception as a new reference, as
|
||||
accessible from Python through :attr:`__traceback__`. If there is no
|
||||
traceback associated, this returns *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyException_SetTraceback(PyObject *ex, PyObject *tb)
|
||||
|
||||
Set the traceback associated with the exception to *tb*. Use ``Py_None`` to
|
||||
clear it.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyException_GetContext(PyObject *ex)
|
||||
|
||||
Return the context (another exception instance during whose handling *ex* was
|
||||
raised) associated with the exception as a new reference, as accessible from
|
||||
Python through :attr:`__context__`. If there is no context associated, this
|
||||
returns *NULL*.
|
||||
|
||||
|
||||
.. c:function:: void PyException_SetContext(PyObject *ex, PyObject *ctx)
|
||||
|
||||
Set the context associated with the exception to *ctx*. Use *NULL* to clear
|
||||
it. There is no type check to make sure that *ctx* is an exception instance.
|
||||
This steals a reference to *ctx*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyException_GetCause(PyObject *ex)
|
||||
|
||||
Return the cause (either an exception instance, or :const:`None`,
|
||||
set by ``raise ... from ...``) associated with the exception as a new
|
||||
reference, as accessible from Python through :attr:`__cause__`.
|
||||
|
||||
|
||||
.. c:function:: void PyException_SetCause(PyObject *ex, PyObject *cause)
|
||||
|
||||
Set the cause associated with the exception to *cause*. Use *NULL* to clear
|
||||
it. There is no type check to make sure that *cause* is either an exception
|
||||
instance or :const:`None`. This steals a reference to *cause*.
|
||||
|
||||
:attr:`__suppress_context__` is implicitly set to ``True`` by this function.
|
||||
|
||||
|
||||
.. _unicodeexceptions:
|
||||
|
||||
Unicode Exception Objects
|
||||
=========================
|
||||
|
||||
The following functions are used to create and modify Unicode exceptions from C.
|
||||
|
||||
.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
|
||||
|
||||
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
|
||||
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
|
||||
UTF-8 encoded strings.
|
||||
|
||||
.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
|
||||
|
||||
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
|
||||
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
|
||||
UTF-8 encoded strings.
|
||||
|
||||
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
|
||||
|
||||
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
|
||||
*length*, *start*, *end* and *reason*. *reason* is an UTF-8 encoded string.
|
||||
|
||||
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
|
||||
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
|
||||
|
||||
Return the *encoding* attribute of the given exception object.
|
||||
|
||||
.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
|
||||
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
|
||||
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
|
||||
|
||||
Return the *object* attribute of the given exception object.
|
||||
|
||||
.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
|
||||
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
|
||||
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
|
||||
|
||||
Get the *start* attribute of the given exception object and place it into
|
||||
*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
|
||||
failure.
|
||||
|
||||
.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
|
||||
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
|
||||
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
|
||||
|
||||
Set the *start* attribute of the given exception object to *start*. Return
|
||||
``0`` on success, ``-1`` on failure.
|
||||
|
||||
.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
|
||||
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
|
||||
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
|
||||
|
||||
Get the *end* attribute of the given exception object and place it into
|
||||
*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
|
||||
failure.
|
||||
|
||||
.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
|
||||
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
|
||||
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
|
||||
|
||||
Set the *end* attribute of the given exception object to *end*. Return ``0``
|
||||
on success, ``-1`` on failure.
|
||||
|
||||
.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
|
||||
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
|
||||
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
|
||||
|
||||
Return the *reason* attribute of the given exception object.
|
||||
|
||||
.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
|
||||
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
|
||||
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
|
||||
|
||||
Set the *reason* attribute of the given exception object to *reason*. Return
|
||||
``0`` on success, ``-1`` on failure.
|
||||
|
||||
|
||||
Recursion Control
|
||||
=================
|
||||
|
||||
These two functions provide a way to perform safe recursive calls at the C
|
||||
level, both in the core and in extension modules. They are needed if the
|
||||
recursive code does not necessarily invoke Python code (which tracks its
|
||||
recursion depth automatically).
|
||||
|
||||
.. c:function:: int Py_EnterRecursiveCall(char *where)
|
||||
|
||||
Marks a point where a recursive C-level call is about to be performed.
|
||||
|
||||
If :const:`USE_STACKCHECK` is defined, this function checks if the OS
|
||||
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
|
||||
sets a :exc:`MemoryError` and returns a nonzero value.
|
||||
|
||||
The function then checks if the recursion limit is reached. If this is the
|
||||
case, a :exc:`RuntimeError` is set and a nonzero value is returned.
|
||||
Otherwise, zero is returned.
|
||||
|
||||
*where* should be a string such as ``" in instance check"`` to be
|
||||
concatenated to the :exc:`RuntimeError` message caused by the recursion depth
|
||||
limit.
|
||||
|
||||
.. c:function:: void Py_LeaveRecursiveCall()
|
||||
|
||||
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
|
||||
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
|
||||
|
||||
Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
|
||||
special recursion handling. In addition to protecting the stack,
|
||||
:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles. The
|
||||
following two functions facilitate this functionality. Effectively,
|
||||
these are the C equivalent to :func:`reprlib.recursive_repr`.
|
||||
|
||||
.. c:function:: int Py_ReprEnter(PyObject *object)
|
||||
|
||||
Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
|
||||
detect cycles.
|
||||
|
||||
If the object has already been processed, the function returns a
|
||||
positive integer. In that case the :c:member:`~PyTypeObject.tp_repr` implementation
|
||||
should return a string object indicating a cycle. As examples,
|
||||
:class:`dict` objects return ``{...}`` and :class:`list` objects
|
||||
return ``[...]``.
|
||||
|
||||
The function will return a negative integer if the recursion limit
|
||||
is reached. In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
|
||||
typically return ``NULL``.
|
||||
|
||||
Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
|
||||
implementation can continue normally.
|
||||
|
||||
.. c:function:: void Py_ReprLeave(PyObject *object)
|
||||
|
||||
Ends a :c:func:`Py_ReprEnter`. Must be called once for each
|
||||
invocation of :c:func:`Py_ReprEnter` that returns zero.
|
||||
|
||||
|
||||
.. _standardexceptions:
|
||||
|
||||
Standard Exceptions
|
||||
===================
|
||||
|
||||
All standard Python exceptions are available as global variables whose names are
|
||||
``PyExc_`` followed by the Python exception name. These have the type
|
||||
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
|
||||
the variables:
|
||||
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| C Name | Python Name | Notes |
|
||||
+=========================================+=================================+==========+
|
||||
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | \(1) |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_OSError` | :exc:`OSError` | \(1) |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
|
||||
+-----------------------------------------+---------------------------------+----------+
|
||||
|
||||
.. versionadded:: 3.3
|
||||
:c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
|
||||
:c:data:`PyExc_ChildProcessError`, :c:data:`PyExc_ConnectionError`,
|
||||
:c:data:`PyExc_ConnectionAbortedError`, :c:data:`PyExc_ConnectionRefusedError`,
|
||||
:c:data:`PyExc_ConnectionResetError`, :c:data:`PyExc_FileExistsError`,
|
||||
:c:data:`PyExc_FileNotFoundError`, :c:data:`PyExc_InterruptedError`,
|
||||
:c:data:`PyExc_IsADirectoryError`, :c:data:`PyExc_NotADirectoryError`,
|
||||
:c:data:`PyExc_PermissionError`, :c:data:`PyExc_ProcessLookupError`
|
||||
and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
|
||||
|
||||
|
||||
These are compatibility aliases to :c:data:`PyExc_OSError`:
|
||||
|
||||
+-------------------------------------+----------+
|
||||
| C Name | Notes |
|
||||
+=====================================+==========+
|
||||
| :c:data:`PyExc_EnvironmentError` | |
|
||||
+-------------------------------------+----------+
|
||||
| :c:data:`PyExc_IOError` | |
|
||||
+-------------------------------------+----------+
|
||||
| :c:data:`PyExc_WindowsError` | \(3) |
|
||||
+-------------------------------------+----------+
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
These aliases used to be separate exception types.
|
||||
|
||||
|
||||
.. index::
|
||||
single: PyExc_BaseException
|
||||
single: PyExc_Exception
|
||||
single: PyExc_ArithmeticError
|
||||
single: PyExc_LookupError
|
||||
single: PyExc_AssertionError
|
||||
single: PyExc_AttributeError
|
||||
single: PyExc_BlockingIOError
|
||||
single: PyExc_BrokenPipeError
|
||||
single: PyExc_ConnectionError
|
||||
single: PyExc_ConnectionAbortedError
|
||||
single: PyExc_ConnectionRefusedError
|
||||
single: PyExc_ConnectionResetError
|
||||
single: PyExc_EOFError
|
||||
single: PyExc_FileExistsError
|
||||
single: PyExc_FileNotFoundError
|
||||
single: PyExc_FloatingPointError
|
||||
single: PyExc_ImportError
|
||||
single: PyExc_IndexError
|
||||
single: PyExc_InterruptedError
|
||||
single: PyExc_IsADirectoryError
|
||||
single: PyExc_KeyError
|
||||
single: PyExc_KeyboardInterrupt
|
||||
single: PyExc_MemoryError
|
||||
single: PyExc_NameError
|
||||
single: PyExc_NotADirectoryError
|
||||
single: PyExc_NotImplementedError
|
||||
single: PyExc_OSError
|
||||
single: PyExc_OverflowError
|
||||
single: PyExc_PermissionError
|
||||
single: PyExc_ProcessLookupError
|
||||
single: PyExc_ReferenceError
|
||||
single: PyExc_RuntimeError
|
||||
single: PyExc_SyntaxError
|
||||
single: PyExc_SystemError
|
||||
single: PyExc_SystemExit
|
||||
single: PyExc_TimeoutError
|
||||
single: PyExc_TypeError
|
||||
single: PyExc_ValueError
|
||||
single: PyExc_ZeroDivisionError
|
||||
single: PyExc_EnvironmentError
|
||||
single: PyExc_IOError
|
||||
single: PyExc_WindowsError
|
||||
|
||||
Notes:
|
||||
|
||||
(1)
|
||||
This is a base class for other standard exceptions.
|
||||
|
||||
(2)
|
||||
This is the same as :exc:`weakref.ReferenceError`.
|
||||
|
||||
(3)
|
||||
Only defined on Windows; protect code that uses this by testing that the
|
||||
preprocessor macro ``MS_WINDOWS`` is defined.
|
|
@ -0,0 +1,76 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _fileobjects:
|
||||
|
||||
File Objects
|
||||
------------
|
||||
|
||||
.. index:: object: file
|
||||
|
||||
These APIs are a minimal emulation of the Python 2 C API for built-in file
|
||||
objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
|
||||
from the C standard library. In Python 3, files and streams use the new
|
||||
:mod:`io` module, which defines several layers over the low-level unbuffered
|
||||
I/O of the operating system. The functions described below are
|
||||
convenience C wrappers over these new APIs, and meant mostly for internal
|
||||
error reporting in the interpreter; third-party code is advised to access
|
||||
the :mod:`io` APIs instead.
|
||||
|
||||
|
||||
.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
|
||||
|
||||
Create a Python file object from the file descriptor of an already
|
||||
opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline*
|
||||
can be *NULL* to use the defaults; *buffering* can be *-1* to use the
|
||||
default. *name* is ignored and kept for backward compatibility. Return
|
||||
*NULL* on failure. For a more comprehensive description of the arguments,
|
||||
please refer to the :func:`io.open` function documentation.
|
||||
|
||||
.. warning::
|
||||
|
||||
Since Python streams have their own buffering layer, mixing them with
|
||||
OS-level file descriptors can produce various issues (such as unexpected
|
||||
ordering of data).
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
Ignore *name* attribute.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
|
||||
|
||||
Return the file descriptor associated with *p* as an :c:type:`int`. If the
|
||||
object is an integer, its value is returned. If not, the
|
||||
object's :meth:`~io.IOBase.fileno` method is called if it exists; the
|
||||
method must return an integer, which is returned as the file descriptor
|
||||
value. Sets an exception and returns ``-1`` on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
|
||||
|
||||
.. index:: single: EOFError (built-in exception)
|
||||
|
||||
Equivalent to ``p.readline([n])``, this function reads one line from the
|
||||
object *p*. *p* may be a file object or any object with a
|
||||
:meth:`~io.IOBase.readline`
|
||||
method. If *n* is ``0``, exactly one line is read, regardless of the length of
|
||||
the line. If *n* is greater than ``0``, no more than *n* bytes will be read
|
||||
from the file; a partial line can be returned. In both cases, an empty string
|
||||
is returned if the end of the file is reached immediately. If *n* is less than
|
||||
``0``, however, one line is read regardless of length, but :exc:`EOFError` is
|
||||
raised if the end of the file is reached immediately.
|
||||
|
||||
|
||||
.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
|
||||
|
||||
.. index:: single: Py_PRINT_RAW
|
||||
|
||||
Write object *obj* to file object *p*. The only supported flag for *flags* is
|
||||
:const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
|
||||
instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
|
||||
appropriate exception will be set.
|
||||
|
||||
|
||||
.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
|
||||
|
||||
Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
|
||||
failure; the appropriate exception will be set.
|
|
@ -0,0 +1,79 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _floatobjects:
|
||||
|
||||
Floating Point Objects
|
||||
----------------------
|
||||
|
||||
.. index:: object: floating point
|
||||
|
||||
|
||||
.. c:type:: PyFloatObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python floating point object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyFloat_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python floating point
|
||||
type. This is the same object as :class:`float` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyFloat_Check(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
|
||||
:c:type:`PyFloatObject`.
|
||||
|
||||
|
||||
.. c:function:: int PyFloat_CheckExact(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
|
||||
:c:type:`PyFloatObject`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFloat_FromString(PyObject *str)
|
||||
|
||||
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFloat_FromDouble(double v)
|
||||
|
||||
Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
|
||||
|
||||
Return a C :c:type:`double` representation of the contents of *pyfloat*. If
|
||||
*pyfloat* is not a Python floating point object but has a :meth:`__float__`
|
||||
method, this method will first be called to convert *pyfloat* into a float.
|
||||
This method returns ``-1.0`` upon failure, so one should call
|
||||
:c:func:`PyErr_Occurred` to check for errors.
|
||||
|
||||
|
||||
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
|
||||
|
||||
Return a C :c:type:`double` representation of the contents of *pyfloat*, but
|
||||
without error checking.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFloat_GetInfo(void)
|
||||
|
||||
Return a structseq instance which contains information about the
|
||||
precision, minimum and maximum values of a float. It's a thin wrapper
|
||||
around the header file :file:`float.h`.
|
||||
|
||||
|
||||
.. c:function:: double PyFloat_GetMax()
|
||||
|
||||
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
|
||||
|
||||
|
||||
.. c:function:: double PyFloat_GetMin()
|
||||
|
||||
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
|
||||
|
||||
.. c:function:: int PyFloat_ClearFreeList()
|
||||
|
||||
Clear the float free list. Return the number of items that could not
|
||||
be freed.
|
|
@ -0,0 +1,107 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _function-objects:
|
||||
|
||||
Function Objects
|
||||
----------------
|
||||
|
||||
.. index:: object: function
|
||||
|
||||
There are a few functions specific to Python functions.
|
||||
|
||||
|
||||
.. c:type:: PyFunctionObject
|
||||
|
||||
The C structure used for functions.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyFunction_Type
|
||||
|
||||
.. index:: single: MethodType (in module types)
|
||||
|
||||
This is an instance of :c:type:`PyTypeObject` and represents the Python function
|
||||
type. It is exposed to Python programmers as ``types.FunctionType``.
|
||||
|
||||
|
||||
.. c:function:: int PyFunction_Check(PyObject *o)
|
||||
|
||||
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
|
||||
The parameter must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
|
||||
|
||||
Return a new function object associated with the code object *code*. *globals*
|
||||
must be a dictionary with the global variables accessible to the function.
|
||||
|
||||
The function's docstring, name and *__module__* are retrieved from the code
|
||||
object, the argument defaults and closure are set to *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
|
||||
|
||||
As :c:func:`PyFunction_New`, but also allows to set the function object's
|
||||
``__qualname__`` attribute. *qualname* should be a unicode object or NULL;
|
||||
if NULL, the ``__qualname__`` attribute is set to the same value as its
|
||||
``__name__`` attribute.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
|
||||
|
||||
Return the code object associated with the function object *op*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
|
||||
|
||||
Return the globals dictionary associated with the function object *op*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
|
||||
|
||||
Return the *__module__* attribute of the function object *op*. This is normally
|
||||
a string containing the module name, but can be set to any other object by
|
||||
Python code.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
|
||||
|
||||
Return the argument default values of the function object *op*. This can be a
|
||||
tuple of arguments or *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
|
||||
|
||||
Set the argument default values for the function object *op*. *defaults* must be
|
||||
*Py_None* or a tuple.
|
||||
|
||||
Raises :exc:`SystemError` and returns ``-1`` on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
|
||||
|
||||
Return the closure associated with the function object *op*. This can be *NULL*
|
||||
or a tuple of cell objects.
|
||||
|
||||
|
||||
.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
|
||||
|
||||
Set the closure associated with the function object *op*. *closure* must be
|
||||
*Py_None* or a tuple of cell objects.
|
||||
|
||||
Raises :exc:`SystemError` and returns ``-1`` on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
|
||||
|
||||
Return the annotations of the function object *op*. This can be a
|
||||
mutable dictionary or *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
|
||||
|
||||
Set the annotations for the function object *op*. *annotations*
|
||||
must be a dictionary or *Py_None*.
|
||||
|
||||
Raises :exc:`SystemError` and returns ``-1`` on failure.
|
|
@ -0,0 +1,152 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _supporting-cycle-detection:
|
||||
|
||||
Supporting Cyclic Garbage Collection
|
||||
====================================
|
||||
|
||||
Python's support for detecting and collecting garbage which involves circular
|
||||
references requires support from object types which are "containers" for other
|
||||
objects which may also be containers. Types which do not store references to
|
||||
other objects, or which only store references to atomic types (such as numbers
|
||||
or strings), do not need to provide any explicit support for garbage
|
||||
collection.
|
||||
|
||||
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
|
||||
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
|
||||
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
|
||||
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
|
||||
|
||||
|
||||
.. data:: Py_TPFLAGS_HAVE_GC
|
||||
:noindex:
|
||||
|
||||
Objects with a type with this flag set must conform with the rules
|
||||
documented here. For convenience these objects will be referred to as
|
||||
container objects.
|
||||
|
||||
Constructors for container types must conform to two rules:
|
||||
|
||||
#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
|
||||
or :c:func:`PyObject_GC_NewVar`.
|
||||
|
||||
#. Once all the fields which may contain references to other containers are
|
||||
initialized, it must call :c:func:`PyObject_GC_Track`.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
|
||||
|
||||
Analogous to :c:func:`PyObject_New` but for container objects with the
|
||||
:const:`Py_TPFLAGS_HAVE_GC` flag set.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
|
||||
|
||||
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
|
||||
:const:`Py_TPFLAGS_HAVE_GC` flag set.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
|
||||
|
||||
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
|
||||
resized object or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: void PyObject_GC_Track(PyObject *op)
|
||||
|
||||
Adds the object *op* to the set of container objects tracked by the
|
||||
collector. The collector can run at unexpected times so objects must be
|
||||
valid while being tracked. This should be called once all the fields
|
||||
followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
|
||||
end of the constructor.
|
||||
|
||||
|
||||
.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
|
||||
|
||||
A macro version of :c:func:`PyObject_GC_Track`. It should not be used for
|
||||
extension modules.
|
||||
|
||||
Similarly, the deallocator for the object must conform to a similar pair of
|
||||
rules:
|
||||
|
||||
#. Before fields which refer to other containers are invalidated,
|
||||
:c:func:`PyObject_GC_UnTrack` must be called.
|
||||
|
||||
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
|
||||
|
||||
|
||||
.. c:function:: void PyObject_GC_Del(void *op)
|
||||
|
||||
Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
|
||||
:c:func:`PyObject_GC_NewVar`.
|
||||
|
||||
|
||||
.. c:function:: void PyObject_GC_UnTrack(void *op)
|
||||
|
||||
Remove the object *op* from the set of container objects tracked by the
|
||||
collector. Note that :c:func:`PyObject_GC_Track` can be called again on
|
||||
this object to add it back to the set of tracked objects. The deallocator
|
||||
(:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
|
||||
the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
|
||||
|
||||
|
||||
.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
|
||||
|
||||
A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for
|
||||
extension modules.
|
||||
|
||||
The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
|
||||
|
||||
|
||||
.. c:type:: int (*visitproc)(PyObject *object, void *arg)
|
||||
|
||||
Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
|
||||
The function should be called with an object to traverse as *object* and
|
||||
the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The
|
||||
Python core uses several visitor functions to implement cyclic garbage
|
||||
detection; it's not expected that users will need to write their own
|
||||
visitor functions.
|
||||
|
||||
The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
|
||||
|
||||
|
||||
.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
|
||||
|
||||
Traversal function for a container object. Implementations must call the
|
||||
*visit* function for each object directly contained by *self*, with the
|
||||
parameters to *visit* being the contained object and the *arg* value passed
|
||||
to the handler. The *visit* function must not be called with a *NULL*
|
||||
object argument. If *visit* returns a non-zero value that value should be
|
||||
returned immediately.
|
||||
|
||||
To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
|
||||
provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
|
||||
must name its arguments exactly *visit* and *arg*:
|
||||
|
||||
|
||||
.. c:function:: void Py_VISIT(PyObject *o)
|
||||
|
||||
Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
|
||||
a non-zero value, then return it. Using this macro, :c:member:`~PyTypeObject.tp_traverse`
|
||||
handlers look like::
|
||||
|
||||
static int
|
||||
my_traverse(Noddy *self, visitproc visit, void *arg)
|
||||
{
|
||||
Py_VISIT(self->foo);
|
||||
Py_VISIT(self->bar);
|
||||
return 0;
|
||||
}
|
||||
|
||||
The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
|
||||
if the object is immutable.
|
||||
|
||||
|
||||
.. c:type:: int (*inquiry)(PyObject *self)
|
||||
|
||||
Drop references that may have created reference cycles. Immutable objects
|
||||
do not have to define this method since they can never directly create
|
||||
reference cycles. Note that the object must still be valid after calling
|
||||
this method (don't just call :c:func:`Py_DECREF` on a reference). The
|
||||
collector will call this method if it detects that this object is involved
|
||||
in a reference cycle.
|
|
@ -0,0 +1,38 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _gen-objects:
|
||||
|
||||
Generator Objects
|
||||
-----------------
|
||||
|
||||
Generator objects are what Python uses to implement generator iterators. They
|
||||
are normally created by iterating over a function that yields values, rather
|
||||
than explicitly calling :c:func:`PyGen_New`.
|
||||
|
||||
|
||||
.. c:type:: PyGenObject
|
||||
|
||||
The C structure used for generator objects.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyGen_Type
|
||||
|
||||
The type object corresponding to generator objects
|
||||
|
||||
|
||||
.. c:function:: int PyGen_Check(ob)
|
||||
|
||||
Return true if *ob* is a generator object; *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: int PyGen_CheckExact(ob)
|
||||
|
||||
Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
|
||||
be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
|
||||
|
||||
Create and return a new generator object based on the *frame* object. A
|
||||
reference to *frame* is stolen by this function. The parameter must not be
|
||||
*NULL*.
|
|
@ -0,0 +1,314 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _importing:
|
||||
|
||||
Importing Modules
|
||||
=================
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModule(const char *name)
|
||||
|
||||
.. index::
|
||||
single: package variable; __all__
|
||||
single: __all__ (package variable)
|
||||
single: modules (in module sys)
|
||||
|
||||
This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
|
||||
leaving the *globals* and *locals* arguments set to *NULL* and *level* set
|
||||
to 0. When the *name*
|
||||
argument contains a dot (when it specifies a submodule of a package), the
|
||||
*fromlist* argument is set to the list ``['*']`` so that the return value is the
|
||||
named module rather than the top-level package containing it as would otherwise
|
||||
be the case. (Unfortunately, this has an additional side effect when *name* in
|
||||
fact specifies a subpackage instead of a submodule: the submodules specified in
|
||||
the package's ``__all__`` variable are loaded.) Return a new reference to the
|
||||
imported module, or *NULL* with an exception set on failure. A failing
|
||||
import of a module doesn't leave the module in :data:`sys.modules`.
|
||||
|
||||
This function always uses absolute imports.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
|
||||
|
||||
This function is a deprecated alias of :c:func:`PyImport_ImportModule`.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
This function used to fail immediately when the import lock was held
|
||||
by another thread. In Python 3.3 though, the locking scheme switched
|
||||
to per-module locks for most purposes, so this function's special
|
||||
behaviour isn't needed anymore.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
|
||||
|
||||
.. index:: builtin: __import__
|
||||
|
||||
Import a module. This is best described by referring to the built-in Python
|
||||
function :func:`__import__`.
|
||||
|
||||
The return value is a new reference to the imported module or top-level
|
||||
package, or *NULL* with an exception set on failure. Like for
|
||||
:func:`__import__`, the return value when a submodule of a package was
|
||||
requested is normally the top-level package, unless a non-empty *fromlist*
|
||||
was given.
|
||||
|
||||
Failing imports remove incomplete module objects, like with
|
||||
:c:func:`PyImport_ImportModule`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
|
||||
|
||||
Import a module. This is best described by referring to the built-in Python
|
||||
function :func:`__import__`, as the standard :func:`__import__` function calls
|
||||
this function directly.
|
||||
|
||||
The return value is a new reference to the imported module or top-level package,
|
||||
or *NULL* with an exception set on failure. Like for :func:`__import__`,
|
||||
the return value when a submodule of a package was requested is normally the
|
||||
top-level package, unless a non-empty *fromlist* was given.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
|
||||
|
||||
Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is an
|
||||
UTF-8 encoded string instead of a Unicode object.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Negative values for *level* are no longer accepted.
|
||||
|
||||
.. c:function:: PyObject* PyImport_Import(PyObject *name)
|
||||
|
||||
This is a higher-level interface that calls the current "import hook
|
||||
function" (with an explicit *level* of 0, meaning absolute import). It
|
||||
invokes the :func:`__import__` function from the ``__builtins__`` of the
|
||||
current globals. This means that the import is done using whatever import
|
||||
hooks are installed in the current environment.
|
||||
|
||||
This function always uses absolute imports.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
|
||||
|
||||
Reload a module. Return a new reference to the reloaded module, or *NULL* with
|
||||
an exception set on failure (the module still exists in this case).
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
|
||||
|
||||
Return the module object corresponding to a module name. The *name* argument
|
||||
may be of the form ``package.module``. First check the modules dictionary if
|
||||
there's one there, and if not, create a new one and insert it in the modules
|
||||
dictionary. Return *NULL* with an exception set on failure.
|
||||
|
||||
.. note::
|
||||
|
||||
This function does not load or import the module; if the module wasn't already
|
||||
loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
|
||||
or one of its variants to import a module. Package structures implied by a
|
||||
dotted name for *name* are not created if not already present.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_AddModule(const char *name)
|
||||
|
||||
Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8
|
||||
encoded string instead of a Unicode object.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
|
||||
|
||||
.. index:: builtin: compile
|
||||
|
||||
Given a module name (possibly of the form ``package.module``) and a code object
|
||||
read from a Python bytecode file or obtained from the built-in function
|
||||
:func:`compile`, load the module. Return a new reference to the module object,
|
||||
or *NULL* with an exception set if an error occurred. *name*
|
||||
is removed from :attr:`sys.modules` in error cases, even if *name* was already
|
||||
in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
|
||||
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
|
||||
such modules have no way to know that the module object is an unknown (and
|
||||
probably damaged with respect to the module author's intents) state.
|
||||
|
||||
The module's :attr:`__file__` attribute will be set to the code object's
|
||||
:c:member:`co_filename`.
|
||||
|
||||
This function will reload the module if it was already imported. See
|
||||
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
|
||||
|
||||
If *name* points to a dotted name of the form ``package.module``, any package
|
||||
structures not already created will still not be created.
|
||||
|
||||
See also :c:func:`PyImport_ExecCodeModuleEx` and
|
||||
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
|
||||
|
||||
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
|
||||
the module object is set to *pathname* if it is non-``NULL``.
|
||||
|
||||
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
|
||||
|
||||
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
|
||||
attribute of the module object is set to *cpathname* if it is
|
||||
non-``NULL``. Of the three functions, this is the preferred one to use.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
|
||||
|
||||
Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and
|
||||
*cpathname* are UTF-8 encoded strings. Attempts are also made to figure out
|
||||
what the value for *pathname* should be from *cpathname* if the former is
|
||||
set to ``NULL``.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
.. versionchanged:: 3.3
|
||||
Uses :func:`imp.source_from_cache()` in calculating the source path if
|
||||
only the bytecode path is provided.
|
||||
|
||||
|
||||
.. c:function:: long PyImport_GetMagicNumber()
|
||||
|
||||
Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
|
||||
:file:`.pyo` files). The magic number should be present in the first four bytes
|
||||
of the bytecode file, in little-endian byte order. Returns -1 on error.
|
||||
|
||||
.. versionchanged:: 3.3
|
||||
Return value of -1 upon failure.
|
||||
|
||||
|
||||
.. c:function:: const char * PyImport_GetMagicTag()
|
||||
|
||||
Return the magic tag string for :pep:`3147` format Python bytecode file
|
||||
names. Keep in mind that the value at ``sys.implementation.cache_tag`` is
|
||||
authoritative and should be used instead of this function.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: PyObject* PyImport_GetModuleDict()
|
||||
|
||||
Return the dictionary used for the module administration (a.k.a.
|
||||
``sys.modules``). Note that this is a per-interpreter variable.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
|
||||
|
||||
Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item
|
||||
*path*, possibly by fetching it from the :data:`sys.path_importer_cache`
|
||||
dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
|
||||
is found that can handle the path item. Return ``None`` if no hook could;
|
||||
this tells our caller it should fall back to the built-in import mechanism.
|
||||
Cache the result in :data:`sys.path_importer_cache`. Return a new reference
|
||||
to the importer object.
|
||||
|
||||
|
||||
.. c:function:: void _PyImport_Init()
|
||||
|
||||
Initialize the import mechanism. For internal use only.
|
||||
|
||||
|
||||
.. c:function:: void PyImport_Cleanup()
|
||||
|
||||
Empty the module table. For internal use only.
|
||||
|
||||
|
||||
.. c:function:: void _PyImport_Fini()
|
||||
|
||||
Finalize the import mechanism. For internal use only.
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
|
||||
|
||||
For internal use only.
|
||||
|
||||
|
||||
.. c:function:: PyObject* _PyImport_FixupExtension(char *, char *)
|
||||
|
||||
For internal use only.
|
||||
|
||||
|
||||
.. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
|
||||
|
||||
Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
|
||||
module is not found, and ``-1`` with an exception set if the initialization
|
||||
failed. To access the imported module on a successful load, use
|
||||
:c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would
|
||||
reload the module if it was already imported.)
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The ``__file__`` attribute is no longer set on the module.
|
||||
|
||||
|
||||
.. c:function:: int PyImport_ImportFrozenModule(const char *name)
|
||||
|
||||
Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a
|
||||
UTF-8 encoded string instead of a Unicode object.
|
||||
|
||||
|
||||
.. c:type:: struct _frozen
|
||||
|
||||
.. index:: single: freeze utility
|
||||
|
||||
This is the structure type definition for frozen module descriptors, as
|
||||
generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
|
||||
Python source distribution). Its definition, found in :file:`Include/import.h`,
|
||||
is::
|
||||
|
||||
struct _frozen {
|
||||
char *name;
|
||||
unsigned char *code;
|
||||
int size;
|
||||
};
|
||||
|
||||
|
||||
.. c:var:: struct _frozen* PyImport_FrozenModules
|
||||
|
||||
This pointer is initialized to point to an array of :c:type:`struct _frozen`
|
||||
records, terminated by one whose members are all *NULL* or zero. When a frozen
|
||||
module is imported, it is searched in this table. Third-party code could play
|
||||
tricks with this to provide a dynamically created collection of frozen modules.
|
||||
|
||||
|
||||
.. c:function:: int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))
|
||||
|
||||
Add a single module to the existing table of built-in modules. This is a
|
||||
convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if
|
||||
the table could not be extended. The new module can be imported by the name
|
||||
*name*, and uses the function *initfunc* as the initialization function called
|
||||
on the first attempted import. This should be called before
|
||||
:c:func:`Py_Initialize`.
|
||||
|
||||
|
||||
.. c:type:: struct _inittab
|
||||
|
||||
Structure describing a single entry in the list of built-in modules. Each of
|
||||
these structures gives the name and initialization function for a module built
|
||||
into the interpreter. The name is an ASCII encoded string. Programs which
|
||||
embed Python may use an array of these structures in conjunction with
|
||||
:c:func:`PyImport_ExtendInittab` to provide additional built-in modules.
|
||||
The structure is defined in :file:`Include/import.h` as::
|
||||
|
||||
struct _inittab {
|
||||
char *name; /* ASCII encoded string */
|
||||
PyObject* (*initfunc)(void);
|
||||
};
|
||||
|
||||
|
||||
.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
|
||||
|
||||
Add a collection of modules to the table of built-in modules. The *newtab*
|
||||
array must end with a sentinel entry which contains *NULL* for the :attr:`name`
|
||||
field; failure to provide the sentinel value can result in a memory fault.
|
||||
Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
|
||||
extend the internal table. In the event of failure, no modules are added to the
|
||||
internal table. This should be called before :c:func:`Py_Initialize`.
|
|
@ -0,0 +1,26 @@
|
|||
.. _c-api-index:
|
||||
|
||||
##################################
|
||||
Python/C API Reference Manual
|
||||
##################################
|
||||
|
||||
This manual documents the API used by C and C++ programmers who want to write
|
||||
extension modules or embed Python. It is a companion to :ref:`extending-index`,
|
||||
which describes the general principles of extension writing but does not
|
||||
document the API functions in detail.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
intro.rst
|
||||
stable.rst
|
||||
veryhigh.rst
|
||||
refcounting.rst
|
||||
exceptions.rst
|
||||
utilities.rst
|
||||
abstract.rst
|
||||
concrete.rst
|
||||
init.rst
|
||||
memory.rst
|
||||
objimpl.rst
|
||||
apiabiversion.rst
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,644 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
|
||||
.. _api-intro:
|
||||
|
||||
************
|
||||
Introduction
|
||||
************
|
||||
|
||||
The Application Programmer's Interface to Python gives C and C++ programmers
|
||||
access to the Python interpreter at a variety of levels. The API is equally
|
||||
usable from C++, but for brevity it is generally referred to as the Python/C
|
||||
API. There are two fundamentally different reasons for using the Python/C API.
|
||||
The first reason is to write *extension modules* for specific purposes; these
|
||||
are C modules that extend the Python interpreter. This is probably the most
|
||||
common use. The second reason is to use Python as a component in a larger
|
||||
application; this technique is generally referred to as :dfn:`embedding` Python
|
||||
in an application.
|
||||
|
||||
Writing an extension module is a relatively well-understood process, where a
|
||||
"cookbook" approach works well. There are several tools that automate the
|
||||
process to some extent. While people have embedded Python in other
|
||||
applications since its early existence, the process of embedding Python is less
|
||||
straightforward than writing an extension.
|
||||
|
||||
Many API functions are useful independent of whether you're embedding or
|
||||
extending Python; moreover, most applications that embed Python will need to
|
||||
provide a custom extension as well, so it's probably a good idea to become
|
||||
familiar with writing an extension before attempting to embed Python in a real
|
||||
application.
|
||||
|
||||
|
||||
.. _api-includes:
|
||||
|
||||
Include Files
|
||||
=============
|
||||
|
||||
All function, type and macro definitions needed to use the Python/C API are
|
||||
included in your code by the following line::
|
||||
|
||||
#include "Python.h"
|
||||
|
||||
This implies inclusion of the following standard headers: ``<stdio.h>``,
|
||||
``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
|
||||
(if available).
|
||||
|
||||
.. note::
|
||||
|
||||
Since Python may define some pre-processor definitions which affect the standard
|
||||
headers on some systems, you *must* include :file:`Python.h` before any standard
|
||||
headers are included.
|
||||
|
||||
All user visible names defined by Python.h (except those defined by the included
|
||||
standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning
|
||||
with ``_Py`` are for internal use by the Python implementation and should not be
|
||||
used by extension writers. Structure member names do not have a reserved prefix.
|
||||
|
||||
**Important:** user code should never define names that begin with ``Py`` or
|
||||
``_Py``. This confuses the reader, and jeopardizes the portability of the user
|
||||
code to future Python versions, which may define additional names beginning with
|
||||
one of these prefixes.
|
||||
|
||||
The header files are typically installed with Python. On Unix, these are
|
||||
located in the directories :file:`{prefix}/include/pythonversion/` and
|
||||
:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
|
||||
:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
|
||||
:program:`configure` script and *version* is ``sys.version[:3]``. On Windows,
|
||||
the headers are installed in :file:`{prefix}/include`, where :envvar:`prefix` is
|
||||
the installation directory specified to the installer.
|
||||
|
||||
To include the headers, place both directories (if different) on your compiler's
|
||||
search path for includes. Do *not* place the parent directories on the search
|
||||
path and then use ``#include <pythonX.Y/Python.h>``; this will break on
|
||||
multi-platform builds since the platform independent headers under
|
||||
:envvar:`prefix` include the platform specific headers from
|
||||
:envvar:`exec_prefix`.
|
||||
|
||||
C++ users should note that though the API is defined entirely using C, the
|
||||
header files do properly declare the entry points to be ``extern "C"``, so there
|
||||
is no need to do anything special to use the API from C++.
|
||||
|
||||
|
||||
.. _api-objects:
|
||||
|
||||
Objects, Types and Reference Counts
|
||||
===================================
|
||||
|
||||
.. index:: object: type
|
||||
|
||||
Most Python/C API functions have one or more arguments as well as a return value
|
||||
of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type
|
||||
representing an arbitrary Python object. Since all Python object types are
|
||||
treated the same way by the Python language in most situations (e.g.,
|
||||
assignments, scope rules, and argument passing), it is only fitting that they
|
||||
should be represented by a single C type. Almost all Python objects live on the
|
||||
heap: you never declare an automatic or static variable of type
|
||||
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be
|
||||
declared. The sole exception are the type objects; since these must never be
|
||||
deallocated, they are typically static :c:type:`PyTypeObject` objects.
|
||||
|
||||
All Python objects (even Python integers) have a :dfn:`type` and a
|
||||
:dfn:`reference count`. An object's type determines what kind of object it is
|
||||
(e.g., an integer, a list, or a user-defined function; there are many more as
|
||||
explained in :ref:`types`). For each of the well-known types there is a macro
|
||||
to check whether an object is of that type; for instance, ``PyList_Check(a)`` is
|
||||
true if (and only if) the object pointed to by *a* is a Python list.
|
||||
|
||||
|
||||
.. _api-refcounts:
|
||||
|
||||
Reference Counts
|
||||
----------------
|
||||
|
||||
The reference count is important because today's computers have a finite (and
|
||||
often severely limited) memory size; it counts how many different places there
|
||||
are that have a reference to an object. Such a place could be another object,
|
||||
or a global (or static) C variable, or a local variable in some C function.
|
||||
When an object's reference count becomes zero, the object is deallocated. If
|
||||
it contains references to other objects, their reference count is decremented.
|
||||
Those other objects may be deallocated in turn, if this decrement makes their
|
||||
reference count become zero, and so on. (There's an obvious problem with
|
||||
objects that reference each other here; for now, the solution is "don't do
|
||||
that.")
|
||||
|
||||
.. index::
|
||||
single: Py_INCREF()
|
||||
single: Py_DECREF()
|
||||
|
||||
Reference counts are always manipulated explicitly. The normal way is to use
|
||||
the macro :c:func:`Py_INCREF` to increment an object's reference count by one,
|
||||
and :c:func:`Py_DECREF` to decrement it by one. The :c:func:`Py_DECREF` macro
|
||||
is considerably more complex than the incref one, since it must check whether
|
||||
the reference count becomes zero and then cause the object's deallocator to be
|
||||
called. The deallocator is a function pointer contained in the object's type
|
||||
structure. The type-specific deallocator takes care of decrementing the
|
||||
reference counts for other objects contained in the object if this is a compound
|
||||
object type, such as a list, as well as performing any additional finalization
|
||||
that's needed. There's no chance that the reference count can overflow; at
|
||||
least as many bits are used to hold the reference count as there are distinct
|
||||
memory locations in virtual memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``).
|
||||
Thus, the reference count increment is a simple operation.
|
||||
|
||||
It is not necessary to increment an object's reference count for every local
|
||||
variable that contains a pointer to an object. In theory, the object's
|
||||
reference count goes up by one when the variable is made to point to it and it
|
||||
goes down by one when the variable goes out of scope. However, these two
|
||||
cancel each other out, so at the end the reference count hasn't changed. The
|
||||
only real reason to use the reference count is to prevent the object from being
|
||||
deallocated as long as our variable is pointing to it. If we know that there
|
||||
is at least one other reference to the object that lives at least as long as
|
||||
our variable, there is no need to increment the reference count temporarily.
|
||||
An important situation where this arises is in objects that are passed as
|
||||
arguments to C functions in an extension module that are called from Python;
|
||||
the call mechanism guarantees to hold a reference to every argument for the
|
||||
duration of the call.
|
||||
|
||||
However, a common pitfall is to extract an object from a list and hold on to it
|
||||
for a while without incrementing its reference count. Some other operation might
|
||||
conceivably remove the object from the list, decrementing its reference count
|
||||
and possible deallocating it. The real danger is that innocent-looking
|
||||
operations may invoke arbitrary Python code which could do this; there is a code
|
||||
path which allows control to flow back to the user from a :c:func:`Py_DECREF`, so
|
||||
almost any operation is potentially dangerous.
|
||||
|
||||
A safe approach is to always use the generic operations (functions whose name
|
||||
begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).
|
||||
These operations always increment the reference count of the object they return.
|
||||
This leaves the caller with the responsibility to call :c:func:`Py_DECREF` when
|
||||
they are done with the result; this soon becomes second nature.
|
||||
|
||||
|
||||
.. _api-refcountdetails:
|
||||
|
||||
Reference Count Details
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The reference count behavior of functions in the Python/C API is best explained
|
||||
in terms of *ownership of references*. Ownership pertains to references, never
|
||||
to objects (objects are not owned: they are always shared). "Owning a
|
||||
reference" means being responsible for calling Py_DECREF on it when the
|
||||
reference is no longer needed. Ownership can also be transferred, meaning that
|
||||
the code that receives ownership of the reference then becomes responsible for
|
||||
eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`
|
||||
when it's no longer needed---or passing on this responsibility (usually to its
|
||||
caller). When a function passes ownership of a reference on to its caller, the
|
||||
caller is said to receive a *new* reference. When no ownership is transferred,
|
||||
the caller is said to *borrow* the reference. Nothing needs to be done for a
|
||||
borrowed reference.
|
||||
|
||||
Conversely, when a calling function passes in a reference to an object, there
|
||||
are two possibilities: the function *steals* a reference to the object, or it
|
||||
does not. *Stealing a reference* means that when you pass a reference to a
|
||||
function, that function assumes that it now owns that reference, and you are not
|
||||
responsible for it any longer.
|
||||
|
||||
.. index::
|
||||
single: PyList_SetItem()
|
||||
single: PyTuple_SetItem()
|
||||
|
||||
Few functions steal references; the two notable exceptions are
|
||||
:c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference
|
||||
to the item (but not to the tuple or list into which the item is put!). These
|
||||
functions were designed to steal a reference because of a common idiom for
|
||||
populating a tuple or list with newly created objects; for example, the code to
|
||||
create the tuple ``(1, 2, "three")`` could look like this (forgetting about
|
||||
error handling for the moment; a better way to code this is shown below)::
|
||||
|
||||
PyObject *t;
|
||||
|
||||
t = PyTuple_New(3);
|
||||
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
|
||||
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
|
||||
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));
|
||||
|
||||
Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately
|
||||
stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object
|
||||
although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab
|
||||
another reference before calling the reference-stealing function.
|
||||
|
||||
Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple items;
|
||||
:c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to do this
|
||||
since tuples are an immutable data type. You should only use
|
||||
:c:func:`PyTuple_SetItem` for tuples that you are creating yourself.
|
||||
|
||||
Equivalent code for populating a list can be written using :c:func:`PyList_New`
|
||||
and :c:func:`PyList_SetItem`.
|
||||
|
||||
However, in practice, you will rarely use these ways of creating and populating
|
||||
a tuple or list. There's a generic function, :c:func:`Py_BuildValue`, that can
|
||||
create most common objects from C values, directed by a :dfn:`format string`.
|
||||
For example, the above two blocks of code could be replaced by the following
|
||||
(which also takes care of the error checking)::
|
||||
|
||||
PyObject *tuple, *list;
|
||||
|
||||
tuple = Py_BuildValue("(iis)", 1, 2, "three");
|
||||
list = Py_BuildValue("[iis]", 1, 2, "three");
|
||||
|
||||
It is much more common to use :c:func:`PyObject_SetItem` and friends with items
|
||||
whose references you are only borrowing, like arguments that were passed in to
|
||||
the function you are writing. In that case, their behaviour regarding reference
|
||||
counts is much saner, since you don't have to increment a reference count so you
|
||||
can give a reference away ("have it be stolen"). For example, this function
|
||||
sets all items of a list (actually, any mutable sequence) to a given item::
|
||||
|
||||
int
|
||||
set_all(PyObject *target, PyObject *item)
|
||||
{
|
||||
Py_ssize_t i, n;
|
||||
|
||||
n = PyObject_Length(target);
|
||||
if (n < 0)
|
||||
return -1;
|
||||
for (i = 0; i < n; i++) {
|
||||
PyObject *index = PyLong_FromSsize_t(i);
|
||||
if (!index)
|
||||
return -1;
|
||||
if (PyObject_SetItem(target, index, item) < 0) {
|
||||
Py_DECREF(index);
|
||||
return -1;
|
||||
}
|
||||
Py_DECREF(index);
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
.. index:: single: set_all()
|
||||
|
||||
The situation is slightly different for function return values. While passing
|
||||
a reference to most functions does not change your ownership responsibilities
|
||||
for that reference, many functions that return a reference to an object give
|
||||
you ownership of the reference. The reason is simple: in many cases, the
|
||||
returned object is created on the fly, and the reference you get is the only
|
||||
reference to the object. Therefore, the generic functions that return object
|
||||
references, like :c:func:`PyObject_GetItem` and :c:func:`PySequence_GetItem`,
|
||||
always return a new reference (the caller becomes the owner of the reference).
|
||||
|
||||
It is important to realize that whether you own a reference returned by a
|
||||
function depends on which function you call only --- *the plumage* (the type of
|
||||
the object passed as an argument to the function) *doesn't enter into it!*
|
||||
Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, you
|
||||
don't own the reference --- but if you obtain the same item from the same list
|
||||
using :c:func:`PySequence_GetItem` (which happens to take exactly the same
|
||||
arguments), you do own a reference to the returned object.
|
||||
|
||||
.. index::
|
||||
single: PyList_GetItem()
|
||||
single: PySequence_GetItem()
|
||||
|
||||
Here is an example of how you could write a function that computes the sum of
|
||||
the items in a list of integers; once using :c:func:`PyList_GetItem`, and once
|
||||
using :c:func:`PySequence_GetItem`. ::
|
||||
|
||||
long
|
||||
sum_list(PyObject *list)
|
||||
{
|
||||
Py_ssize_t i, n;
|
||||
long total = 0, value;
|
||||
PyObject *item;
|
||||
|
||||
n = PyList_Size(list);
|
||||
if (n < 0)
|
||||
return -1; /* Not a list */
|
||||
for (i = 0; i < n; i++) {
|
||||
item = PyList_GetItem(list, i); /* Can't fail */
|
||||
if (!PyLong_Check(item)) continue; /* Skip non-integers */
|
||||
value = PyLong_AsLong(item);
|
||||
if (value == -1 && PyErr_Occurred())
|
||||
/* Integer too big to fit in a C long, bail out */
|
||||
return -1;
|
||||
total += value;
|
||||
}
|
||||
return total;
|
||||
}
|
||||
|
||||
.. index:: single: sum_list()
|
||||
|
||||
::
|
||||
|
||||
long
|
||||
sum_sequence(PyObject *sequence)
|
||||
{
|
||||
Py_ssize_t i, n;
|
||||
long total = 0, value;
|
||||
PyObject *item;
|
||||
n = PySequence_Length(sequence);
|
||||
if (n < 0)
|
||||
return -1; /* Has no length */
|
||||
for (i = 0; i < n; i++) {
|
||||
item = PySequence_GetItem(sequence, i);
|
||||
if (item == NULL)
|
||||
return -1; /* Not a sequence, or other failure */
|
||||
if (PyLong_Check(item)) {
|
||||
value = PyLong_AsLong(item);
|
||||
Py_DECREF(item);
|
||||
if (value == -1 && PyErr_Occurred())
|
||||
/* Integer too big to fit in a C long, bail out */
|
||||
return -1;
|
||||
total += value;
|
||||
}
|
||||
else {
|
||||
Py_DECREF(item); /* Discard reference ownership */
|
||||
}
|
||||
}
|
||||
return total;
|
||||
}
|
||||
|
||||
.. index:: single: sum_sequence()
|
||||
|
||||
|
||||
.. _api-types:
|
||||
|
||||
Types
|
||||
-----
|
||||
|
||||
There are few other data types that play a significant role in the Python/C
|
||||
API; most are simple C types such as :c:type:`int`, :c:type:`long`,
|
||||
:c:type:`double` and :c:type:`char\*`. A few structure types are used to
|
||||
describe static tables used to list the functions exported by a module or the
|
||||
data attributes of a new object type, and another is used to describe the value
|
||||
of a complex number. These will be discussed together with the functions that
|
||||
use them.
|
||||
|
||||
|
||||
.. _api-exceptions:
|
||||
|
||||
Exceptions
|
||||
==========
|
||||
|
||||
The Python programmer only needs to deal with exceptions if specific error
|
||||
handling is required; unhandled exceptions are automatically propagated to the
|
||||
caller, then to the caller's caller, and so on, until they reach the top-level
|
||||
interpreter, where they are reported to the user accompanied by a stack
|
||||
traceback.
|
||||
|
||||
.. index:: single: PyErr_Occurred()
|
||||
|
||||
For C programmers, however, error checking always has to be explicit. All
|
||||
functions in the Python/C API can raise exceptions, unless an explicit claim is
|
||||
made otherwise in a function's documentation. In general, when a function
|
||||
encounters an error, it sets an exception, discards any object references that
|
||||
it owns, and returns an error indicator. If not documented otherwise, this
|
||||
indicator is either *NULL* or ``-1``, depending on the function's return type.
|
||||
A few functions return a Boolean true/false result, with false indicating an
|
||||
error. Very few functions return no explicit error indicator or have an
|
||||
ambiguous return value, and require explicit testing for errors with
|
||||
:c:func:`PyErr_Occurred`. These exceptions are always explicitly documented.
|
||||
|
||||
.. index::
|
||||
single: PyErr_SetString()
|
||||
single: PyErr_Clear()
|
||||
|
||||
Exception state is maintained in per-thread storage (this is equivalent to
|
||||
using global storage in an unthreaded application). A thread can be in one of
|
||||
two states: an exception has occurred, or not. The function
|
||||
:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed
|
||||
reference to the exception type object when an exception has occurred, and
|
||||
*NULL* otherwise. There are a number of functions to set the exception state:
|
||||
:c:func:`PyErr_SetString` is the most common (though not the most general)
|
||||
function to set the exception state, and :c:func:`PyErr_Clear` clears the
|
||||
exception state.
|
||||
|
||||
The full exception state consists of three objects (all of which can be
|
||||
*NULL*): the exception type, the corresponding exception value, and the
|
||||
traceback. These have the same meanings as the Python result of
|
||||
``sys.exc_info()``; however, they are not the same: the Python objects represent
|
||||
the last exception being handled by a Python :keyword:`try` ...
|
||||
:keyword:`except` statement, while the C level exception state only exists while
|
||||
an exception is being passed on between C functions until it reaches the Python
|
||||
bytecode interpreter's main loop, which takes care of transferring it to
|
||||
``sys.exc_info()`` and friends.
|
||||
|
||||
.. index:: single: exc_info() (in module sys)
|
||||
|
||||
Note that starting with Python 1.5, the preferred, thread-safe way to access the
|
||||
exception state from Python code is to call the function :func:`sys.exc_info`,
|
||||
which returns the per-thread exception state for Python code. Also, the
|
||||
semantics of both ways to access the exception state have changed so that a
|
||||
function which catches an exception will save and restore its thread's exception
|
||||
state so as to preserve the exception state of its caller. This prevents common
|
||||
bugs in exception handling code caused by an innocent-looking function
|
||||
overwriting the exception being handled; it also reduces the often unwanted
|
||||
lifetime extension for objects that are referenced by the stack frames in the
|
||||
traceback.
|
||||
|
||||
As a general principle, a function that calls another function to perform some
|
||||
task should check whether the called function raised an exception, and if so,
|
||||
pass the exception state on to its caller. It should discard any object
|
||||
references that it owns, and return an error indicator, but it should *not* set
|
||||
another exception --- that would overwrite the exception that was just raised,
|
||||
and lose important information about the exact cause of the error.
|
||||
|
||||
.. index:: single: sum_sequence()
|
||||
|
||||
A simple example of detecting exceptions and passing them on is shown in the
|
||||
:c:func:`sum_sequence` example above. It so happens that this example doesn't
|
||||
need to clean up any owned references when it detects an error. The following
|
||||
example function shows some error cleanup. First, to remind you why you like
|
||||
Python, we show the equivalent Python code::
|
||||
|
||||
def incr_item(dict, key):
|
||||
try:
|
||||
item = dict[key]
|
||||
except KeyError:
|
||||
item = 0
|
||||
dict[key] = item + 1
|
||||
|
||||
.. index:: single: incr_item()
|
||||
|
||||
Here is the corresponding C code, in all its glory::
|
||||
|
||||
int
|
||||
incr_item(PyObject *dict, PyObject *key)
|
||||
{
|
||||
/* Objects all initialized to NULL for Py_XDECREF */
|
||||
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
|
||||
int rv = -1; /* Return value initialized to -1 (failure) */
|
||||
|
||||
item = PyObject_GetItem(dict, key);
|
||||
if (item == NULL) {
|
||||
/* Handle KeyError only: */
|
||||
if (!PyErr_ExceptionMatches(PyExc_KeyError))
|
||||
goto error;
|
||||
|
||||
/* Clear the error and use zero: */
|
||||
PyErr_Clear();
|
||||
item = PyLong_FromLong(0L);
|
||||
if (item == NULL)
|
||||
goto error;
|
||||
}
|
||||
const_one = PyLong_FromLong(1L);
|
||||
if (const_one == NULL)
|
||||
goto error;
|
||||
|
||||
incremented_item = PyNumber_Add(item, const_one);
|
||||
if (incremented_item == NULL)
|
||||
goto error;
|
||||
|
||||
if (PyObject_SetItem(dict, key, incremented_item) < 0)
|
||||
goto error;
|
||||
rv = 0; /* Success */
|
||||
/* Continue with cleanup code */
|
||||
|
||||
error:
|
||||
/* Cleanup code, shared by success and failure path */
|
||||
|
||||
/* Use Py_XDECREF() to ignore NULL references */
|
||||
Py_XDECREF(item);
|
||||
Py_XDECREF(const_one);
|
||||
Py_XDECREF(incremented_item);
|
||||
|
||||
return rv; /* -1 for error, 0 for success */
|
||||
}
|
||||
|
||||
.. index:: single: incr_item()
|
||||
|
||||
.. index::
|
||||
single: PyErr_ExceptionMatches()
|
||||
single: PyErr_Clear()
|
||||
single: Py_XDECREF()
|
||||
|
||||
This example represents an endorsed use of the ``goto`` statement in C!
|
||||
It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
|
||||
:c:func:`PyErr_Clear` to handle specific exceptions, and the use of
|
||||
:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
|
||||
``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a
|
||||
*NULL* reference). It is important that the variables used to hold owned
|
||||
references are initialized to *NULL* for this to work; likewise, the proposed
|
||||
return value is initialized to ``-1`` (failure) and only set to success after
|
||||
the final call made is successful.
|
||||
|
||||
|
||||
.. _api-embedding:
|
||||
|
||||
Embedding Python
|
||||
================
|
||||
|
||||
The one important task that only embedders (as opposed to extension writers) of
|
||||
the Python interpreter have to worry about is the initialization, and possibly
|
||||
the finalization, of the Python interpreter. Most functionality of the
|
||||
interpreter can only be used after the interpreter has been initialized.
|
||||
|
||||
.. index::
|
||||
single: Py_Initialize()
|
||||
module: builtins
|
||||
module: __main__
|
||||
module: sys
|
||||
triple: module; search; path
|
||||
single: path (in module sys)
|
||||
|
||||
The basic initialization function is :c:func:`Py_Initialize`. This initializes
|
||||
the table of loaded modules, and creates the fundamental modules
|
||||
:mod:`builtins`, :mod:`__main__`, and :mod:`sys`. It also
|
||||
initializes the module search path (``sys.path``).
|
||||
|
||||
.. index:: single: PySys_SetArgvEx()
|
||||
|
||||
:c:func:`Py_Initialize` does not set the "script argument list" (``sys.argv``).
|
||||
If this variable is needed by Python code that will be executed later, it must
|
||||
be set explicitly with a call to ``PySys_SetArgvEx(argc, argv, updatepath)``
|
||||
after the call to :c:func:`Py_Initialize`.
|
||||
|
||||
On most systems (in particular, on Unix and Windows, although the details are
|
||||
slightly different), :c:func:`Py_Initialize` calculates the module search path
|
||||
based upon its best guess for the location of the standard Python interpreter
|
||||
executable, assuming that the Python library is found in a fixed location
|
||||
relative to the Python interpreter executable. In particular, it looks for a
|
||||
directory named :file:`lib/python{X.Y}` relative to the parent directory
|
||||
where the executable named :file:`python` is found on the shell command search
|
||||
path (the environment variable :envvar:`PATH`).
|
||||
|
||||
For instance, if the Python executable is found in
|
||||
:file:`/usr/local/bin/python`, it will assume that the libraries are in
|
||||
:file:`/usr/local/lib/python{X.Y}`. (In fact, this particular path is also
|
||||
the "fallback" location, used when no executable file named :file:`python` is
|
||||
found along :envvar:`PATH`.) The user can override this behavior by setting the
|
||||
environment variable :envvar:`PYTHONHOME`, or insert additional directories in
|
||||
front of the standard path by setting :envvar:`PYTHONPATH`.
|
||||
|
||||
.. index::
|
||||
single: Py_SetProgramName()
|
||||
single: Py_GetPath()
|
||||
single: Py_GetPrefix()
|
||||
single: Py_GetExecPrefix()
|
||||
single: Py_GetProgramFullPath()
|
||||
|
||||
The embedding application can steer the search by calling
|
||||
``Py_SetProgramName(file)`` *before* calling :c:func:`Py_Initialize`. Note that
|
||||
:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still
|
||||
inserted in front of the standard path. An application that requires total
|
||||
control has to provide its own implementation of :c:func:`Py_GetPath`,
|
||||
:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and
|
||||
:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
|
||||
|
||||
.. index:: single: Py_IsInitialized()
|
||||
|
||||
Sometimes, it is desirable to "uninitialize" Python. For instance, the
|
||||
application may want to start over (make another call to
|
||||
:c:func:`Py_Initialize`) or the application is simply done with its use of
|
||||
Python and wants to free memory allocated by Python. This can be accomplished
|
||||
by calling :c:func:`Py_Finalize`. The function :c:func:`Py_IsInitialized` returns
|
||||
true if Python is currently in the initialized state. More information about
|
||||
these functions is given in a later chapter. Notice that :c:func:`Py_Finalize`
|
||||
does *not* free all memory allocated by the Python interpreter, e.g. memory
|
||||
allocated by extension modules currently cannot be released.
|
||||
|
||||
|
||||
.. _api-debugging:
|
||||
|
||||
Debugging Builds
|
||||
================
|
||||
|
||||
Python can be built with several macros to enable extra checks of the
|
||||
interpreter and extension modules. These checks tend to add a large amount of
|
||||
overhead to the runtime so they are not enabled by default.
|
||||
|
||||
A full list of the various types of debugging builds is in the file
|
||||
:file:`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are
|
||||
available that support tracing of reference counts, debugging the memory
|
||||
allocator, or low-level profiling of the main interpreter loop. Only the most
|
||||
frequently-used builds will be described in the remainder of this section.
|
||||
|
||||
Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
|
||||
what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
|
||||
enabled in the Unix build by adding ``--with-pydebug`` to the
|
||||
:file:`./configure` command. It is also implied by the presence of the
|
||||
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled
|
||||
in the Unix build, compiler optimization is disabled.
|
||||
|
||||
In addition to the reference count debugging described below, the following
|
||||
extra checks are performed:
|
||||
|
||||
* Extra checks are added to the object allocator.
|
||||
|
||||
* Extra checks are added to the parser and compiler.
|
||||
|
||||
* Downcasts from wide types to narrow types are checked for loss of information.
|
||||
|
||||
* A number of assertions are added to the dictionary and set implementations.
|
||||
In addition, the set object acquires a :meth:`test_c_api` method.
|
||||
|
||||
* Sanity checks of the input arguments are added to frame creation.
|
||||
|
||||
* The storage for ints is initialized with a known invalid pattern to catch
|
||||
reference to uninitialized digits.
|
||||
|
||||
* Low-level tracing and extra exception checking are added to the runtime
|
||||
virtual machine.
|
||||
|
||||
* Extra checks are added to the memory arena implementation.
|
||||
|
||||
* Extra debugging is added to the thread module.
|
||||
|
||||
There may be additional checks not mentioned here.
|
||||
|
||||
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
|
||||
circular doubly linked list of active objects is maintained by adding two extra
|
||||
fields to every :c:type:`PyObject`. Total allocations are tracked as well. Upon
|
||||
exit, all existing references are printed. (In interactive mode this happens
|
||||
after every statement run by the interpreter.) Implied by :c:macro:`Py_DEBUG`.
|
||||
|
||||
Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
|
||||
for more detailed information.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _iterator:
|
||||
|
||||
Iterator Protocol
|
||||
=================
|
||||
|
||||
There are two functions specifically for working with iterators.
|
||||
|
||||
.. c:function:: int PyIter_Check(PyObject *o)
|
||||
|
||||
Return true if the object *o* supports the iterator protocol.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyIter_Next(PyObject *o)
|
||||
|
||||
Return the next value from the iteration *o*. The object must be an iterator
|
||||
(it is up to the caller to check this). If there are no remaining values,
|
||||
returns *NULL* with no exception set. If an error occurs while retrieving
|
||||
the item, returns *NULL* and passes along the exception.
|
||||
|
||||
To write a loop which iterates over an iterator, the C code should look
|
||||
something like this::
|
||||
|
||||
PyObject *iterator = PyObject_GetIter(obj);
|
||||
PyObject *item;
|
||||
|
||||
if (iterator == NULL) {
|
||||
/* propagate error */
|
||||
}
|
||||
|
||||
while (item = PyIter_Next(iterator)) {
|
||||
/* do something with item */
|
||||
...
|
||||
/* release reference when done */
|
||||
Py_DECREF(item);
|
||||
}
|
||||
|
||||
Py_DECREF(iterator);
|
||||
|
||||
if (PyErr_Occurred()) {
|
||||
/* propagate error */
|
||||
}
|
||||
else {
|
||||
/* continue doing useful work */
|
||||
}
|
|
@ -0,0 +1,50 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _iterator-objects:
|
||||
|
||||
Iterator Objects
|
||||
----------------
|
||||
|
||||
Python provides two general-purpose iterator objects. The first, a sequence
|
||||
iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
|
||||
method. The second works with a callable object and a sentinel value, calling
|
||||
the callable for each item in the sequence, and ending the iteration when the
|
||||
sentinel value is returned.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PySeqIter_Type
|
||||
|
||||
Type object for iterator objects returned by :c:func:`PySeqIter_New` and the
|
||||
one-argument form of the :func:`iter` built-in function for built-in sequence
|
||||
types.
|
||||
|
||||
|
||||
.. c:function:: int PySeqIter_Check(op)
|
||||
|
||||
Return true if the type of *op* is :c:data:`PySeqIter_Type`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
|
||||
|
||||
Return an iterator that works with a general sequence object, *seq*. The
|
||||
iteration ends when the sequence raises :exc:`IndexError` for the subscripting
|
||||
operation.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyCallIter_Type
|
||||
|
||||
Type object for iterator objects returned by :c:func:`PyCallIter_New` and the
|
||||
two-argument form of the :func:`iter` built-in function.
|
||||
|
||||
|
||||
.. c:function:: int PyCallIter_Check(op)
|
||||
|
||||
Return true if the type of *op* is :c:data:`PyCallIter_Type`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
|
||||
|
||||
Return a new iterator. The first parameter, *callable*, can be any Python
|
||||
callable object that can be called with no parameters; each call to it should
|
||||
return the next item in the iteration. When *callable* returns a value equal to
|
||||
*sentinel*, the iteration will be terminated.
|
|
@ -0,0 +1,151 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _listobjects:
|
||||
|
||||
List Objects
|
||||
------------
|
||||
|
||||
.. index:: object: list
|
||||
|
||||
|
||||
.. c:type:: PyListObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python list object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyList_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python list type.
|
||||
This is the same object as :class:`list` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyList_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a list object or an instance of a subtype of the list
|
||||
type.
|
||||
|
||||
|
||||
.. c:function:: int PyList_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a list object, but not an instance of a subtype of
|
||||
the list type.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyList_New(Py_ssize_t len)
|
||||
|
||||
Return a new list of length *len* on success, or *NULL* on failure.
|
||||
|
||||
.. note::
|
||||
|
||||
If *len* is greater than zero, the returned list object's items are
|
||||
set to ``NULL``. Thus you cannot use abstract API functions such as
|
||||
:c:func:`PySequence_SetItem` or expose the object to Python code before
|
||||
setting all items to a real object with :c:func:`PyList_SetItem`.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyList_Size(PyObject *list)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Return the length of the list object in *list*; this is equivalent to
|
||||
``len(list)`` on a list object.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
|
||||
|
||||
Macro form of :c:func:`PyList_Size` without error checking.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
|
||||
|
||||
Return the object at position *index* in the list pointed to by *list*. The
|
||||
position must be positive, indexing from the end of the list is not
|
||||
supported. If *index* is out of bounds, return *NULL* and set an
|
||||
:exc:`IndexError` exception.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
|
||||
|
||||
Macro form of :c:func:`PyList_GetItem` without error checking.
|
||||
|
||||
|
||||
.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
|
||||
|
||||
Set the item at index *index* in list to *item*. Return ``0`` on success
|
||||
or ``-1`` on failure.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *item* and discards a reference to
|
||||
an item already in the list at the affected position.
|
||||
|
||||
|
||||
.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
|
||||
|
||||
Macro form of :c:func:`PyList_SetItem` without error checking. This is
|
||||
normally only used to fill in new lists where there is no previous content.
|
||||
|
||||
.. note::
|
||||
|
||||
This macro "steals" a reference to *item*, and, unlike
|
||||
:c:func:`PyList_SetItem`, does *not* discard a reference to any item that
|
||||
is being replaced; any reference in *list* at position *i* will be
|
||||
leaked.
|
||||
|
||||
|
||||
.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
|
||||
|
||||
Insert the item *item* into list *list* in front of index *index*. Return
|
||||
``0`` if successful; return ``-1`` and set an exception if unsuccessful.
|
||||
Analogous to ``list.insert(index, item)``.
|
||||
|
||||
|
||||
.. c:function:: int PyList_Append(PyObject *list, PyObject *item)
|
||||
|
||||
Append the object *item* at the end of list *list*. Return ``0`` if
|
||||
successful; return ``-1`` and set an exception if unsuccessful. Analogous
|
||||
to ``list.append(item)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
|
||||
|
||||
Return a list of the objects in *list* containing the objects *between* *low*
|
||||
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous
|
||||
to ``list[low:high]``. Negative indices, as when slicing from Python, are not
|
||||
supported.
|
||||
|
||||
|
||||
.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
|
||||
|
||||
Set the slice of *list* between *low* and *high* to the contents of
|
||||
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
|
||||
be *NULL*, indicating the assignment of an empty list (slice deletion).
|
||||
Return ``0`` on success, ``-1`` on failure. Negative indices, as when
|
||||
slicing from Python, are not supported.
|
||||
|
||||
|
||||
.. c:function:: int PyList_Sort(PyObject *list)
|
||||
|
||||
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
|
||||
failure. This is equivalent to ``list.sort()``.
|
||||
|
||||
|
||||
.. c:function:: int PyList_Reverse(PyObject *list)
|
||||
|
||||
Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
|
||||
failure. This is the equivalent of ``list.reverse()``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyList_AsTuple(PyObject *list)
|
||||
|
||||
.. index:: builtin: tuple
|
||||
|
||||
Return a new tuple object containing the contents of *list*; equivalent to
|
||||
``tuple(list)``.
|
||||
|
||||
|
||||
.. c:function:: int PyList_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
.. versionadded:: 3.3
|
|
@ -0,0 +1,262 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _longobjects:
|
||||
|
||||
Integer Objects
|
||||
---------------
|
||||
|
||||
.. index:: object: long integer
|
||||
object: integer
|
||||
|
||||
All integers are implemented as "long" integer objects of arbitrary size.
|
||||
|
||||
.. c:type:: PyLongObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python integer object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyLong_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python integer type.
|
||||
This is the same object as :class:`int` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyLong_Check(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyLongObject` or a subtype of
|
||||
:c:type:`PyLongObject`.
|
||||
|
||||
|
||||
.. c:function:: int PyLong_CheckExact(PyObject *p)
|
||||
|
||||
Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
|
||||
:c:type:`PyLongObject`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromLong(long v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
|
||||
|
||||
The current implementation keeps an array of integer objects for all integers
|
||||
between ``-5`` and ``256``, when you create an int in that range you actually
|
||||
just get back a reference to the existing object. So it should be possible to
|
||||
change the value of ``1``. I suspect the behaviour of Python in this case is
|
||||
undefined. :-)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
|
||||
on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
|
||||
or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromDouble(double v)
|
||||
|
||||
Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base)
|
||||
|
||||
Return a new :c:type:`PyLongObject` based on the string value in *str*, which
|
||||
is interpreted according to the radix in *base*. If *pend* is non-*NULL*,
|
||||
*\*pend* will point to the first character in *str* which follows the
|
||||
representation of the number. If *base* is ``0``, the radix will be
|
||||
determined based on the leading characters of *str*: if *str* starts with
|
||||
``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
|
||||
``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
|
||||
radix 2 will be used; otherwise radix 10 will be used. If *base* is not
|
||||
``0``, it must be between ``2`` and ``36``, inclusive. Leading spaces are
|
||||
ignored. If there are no digits, :exc:`ValueError` will be raised.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
|
||||
|
||||
Convert a sequence of Unicode digits to a Python integer value. The Unicode
|
||||
string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
|
||||
and then converted using :c:func:`PyLong_FromString`.
|
||||
|
||||
.. deprecated-removed:: 3.3 4.0
|
||||
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
|
||||
:c:func:`PyLong_FromUnicodeObject`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
|
||||
|
||||
Convert a sequence of Unicode digits in the string *u* to a Python integer
|
||||
value. The Unicode string is first encoded to a byte string using
|
||||
:c:func:`PyUnicode_EncodeDecimal` and then converted using
|
||||
:c:func:`PyLong_FromString`.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
|
||||
|
||||
Create a Python integer from the pointer *p*. The pointer value can be
|
||||
retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
|
||||
|
||||
|
||||
.. XXX alias PyLong_AS_LONG (for now)
|
||||
.. c:function:: long PyLong_AsLong(PyObject *obj)
|
||||
|
||||
.. index::
|
||||
single: LONG_MAX
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
|
||||
:c:type:`long`.
|
||||
|
||||
|
||||
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
|
||||
|
||||
Return a C :c:type:`long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* is greater than :const:`LONG_MAX` or less than
|
||||
:const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
|
||||
return ``-1``; otherwise, set *\*overflow* to ``0``. If any other exception
|
||||
occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
|
||||
|
||||
|
||||
.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *obj)
|
||||
|
||||
.. index::
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *obj* is out of range for a
|
||||
:c:type:`long`.
|
||||
|
||||
|
||||
.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
|
||||
|
||||
Return a C :c:type:`long long` representation of *obj*. If *obj* is not an
|
||||
instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
|
||||
(if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
|
||||
:const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
|
||||
and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other
|
||||
exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
|
||||
|
||||
.. index::
|
||||
single: PY_SSIZE_T_MAX
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must
|
||||
be an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`Py_ssize_t`.
|
||||
|
||||
|
||||
.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
|
||||
|
||||
.. index::
|
||||
single: ULONG_MAX
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`unsigned long` representation of *pylong*. *pylong*
|
||||
must be an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`unsigned long`.
|
||||
|
||||
|
||||
.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
|
||||
|
||||
Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be
|
||||
an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`size_t`.
|
||||
|
||||
|
||||
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
|
||||
|
||||
.. index::
|
||||
single: OverflowError (built-in exception)
|
||||
|
||||
Return a C :c:type:`unsigned PY_LONG_LONG` representation of *pylong*.
|
||||
*pylong* must be an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
|
||||
:c:type:`unsigned PY_LONG_LONG`.
|
||||
|
||||
.. versionchanged:: 3.1
|
||||
A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
|
||||
|
||||
|
||||
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
|
||||
|
||||
Return a C :c:type:`unsigned long` representation of *obj*. If *obj*
|
||||
is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
|
||||
method (if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* is out of range for an :c:type:`unsigned long`,
|
||||
return the reduction of that value modulo :const:`ULONG_MAX + 1`.
|
||||
|
||||
|
||||
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)
|
||||
|
||||
Return a C :c:type:`unsigned long long` representation of *obj*. If *obj*
|
||||
is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
|
||||
method (if present) to convert it to a :c:type:`PyLongObject`.
|
||||
|
||||
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
|
||||
return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
|
||||
|
||||
|
||||
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
|
||||
|
||||
Return a C :c:type:`double` representation of *pylong*. *pylong* must be
|
||||
an instance of :c:type:`PyLongObject`.
|
||||
|
||||
Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
|
||||
:c:type:`double`.
|
||||
|
||||
|
||||
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
|
||||
|
||||
Convert a Python integer *pylong* to a C :c:type:`void` pointer.
|
||||
If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
|
||||
is only assured to produce a usable :c:type:`void` pointer for values created
|
||||
with :c:func:`PyLong_FromVoidPtr`.
|
|
@ -0,0 +1,79 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _mapping:
|
||||
|
||||
Mapping Protocol
|
||||
================
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_Check(PyObject *o)
|
||||
|
||||
Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This
|
||||
function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
|
||||
Py_ssize_t PyMapping_Length(PyObject *o)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Returns the number of keys in object *o* on success, and ``-1`` on failure. For
|
||||
objects that do not provide mapping protocol, this is equivalent to the Python
|
||||
expression ``len(o)``.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
|
||||
|
||||
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
|
||||
failure. This is equivalent to the Python statement ``del o[key]``.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
|
||||
|
||||
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
|
||||
failure. This is equivalent to the Python statement ``del o[key]``.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_HasKeyString(PyObject *o, char *key)
|
||||
|
||||
On success, return ``1`` if the mapping object has the key *key* and ``0``
|
||||
otherwise. This is equivalent to the Python expression ``key in o``.
|
||||
This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
|
||||
|
||||
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. This
|
||||
is equivalent to the Python expression ``key in o``. This function always
|
||||
succeeds.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
|
||||
|
||||
On success, return a list of the keys in object *o*. On failure, return *NULL*.
|
||||
This is equivalent to the Python expression ``list(o.keys())``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_Values(PyObject *o)
|
||||
|
||||
On success, return a list of the values in object *o*. On failure, return
|
||||
*NULL*. This is equivalent to the Python expression ``list(o.values())``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_Items(PyObject *o)
|
||||
|
||||
On success, return a list of the items in object *o*, where each item is a tuple
|
||||
containing a key-value pair. On failure, return *NULL*. This is equivalent to
|
||||
the Python expression ``list(o.items())``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
|
||||
|
||||
Return element of *o* corresponding to the object *key* or *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``o[key]``.
|
||||
|
||||
|
||||
.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
|
||||
|
||||
Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
|
||||
This is the equivalent of the Python statement ``o[key] = v``.
|
|
@ -0,0 +1,89 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _marshalling-utils:
|
||||
|
||||
Data marshalling support
|
||||
========================
|
||||
|
||||
These routines allow C code to work with serialized objects using the same
|
||||
data format as the :mod:`marshal` module. There are functions to write data
|
||||
into the serialization format, and additional functions that can be used to
|
||||
read the data back. Files used to store marshalled data must be opened in
|
||||
binary mode.
|
||||
|
||||
Numeric values are stored with the least significant byte first.
|
||||
|
||||
The module supports two versions of the data format: version 0 is the
|
||||
historical version, version 1 shares interned strings in the file, and upon
|
||||
unmarshalling. Version 2 uses a binary format for floating point numbers.
|
||||
*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
|
||||
|
||||
|
||||
.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
|
||||
|
||||
Marshal a :c:type:`long` integer, *value*, to *file*. This will only write
|
||||
the least-significant 32 bits of *value*; regardless of the size of the
|
||||
native :c:type:`long` type. *version* indicates the file format.
|
||||
|
||||
|
||||
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
|
||||
|
||||
Marshal a Python object, *value*, to *file*.
|
||||
*version* indicates the file format.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
|
||||
|
||||
Return a string object containing the marshalled representation of *value*.
|
||||
*version* indicates the file format.
|
||||
|
||||
|
||||
The following functions allow marshalled values to be read back in.
|
||||
|
||||
XXX What about error detection? It appears that reading past the end of the
|
||||
file will always result in a negative numeric value (where that's relevant),
|
||||
but it's not clear that negative values won't be handled properly when there's
|
||||
no error. What's the right way to tell? Should only non-negative values be
|
||||
written using these routines?
|
||||
|
||||
|
||||
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
|
||||
|
||||
Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
|
||||
for reading. Only a 32-bit value can be read in using this function,
|
||||
regardless of the native size of :c:type:`long`.
|
||||
|
||||
|
||||
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
|
||||
|
||||
Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
|
||||
for reading. Only a 16-bit value can be read in using this function,
|
||||
regardless of the native size of :c:type:`short`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
|
||||
|
||||
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
|
||||
reading. On error, sets the appropriate exception (:exc:`EOFError` or
|
||||
:exc:`TypeError`) and returns *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
|
||||
|
||||
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
|
||||
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
|
||||
assumes that no further objects will be read from the file, allowing it to
|
||||
aggressively load file data into memory so that the de-serialization can
|
||||
operate from data in memory rather than reading a byte at a time from the
|
||||
file. Only use these variant if you are certain that you won't be reading
|
||||
anything else from the file. On error, sets the appropriate exception
|
||||
(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
|
||||
|
||||
Return a Python object from the data stream in a character buffer
|
||||
containing *len* bytes pointed to by *string*. On error, sets the
|
||||
appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
|
||||
*NULL*.
|
||||
|
|
@ -0,0 +1,378 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
|
||||
.. _memory:
|
||||
|
||||
*****************
|
||||
Memory Management
|
||||
*****************
|
||||
|
||||
.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>
|
||||
|
||||
|
||||
|
||||
.. _memoryoverview:
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
Memory management in Python involves a private heap containing all Python
|
||||
objects and data structures. The management of this private heap is ensured
|
||||
internally by the *Python memory manager*. The Python memory manager has
|
||||
different components which deal with various dynamic storage management aspects,
|
||||
like sharing, segmentation, preallocation or caching.
|
||||
|
||||
At the lowest level, a raw memory allocator ensures that there is enough room in
|
||||
the private heap for storing all Python-related data by interacting with the
|
||||
memory manager of the operating system. On top of the raw memory allocator,
|
||||
several object-specific allocators operate on the same heap and implement
|
||||
distinct memory management policies adapted to the peculiarities of every object
|
||||
type. For example, integer objects are managed differently within the heap than
|
||||
strings, tuples or dictionaries because integers imply different storage
|
||||
requirements and speed/space tradeoffs. The Python memory manager thus delegates
|
||||
some of the work to the object-specific allocators, but ensures that the latter
|
||||
operate within the bounds of the private heap.
|
||||
|
||||
It is important to understand that the management of the Python heap is
|
||||
performed by the interpreter itself and that the user has no control over it,
|
||||
even if she regularly manipulates object pointers to memory blocks inside that
|
||||
heap. The allocation of heap space for Python objects and other internal
|
||||
buffers is performed on demand by the Python memory manager through the Python/C
|
||||
API functions listed in this document.
|
||||
|
||||
.. index::
|
||||
single: malloc()
|
||||
single: calloc()
|
||||
single: realloc()
|
||||
single: free()
|
||||
|
||||
To avoid memory corruption, extension writers should never try to operate on
|
||||
Python objects with the functions exported by the C library: :c:func:`malloc`,
|
||||
:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will result in mixed
|
||||
calls between the C allocator and the Python memory manager with fatal
|
||||
consequences, because they implement different algorithms and operate on
|
||||
different heaps. However, one may safely allocate and release memory blocks
|
||||
with the C library allocator for individual purposes, as shown in the following
|
||||
example::
|
||||
|
||||
PyObject *res;
|
||||
char *buf = (char *) malloc(BUFSIZ); /* for I/O */
|
||||
|
||||
if (buf == NULL)
|
||||
return PyErr_NoMemory();
|
||||
...Do some I/O operation involving buf...
|
||||
res = PyBytes_FromString(buf);
|
||||
free(buf); /* malloc'ed */
|
||||
return res;
|
||||
|
||||
In this example, the memory request for the I/O buffer is handled by the C
|
||||
library allocator. The Python memory manager is involved only in the allocation
|
||||
of the string object returned as a result.
|
||||
|
||||
In most situations, however, it is recommended to allocate memory from the
|
||||
Python heap specifically because the latter is under control of the Python
|
||||
memory manager. For example, this is required when the interpreter is extended
|
||||
with new object types written in C. Another reason for using the Python heap is
|
||||
the desire to *inform* the Python memory manager about the memory needs of the
|
||||
extension module. Even when the requested memory is used exclusively for
|
||||
internal, highly-specific purposes, delegating all memory requests to the Python
|
||||
memory manager causes the interpreter to have a more accurate image of its
|
||||
memory footprint as a whole. Consequently, under certain circumstances, the
|
||||
Python memory manager may or may not trigger appropriate actions, like garbage
|
||||
collection, memory compaction or other preventive procedures. Note that by using
|
||||
the C library allocator as shown in the previous example, the allocated memory
|
||||
for the I/O buffer escapes completely the Python memory manager.
|
||||
|
||||
|
||||
Raw Memory Interface
|
||||
====================
|
||||
|
||||
The following function sets are wrappers to the system allocator. These
|
||||
functions are thread-safe, the :term:`GIL <global interpreter lock>` does not
|
||||
need to be held.
|
||||
|
||||
The default raw memory block allocator uses the following functions:
|
||||
:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when
|
||||
requesting zero bytes.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:function:: void* PyMem_RawMalloc(size_t n)
|
||||
|
||||
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
|
||||
allocated memory, or *NULL* if the request fails. Requesting zero bytes
|
||||
returns a distinct non-*NULL* pointer if possible, as if
|
||||
``PyMem_RawMalloc(1)`` had been called instead. The memory will not have
|
||||
been initialized in any way.
|
||||
|
||||
|
||||
.. c:function:: void* PyMem_RawRealloc(void *p, size_t n)
|
||||
|
||||
Resizes the memory block pointed to by *p* to *n* bytes. The contents will
|
||||
be unchanged to the minimum of the old and the new sizes. If *p* is *NULL*,
|
||||
the call is equivalent to ``PyMem_RawMalloc(n)``; else if *n* is equal to
|
||||
zero, the memory block is resized but is not freed, and the returned pointer
|
||||
is non-*NULL*. Unless *p* is *NULL*, it must have been returned by a
|
||||
previous call to :c:func:`PyMem_RawMalloc` or :c:func:`PyMem_RawRealloc`. If
|
||||
the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p* remains
|
||||
a valid pointer to the previous memory area.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_RawFree(void *p)
|
||||
|
||||
Frees the memory block pointed to by *p*, which must have been returned by a
|
||||
previous call to :c:func:`PyMem_RawMalloc` or :c:func:`PyMem_RawRealloc`.
|
||||
Otherwise, or if ``PyMem_Free(p)`` has been called before, undefined
|
||||
behavior occurs. If *p* is *NULL*, no operation is performed.
|
||||
|
||||
|
||||
.. _memoryinterface:
|
||||
|
||||
Memory Interface
|
||||
================
|
||||
|
||||
The following function sets, modeled after the ANSI C standard, but specifying
|
||||
behavior when requesting zero bytes, are available for allocating and releasing
|
||||
memory from the Python heap.
|
||||
|
||||
The default memory block allocator uses the following functions:
|
||||
:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when
|
||||
requesting zero bytes.
|
||||
|
||||
.. warning::
|
||||
|
||||
The :term:`GIL <global interpreter lock>` must be held when using these
|
||||
functions.
|
||||
|
||||
.. c:function:: void* PyMem_Malloc(size_t n)
|
||||
|
||||
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
|
||||
allocated memory, or *NULL* if the request fails. Requesting zero bytes returns
|
||||
a distinct non-*NULL* pointer if possible, as if ``PyMem_Malloc(1)`` had
|
||||
been called instead. The memory will not have been initialized in any way.
|
||||
|
||||
|
||||
.. c:function:: void* PyMem_Realloc(void *p, size_t n)
|
||||
|
||||
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
|
||||
unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, the
|
||||
call is equivalent to ``PyMem_Malloc(n)``; else if *n* is equal to zero,
|
||||
the memory block is resized but is not freed, and the returned pointer is
|
||||
non-*NULL*. Unless *p* is *NULL*, it must have been returned by a previous call
|
||||
to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. If the request fails,
|
||||
:c:func:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the
|
||||
previous memory area.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_Free(void *p)
|
||||
|
||||
Frees the memory block pointed to by *p*, which must have been returned by a
|
||||
previous call to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. Otherwise, or
|
||||
if ``PyMem_Free(p)`` has been called before, undefined behavior occurs. If
|
||||
*p* is *NULL*, no operation is performed.
|
||||
|
||||
The following type-oriented macros are provided for convenience. Note that
|
||||
*TYPE* refers to any C type.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
|
||||
|
||||
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
|
||||
memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have
|
||||
been initialized in any way.
|
||||
|
||||
|
||||
.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
|
||||
|
||||
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
|
||||
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
|
||||
*p* will be a pointer to the new memory area, or *NULL* in the event of
|
||||
failure. This is a C preprocessor macro; p is always reassigned. Save
|
||||
the original value of p to avoid losing memory when handling errors.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_Del(void *p)
|
||||
|
||||
Same as :c:func:`PyMem_Free`.
|
||||
|
||||
In addition, the following macro sets are provided for calling the Python memory
|
||||
allocator directly, without involving the C API functions listed above. However,
|
||||
note that their use does not preserve binary compatibility across Python
|
||||
versions and is therefore deprecated in extension modules.
|
||||
|
||||
:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`.
|
||||
|
||||
:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
|
||||
|
||||
|
||||
Customize Memory Allocators
|
||||
===========================
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:type:: PyMemAllocator
|
||||
|
||||
Structure used to describe a memory block allocator. The structure has
|
||||
four fields:
|
||||
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| Field | Meaning |
|
||||
+==========================================================+=======================================+
|
||||
| ``void *ctx`` | user context passed as first argument |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void* malloc(void *ctx, size_t size)`` | allocate a memory block |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
| ``void free(void *ctx, void *ptr)`` | free a memory block |
|
||||
+----------------------------------------------------------+---------------------------------------+
|
||||
|
||||
.. c:type:: PyMemAllocatorDomain
|
||||
|
||||
Enum used to identify an allocator domain. Domains:
|
||||
|
||||
* :c:data:`PYMEM_DOMAIN_RAW`: functions :c:func:`PyMem_RawMalloc`,
|
||||
:c:func:`PyMem_RawRealloc` and :c:func:`PyMem_RawFree`
|
||||
* :c:data:`PYMEM_DOMAIN_MEM`: functions :c:func:`PyMem_Malloc`,
|
||||
:c:func:`PyMem_Realloc` and :c:func:`PyMem_Free`
|
||||
* :c:data:`PYMEM_DOMAIN_OBJ`: functions :c:func:`PyObject_Malloc`,
|
||||
:c:func:`PyObject_Realloc` and :c:func:`PyObject_Free`
|
||||
|
||||
|
||||
.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)
|
||||
|
||||
Get the memory block allocator of the specified domain.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)
|
||||
|
||||
Set the memory block allocator of the specified domain.
|
||||
|
||||
The new allocator must return a distinct non-NULL pointer when requesting
|
||||
zero bytes.
|
||||
|
||||
For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be
|
||||
thread-safe: the :term:`GIL <global interpreter lock>` is not held when the
|
||||
allocator is called.
|
||||
|
||||
If the new allocator is not a hook (does not call the previous allocator),
|
||||
the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
|
||||
debug hooks on top on the new allocator.
|
||||
|
||||
|
||||
.. c:function:: void PyMem_SetupDebugHooks(void)
|
||||
|
||||
Setup hooks to detect bugs in the following Python memory allocator
|
||||
functions:
|
||||
|
||||
- :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc`,
|
||||
:c:func:`PyMem_RawFree`
|
||||
- :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc`, :c:func:`PyMem_Free`
|
||||
- :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc`,
|
||||
:c:func:`PyObject_Free`
|
||||
|
||||
Newly allocated memory is filled with the byte ``0xCB``, freed memory is
|
||||
filled with the byte ``0xDB``. Additionnal checks:
|
||||
|
||||
- detect API violations, ex: :c:func:`PyObject_Free` called on a buffer
|
||||
allocated by :c:func:`PyMem_Malloc`
|
||||
- detect write before the start of the buffer (buffer underflow)
|
||||
- detect write after the end of the buffer (buffer overflow)
|
||||
|
||||
The function does nothing if Python is not compiled is debug mode.
|
||||
|
||||
|
||||
Customize PyObject Arena Allocator
|
||||
==================================
|
||||
|
||||
Python has a *pymalloc* allocator for allocations smaller than 512 bytes. This
|
||||
allocator is optimized for small objects with a short lifetime. It uses memory
|
||||
mappings called "arenas" with a fixed size of 256 KB. It falls back to
|
||||
:c:func:`PyMem_RawMalloc` and :c:func:`PyMem_RawRealloc` for allocations larger
|
||||
than 512 bytes. *pymalloc* is the default allocator used by
|
||||
:c:func:`PyObject_Malloc`.
|
||||
|
||||
The default arena allocator uses the following functions:
|
||||
|
||||
* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,
|
||||
* :c:func:`mmap` and :c:func:`munmap` if available,
|
||||
* :c:func:`malloc` and :c:func:`free` otherwise.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. c:type:: PyObjectArenaAllocator
|
||||
|
||||
Structure used to describe an arena allocator. The structure has
|
||||
three fields:
|
||||
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
| Field | Meaning |
|
||||
+==================================================+=======================================+
|
||||
| ``void *ctx`` | user context passed as first argument |
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
| ``void* alloc(void *ctx, size_t size)`` | allocate an arena of size bytes |
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
| ``void free(void *ctx, size_t size, void *ptr)`` | free an arena |
|
||||
+--------------------------------------------------+---------------------------------------+
|
||||
|
||||
.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
|
||||
|
||||
Get the arena allocator.
|
||||
|
||||
.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
|
||||
|
||||
Set the arena allocator.
|
||||
|
||||
|
||||
.. _memoryexamples:
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
Here is the example from section :ref:`memoryoverview`, rewritten so that the
|
||||
I/O buffer is allocated from the Python heap by using the first function set::
|
||||
|
||||
PyObject *res;
|
||||
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
|
||||
|
||||
if (buf == NULL)
|
||||
return PyErr_NoMemory();
|
||||
/* ...Do some I/O operation involving buf... */
|
||||
res = PyBytes_FromString(buf);
|
||||
PyMem_Free(buf); /* allocated with PyMem_Malloc */
|
||||
return res;
|
||||
|
||||
The same code using the type-oriented function set::
|
||||
|
||||
PyObject *res;
|
||||
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
|
||||
|
||||
if (buf == NULL)
|
||||
return PyErr_NoMemory();
|
||||
/* ...Do some I/O operation involving buf... */
|
||||
res = PyBytes_FromString(buf);
|
||||
PyMem_Del(buf); /* allocated with PyMem_New */
|
||||
return res;
|
||||
|
||||
Note that in the two examples above, the buffer is always manipulated via
|
||||
functions belonging to the same set. Indeed, it is required to use the same
|
||||
memory API family for a given memory block, so that the risk of mixing different
|
||||
allocators is reduced to a minimum. The following code sequence contains two
|
||||
errors, one of which is labeled as *fatal* because it mixes two different
|
||||
allocators operating on different heaps. ::
|
||||
|
||||
char *buf1 = PyMem_New(char, BUFSIZ);
|
||||
char *buf2 = (char *) malloc(BUFSIZ);
|
||||
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
|
||||
...
|
||||
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
|
||||
free(buf2); /* Right -- allocated via malloc() */
|
||||
free(buf1); /* Fatal -- should be PyMem_Del() */
|
||||
|
||||
In addition to the functions aimed at handling raw memory blocks from the Python
|
||||
heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
|
||||
:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
|
||||
|
||||
These will be explained in the next chapter on defining and implementing new
|
||||
object types in C.
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _memoryview-objects:
|
||||
|
||||
.. index::
|
||||
object: memoryview
|
||||
|
||||
MemoryView objects
|
||||
------------------
|
||||
|
||||
A :class:`memoryview` object exposes the C level :ref:`buffer interface
|
||||
<bufferobjects>` as a Python object which can then be passed around like
|
||||
any other object.
|
||||
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
|
||||
|
||||
Create a memoryview object from an object that provides the buffer interface.
|
||||
If *obj* supports writable buffer exports, the memoryview object will be
|
||||
read/write, otherwise it may be either read-only or read/write at the
|
||||
discretion of the exporter.
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
|
||||
|
||||
Create a memoryview object using *mem* as the underlying buffer.
|
||||
*flags* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
|
||||
|
||||
Create a memoryview object wrapping the given buffer structure *view*.
|
||||
For simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred
|
||||
function.
|
||||
|
||||
.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
|
||||
|
||||
Create a memoryview object to a contiguous chunk of memory (in either
|
||||
'C' or 'F'ortran *order*) from an object that defines the buffer
|
||||
interface. If memory is contiguous, the memoryview object points to the
|
||||
original memory. Otherwise, a copy is made and the memoryview points to a
|
||||
new bytes object.
|
||||
|
||||
|
||||
.. c:function:: int PyMemoryView_Check(PyObject *obj)
|
||||
|
||||
Return true if the object *obj* is a memoryview object. It is not
|
||||
currently allowed to create subclasses of :class:`memoryview`.
|
||||
|
||||
|
||||
.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)
|
||||
|
||||
Return a pointer to the memoryview's private copy of the exporter's buffer.
|
||||
*mview* **must** be a memoryview instance; this macro doesn't check its type,
|
||||
you must do it yourself or you will risk crashes.
|
||||
|
||||
.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)
|
||||
|
||||
Return either a pointer to the exporting object that the memoryview is based
|
||||
on or *NULL* if the memoryview has been created by one of the functions
|
||||
:c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`.
|
||||
*mview* **must** be a memoryview instance.
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _instancemethod-objects:
|
||||
|
||||
Instance Method Objects
|
||||
-----------------------
|
||||
|
||||
.. index:: object: instancemethod
|
||||
|
||||
An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
|
||||
to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
|
||||
``PyMethod_New(func, NULL, class)``.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyInstanceMethod_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python instance
|
||||
method type. It is not exposed to Python programs.
|
||||
|
||||
|
||||
.. c:function:: int PyInstanceMethod_Check(PyObject *o)
|
||||
|
||||
Return true if *o* is an instance method object (has type
|
||||
:c:data:`PyInstanceMethod_Type`). The parameter must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
|
||||
|
||||
Return a new instance method object, with *func* being any callable object
|
||||
*func* is the function that will be called when the instance method is
|
||||
called.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyInstanceMethod_Function(PyObject *im)
|
||||
|
||||
Return the function object associated with the instance method *im*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
|
||||
|
||||
Macro version of :c:func:`PyInstanceMethod_Function` which avoids error checking.
|
||||
|
||||
|
||||
.. _method-objects:
|
||||
|
||||
Method Objects
|
||||
--------------
|
||||
|
||||
.. index:: object: method
|
||||
|
||||
Methods are bound function objects. Methods are always bound to an instance of
|
||||
an user-defined class. Unbound methods (methods bound to a class object) are
|
||||
no longer available.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyMethod_Type
|
||||
|
||||
.. index:: single: MethodType (in module types)
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python method type. This
|
||||
is exposed to Python programs as ``types.MethodType``.
|
||||
|
||||
|
||||
.. c:function:: int PyMethod_Check(PyObject *o)
|
||||
|
||||
Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The
|
||||
parameter must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
|
||||
|
||||
Return a new method object, with *func* being any callable object and *self*
|
||||
the instance the method should be bound. *func* is the function that will
|
||||
be called when the method is called. *self* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMethod_Function(PyObject *meth)
|
||||
|
||||
Return the function object associated with the method *meth*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
|
||||
|
||||
Macro version of :c:func:`PyMethod_Function` which avoids error checking.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMethod_Self(PyObject *meth)
|
||||
|
||||
Return the instance associated with the method *meth*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
|
||||
|
||||
Macro version of :c:func:`PyMethod_Self` which avoids error checking.
|
||||
|
||||
|
||||
.. c:function:: int PyMethod_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
|
@ -0,0 +1,264 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _moduleobjects:
|
||||
|
||||
Module Objects
|
||||
--------------
|
||||
|
||||
.. index:: object: module
|
||||
|
||||
There are only a few functions special to module objects.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyModule_Type
|
||||
|
||||
.. index:: single: ModuleType (in module types)
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python module type. This
|
||||
is exposed to Python programs as ``types.ModuleType``.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a module object, or a subtype of a module object.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a module object, but not a subtype of
|
||||
:c:data:`PyModule_Type`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
|
||||
|
||||
.. index::
|
||||
single: __name__ (module attribute)
|
||||
single: __doc__ (module attribute)
|
||||
single: __file__ (module attribute)
|
||||
single: __package__ (module attribute)
|
||||
single: __loader__ (module attribute)
|
||||
|
||||
Return a new module object with the :attr:`__name__` attribute set to *name*.
|
||||
The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
|
||||
:attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
|
||||
to ``None``); the caller is responsible for providing a :attr:`__file__`
|
||||
attribute.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
:attr:`__package__` and :attr:`__loader__` are set to ``None``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_New(const char *name)
|
||||
|
||||
Similar to :c:func:`PyImport_NewObject`, but the name is an UTF-8 encoded
|
||||
string instead of a Unicode object.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
|
||||
|
||||
.. index:: single: __dict__ (module attribute)
|
||||
|
||||
Return the dictionary object that implements *module*'s namespace; this object
|
||||
is the same as the :attr:`__dict__` attribute of the module object. This
|
||||
function never fails. It is recommended extensions use other
|
||||
:c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
|
||||
manipulate a module's :attr:`__dict__`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
|
||||
|
||||
.. index::
|
||||
single: __name__ (module attribute)
|
||||
single: SystemError (built-in exception)
|
||||
|
||||
Return *module*'s :attr:`__name__` value. If the module does not provide one,
|
||||
or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: char* PyModule_GetName(PyObject *module)
|
||||
|
||||
Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
|
||||
``'utf-8'``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
|
||||
|
||||
.. index::
|
||||
single: __file__ (module attribute)
|
||||
single: SystemError (built-in exception)
|
||||
|
||||
Return the name of the file from which *module* was loaded using *module*'s
|
||||
:attr:`__file__` attribute. If this is not defined, or if it is not a
|
||||
unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
|
||||
a reference to a Unicode object.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. c:function:: char* PyModule_GetFilename(PyObject *module)
|
||||
|
||||
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
|
||||
encoded to 'utf-8'.
|
||||
|
||||
.. deprecated:: 3.2
|
||||
:c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
|
||||
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
|
||||
|
||||
|
||||
.. c:function:: void* PyModule_GetState(PyObject *module)
|
||||
|
||||
Return the "state" of the module, that is, a pointer to the block of memory
|
||||
allocated at module creation time, or *NULL*. See
|
||||
:c:member:`PyModuleDef.m_size`.
|
||||
|
||||
|
||||
.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
|
||||
|
||||
Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
|
||||
created, or *NULL* if the module wasn't created with
|
||||
:c:func:`PyModule_Create`.
|
||||
|
||||
.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
|
||||
|
||||
Returns the module object that was created from *def* for the current interpreter.
|
||||
This method requires that the module object has been attached to the interpreter state with
|
||||
:c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
|
||||
found or has not been attached to the interpreter state yet, it returns NULL.
|
||||
|
||||
.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
|
||||
|
||||
Attaches the module object passed to the function to the interpreter state. This allows
|
||||
the module object to be accessible via
|
||||
:c:func:`PyState_FindModule`.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
|
||||
|
||||
Removes the module object created from *def* from the interpreter state.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
Initializing C modules
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
These functions are usually used in the module initialization function.
|
||||
|
||||
.. c:function:: PyObject* PyModule_Create(PyModuleDef *module)
|
||||
|
||||
Create a new module object, given the definition in *module*. This behaves
|
||||
like :c:func:`PyModule_Create2` with *module_api_version* set to
|
||||
:const:`PYTHON_API_VERSION`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyModule_Create2(PyModuleDef *module, int module_api_version)
|
||||
|
||||
Create a new module object, given the definition in *module*, assuming the
|
||||
API version *module_api_version*. If that version does not match the version
|
||||
of the running interpreter, a :exc:`RuntimeWarning` is emitted.
|
||||
|
||||
.. note::
|
||||
|
||||
Most uses of this function should be using :c:func:`PyModule_Create`
|
||||
instead; only use this if you are sure you need it.
|
||||
|
||||
|
||||
.. c:type:: PyModuleDef
|
||||
|
||||
This struct holds all information that is needed to create a module object.
|
||||
There is usually only one static variable of that type for each module, which
|
||||
is statically initialized and then passed to :c:func:`PyModule_Create` in the
|
||||
module initialization function.
|
||||
|
||||
.. c:member:: PyModuleDef_Base m_base
|
||||
|
||||
Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
|
||||
|
||||
.. c:member:: char* m_name
|
||||
|
||||
Name for the new module.
|
||||
|
||||
.. c:member:: char* m_doc
|
||||
|
||||
Docstring for the module; usually a docstring variable created with
|
||||
:c:func:`PyDoc_STRVAR` is used.
|
||||
|
||||
.. c:member:: Py_ssize_t m_size
|
||||
|
||||
Some modules allow re-initialization (calling their ``PyInit_*`` function
|
||||
more than once). These modules should keep their state in a per-module
|
||||
memory area that can be retrieved with :c:func:`PyModule_GetState`.
|
||||
|
||||
This memory should be used, rather than static globals, to hold per-module
|
||||
state, since it is then safe for use in multiple sub-interpreters. It is
|
||||
freed when the module object is deallocated, after the :c:member:`m_free`
|
||||
function has been called, if present.
|
||||
|
||||
Setting ``m_size`` to ``-1`` means that the module can not be
|
||||
re-initialized because it has global state. Setting it to a non-negative
|
||||
value means that the module can be re-initialized and specifies the
|
||||
additional amount of memory it requires for its state.
|
||||
|
||||
See :PEP:`3121` for more details.
|
||||
|
||||
.. c:member:: PyMethodDef* m_methods
|
||||
|
||||
A pointer to a table of module-level functions, described by
|
||||
:c:type:`PyMethodDef` values. Can be *NULL* if no functions are present.
|
||||
|
||||
.. c:member:: inquiry m_reload
|
||||
|
||||
Currently unused, should be *NULL*.
|
||||
|
||||
.. c:member:: traverseproc m_traverse
|
||||
|
||||
A traversal function to call during GC traversal of the module object, or
|
||||
*NULL* if not needed.
|
||||
|
||||
.. c:member:: inquiry m_clear
|
||||
|
||||
A clear function to call during GC clearing of the module object, or
|
||||
*NULL* if not needed.
|
||||
|
||||
.. c:member:: freefunc m_free
|
||||
|
||||
A function to call during deallocation of the module object, or *NULL* if
|
||||
not needed.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
|
||||
|
||||
Add an object to *module* as *name*. This is a convenience function which can
|
||||
be used from the module's initialization function. This steals a reference to
|
||||
*value*. Return ``-1`` on error, ``0`` on success.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
|
||||
|
||||
Add an integer constant to *module* as *name*. This convenience function can be
|
||||
used from the module's initialization function. Return ``-1`` on error, ``0`` on
|
||||
success.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
|
||||
|
||||
Add a string constant to *module* as *name*. This convenience function can be
|
||||
used from the module's initialization function. The string *value* must be
|
||||
null-terminated. Return ``-1`` on error, ``0`` on success.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
|
||||
|
||||
Add an int constant to *module*. The name and the value are taken from
|
||||
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
|
||||
constant *AF_INET* with the value of *AF_INET* to *module*.
|
||||
Return ``-1`` on error, ``0`` on success.
|
||||
|
||||
|
||||
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
|
||||
|
||||
Add a string constant to *module*.
|
|
@ -0,0 +1,26 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _noneobject:
|
||||
|
||||
The None Object
|
||||
---------------
|
||||
|
||||
.. index:: object: None
|
||||
|
||||
Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
|
||||
Python/C API. Since ``None`` is a singleton, testing for object identity (using
|
||||
``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
|
||||
same reason.
|
||||
|
||||
|
||||
.. c:var:: PyObject* Py_None
|
||||
|
||||
The Python ``None`` object, denoting lack of value. This object has no methods.
|
||||
It needs to be treated just like any other object with respect to reference
|
||||
counts.
|
||||
|
||||
|
||||
.. c:macro:: Py_RETURN_NONE
|
||||
|
||||
Properly handle returning :c:data:`Py_None` from within a C function (that is,
|
||||
increment the reference count of None and return it.)
|
|
@ -0,0 +1,265 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _number:
|
||||
|
||||
Number Protocol
|
||||
===============
|
||||
|
||||
|
||||
.. c:function:: int PyNumber_Check(PyObject *o)
|
||||
|
||||
Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
|
||||
This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is the
|
||||
equivalent of the Python expression ``o1 + o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. This is
|
||||
the equivalent of the Python expression ``o1 - o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This is
|
||||
the equivalent of the Python expression ``o1 * o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
|
||||
|
||||
Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is
|
||||
equivalent to the "classic" division of integers.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
|
||||
|
||||
Return a reasonable approximation for the mathematical value of *o1* divided by
|
||||
*o2*, or *NULL* on failure. The return value is "approximate" because binary
|
||||
floating point numbers are approximate; it is not possible to represent all real
|
||||
numbers in base two. This function can return a floating point value when
|
||||
passed two integers.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is
|
||||
the equivalent of the Python expression ``o1 % o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
|
||||
|
||||
.. index:: builtin: divmod
|
||||
|
||||
See the built-in function :func:`divmod`. Returns *NULL* on failure. This is
|
||||
the equivalent of the Python expression ``divmod(o1, o2)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
|
||||
|
||||
.. index:: builtin: pow
|
||||
|
||||
See the built-in function :func:`pow`. Returns *NULL* on failure. This is the
|
||||
equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
|
||||
If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for
|
||||
*o3* would cause an illegal memory access).
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Negative(PyObject *o)
|
||||
|
||||
Returns the negation of *o* on success, or *NULL* on failure. This is the
|
||||
equivalent of the Python expression ``-o``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Positive(PyObject *o)
|
||||
|
||||
Returns *o* on success, or *NULL* on failure. This is the equivalent of the
|
||||
Python expression ``+o``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
|
||||
|
||||
.. index:: builtin: abs
|
||||
|
||||
Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent
|
||||
of the Python expression ``abs(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Invert(PyObject *o)
|
||||
|
||||
Returns the bitwise negation of *o* on success, or *NULL* on failure. This is
|
||||
the equivalent of the Python expression ``~o``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``o1 << o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``o1 >> o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``o1 & o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``o1 ^ o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``o1 | o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation
|
||||
is done *in-place* when *o1* supports it. This is the equivalent of the Python
|
||||
statement ``o1 += o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The
|
||||
operation is done *in-place* when *o1* supports it. This is the equivalent of
|
||||
the Python statement ``o1 -= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The
|
||||
operation is done *in-place* when *o1* supports it. This is the equivalent of
|
||||
the Python statement ``o1 *= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
|
||||
The operation is done *in-place* when *o1* supports it. This is the equivalent
|
||||
of the Python statement ``o1 //= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
|
||||
|
||||
Return a reasonable approximation for the mathematical value of *o1* divided by
|
||||
*o2*, or *NULL* on failure. The return value is "approximate" because binary
|
||||
floating point numbers are approximate; it is not possible to represent all real
|
||||
numbers in base two. This function can return a floating point value when
|
||||
passed two integers. The operation is done *in-place* when *o1* supports it.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The
|
||||
operation is done *in-place* when *o1* supports it. This is the equivalent of
|
||||
the Python statement ``o1 %= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
|
||||
|
||||
.. index:: builtin: pow
|
||||
|
||||
See the built-in function :func:`pow`. Returns *NULL* on failure. The operation
|
||||
is done *in-place* when *o1* supports it. This is the equivalent of the Python
|
||||
statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
|
||||
``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
|
||||
in its place (passing *NULL* for *o3* would cause an illegal memory access).
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
|
||||
failure. The operation is done *in-place* when *o1* supports it. This is the
|
||||
equivalent of the Python statement ``o1 <<= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
|
||||
failure. The operation is done *in-place* when *o1* supports it. This is the
|
||||
equivalent of the Python statement ``o1 >>= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
|
||||
operation is done *in-place* when *o1* supports it. This is the equivalent of
|
||||
the Python statement ``o1 &= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
|
||||
failure. The operation is done *in-place* when *o1* supports it. This is the
|
||||
equivalent of the Python statement ``o1 ^= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
|
||||
|
||||
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. The
|
||||
operation is done *in-place* when *o1* supports it. This is the equivalent of
|
||||
the Python statement ``o1 |= o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Long(PyObject *o)
|
||||
|
||||
.. index:: builtin: int
|
||||
|
||||
Returns the *o* converted to an integer object on success, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``int(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Float(PyObject *o)
|
||||
|
||||
.. index:: builtin: float
|
||||
|
||||
Returns the *o* converted to a float object on success, or *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``float(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_Index(PyObject *o)
|
||||
|
||||
Returns the *o* converted to a Python int on success or *NULL* with a
|
||||
:exc:`TypeError` exception raised on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
|
||||
|
||||
Returns the integer *n* converted to base *base* as a string. The *base*
|
||||
argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the
|
||||
returned string is prefixed with a base marker of ``'0b'``, ``'0o'``, or
|
||||
``'0x'``, respectively. If *n* is not a Python int, it is converted with
|
||||
:c:func:`PyNumber_Index` first.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
|
||||
|
||||
Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
|
||||
integer. If the call fails, an exception is raised and -1 is returned.
|
||||
|
||||
If *o* can be converted to a Python int but the attempt to
|
||||
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
|
||||
*exc* argument is the type of exception that will be raised (usually
|
||||
:exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the
|
||||
exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
|
||||
integer or *PY_SSIZE_T_MAX* for a positive integer.
|
||||
|
||||
|
||||
.. c:function:: int PyIndex_Check(PyObject *o)
|
||||
|
||||
Returns True if *o* is an index integer (has the nb_index slot of the
|
||||
tp_as_number structure filled in).
|
|
@ -0,0 +1,51 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
Old Buffer Protocol
|
||||
-------------------
|
||||
|
||||
.. deprecated:: 3.0
|
||||
|
||||
These functions were part of the "old buffer protocol" API in Python 2.
|
||||
In Python 3, this protocol doesn't exist anymore but the functions are still
|
||||
exposed to ease porting 2.x code. They act as a compatibility wrapper
|
||||
around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
|
||||
you control over the lifetime of the resources acquired when a buffer is
|
||||
exported.
|
||||
|
||||
Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer`
|
||||
(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
|
||||
:c:func:`PyArg_ParseTuple` family of functions) to get a buffer view over
|
||||
an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
|
||||
|
||||
Returns a pointer to a read-only memory location usable as character-based
|
||||
input. The *obj* argument must support the single-segment character buffer
|
||||
interface. On success, returns ``0``, sets *buffer* to the memory location
|
||||
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
|
||||
:exc:`TypeError` on error.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
|
||||
|
||||
Returns a pointer to a read-only memory location containing arbitrary data.
|
||||
The *obj* argument must support the single-segment readable buffer
|
||||
interface. On success, returns ``0``, sets *buffer* to the memory location
|
||||
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
|
||||
:exc:`TypeError` on error.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
|
||||
|
||||
Returns ``1`` if *o* supports the single-segment readable buffer interface.
|
||||
Otherwise returns ``0``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
|
||||
|
||||
Returns a pointer to a writable memory location. The *obj* argument must
|
||||
support the single-segment, character buffer interface. On success,
|
||||
returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
|
||||
buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
|
||||
|
|
@ -0,0 +1,400 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _object:
|
||||
|
||||
Object Protocol
|
||||
===============
|
||||
|
||||
|
||||
.. c:var:: PyObject* Py_NotImplemented
|
||||
|
||||
The ``NotImplemented`` singleton, used to signal that an operation is
|
||||
not implemented for the given type combination.
|
||||
|
||||
|
||||
.. c:macro:: Py_RETURN_NOTIMPLEMENTED
|
||||
|
||||
Properly handle returning :c:data:`Py_NotImplemented` from within a C
|
||||
function (that is, increment the reference count of NotImplemented and
|
||||
return it).
|
||||
|
||||
|
||||
.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
|
||||
|
||||
Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
|
||||
is used to enable certain printing options. The only option currently supported
|
||||
is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
|
||||
instead of the :func:`repr`.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
|
||||
|
||||
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
|
||||
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
|
||||
always succeeds.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
|
||||
|
||||
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
|
||||
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
|
||||
always succeeds.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
|
||||
|
||||
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
|
||||
value on success, or *NULL* on failure. This is the equivalent of the Python
|
||||
expression ``o.attr_name``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
|
||||
|
||||
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
|
||||
value on success, or *NULL* on failure. This is the equivalent of the Python
|
||||
expression ``o.attr_name``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
|
||||
|
||||
Generic attribute getter function that is meant to be put into a type
|
||||
object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
|
||||
of classes in the object's MRO as well as an attribute in the object's
|
||||
:attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`,
|
||||
data descriptors take preference over instance attributes, while non-data
|
||||
descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
|
||||
|
||||
Set the value of the attribute named *attr_name*, for object *o*, to the value
|
||||
*v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
|
||||
``o.attr_name = v``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
|
||||
|
||||
Set the value of the attribute named *attr_name*, for object *o*, to the value
|
||||
*v*. Returns ``-1`` on failure. This is the equivalent of the Python statement
|
||||
``o.attr_name = v``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
|
||||
|
||||
Generic attribute setter function that is meant to be put into a type
|
||||
object's ``tp_setattro`` slot. It looks for a data descriptor in the
|
||||
dictionary of classes in the object's MRO, and if found it takes preference
|
||||
over setting the attribute in the instance dictionary. Otherwise, the
|
||||
attribute is set in the object's :attr:`~object.__dict__` (if present).
|
||||
Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
|
||||
|
||||
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
|
||||
This is the equivalent of the Python statement ``del o.attr_name``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
|
||||
|
||||
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
|
||||
This is the equivalent of the Python statement ``del o.attr_name``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyType_GenericGetDict(PyObject *o, void *context)
|
||||
|
||||
A generic implementation for the getter of a ``__dict__`` descriptor. It
|
||||
creates the dictionary if necessary.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: int PyType_GenericSetDict(PyObject *o, void *context)
|
||||
|
||||
A generic implementation for the setter of a ``__dict__`` descriptor. This
|
||||
implementation does not allow the dictionary to be deleted.
|
||||
|
||||
.. versionadded:: 3.3
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
|
||||
|
||||
Compare the values of *o1* and *o2* using the operation specified by *opid*,
|
||||
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
|
||||
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
|
||||
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
|
||||
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
|
||||
to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
|
||||
|
||||
Compare the values of *o1* and *o2* using the operation specified by *opid*,
|
||||
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
|
||||
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
|
||||
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
|
||||
``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
|
||||
Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
|
||||
*opid*.
|
||||
|
||||
.. note::
|
||||
If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
|
||||
will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
|
||||
|
||||
.. c:function:: PyObject* PyObject_Repr(PyObject *o)
|
||||
|
||||
.. index:: builtin: repr
|
||||
|
||||
Compute a string representation of object *o*. Returns the string
|
||||
representation on success, *NULL* on failure. This is the equivalent of the
|
||||
Python expression ``repr(o)``. Called by the :func:`repr` built-in function.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
This function now includes a debug assertion to help ensure that it
|
||||
does not silently discard an active exception.
|
||||
|
||||
.. c:function:: PyObject* PyObject_ASCII(PyObject *o)
|
||||
|
||||
.. index:: builtin: ascii
|
||||
|
||||
As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
|
||||
escape the non-ASCII characters in the string returned by
|
||||
:c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates
|
||||
a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
|
||||
Called by the :func:`ascii` built-in function.
|
||||
|
||||
.. index:: string; PyObject_Str (C function)
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Str(PyObject *o)
|
||||
|
||||
Compute a string representation of object *o*. Returns the string
|
||||
representation on success, *NULL* on failure. This is the equivalent of the
|
||||
Python expression ``str(o)``. Called by the :func:`str` built-in function
|
||||
and, therefore, by the :func:`print` function.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
This function now includes a debug assertion to help ensure that it
|
||||
does not silently discard an active exception.
|
||||
|
||||
.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
|
||||
|
||||
.. index:: builtin: bytes
|
||||
|
||||
Compute a bytes representation of object *o*. *NULL* is returned on
|
||||
failure and a bytes object on success. This is equivalent to the Python
|
||||
expression ``bytes(o)``, when *o* is not an integer. Unlike ``bytes(o)``,
|
||||
a TypeError is raised when *o* is an integer instead of a zero-initialized
|
||||
bytes object.
|
||||
|
||||
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
|
||||
|
||||
Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
|
||||
*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
|
||||
*cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`
|
||||
returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
|
||||
be done against every entry in *cls*. The result will be ``1`` when at least one
|
||||
of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
|
||||
class instance and *cls* is neither a type object, nor a class object, nor a
|
||||
tuple, *inst* must have a :attr:`~instance.__class__` attribute --- the
|
||||
class relationship of the value of that attribute with *cls* will be used
|
||||
to determine the result of this function.
|
||||
|
||||
|
||||
Subclass determination is done in a fairly straightforward way, but includes a
|
||||
wrinkle that implementors of extensions to the class system may want to be aware
|
||||
of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
|
||||
:class:`A` if it inherits from :class:`A` either directly or indirectly. If
|
||||
either is not a class object, a more general mechanism is used to determine the
|
||||
class relationship of the two objects. When testing if *B* is a subclass of
|
||||
*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
|
||||
are different objects, *B*'s :attr:`~class.__bases__` attribute is searched in
|
||||
a depth-first fashion for *A* --- the presence of the :attr:`~class.__bases__`
|
||||
attribute is considered sufficient for this determination.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
|
||||
|
||||
Returns ``1`` if the class *derived* is identical to or derived from the class
|
||||
*cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
|
||||
is a tuple, the check will be done against every entry in *cls*. The result will
|
||||
be ``1`` when at least one of the checks returns ``1``, otherwise it will be
|
||||
``0``. If either *derived* or *cls* is not an actual class object (or tuple),
|
||||
this function uses the generic algorithm described above.
|
||||
|
||||
|
||||
.. c:function:: int PyCallable_Check(PyObject *o)
|
||||
|
||||
Determine if the object *o* is callable. Return ``1`` if the object is callable
|
||||
and ``0`` otherwise. This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
|
||||
|
||||
Call a callable Python object *callable_object*, with arguments given by the
|
||||
tuple *args*, and named arguments given by the dictionary *kw*. If no named
|
||||
arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
|
||||
empty tuple if no arguments are needed. Returns the result of the call on
|
||||
success, or *NULL* on failure. This is the equivalent of the Python expression
|
||||
``callable_object(*args, **kw)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
|
||||
|
||||
Call a callable Python object *callable_object*, with arguments given by the
|
||||
tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
|
||||
the result of the call on success, or *NULL* on failure. This is the equivalent
|
||||
of the Python expression ``callable_object(*args)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
|
||||
|
||||
Call a callable Python object *callable*, with a variable number of C arguments.
|
||||
The C arguments are described using a :c:func:`Py_BuildValue` style format
|
||||
string. The format may be *NULL*, indicating that no arguments are provided.
|
||||
Returns the result of the call on success, or *NULL* on failure. This is the
|
||||
equivalent of the Python expression ``callable(*args)``. Note that if you only
|
||||
pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a
|
||||
faster alternative.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The type of *format* was changed from ``char *``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...)
|
||||
|
||||
Call the method named *method* of object *o* with a variable number of C
|
||||
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
|
||||
string that should produce a tuple. The format may be *NULL*, indicating that
|
||||
no arguments are provided. Returns the result of the call on success, or *NULL*
|
||||
on failure. This is the equivalent of the Python expression ``o.method(args)``.
|
||||
Note that if you only pass :c:type:`PyObject \*` args,
|
||||
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
The types of *method* and *format* were changed from ``char *``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
|
||||
|
||||
Call a callable Python object *callable*, with a variable number of
|
||||
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
|
||||
of parameters followed by *NULL*. Returns the result of the call on success, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
|
||||
|
||||
Calls a method of the object *o*, where the name of the method is given as a
|
||||
Python string object in *name*. It is called with a variable number of
|
||||
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
|
||||
of parameters followed by *NULL*. Returns the result of the call on success, or
|
||||
*NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
|
||||
|
||||
.. index:: builtin: hash
|
||||
|
||||
Compute and return the hash value of an object *o*. On failure, return ``-1``.
|
||||
This is the equivalent of the Python expression ``hash(o)``.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The return type is now Py_hash_t. This is a signed integer the same size
|
||||
as Py_ssize_t.
|
||||
|
||||
|
||||
.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
|
||||
|
||||
Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
|
||||
This function receives special treatment when stored in a ``tp_hash`` slot,
|
||||
allowing a type to explicitly indicate to the interpreter that it is not
|
||||
hashable.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_IsTrue(PyObject *o)
|
||||
|
||||
Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
|
||||
This is equivalent to the Python expression ``not not o``. On failure, return
|
||||
``-1``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_Not(PyObject *o)
|
||||
|
||||
Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
|
||||
This is equivalent to the Python expression ``not o``. On failure, return
|
||||
``-1``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Type(PyObject *o)
|
||||
|
||||
.. index:: builtin: type
|
||||
|
||||
When *o* is non-*NULL*, returns a type object corresponding to the object type
|
||||
of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
|
||||
is equivalent to the Python expression ``type(o)``. This function increments the
|
||||
reference count of the return value. There's really no reason to use this
|
||||
function instead of the common expression ``o->ob_type``, which returns a
|
||||
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
|
||||
count is needed.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
|
||||
|
||||
Return true if the object *o* is of type *type* or a subtype of *type*. Both
|
||||
parameters must be non-*NULL*.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
|
||||
Py_ssize_t PyObject_Size(PyObject *o)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Return the length of object *o*. If the object *o* provides either the sequence
|
||||
and mapping protocols, the sequence length is returned. On error, ``-1`` is
|
||||
returned. This is the equivalent to the Python expression ``len(o)``.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
|
||||
|
||||
Return an estimated length for the object *o*. First try to return its
|
||||
actual length, then an estimate using :meth:`~object.__length_hint__`, and
|
||||
finally return the default value. On error return ``-1``. This is the
|
||||
equivalent to the Python expression ``operator.length_hint(o, default)``.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
|
||||
|
||||
Return element of *o* corresponding to the object *key* or *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``o[key]``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
|
||||
|
||||
Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the
|
||||
equivalent of the Python statement ``o[key] = v``.
|
||||
|
||||
|
||||
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
|
||||
|
||||
Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
|
||||
equivalent of the Python statement ``del o[key]``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_Dir(PyObject *o)
|
||||
|
||||
This is equivalent to the Python expression ``dir(o)``, returning a (possibly
|
||||
empty) list of strings appropriate for the object argument, or *NULL* if there
|
||||
was an error. If the argument is *NULL*, this is like the Python ``dir()``,
|
||||
returning the names of the current locals; in this case, if no execution frame
|
||||
is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyObject_GetIter(PyObject *o)
|
||||
|
||||
This is equivalent to the Python expression ``iter(o)``. It returns a new
|
||||
iterator for the object argument, or the object itself if the object is already
|
||||
an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
|
||||
iterated.
|
|
@ -0,0 +1,17 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _newtypes:
|
||||
|
||||
*****************************
|
||||
Object Implementation Support
|
||||
*****************************
|
||||
|
||||
This chapter describes the functions, types, and macros used when defining new
|
||||
object types.
|
||||
|
||||
.. toctree::
|
||||
|
||||
allocation.rst
|
||||
structures.rst
|
||||
typeobj.rst
|
||||
gcsupport.rst
|
|
@ -0,0 +1,73 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
|
||||
.. _countingrefs:
|
||||
|
||||
******************
|
||||
Reference Counting
|
||||
******************
|
||||
|
||||
The macros in this section are used for managing reference counts of Python
|
||||
objects.
|
||||
|
||||
|
||||
.. c:function:: void Py_INCREF(PyObject *o)
|
||||
|
||||
Increment the reference count for object *o*. The object must not be *NULL*; if
|
||||
you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`.
|
||||
|
||||
|
||||
.. c:function:: void Py_XINCREF(PyObject *o)
|
||||
|
||||
Increment the reference count for object *o*. The object may be *NULL*, in
|
||||
which case the macro has no effect.
|
||||
|
||||
|
||||
.. c:function:: void Py_DECREF(PyObject *o)
|
||||
|
||||
Decrement the reference count for object *o*. The object must not be *NULL*; if
|
||||
you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`. If the reference
|
||||
count reaches zero, the object's type's deallocation function (which must not be
|
||||
*NULL*) is invoked.
|
||||
|
||||
.. warning::
|
||||
|
||||
The deallocation function can cause arbitrary Python code to be invoked (e.g.
|
||||
when a class instance with a :meth:`__del__` method is deallocated). While
|
||||
exceptions in such code are not propagated, the executed code has free access to
|
||||
all Python global variables. This means that any object that is reachable from
|
||||
a global variable should be in a consistent state before :c:func:`Py_DECREF` is
|
||||
invoked. For example, code to delete an object from a list should copy a
|
||||
reference to the deleted object in a temporary variable, update the list data
|
||||
structure, and then call :c:func:`Py_DECREF` for the temporary variable.
|
||||
|
||||
|
||||
.. c:function:: void Py_XDECREF(PyObject *o)
|
||||
|
||||
Decrement the reference count for object *o*. The object may be *NULL*, in
|
||||
which case the macro has no effect; otherwise the effect is the same as for
|
||||
:c:func:`Py_DECREF`, and the same warning applies.
|
||||
|
||||
|
||||
.. c:function:: void Py_CLEAR(PyObject *o)
|
||||
|
||||
Decrement the reference count for object *o*. The object may be *NULL*, in
|
||||
which case the macro has no effect; otherwise the effect is the same as for
|
||||
:c:func:`Py_DECREF`, except that the argument is also set to *NULL*. The warning
|
||||
for :c:func:`Py_DECREF` does not apply with respect to the object passed because
|
||||
the macro carefully uses a temporary variable and sets the argument to *NULL*
|
||||
before decrementing its reference count.
|
||||
|
||||
It is a good idea to use this macro whenever decrementing the value of a
|
||||
variable that might be traversed during garbage collection.
|
||||
|
||||
|
||||
The following functions are for runtime dynamic embedding of Python:
|
||||
``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are
|
||||
simply exported function versions of :c:func:`Py_XINCREF` and
|
||||
:c:func:`Py_XDECREF`, respectively.
|
||||
|
||||
The following functions or macros are only for use within the interpreter core:
|
||||
:c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:`_Py_NewReference`,
|
||||
as well as the global variable :c:data:`_Py_RefTotal`.
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _reflection:
|
||||
|
||||
Reflection
|
||||
==========
|
||||
|
||||
.. c:function:: PyObject* PyEval_GetBuiltins()
|
||||
|
||||
Return a dictionary of the builtins in the current execution frame,
|
||||
or the interpreter of the thread state if no frame is currently executing.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyEval_GetLocals()
|
||||
|
||||
Return a dictionary of the local variables in the current execution frame,
|
||||
or *NULL* if no frame is currently executing.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyEval_GetGlobals()
|
||||
|
||||
Return a dictionary of the global variables in the current execution frame,
|
||||
or *NULL* if no frame is currently executing.
|
||||
|
||||
|
||||
.. c:function:: PyFrameObject* PyEval_GetFrame()
|
||||
|
||||
Return the current thread state's frame, which is *NULL* if no frame is
|
||||
currently executing.
|
||||
|
||||
|
||||
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
|
||||
|
||||
Return the line number that *frame* is currently executing.
|
||||
|
||||
|
||||
.. c:function:: const char* PyEval_GetFuncName(PyObject *func)
|
||||
|
||||
Return the name of *func* if it is a function, class or instance object, else the
|
||||
name of *func*\s type.
|
||||
|
||||
|
||||
.. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
|
||||
|
||||
Return a description string, depending on the type of *func*.
|
||||
Return values include "()" for functions and methods, " constructor",
|
||||
" instance", and " object". Concatenated with the result of
|
||||
:c:func:`PyEval_GetFuncName`, the result will be a description of
|
||||
*func*.
|
|
@ -0,0 +1,162 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _sequence:
|
||||
|
||||
Sequence Protocol
|
||||
=================
|
||||
|
||||
|
||||
.. c:function:: int PySequence_Check(PyObject *o)
|
||||
|
||||
Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
|
||||
This function always succeeds.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
|
||||
Py_ssize_t PySequence_Length(PyObject *o)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
|
||||
For objects that do not provide sequence protocol, this is equivalent to the
|
||||
Python expression ``len(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
|
||||
|
||||
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
|
||||
This is the equivalent of the Python expression ``o1 + o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
|
||||
|
||||
Return the result of repeating sequence object *o* *count* times, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``o * count``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
|
||||
|
||||
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
|
||||
The operation is done *in-place* when *o1* supports it. This is the equivalent
|
||||
of the Python expression ``o1 += o2``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
|
||||
|
||||
Return the result of repeating sequence object *o* *count* times, or *NULL* on
|
||||
failure. The operation is done *in-place* when *o* supports it. This is the
|
||||
equivalent of the Python expression ``o *= count``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
|
||||
|
||||
Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
|
||||
the Python expression ``o[i]``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
|
||||
|
||||
Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
|
||||
failure. This is the equivalent of the Python expression ``o[i1:i2]``.
|
||||
|
||||
|
||||
.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
|
||||
|
||||
Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This
|
||||
is the equivalent of the Python statement ``o[i] = v``. This function *does
|
||||
not* steal a reference to *v*.
|
||||
|
||||
|
||||
.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
|
||||
|
||||
Delete the *i*\ th element of object *o*. Returns ``-1`` on failure. This is the
|
||||
equivalent of the Python statement ``del o[i]``.
|
||||
|
||||
|
||||
.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
|
||||
|
||||
Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
|
||||
*i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
|
||||
|
||||
|
||||
.. c:function:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
|
||||
|
||||
Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
|
||||
failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
|
||||
|
||||
Return the number of occurrences of *value* in *o*, that is, return the number
|
||||
of keys for which ``o[key] == value``. On failure, return ``-1``. This is
|
||||
equivalent to the Python expression ``o.count(value)``.
|
||||
|
||||
|
||||
.. c:function:: int PySequence_Contains(PyObject *o, PyObject *value)
|
||||
|
||||
Determine if *o* contains *value*. If an item in *o* is equal to *value*,
|
||||
return ``1``, otherwise return ``0``. On error, return ``-1``. This is
|
||||
equivalent to the Python expression ``value in o``.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
|
||||
|
||||
Return the first index *i* for which ``o[i] == value``. On error, return
|
||||
``-1``. This is equivalent to the Python expression ``o.index(value)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_List(PyObject *o)
|
||||
|
||||
Return a list object with the same contents as the arbitrary sequence *o*. The
|
||||
returned list is guaranteed to be new.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
|
||||
|
||||
.. index:: builtin: tuple
|
||||
|
||||
Return a tuple object with the same contents as the arbitrary sequence *o* or
|
||||
*NULL* on failure. If *o* is a tuple, a new reference will be returned,
|
||||
otherwise a tuple will be constructed with the appropriate contents. This is
|
||||
equivalent to the Python expression ``tuple(o)``.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)
|
||||
|
||||
Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
|
||||
which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access the
|
||||
members of the result. Returns *NULL* on failure. If the object is not a
|
||||
sequence, raises :exc:`TypeError` with *m* as the message text.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
|
||||
|
||||
Return the *i*\ th element of *o*, assuming that *o* was returned by
|
||||
:c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
|
||||
|
||||
|
||||
.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
|
||||
|
||||
Return the underlying array of PyObject pointers. Assumes that *o* was returned
|
||||
by :c:func:`PySequence_Fast` and *o* is not *NULL*.
|
||||
|
||||
Note, if a list gets resized, the reallocation may relocate the items array.
|
||||
So, only use the underlying array pointer in contexts where the sequence
|
||||
cannot change.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
|
||||
|
||||
Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
|
||||
:c:func:`PySequence_GetItem` but without checking that
|
||||
:c:func:`PySequence_Check` on *o* is true and without adjustment for negative
|
||||
indices.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
|
||||
|
||||
Returns the length of *o*, assuming that *o* was returned by
|
||||
:c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
|
||||
gotten by calling :c:func:`PySequence_Size` on *o*, but
|
||||
:c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
|
||||
or tuple.
|
|
@ -0,0 +1,166 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _setobjects:
|
||||
|
||||
Set Objects
|
||||
-----------
|
||||
|
||||
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
|
||||
|
||||
|
||||
.. index::
|
||||
object: set
|
||||
object: frozenset
|
||||
|
||||
This section details the public API for :class:`set` and :class:`frozenset`
|
||||
objects. Any functionality not listed below is best accessed using the either
|
||||
the abstract object protocol (including :c:func:`PyObject_CallMethod`,
|
||||
:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
|
||||
:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
|
||||
:c:func:`PyObject_GetIter`) or the abstract number protocol (including
|
||||
:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
|
||||
:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
|
||||
:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
|
||||
:c:func:`PyNumber_InPlaceXor`).
|
||||
|
||||
|
||||
.. c:type:: PySetObject
|
||||
|
||||
This subtype of :c:type:`PyObject` is used to hold the internal data for both
|
||||
:class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject`
|
||||
in that it is a fixed size for small sets (much like tuple storage) and will
|
||||
point to a separate, variable sized block of memory for medium and large sized
|
||||
sets (much like list storage). None of the fields of this structure should be
|
||||
considered public and are subject to change. All access should be done through
|
||||
the documented API rather than by manipulating the values in the structure.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PySet_Type
|
||||
|
||||
This is an instance of :c:type:`PyTypeObject` representing the Python
|
||||
:class:`set` type.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyFrozenSet_Type
|
||||
|
||||
This is an instance of :c:type:`PyTypeObject` representing the Python
|
||||
:class:`frozenset` type.
|
||||
|
||||
The following type check macros work on pointers to any Python object. Likewise,
|
||||
the constructor functions work with any iterable Python object.
|
||||
|
||||
|
||||
.. c:function:: int PySet_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a :class:`set` object or an instance of a subtype.
|
||||
|
||||
.. c:function:: int PyFrozenSet_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a :class:`frozenset` object or an instance of a
|
||||
subtype.
|
||||
|
||||
.. c:function:: int PyAnySet_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
|
||||
instance of a subtype.
|
||||
|
||||
|
||||
.. c:function:: int PyAnySet_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
|
||||
not an instance of a subtype.
|
||||
|
||||
|
||||
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a :class:`frozenset` object but not an instance of a
|
||||
subtype.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySet_New(PyObject *iterable)
|
||||
|
||||
Return a new :class:`set` containing objects returned by the *iterable*. The
|
||||
*iterable* may be *NULL* to create a new empty set. Return the new set on
|
||||
success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not
|
||||
actually iterable. The constructor is also useful for copying a set
|
||||
(``c=set(s)``).
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
|
||||
|
||||
Return a new :class:`frozenset` containing objects returned by the *iterable*.
|
||||
The *iterable* may be *NULL* to create a new empty frozenset. Return the new
|
||||
set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
|
||||
not actually iterable.
|
||||
|
||||
|
||||
The following functions and macros are available for instances of :class:`set`
|
||||
or :class:`frozenset` or instances of their subtypes.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
|
||||
``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
|
||||
:class:`set`, :class:`frozenset`, or an instance of a subtype.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
|
||||
|
||||
Macro form of :c:func:`PySet_Size` without error checking.
|
||||
|
||||
|
||||
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
|
||||
|
||||
Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike
|
||||
the Python :meth:`__contains__` method, this function does not automatically
|
||||
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
|
||||
the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
|
||||
:class:`set`, :class:`frozenset`, or an instance of a subtype.
|
||||
|
||||
|
||||
.. c:function:: int PySet_Add(PyObject *set, PyObject *key)
|
||||
|
||||
Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
|
||||
instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
|
||||
of brand new frozensets before they are exposed to other code). Return 0 on
|
||||
success or -1 on failure. Raise a :exc:`TypeError` if the *key* is
|
||||
unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a
|
||||
:exc:`SystemError` if *set* is an not an instance of :class:`set` or its
|
||||
subtype.
|
||||
|
||||
|
||||
The following functions are available for instances of :class:`set` or its
|
||||
subtypes but not for instances of :class:`frozenset` or its subtypes.
|
||||
|
||||
|
||||
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
|
||||
|
||||
Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
|
||||
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
|
||||
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
|
||||
method, this function does not automatically convert unhashable sets into
|
||||
temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an not an
|
||||
instance of :class:`set` or its subtype.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySet_Pop(PyObject *set)
|
||||
|
||||
Return a new reference to an arbitrary object in the *set*, and removes the
|
||||
object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the
|
||||
set is empty. Raise a :exc:`SystemError` if *set* is an not an instance of
|
||||
:class:`set` or its subtype.
|
||||
|
||||
|
||||
.. c:function:: int PySet_Clear(PyObject *set)
|
||||
|
||||
Empty an existing set of all elements.
|
||||
|
||||
|
||||
.. c:function:: int PySet_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
.. versionadded:: 3.3
|
|
@ -0,0 +1,58 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _slice-objects:
|
||||
|
||||
Slice Objects
|
||||
-------------
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PySlice_Type
|
||||
|
||||
The type object for slice objects. This is the same as :class:`slice` in the
|
||||
Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PySlice_Check(PyObject *ob)
|
||||
|
||||
Return true if *ob* is a slice object; *ob* must not be *NULL*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
|
||||
|
||||
Return a new slice object with the given values. The *start*, *stop*, and
|
||||
*step* parameters are used as the values of the slice object attributes of
|
||||
the same names. Any of the values may be *NULL*, in which case the
|
||||
``None`` will be used for the corresponding attribute. Return *NULL* if
|
||||
the new object could not be allocated.
|
||||
|
||||
|
||||
.. c:function:: int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
|
||||
|
||||
Retrieve the start, stop and step indices from the slice object *slice*,
|
||||
assuming a sequence of length *length*. Treats indices greater than
|
||||
*length* as errors.
|
||||
|
||||
Returns 0 on success and -1 on error with no exception set (unless one of
|
||||
the indices was not :const:`None` and failed to be converted to an integer,
|
||||
in which case -1 is returned with an exception set).
|
||||
|
||||
You probably do not want to use this function.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The parameter type for the *slice* parameter was ``PySliceObject*``
|
||||
before.
|
||||
|
||||
|
||||
.. c:function:: int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
|
||||
|
||||
Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start,
|
||||
stop, and step indices from the slice object *slice* assuming a sequence of
|
||||
length *length*, and store the length of the slice in *slicelength*. Out
|
||||
of bounds indices are clipped in a manner consistent with the handling of
|
||||
normal slices.
|
||||
|
||||
Returns 0 on success and -1 on error with exception set.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The parameter type for the *slice* parameter was ``PySliceObject*``
|
||||
before.
|
|
@ -0,0 +1,38 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _stable:
|
||||
|
||||
***********************************
|
||||
Stable Application Binary Interface
|
||||
***********************************
|
||||
|
||||
Traditionally, the C API of Python will change with every release. Most changes
|
||||
will be source-compatible, typically by only adding API, rather than changing
|
||||
existing API or removing API (although some interfaces do get removed after
|
||||
being deprecated first).
|
||||
|
||||
Unfortunately, the API compatibility does not extend to binary compatibility
|
||||
(the ABI). The reason is primarily the evolution of struct definitions, where
|
||||
addition of a new field, or changing the type of a field, might not break the
|
||||
API, but can break the ABI. As a consequence, extension modules need to be
|
||||
recompiled for every Python release (although an exception is possible on Unix
|
||||
when none of the affected interfaces are used). In addition, on Windows,
|
||||
extension modules link with a specific pythonXY.dll and need to be recompiled to
|
||||
link with a newer one.
|
||||
|
||||
Since Python 3.2, a subset of the API has been declared to guarantee a stable
|
||||
ABI. Extension modules wishing to use this API (called "limited API") need to
|
||||
define ``Py_LIMITED_API``. A number of interpreter details then become hidden
|
||||
from the extension module; in return, a module is built that works on any 3.x
|
||||
version (x>=2) without recompilation.
|
||||
|
||||
In some cases, the stable ABI needs to be extended with new functions.
|
||||
Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API``
|
||||
to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python
|
||||
version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules
|
||||
will work on all subsequent Python releases, but fail to load (because of
|
||||
missing symbols) on the older releases.
|
||||
|
||||
As of Python 3.2, the set of functions available to the limited API is
|
||||
documented in PEP 384. In the C API documentation, API elements that are not
|
||||
part of the limited API are marked as "Not part of the limited API."
|
|
@ -0,0 +1,284 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _common-structs:
|
||||
|
||||
Common Object Structures
|
||||
========================
|
||||
|
||||
There are a large number of structures which are used in the definition of
|
||||
object types for Python. This section describes these structures and how they
|
||||
are used.
|
||||
|
||||
All Python objects ultimately share a small number of fields at the beginning
|
||||
of the object's representation in memory. These are represented by the
|
||||
:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
|
||||
by the expansions of some macros also used, whether directly or indirectly, in
|
||||
the definition of all other Python objects.
|
||||
|
||||
|
||||
.. c:type:: PyObject
|
||||
|
||||
All object types are extensions of this type. This is a type which
|
||||
contains the information Python needs to treat a pointer to an object as an
|
||||
object. In a normal "release" build, it contains only the object's
|
||||
reference count and a pointer to the corresponding type object. It
|
||||
corresponds to the fields defined by the expansion of the ``PyObject_HEAD``
|
||||
macro.
|
||||
|
||||
|
||||
.. c:type:: PyVarObject
|
||||
|
||||
This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
|
||||
field. This is only used for objects that have some notion of *length*.
|
||||
This type does not often appear in the Python/C API. It corresponds to the
|
||||
fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
|
||||
|
||||
These macros are used in the definition of :c:type:`PyObject` and
|
||||
:c:type:`PyVarObject`:
|
||||
|
||||
.. XXX need to document PEP 3123 changes here
|
||||
|
||||
.. c:macro:: PyObject_HEAD
|
||||
|
||||
This is a macro which expands to the declarations of the fields of the
|
||||
:c:type:`PyObject` type; it is used when declaring new types which represent
|
||||
objects without a varying length. The specific fields it expands to depend
|
||||
on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is
|
||||
not defined, and :c:macro:`PyObject_HEAD` expands to::
|
||||
|
||||
Py_ssize_t ob_refcnt;
|
||||
PyTypeObject *ob_type;
|
||||
|
||||
When :c:macro:`Py_TRACE_REFS` is defined, it expands to::
|
||||
|
||||
PyObject *_ob_next, *_ob_prev;
|
||||
Py_ssize_t ob_refcnt;
|
||||
PyTypeObject *ob_type;
|
||||
|
||||
|
||||
.. c:macro:: PyObject_VAR_HEAD
|
||||
|
||||
This is a macro which expands to the declarations of the fields of the
|
||||
:c:type:`PyVarObject` type; it is used when declaring new types which
|
||||
represent objects with a length that varies from instance to instance.
|
||||
This macro always expands to::
|
||||
|
||||
PyObject_HEAD
|
||||
Py_ssize_t ob_size;
|
||||
|
||||
Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own
|
||||
expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.
|
||||
|
||||
|
||||
.. c:macro:: PyObject_HEAD_INIT(type)
|
||||
|
||||
This is a macro which expands to initialization values for a new
|
||||
:c:type:`PyObject` type. This macro expands to::
|
||||
|
||||
_PyObject_EXTRA_INIT
|
||||
1, type,
|
||||
|
||||
|
||||
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
|
||||
|
||||
This is a macro which expands to initialization values for a new
|
||||
:c:type:`PyVarObject` type, including the :attr:`ob_size` field.
|
||||
This macro expands to::
|
||||
|
||||
_PyObject_EXTRA_INIT
|
||||
1, type, size,
|
||||
|
||||
|
||||
.. c:type:: PyCFunction
|
||||
|
||||
Type of the functions used to implement most Python callables in C.
|
||||
Functions of this type take two :c:type:`PyObject\*` parameters and return
|
||||
one such value. If the return value is *NULL*, an exception shall have
|
||||
been set. If not *NULL*, the return value is interpreted as the return
|
||||
value of the function as exposed in Python. The function must return a new
|
||||
reference.
|
||||
|
||||
|
||||
.. c:type:: PyCFunctionWithKeywords
|
||||
|
||||
Type of the functions used to implement Python callables in C that take
|
||||
keyword arguments: they take three :c:type:`PyObject\*` parameters and return
|
||||
one such value. See :c:type:`PyCFunction` above for the meaning of the return
|
||||
value.
|
||||
|
||||
|
||||
.. c:type:: PyMethodDef
|
||||
|
||||
Structure used to describe a method of an extension type. This structure has
|
||||
four fields:
|
||||
|
||||
+------------------+-------------+-------------------------------+
|
||||
| Field | C Type | Meaning |
|
||||
+==================+=============+===============================+
|
||||
| :attr:`ml_name` | char \* | name of the method |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`ml_meth` | PyCFunction | pointer to the C |
|
||||
| | | implementation |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`ml_flags` | int | flag bits indicating how the |
|
||||
| | | call should be constructed |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`ml_doc` | char \* | points to the contents of the |
|
||||
| | | docstring |
|
||||
+------------------+-------------+-------------------------------+
|
||||
|
||||
The :attr:`ml_meth` is a C function pointer. The functions may be of different
|
||||
types, but they always return :c:type:`PyObject\*`. If the function is not of
|
||||
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
|
||||
Even though :c:type:`PyCFunction` defines the first parameter as
|
||||
:c:type:`PyObject\*`, it is common that the method implementation uses a the
|
||||
specific C type of the *self* object.
|
||||
|
||||
The :attr:`ml_flags` field is a bitfield which can include the following flags.
|
||||
The individual flags indicate either a calling convention or a binding
|
||||
convention. Of the calling convention flags, only :const:`METH_VARARGS` and
|
||||
:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`
|
||||
alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling
|
||||
convention flags can be combined with a binding flag.
|
||||
|
||||
|
||||
.. data:: METH_VARARGS
|
||||
|
||||
This is the typical calling convention, where the methods have the type
|
||||
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
|
||||
The first one is the *self* object for methods; for module functions, it is
|
||||
the module object. The second parameter (often called *args*) is a tuple
|
||||
object representing all arguments. This parameter is typically processed
|
||||
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
|
||||
|
||||
|
||||
.. data:: METH_KEYWORDS
|
||||
|
||||
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
|
||||
The function expects three parameters: *self*, *args*, and a dictionary of
|
||||
all the keyword arguments. The flag is typically combined with
|
||||
:const:`METH_VARARGS`, and the parameters are typically processed using
|
||||
:c:func:`PyArg_ParseTupleAndKeywords`.
|
||||
|
||||
|
||||
.. data:: METH_NOARGS
|
||||
|
||||
Methods without parameters don't need to check whether arguments are given if
|
||||
they are listed with the :const:`METH_NOARGS` flag. They need to be of type
|
||||
:c:type:`PyCFunction`. The first parameter is typically named *self* and will
|
||||
hold a reference to the module or object instance. In all cases the second
|
||||
parameter will be *NULL*.
|
||||
|
||||
|
||||
.. data:: METH_O
|
||||
|
||||
Methods with a single object argument can be listed with the :const:`METH_O`
|
||||
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
|
||||
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
|
||||
:c:type:`PyObject\*` parameter representing the single argument.
|
||||
|
||||
|
||||
These two constants are not used to indicate the calling convention but the
|
||||
binding when use with methods of classes. These may not be used for functions
|
||||
defined for modules. At most one of these flags may be set for any given
|
||||
method.
|
||||
|
||||
|
||||
.. data:: METH_CLASS
|
||||
|
||||
.. index:: builtin: classmethod
|
||||
|
||||
The method will be passed the type object as the first parameter rather
|
||||
than an instance of the type. This is used to create *class methods*,
|
||||
similar to what is created when using the :func:`classmethod` built-in
|
||||
function.
|
||||
|
||||
|
||||
.. data:: METH_STATIC
|
||||
|
||||
.. index:: builtin: staticmethod
|
||||
|
||||
The method will be passed *NULL* as the first parameter rather than an
|
||||
instance of the type. This is used to create *static methods*, similar to
|
||||
what is created when using the :func:`staticmethod` built-in function.
|
||||
|
||||
One other constant controls whether a method is loaded in place of another
|
||||
definition with the same method name.
|
||||
|
||||
|
||||
.. data:: METH_COEXIST
|
||||
|
||||
The method will be loaded in place of existing definitions. Without
|
||||
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
|
||||
wrappers are loaded before the method table, the existence of a
|
||||
*sq_contains* slot, for example, would generate a wrapped method named
|
||||
:meth:`__contains__` and preclude the loading of a corresponding
|
||||
PyCFunction with the same name. With the flag defined, the PyCFunction
|
||||
will be loaded in place of the wrapper object and will co-exist with the
|
||||
slot. This is helpful because calls to PyCFunctions are optimized more
|
||||
than wrapper object calls.
|
||||
|
||||
|
||||
.. c:type:: PyMemberDef
|
||||
|
||||
Structure which describes an attribute of a type which corresponds to a C
|
||||
struct member. Its fields are:
|
||||
|
||||
+------------------+-------------+-------------------------------+
|
||||
| Field | C Type | Meaning |
|
||||
+==================+=============+===============================+
|
||||
| :attr:`name` | char \* | name of the member |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`type` | int | the type of the member in the |
|
||||
| | | C struct |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
|
||||
| | | member is located on the |
|
||||
| | | type's object struct |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`flags` | int | flag bits indicating if the |
|
||||
| | | field should be read-only or |
|
||||
| | | writable |
|
||||
+------------------+-------------+-------------------------------+
|
||||
| :attr:`doc` | char \* | points to the contents of the |
|
||||
| | | docstring |
|
||||
+------------------+-------------+-------------------------------+
|
||||
|
||||
:attr:`type` can be one of many ``T_`` macros corresponding to various C
|
||||
types. When the member is accessed in Python, it will be converted to the
|
||||
equivalent Python type.
|
||||
|
||||
=============== ==================
|
||||
Macro name C type
|
||||
=============== ==================
|
||||
T_SHORT short
|
||||
T_INT int
|
||||
T_LONG long
|
||||
T_FLOAT float
|
||||
T_DOUBLE double
|
||||
T_STRING char \*
|
||||
T_OBJECT PyObject \*
|
||||
T_OBJECT_EX PyObject \*
|
||||
T_CHAR char
|
||||
T_BYTE char
|
||||
T_UBYTE unsigned char
|
||||
T_UINT unsigned int
|
||||
T_USHORT unsigned short
|
||||
T_ULONG unsigned long
|
||||
T_BOOL char
|
||||
T_LONGLONG long long
|
||||
T_ULONGLONG unsigned long long
|
||||
T_PYSSIZET Py_ssize_t
|
||||
=============== ==================
|
||||
|
||||
:c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
|
||||
:c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
|
||||
:c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
|
||||
:c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
|
||||
handles use of the :keyword:`del` statement on that attribute more correctly
|
||||
than :c:macro:`T_OBJECT`.
|
||||
|
||||
:attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for
|
||||
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
|
||||
:c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
|
||||
members can be deleted. (They are set to *NULL*).
|
|
@ -0,0 +1,180 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _os:
|
||||
|
||||
Operating System Utilities
|
||||
==========================
|
||||
|
||||
|
||||
.. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
|
||||
|
||||
Return true (nonzero) if the standard I/O file *fp* with name *filename* is
|
||||
deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
|
||||
is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function
|
||||
also returns true if the *filename* pointer is *NULL* or if the name is equal to
|
||||
one of the strings ``'<stdin>'`` or ``'???'``.
|
||||
|
||||
|
||||
.. c:function:: void PyOS_AfterFork()
|
||||
|
||||
Function to update some internal state after a process fork; this should be
|
||||
called in the new process if the Python interpreter will continue to be used.
|
||||
If a new executable is loaded into the new process, this function does not need
|
||||
to be called.
|
||||
|
||||
|
||||
.. c:function:: int PyOS_CheckStack()
|
||||
|
||||
Return true when the interpreter runs out of stack space. This is a reliable
|
||||
check, but is only available when :const:`USE_STACKCHECK` is defined (currently
|
||||
on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
|
||||
will be defined automatically; you should never change the definition in your
|
||||
own code.
|
||||
|
||||
|
||||
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
|
||||
|
||||
Return the current signal handler for signal *i*. This is a thin wrapper around
|
||||
either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
|
||||
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
|
||||
(\*)(int)`.
|
||||
|
||||
|
||||
.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
|
||||
|
||||
Set the signal handler for signal *i* to be *h*; return the old signal handler.
|
||||
This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
|
||||
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
|
||||
alias for :c:type:`void (\*)(int)`.
|
||||
|
||||
.. _systemfunctions:
|
||||
|
||||
System Functions
|
||||
================
|
||||
|
||||
These are utility functions that make functionality from the :mod:`sys` module
|
||||
accessible to C code. They all work with the current interpreter thread's
|
||||
:mod:`sys` module's dict, which is contained in the internal thread state structure.
|
||||
|
||||
.. c:function:: PyObject *PySys_GetObject(char *name)
|
||||
|
||||
Return the object *name* from the :mod:`sys` module or *NULL* if it does
|
||||
not exist, without setting an exception.
|
||||
|
||||
.. c:function:: int PySys_SetObject(char *name, PyObject *v)
|
||||
|
||||
Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
|
||||
case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
|
||||
on error.
|
||||
|
||||
.. c:function:: void PySys_ResetWarnOptions()
|
||||
|
||||
Reset :data:`sys.warnoptions` to an empty list.
|
||||
|
||||
.. c:function:: void PySys_AddWarnOption(wchar_t *s)
|
||||
|
||||
Append *s* to :data:`sys.warnoptions`.
|
||||
|
||||
.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
|
||||
|
||||
Append *unicode* to :data:`sys.warnoptions`.
|
||||
|
||||
.. c:function:: void PySys_SetPath(wchar_t *path)
|
||||
|
||||
Set :data:`sys.path` to a list object of paths found in *path* which should
|
||||
be a list of paths separated with the platform's search path delimiter
|
||||
(``:`` on Unix, ``;`` on Windows).
|
||||
|
||||
.. c:function:: void PySys_WriteStdout(const char *format, ...)
|
||||
|
||||
Write the output string described by *format* to :data:`sys.stdout`. No
|
||||
exceptions are raised, even if truncation occurs (see below).
|
||||
|
||||
*format* should limit the total size of the formatted output string to
|
||||
1000 bytes or less -- after 1000 bytes, the output string is truncated.
|
||||
In particular, this means that no unrestricted "%s" formats should occur;
|
||||
these should be limited using "%.<N>s" where <N> is a decimal number
|
||||
calculated so that <N> plus the maximum size of other formatted text does not
|
||||
exceed 1000 bytes. Also watch out for "%f", which can print hundreds of
|
||||
digits for very large numbers.
|
||||
|
||||
If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
|
||||
is written to the real (C level) *stdout*.
|
||||
|
||||
.. c:function:: void PySys_WriteStderr(const char *format, ...)
|
||||
|
||||
As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr*
|
||||
instead.
|
||||
|
||||
.. c:function:: void PySys_FormatStdout(const char *format, ...)
|
||||
|
||||
Function similar to PySys_WriteStdout() but format the message using
|
||||
:c:func:`PyUnicode_FromFormatV` and don't truncate the message to an
|
||||
arbitrary length.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: void PySys_FormatStderr(const char *format, ...)
|
||||
|
||||
As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr*
|
||||
instead.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: void PySys_AddXOption(const wchar_t *s)
|
||||
|
||||
Parse *s* as a set of :option:`-X` options and add them to the current
|
||||
options mapping as returned by :c:func:`PySys_GetXOptions`.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. c:function:: PyObject *PySys_GetXOptions()
|
||||
|
||||
Return the current dictionary of :option:`-X` options, similarly to
|
||||
:data:`sys._xoptions`. On error, *NULL* is returned and an exception is
|
||||
set.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. _processcontrol:
|
||||
|
||||
Process Control
|
||||
===============
|
||||
|
||||
|
||||
.. c:function:: void Py_FatalError(const char *message)
|
||||
|
||||
.. index:: single: abort()
|
||||
|
||||
Print a fatal error message and kill the process. No cleanup is performed.
|
||||
This function should only be invoked when a condition is detected that would
|
||||
make it dangerous to continue using the Python interpreter; e.g., when the
|
||||
object administration appears to be corrupted. On Unix, the standard C library
|
||||
function :c:func:`abort` is called which will attempt to produce a :file:`core`
|
||||
file.
|
||||
|
||||
|
||||
.. c:function:: void Py_Exit(int status)
|
||||
|
||||
.. index::
|
||||
single: Py_Finalize()
|
||||
single: exit()
|
||||
|
||||
Exit the current process. This calls :c:func:`Py_Finalize` and then calls the
|
||||
standard C library function ``exit(status)``.
|
||||
|
||||
|
||||
.. c:function:: int Py_AtExit(void (*func) ())
|
||||
|
||||
.. index::
|
||||
single: Py_Finalize()
|
||||
single: cleanup functions
|
||||
|
||||
Register a cleanup function to be called by :c:func:`Py_Finalize`. The cleanup
|
||||
function will be called with no arguments and should return no value. At most
|
||||
32 cleanup functions can be registered. When the registration is successful,
|
||||
:c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
|
||||
function registered last is called first. Each cleanup function will be called
|
||||
at most once. Since Python's internal finalization will have completed before
|
||||
the cleanup function, no Python APIs should be called by *func*.
|
|
@ -0,0 +1,218 @@
|
|||
.. highlightlang:: c
|
||||
|
||||
.. _tupleobjects:
|
||||
|
||||
Tuple Objects
|
||||
-------------
|
||||
|
||||
.. index:: object: tuple
|
||||
|
||||
|
||||
.. c:type:: PyTupleObject
|
||||
|
||||
This subtype of :c:type:`PyObject` represents a Python tuple object.
|
||||
|
||||
|
||||
.. c:var:: PyTypeObject PyTuple_Type
|
||||
|
||||
This instance of :c:type:`PyTypeObject` represents the Python tuple type; it
|
||||
is the same object as :class:`tuple` in the Python layer.
|
||||
|
||||
|
||||
.. c:function:: int PyTuple_Check(PyObject *p)
|
||||
|
||||
Return true if *p* is a tuple object or an instance of a subtype of the tuple
|
||||
type.
|
||||
|
||||
|
||||
.. c:function:: int PyTuple_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a tuple object, but not an instance of a subtype of the
|
||||
tuple type.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
|
||||
|
||||
Return a new tuple object of size *len*, or *NULL* on failure.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
|
||||
|
||||
Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
|
||||
are initialized to the subsequent *n* C arguments pointing to Python objects.
|
||||
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
|
||||
|
||||
Take a pointer to a tuple object, and return the size of that tuple.
|
||||
|
||||
|
||||
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
|
||||
|
||||
Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
|
||||
no error checking is performed.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
|
||||
out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
|
||||
|
||||
Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
|
||||
as a new tuple.
|
||||
|
||||
|
||||
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
|
||||
|
||||
Insert a reference to object *o* at position *pos* of the tuple pointed to by
|
||||
*p*. Return ``0`` on success.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *o*.
|
||||
|
||||
|
||||
.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
|
||||
|
||||
Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
|
||||
used to fill in brand new tuples.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *o*.
|
||||
|
||||
|
||||
.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
|
||||
|
||||
Can be used to resize a tuple. *newsize* will be the new length of the tuple.
|
||||
Because tuples are *supposed* to be immutable, this should only be used if there
|
||||
is only one reference to the object. Do *not* use this if the tuple may already
|
||||
be known to some other part of the code. The tuple will always grow or shrink
|
||||
at the end. Think of this as destroying the old tuple and creating a new one,
|
||||
only more efficiently. Returns ``0`` on success. Client code should never
|
||||
assume that the resulting value of ``*p`` will be the same as before calling
|
||||
this function. If the object referenced by ``*p`` is replaced, the original
|
||||
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
|
||||
raises :exc:`MemoryError` or :exc:`SystemError`.
|
||||
|
||||
|
||||
.. c:function:: int PyTuple_ClearFreeList()
|
||||
|
||||
Clear the free list. Return the total number of freed items.
|
||||
|
||||
|
||||
Struct Sequence Objects
|
||||
-----------------------
|
||||
|
||||
Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
|
||||
objects, i.e. a sequence whose items can also be accessed through attributes.
|
||||
To create a struct sequence, you first have to create a specific struct sequence
|
||||
type.
|
||||
|
||||
.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
|
||||
|
||||
Create a new struct sequence type from the data in *desc*, described below. Instances
|
||||
of the resulting type can be created with :c:func:`PyStructSequence_New`.
|
||||
|
||||
|
||||
.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
|
||||
|
||||
Initializes a struct sequence type *type* from *desc* in place.
|
||||
|
||||
|
||||
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
|
||||
|
||||
The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
|
||||
failure.
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
|
||||
.. c:type:: PyStructSequence_Desc
|
||||
|
||||
Contains the meta information of a struct sequence type to create.
|
||||
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| Field | C Type | Meaning |
|
||||
+===================+==============================+====================================+
|
||||
| ``name`` | ``char *`` | name of the struct sequence type |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| ``doc`` | ``char *`` | pointer to docstring for the type |
|
||||
| | | or NULL to omit |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
|
||||
| | | with field names of the new type |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
| ``n_in_sequence`` | ``int`` | number of fields visible to the |
|
||||
| | | Python side (if used as tuple) |
|
||||
+-------------------+------------------------------+------------------------------------+
|
||||
|
||||
|
||||
.. c:type:: PyStructSequence_Field
|
||||
|
||||
Describes a field of a struct sequence. As a struct sequence is modeled as a
|
||||
tuple, all fields are typed as :c:type:`PyObject\*`. The index in the
|
||||
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
|
||||
field of the struct sequence is described.
|
||||
|
||||
+-----------+---------------+--------------------------------------+
|
||||
| Field | C Type | Meaning |
|
||||
+===========+===============+======================================+
|
||||
| ``name`` | ``char *`` | name for the field or *NULL* to end |
|
||||
| | | the list of named fields, set to |
|
||||
| | | PyStructSequence_UnnamedField to |
|
||||
| | | leave unnamed |
|
||||
+-----------+---------------+--------------------------------------+
|
||||
| ``doc`` | ``char *`` | field docstring or *NULL* to omit |
|
||||
+-----------+---------------+--------------------------------------+
|
||||
|
||||
|
||||
.. c:var:: char* PyStructSequence_UnnamedField
|
||||
|
||||
Special value for a field name to leave it unnamed.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
|
||||
|
||||
Creates an instance of *type*, which must have been created with
|
||||
:c:func:`PyStructSequence_NewType`.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Return the object at position *pos* in the struct sequence pointed to by *p*.
|
||||
No bounds checking is performed.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
|
||||
|
||||
Macro equivalent of :c:func:`PyStructSequence_GetItem`.
|
||||
|
||||
|
||||
.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
|
||||
|
||||
Sets the field at index *pos* of the struct sequence *p* to value *o*. Like
|
||||
:c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
|
||||
instances.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *o*.
|
||||
|
||||
|
||||
.. c:function:: PyObject* PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
|
||||
|
||||
Macro equivalent of :c:func:`PyStructSequence_SetItem`.
|
||||
|
||||
.. note::
|
||||
|
||||
This function "steals" a reference to *o*.
|
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue