OpenE2K
/
binutils-gdb
12
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

GDB with MCST patches (26.012)

This commit is contained in:
Alibek Omarov 2023-07-20 02:03:19 +03:00
parent 49526e9359
commit b021dfea95
4571 changed files with 2011211 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
bfd/Makefile.am
View File

@ -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 \

22
bfd/Makefile.in
View File

@ -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@

36
bfd/archures.c
View File

@ -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
View File

@ -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;

13
bfd/config.bfd
View File

@ -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

3
bfd/config.in
View File

@ -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

26
bfd/configure vendored
View File

@ -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 ;;

16
bfd/configure.ac
View File

@ -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 ;;

394
bfd/cpu-e2k.c Normal file
View File

@ -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));

8
bfd/cpu-sparc.c
View File

@ -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 =

102
bfd/eir.c Normal file
View File

@ -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
};

9
bfd/elf-bfd.h
View File

@ -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 *);

13
bfd/elf-eh-frame.c
View File

@ -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
View File

@ -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;
}

130
bfd/elf32-e2k-pm.c Normal file
View File

@ -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"

202
bfd/elf32-e2k.c Normal file
View File

@ -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"

30
bfd/elf32-sparc.c
View File

@ -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. */

34
bfd/elf64-e2k-kpda.c Normal file
View File

@ -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"

191
bfd/elf64-e2k.c Normal file
View File

@ -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 */

28
bfd/elf64-sparc.c
View File

@ -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 */

45
bfd/elflink.c
View File

@ -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);
}

7475
bfd/elfxx-e2k.c Normal file
View File

File diff suppressed because it is too large Load Diff

305
bfd/elfxx-e2k.h Normal file
View File

@ -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, ...);

190
bfd/elfxx-elcore-howto.h Normal file
View File

@ -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

465
bfd/elfxx-sparc.c
View File

@ -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 }
};

24
bfd/elfxx-sparc.h
View File

@ -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[];

16
bfd/elfxx-target.h
View File

@ -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. */

21
bfd/hosts/e2klinux.h Normal file
View File

@ -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
View File

@ -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
View File

@ -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

15
bfd/targets.c
View File

@ -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,

2
bfd/version.h
View File

@ -16,7 +16,7 @@
In releases, the date is not included in either version strings or
sonames. */
#define BFD_VERSION_DATE 20200208
#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@

2
config.guess vendored
View File

@ -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"

8
config.sub vendored
View File

@ -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)

2
configure vendored
View File

@ -3036,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

2
configure.ac
View File

@ -366,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

42
cpython/.bzrignore Normal file
View File

@ -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/*

73
cpython/.gitignore vendored Normal file
View File

@ -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/

49
cpython/.hgeol Normal file
View File

@ -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

99
cpython/.hgignore Normal file
View File

@ -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

136
cpython/.hgtags Normal file
View File

@ -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

15
cpython/.hgtouch Normal file
View File

@ -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

129
cpython/Doc/README.txt Normal file
View File

@ -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.
----------------------------------------------------------------------

39
cpython/Doc/about.rst Normal file
View File

@ -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!

87
cpython/Doc/bugs.rst Normal file
View File

@ -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/

26
cpython/Doc/c-api/abstract.rst Normal file
View File

@ -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

71
cpython/Doc/c-api/allocation.rst Normal file
View File

@ -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.

39
cpython/Doc/c-api/apiabiversion.rst Normal file
View File

@ -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`.

640
cpython/Doc/c-api/arg.rst Normal file
View File

@ -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.

46
cpython/Doc/c-api/bool.rst Normal file
View File

@ -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*.

496
cpython/Doc/c-api/buffer.rst Normal file
View File

@ -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.

86
cpython/Doc/c-api/bytearray.rst Normal file
View File

@ -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`.

194
cpython/Doc/c-api/bytes.rst Normal file
View File

@ -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.

150
cpython/Doc/c-api/capsule.rst Normal file
View File

@ -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.

62
cpython/Doc/c-api/cell.rst Normal file
View File

@ -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.

50
cpython/Doc/c-api/code.rst Normal file
View File

@ -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.

118
cpython/Doc/c-api/codec.rst Normal file
View File

@ -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``).

132
cpython/Doc/c-api/complex.rst Normal file
View File

@ -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.

116
cpython/Doc/c-api/concrete.rst Normal file
View File

@ -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

131
cpython/Doc/c-api/conversion.rst Normal file
View File

@ -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.

209
cpython/Doc/c-api/datetime.rst Normal file
View File

@ -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()``.

40
cpython/Doc/c-api/descriptor.rst Normal file
View File

@ -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 *)

230
cpython/Doc/c-api/dict.rst Normal file
View File

@ -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

850
cpython/Doc/c-api/exceptions.rst Normal file
View File

@ -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.

76
cpython/Doc/c-api/file.rst Normal file
View File

@ -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.

79
cpython/Doc/c-api/float.rst Normal file
View File

@ -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.

107
cpython/Doc/c-api/function.rst Normal file
View File

@ -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.

152
cpython/Doc/c-api/gcsupport.rst Normal file
View File

@ -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.

38
cpython/Doc/c-api/gen.rst Normal file
View File

@ -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*.

314
cpython/Doc/c-api/import.rst Normal file
View File

@ -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`.

26
cpython/Doc/c-api/index.rst Normal file
View File

@ -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

1188
cpython/Doc/c-api/init.rst Normal file
View File

File diff suppressed because it is too large Load Diff

644
cpython/Doc/c-api/intro.rst Normal file
View File

@ -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.

46
cpython/Doc/c-api/iter.rst Normal file
View File

@ -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 */
}

50
cpython/Doc/c-api/iterator.rst Normal file
View File

@ -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.

151
cpython/Doc/c-api/list.rst Normal file
View File

@ -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

262
cpython/Doc/c-api/long.rst Normal file
View File

@ -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`.

79
cpython/Doc/c-api/mapping.rst Normal file
View File

@ -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``.

89
cpython/Doc/c-api/marshal.rst Normal file
View File

@ -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*.

378
cpython/Doc/c-api/memory.rst Normal file
View File

@ -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.

63
cpython/Doc/c-api/memoryview.rst Normal file
View File

@ -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.

100
cpython/Doc/c-api/method.rst Normal file
View File

@ -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.

264
cpython/Doc/c-api/module.rst Normal file
View File

@ -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*.

26
cpython/Doc/c-api/none.rst Normal file
View File

@ -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.)

265
cpython/Doc/c-api/number.rst Normal file
View File

@ -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).

51
cpython/Doc/c-api/objbuffer.rst Normal file
View File

@ -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.

400
cpython/Doc/c-api/object.rst Normal file
View File

@ -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.

17
cpython/Doc/c-api/objimpl.rst Normal file
View File

@ -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

73
cpython/Doc/c-api/refcounting.rst Normal file
View File

@ -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`.

49
cpython/Doc/c-api/reflection.rst Normal file
View File

@ -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*.

162
cpython/Doc/c-api/sequence.rst Normal file
View File

@ -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.

166
cpython/Doc/c-api/set.rst Normal file
View File

@ -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

58
cpython/Doc/c-api/slice.rst Normal file
View File

@ -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.

38
cpython/Doc/c-api/stable.rst Normal file
View File

@ -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."

284
cpython/Doc/c-api/structures.rst Normal file
View File

@ -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*).

180
cpython/Doc/c-api/sys.rst Normal file
View File

@ -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*.

218
cpython/Doc/c-api/tuple.rst Normal file
View File

@ -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*.

109
cpython/Doc/c-api/type.rst Normal file
View File

@ -0,0 +1,109 @@
.. highlightlang:: c
.. _typeobjects:
Type Objects
------------
.. index:: object: type
.. c:type:: PyTypeObject
The C structure of the objects used to describe built-in types.
.. c:var:: PyObject* PyType_Type
This is the type object for type objects; it is the same object as
:class:`type` in the Python layer.
.. c:function:: int PyType_Check(PyObject *o)
Return true if the object *o* is a type object, including instances of types
derived from the standard type object. Return false in all other cases.
.. c:function:: int PyType_CheckExact(PyObject *o)
Return true if the object *o* is a type object, but not a subtype of the
standard type object. Return false in all other cases.
.. c:function:: unsigned int PyType_ClearCache()
Clear the internal lookup cache. Return the current version tag.
.. c:function:: long PyType_GetFlags(PyTypeObject* type)
Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
meant for use with `Py_LIMITED_API`; the individual flag bits are
guaranteed to be stable across Python releases, but access to
:c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
.. versionadded:: 3.2
.. c:function:: void PyType_Modified(PyTypeObject *type)
Invalidate the internal lookup cache for the type and all of its
subtypes. This function must be called after any manual
modification of the attributes or base classes of the type.
.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
Return true if the type object *o* sets the feature *feature*. Type features
are denoted by single bit flags.
.. c:function:: int PyType_IS_GC(PyTypeObject *o)
Return true if the type object includes support for the cycle detector; this
tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
Return true if *a* is a subtype of *b*.
.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use
Python's default memory allocation mechanism to allocate a new instance and
initialize all its contents to *NULL*.
.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a
new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot.
.. c:function:: int PyType_Ready(PyTypeObject *type)
Finalize a type object. This should be called on all type objects to finish
their initialization. This function is responsible for adding inherited slots
from a type's base class. Return ``0`` on success, or return ``-1`` and sets an
exception on error.
.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
Creates and returns a heap type object from the *spec* passed to the function.
.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
Creates and returns a heap type object from the *spec*. In addition to that,
the created heap type contains all types contained by the *bases* tuple as base
types. This allows the caller to reference other heap types as base types.
.. versionadded:: 3.3
.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
Return the function pointer stored in the given slot. If the
result is *NULL*, this indicates that either the slot is *NULL*,
or that the function was called with invalid parameters.
Callers will typically cast the result pointer into the appropriate
function type.
.. versionadded:: 3.4

1333
cpython/Doc/c-api/typeobj.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1679
cpython/Doc/c-api/unicode.rst Normal file
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More