head	1.94;
access;
symbols
	REL9_0_0:1.94
	REL9_1_ALPHA1:1.94
	REL9_0_RC1:1.94
	REL9_0_BETA4:1.94
	REL9_0_STABLE:1.94.0.2
	REL9_0_BETA3:1.94
	REL9_0_BETA2:1.94
	REL7_4_29:1.53.2.4
	REL8_0_25:1.64.4.2
	REL8_1_21:1.67.2.3
	REL8_2_17:1.70.2.4
	REL8_3_11:1.78.2.2
	REL8_4_4:1.84.2.4
	REL9_0_BETA1:1.94
	REL9_0_ALPHA5_BRANCH:1.93.0.2
	REL9_0_ALPHA5:1.93
	REL7_4_28:1.53.2.4
	REL8_0_24:1.64.4.2
	REL8_1_20:1.67.2.3
	REL8_2_16:1.70.2.4
	REL8_3_10:1.78.2.2
	REL8_4_3:1.84.2.4
	REL9_0_ALPHA4:1.90
	REL9_0_ALPHA4_BRANCH:1.90.0.2
	REL8_5_ALPHA3:1.88
	REL8_5_ALPHA3_BRANCH:1.88.0.4
	REL7_4_27:1.53.2.4
	REL8_0_23:1.64.4.2
	REL8_1_19:1.67.2.3
	REL8_2_15:1.70.2.4
	REL8_3_9:1.78.2.2
	REL8_4_2:1.84.2.2
	REL8_5_ALPHA2:1.88
	REL8_5_ALPHA2_BRANCH:1.88.0.2
	REL7_4_26:1.53.2.4
	REL8_0_22:1.64.4.2
	REL8_1_18:1.67.2.2
	REL8_2_14:1.70.2.3
	REL8_3_8:1.78.2.1
	REL8_4_1:1.84.2.1
	REL8_5_ALPHA1:1.84
	REL8_5_ALPHA1_BRANCH:1.84.0.4
	REL8_4_STABLE:1.84.0.2
	REL8_4_0:1.84
	REL8_4_RC2:1.84
	REL8_4_RC1:1.84
	REL8_4_BETA2:1.84
	REL8_4_BETA1:1.84
	REL7_4_25:1.53.2.4
	REL8_0_21:1.64.4.2
	REL8_1_17:1.67.2.2
	REL8_2_13:1.70.2.2
	REL8_3_7:1.78
	REL7_4_24:1.53.2.4
	REL8_0_20:1.64.4.2
	REL8_1_16:1.67.2.2
	REL8_2_12:1.70.2.2
	REL8_3_6:1.78
	REL7_4_23:1.53.2.4
	REL8_0_19:1.64.4.2
	REL8_1_15:1.67.2.2
	REL8_2_11:1.70.2.2
	REL8_3_5:1.78
	REL7_4_22:1.53.2.4
	REL8_0_18:1.64.4.2
	REL8_1_14:1.67.2.2
	REL8_2_10:1.70.2.2
	REL8_3_4:1.78
	REL7_4_21:1.53.2.4
	REL8_0_17:1.64.4.2
	REL8_1_13:1.67.2.2
	REL8_2_9:1.70.2.2
	REL8_3_3:1.78
	REL7_4_20:1.53.2.4
	REL8_0_16:1.64.4.2
	REL8_1_12:1.67.2.2
	REL8_2_8:1.70.2.2
	REL8_3_2:1.78
	REL8_2_7:1.70.2.2
	REL8_3_1:1.78
	REL8_3_STABLE:1.78.0.2
	REL8_3_0:1.78
	REL8_3_RC2:1.78
	REL7_3_21:1.43.2.3
	REL7_4_19:1.53.2.4
	REL8_0_15:1.64.4.2
	REL8_1_11:1.67.2.2
	REL8_2_6:1.70.2.2
	REL8_3_RC1:1.78
	REL8_3_BETA4:1.78
	REL8_3_BETA3:1.78
	REL8_3_BETA2:1.78
	REL8_3_BETA1:1.78
	REL7_3_20:1.43.2.3
	REL7_4_18:1.53.2.4
	REL8_0_14:1.64.4.2
	REL8_1_10:1.67.2.2
	REL8_2_5:1.70.2.2
	REL7_3_19:1.43.2.2
	REL7_4_17:1.53.2.3
	REL8_0_13:1.64.4.1
	REL8_1_9:1.67.2.1
	REL8_2_4:1.70.2.1
	REL8_0_12:1.64
	REL8_1_8:1.67
	REL8_2_3:1.70
	REL7_3_18:1.43
	REL7_4_16:1.53.2.1
	REL8_0_11:1.64
	REL8_1_7:1.67
	REL8_2_2:1.70
	REL8_0_10:1.64
	REL8_1_6:1.67
	REL8_2_1:1.70
	REL7_4_15:1.53.2.1
	REL7_3_17:1.43
	REL8_2_STABLE:1.70.0.2
	REL8_2_0:1.70
	REL8_2_RC1:1.70
	REL8_2_BETA3:1.69
	REL8_2_BETA2:1.68
	REL8_1_5:1.67
	REL8_0_9:1.64
	REL7_4_14:1.53.2.1
	REL7_3_16:1.43
	REL8_2_BETA1:1.68
	REL7_3_15:1.43
	REL7_4_13:1.53.2.1
	REL8_0_8:1.64
	REL8_1_4:1.67
	REL7_3_14:1.43
	REL7_4_12:1.53.2.1
	REL8_0_7:1.64
	REL8_1_3:1.67
	REL7_3_13:1.43
	REL7_4_11:1.53.2.1
	REL8_0_6:1.64
	REL8_1_2:1.67
	REL7_3_12:1.43
	REL7_4_10:1.53.2.1
	REL8_0_5:1.64
	REL8_1_1:1.67
	REL8_1_STABLE:1.67.0.2
	REL8_1_0:1.67
	REL8_1_0RC1:1.66
	REL8_1_0BETA4:1.66
	REL8_1_0BETA3:1.66
	REL7_3_11:1.43
	REL7_4_9:1.53.2.1
	REL8_0_4:1.64
	REL8_1_0BETA2:1.66
	REL8_1_0BETA1:1.66
	REL7_2_8:1.30
	REL7_3_10:1.43
	REL7_4_8:1.53.2.1
	REL8_0_3:1.64
	REL8_0_2:1.64
	REL7_2_7:1.30
	REL7_3_9:1.43
	REL7_4_7:1.53.2.1
	REL8_0_1:1.64
	REL8_0_STABLE:1.64.0.4
	REL8_0_0:1.64.0.2
	REL8_0_0RC5:1.64
	REL8_0_0RC4:1.64
	REL8_0_0RC3:1.63
	REL8_0_0RC2:1.63
	REL8_0_0RC1:1.63
	REL8_0_0BETA5:1.62
	REL8_0_0BETA4:1.62
	REL7_4_6:1.53.2.1
	REL7_3_8:1.43
	REL7_2_6:1.30
	REL8_0_0BETA3:1.61
	REL8_0_0BETA2:1.58
	REL7_2_5:1.30
	REL7_4_5:1.53.2.1
	REL7_3_7:1.43
	REL7_4_4:1.53.2.1
	REL8_0_0BETA1:1.58
	REL7_4_3:1.53.2.1
	REL7_4_2:1.53.2.1
	REL7_3_6:1.43
	REL7_4_1:1.53.2.1
	REL7_3_5:1.43
	REL7_4:1.53.2.1
	REL7_4_RC2:1.53
	REL7_4_STABLE:1.53.0.2
	REL7_4_RC1:1.53
	REL7_4_BETA5:1.52
	REL7_4_BETA4:1.52
	REL7_4_BETA3:1.52
	REL7_4_BETA2:1.48
	WIN32_DEV:1.48.0.2
	REL7_4_BETA1:1.48
	REL7_3_4:1.43
	REL7_3_2:1.43
	REL7_2_4:1.30
	REL7_3_STABLE:1.43.0.2
	REL7_2_3:1.30
	REL7_2_STABLE:1.30.0.2
	REL7_2:1.30
	REL7_2_RC2:1.30
	REL7_2_RC1:1.30
	REL7_2_BETA5:1.30
	REL7_2_BETA4:1.30
	REL7_2_BETA3:1.29
	REL7_2_BETA2:1.28
	REL7_2_BETA1:1.27
	REL7_1_2:1.22
	REL7_1_STABLE:1.22.0.2
	REL7_1_BETA:1.20
	REL7_1_BETA3:1.21
	REL7_1_BETA2:1.21
	REL7_1:1.21
	REL7_0_PATCHES:1.13.0.2
	REL7_0:1.13
	REL6_5_PATCHES:1.8.0.2
	REL6_5:1.8
	REL6_4:1.4.0.2;
locks; strict;
comment	@# @;


1.94
date	2010.04.03.07.22.58;	author petere;	state Exp;
branches;
next	1.93;

1.93
date	2010.03.03.03.23.12;	author momjian;	state Exp;
branches;
next	1.92;

1.92
date	2010.03.03.03.14.08;	author momjian;	state Exp;
branches;
next	1.91;

1.91
date	2010.02.25.22.24.00;	author momjian;	state Exp;
branches;
next	1.90;

1.90
date	2010.02.14.01.01.35;	author tgl;	state Exp;
branches;
next	1.89;

1.89
date	2010.02.14.00.48.12;	author tgl;	state Exp;
branches;
next	1.88;

1.88
date	2009.10.08.02.39.14;	author tgl;	state Exp;
branches;
next	1.87;

1.87
date	2009.10.02.18.13.04;	author tgl;	state Exp;
branches;
next	1.86;

1.86
date	2009.09.19.10.23.26;	author petere;	state Exp;
branches;
next	1.85;

1.85
date	2009.09.03.22.11.07;	author tgl;	state Exp;
branches;
next	1.84;

1.84
date	2008.12.31.02.25.03;	author tgl;	state Exp;
branches
	1.84.2.1;
next	1.83;

1.83
date	2008.12.18.18.20.33;	author tgl;	state Exp;
branches;
next	1.82;

1.82
date	2008.12.04.17.51.26;	author petere;	state Exp;
branches;
next	1.81;

1.81
date	2008.11.14.10.22.46;	author petere;	state Exp;
branches;
next	1.80;

1.80
date	2008.07.18.03.32.52;	author tgl;	state Exp;
branches;
next	1.79;

1.79
date	2008.07.16.01.30.21;	author tgl;	state Exp;
branches;
next	1.78;

1.78
date	2007.09.11.00.06.41;	author tgl;	state Exp;
branches
	1.78.2.1;
next	1.77;

1.77
date	2007.09.03.18.46.29;	author tgl;	state Exp;
branches;
next	1.76;

1.76
date	2007.09.03.00.39.13;	author tgl;	state Exp;
branches;
next	1.75;

1.75
date	2007.04.23.16.52.53;	author neilc;	state Exp;
branches;
next	1.74;

1.74
date	2007.04.20.02.37.37;	author tgl;	state Exp;
branches;
next	1.73;

1.73
date	2007.02.01.19.10.24;	author momjian;	state Exp;
branches;
next	1.72;

1.72
date	2007.01.31.23.26.03;	author momjian;	state Exp;
branches;
next	1.71;

1.71
date	2007.01.22.01.35.19;	author tgl;	state Exp;
branches;
next	1.70;

1.70
date	2006.11.10.20.52.18;	author tgl;	state Exp;
branches
	1.70.2.1;
next	1.69;

1.69
date	2006.11.03.07.17.36;	author tgl;	state Exp;
branches;
next	1.68;

1.68
date	2006.09.16.00.30.17;	author momjian;	state Exp;
branches;
next	1.67;

1.67
date	2005.11.01.21.09.50;	author tgl;	state Exp;
branches
	1.67.2.1;
next	1.66;

1.66
date	2005.07.14.06.17.36;	author neilc;	state Exp;
branches;
next	1.65;

1.65
date	2005.03.31.22.45.59;	author tgl;	state Exp;
branches;
next	1.64;

1.64
date	2005.01.04.00.39.53;	author tgl;	state Exp;
branches
	1.64.4.1;
next	1.63;

1.63
date	2004.11.27.21.27.07;	author petere;	state Exp;
branches;
next	1.62;

1.62
date	2004.10.01.02.00.44;	author neilc;	state Exp;
branches;
next	1.61;

1.61
date	2004.09.20.22.48.29;	author tgl;	state Exp;
branches;
next	1.60;

1.60
date	2004.09.16.04.16.08;	author neilc;	state Exp;
branches;
next	1.59;

1.59
date	2004.09.13.20.05.38;	author tgl;	state Exp;
branches;
next	1.58;

1.58
date	2004.07.11.23.23.43;	author momjian;	state Exp;
branches;
next	1.57;

1.57
date	2004.06.25.07.05.34;	author dennis;	state Exp;
branches;
next	1.56;

1.56
date	2004.05.16.23.22.07;	author neilc;	state Exp;
branches;
next	1.55;

1.55
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.54;

1.54
date	2003.11.12.22.47.47;	author petere;	state Exp;
branches;
next	1.53;

1.53
date	2003.10.26.04.34.05;	author momjian;	state Exp;
branches
	1.53.2.1;
next	1.52;

1.52
date	2003.09.11.21.42.20;	author momjian;	state Exp;
branches;
next	1.51;

1.51
date	2003.09.10.20.13.45;	author momjian;	state Exp;
branches;
next	1.50;

1.50
date	2003.09.09.18.28.52;	author tgl;	state Exp;
branches;
next	1.49;

1.49
date	2003.08.31.17.32.22;	author petere;	state Exp;
branches;
next	1.48;

1.48
date	2003.06.27.14.45.26;	author petere;	state Exp;
branches
	1.48.2.1;
next	1.47;

1.47
date	2003.04.22.10.08.08;	author petere;	state Exp;
branches;
next	1.46;

1.46
date	2003.03.25.16.15.39;	author petere;	state Exp;
branches;
next	1.45;

1.45
date	2003.03.20.04.41.13;	author momjian;	state Exp;
branches;
next	1.44;

1.44
date	2003.01.19.00.13.29;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	2002.09.21.18.32.54;	author petere;	state Exp;
branches
	1.43.2.1;
next	1.42;

1.42
date	2002.08.22.00.01.40;	author tgl;	state Exp;
branches;
next	1.41;

1.41
date	2002.07.24.19.11.07;	author petere;	state Exp;
branches;
next	1.40;

1.40
date	2002.07.18.23.11.27;	author petere;	state Exp;
branches;
next	1.39;

1.39
date	2002.05.18.13.47.59;	author petere;	state Exp;
branches;
next	1.38;

1.38
date	2002.05.17.18.32.52;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2002.04.23.02.07.15;	author tgl;	state Exp;
branches;
next	1.36;

1.36
date	2002.04.11.19.59.55;	author tgl;	state Exp;
branches;
next	1.35;

1.35
date	2002.04.05.00.31.24;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2002.03.22.19.20.37;	author petere;	state Exp;
branches;
next	1.33;

1.33
date	2002.03.01.20.38.12;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2002.03.01.19.01.22;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2002.02.18.23.11.02;	author petere;	state Exp;
branches;
next	1.30;

1.30
date	2001.12.08.03.24.34;	author thomas;	state Exp;
branches;
next	1.29;

1.29
date	2001.11.18.20.35.02;	author petere;	state Exp;
branches;
next	1.28;

1.28
date	2001.10.26.21.17.03;	author tgl;	state Exp;
branches;
next	1.27;

1.27
date	2001.10.02.21.39.35;	author tgl;	state Exp;
branches;
next	1.26;

1.26
date	2001.09.03.12.57.49;	author petere;	state Exp;
branches;
next	1.25;

1.25
date	2001.08.13.21.34.51;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2001.06.04.23.27.23;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	2001.05.19.09.01.10;	author petere;	state Exp;
branches;
next	1.22;

1.22
date	2001.04.28.13.59.07;	author momjian;	state Exp;
branches;
next	1.21;

1.21
date	2000.12.25.23.15.26;	author petere;	state Exp;
branches;
next	1.20;

1.20
date	2000.11.20.20.36.46;	author tgl;	state Exp;
branches;
next	1.19;

1.19
date	2000.11.02.19.26.44;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	2000.10.05.19.48.17;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	2000.08.25.15.17.50;	author thomas;	state Exp;
branches;
next	1.16;

1.16
date	2000.08.24.23.36.29;	author tgl;	state Exp;
branches;
next	1.15;

1.15
date	2000.07.22.04.30.27;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2000.07.22.02.39.10;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2000.03.27.17.14.42;	author thomas;	state Exp;
branches;
next	1.12;

1.12
date	2000.03.26.18.32.27;	author petere;	state Exp;
branches;
next	1.11;

1.11
date	99.10.02.21.27.49;	author tgl;	state Exp;
branches;
next	1.10;

1.10
date	99.09.28.04.34.39;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	99.07.22.15.09.07;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	99.07.06.17.16.34;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	99.06.14.07.37.03;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	99.05.20.02.57.15;	author tgl;	state Exp;
branches;
next	1.5;

1.5
date	98.12.29.02.24.34;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.10.30.19.33.43;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.09.16.14.43.02;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.09.07.15.58.10;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.05.13.05.33.59;	author thomas;	state Exp;
branches;
next	;

1.43.2.1
date	2007.04.20.02.38.57;	author tgl;	state Exp;
branches;
next	1.43.2.2;

1.43.2.2
date	2007.04.20.03.10.57;	author tgl;	state Exp;
branches;
next	1.43.2.3;

1.43.2.3
date	2007.04.23.16.53.15;	author neilc;	state Exp;
branches;
next	;

1.48.2.1
date	2003.09.07.04.36.45;	author momjian;	state Exp;
branches;
next	;

1.53.2.1
date	2003.11.12.20.05.15;	author petere;	state Exp;
branches;
next	1.53.2.2;

1.53.2.2
date	2007.04.20.02.38.44;	author tgl;	state Exp;
branches;
next	1.53.2.3;

1.53.2.3
date	2007.04.20.03.10.51;	author tgl;	state Exp;
branches;
next	1.53.2.4;

1.53.2.4
date	2007.04.23.16.53.13;	author neilc;	state Exp;
branches;
next	;

1.64.4.1
date	2007.04.20.02.38.29;	author tgl;	state Exp;
branches;
next	1.64.4.2;

1.64.4.2
date	2007.04.23.16.53.09;	author neilc;	state Exp;
branches;
next	;

1.67.2.1
date	2007.04.20.02.38.04;	author tgl;	state Exp;
branches;
next	1.67.2.2;

1.67.2.2
date	2007.04.23.16.52.58;	author neilc;	state Exp;
branches;
next	1.67.2.3;

1.67.2.3
date	2009.10.02.18.13.32;	author tgl;	state Exp;
branches;
next	;

1.70.2.1
date	2007.04.20.02.37.48;	author tgl;	state Exp;
branches;
next	1.70.2.2;

1.70.2.2
date	2007.04.23.16.52.56;	author neilc;	state Exp;
branches;
next	1.70.2.3;

1.70.2.3
date	2009.09.03.22.11.30;	author tgl;	state Exp;
branches;
next	1.70.2.4;

1.70.2.4
date	2009.10.02.18.13.26;	author tgl;	state Exp;
branches;
next	;

1.78.2.1
date	2009.09.03.22.11.22;	author tgl;	state Exp;
branches;
next	1.78.2.2;

1.78.2.2
date	2009.10.02.18.13.19;	author tgl;	state Exp;
branches;
next	;

1.84.2.1
date	2009.09.03.22.11.13;	author tgl;	state Exp;
branches;
next	1.84.2.2;

1.84.2.2
date	2009.10.02.18.13.10;	author tgl;	state Exp;
branches;
next	1.84.2.3;

1.84.2.3
date	2010.02.14.00.48.20;	author tgl;	state Exp;
branches;
next	1.84.2.4;

1.84.2.4
date	2010.02.14.01.01.40;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.94
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.93 2010/03/03 03:23:12 momjian Exp $
-->

<refentry id="SQL-CREATEFUNCTION">
 <refmeta>
  <refentrytitle>CREATE FUNCTION</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE FUNCTION</refname>
  <refpurpose>define a new function</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createfunction">
  <primary>CREATE FUNCTION</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE [ OR REPLACE ] FUNCTION
    <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [ { DEFAULT | = } <replaceable class="parameter">default_expr</replaceable> ] [, ...] ] )
    [ RETURNS <replaceable class="parameter">rettype</replaceable>
      | RETURNS TABLE ( <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">column_type</replaceable> [, ...] ) ]
  { LANGUAGE <replaceable class="parameter">lang_name</replaceable>
    | WINDOW
    | IMMUTABLE | STABLE | VOLATILE
    | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
    | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
    | COST <replaceable class="parameter">execution_cost</replaceable>
    | ROWS <replaceable class="parameter">result_rows</replaceable>
    | SET <replaceable class="parameter">configuration_parameter</replaceable> { TO <replaceable class="parameter">value</replaceable> | = <replaceable class="parameter">value</replaceable> | FROM CURRENT }
    | AS '<replaceable class="parameter">definition</replaceable>'
    | AS '<replaceable class="parameter">obj_file</replaceable>', '<replaceable class="parameter">link_symbol</replaceable>'
  } ...
    [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
</synopsis>
 </refsynopsisdiv>

 <refsect1 id="sql-createfunction-description">
  <title>Description</title>

  <para>
   <command>CREATE FUNCTION</command> defines a new function.
   <command>CREATE OR REPLACE FUNCTION</command> will either create a
   new function, or replace an existing definition.
   To be able to define a function, the user must have the
   <literal>USAGE</literal> privilege on the language.
  </para>

  <para>
   If a schema name is included, then the function is created in the
   specified schema.  Otherwise it is created in the current schema.
   The name of the new function must not match any existing function
   with the same input argument types in the same schema.  However,
   functions of different argument types can share a name (this is
   called <firstterm>overloading</>).
  </para>

  <para>
   To replace the current definition of an existing function, use
   <command>CREATE OR REPLACE FUNCTION</command>.  It is not possible
   to change the name or argument types of a function this way (if you
   tried, you would actually be creating a new, distinct function).
   Also, <command>CREATE OR REPLACE FUNCTION</command> will not let
   you change the return type of an existing function.  To do that,
   you must drop and recreate the function.  (When using <literal>OUT</>
   parameters, that means you cannot change the types of any
   <literal>OUT</> parameters except by dropping the function.)
  </para>

  <para>
   When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
   existing function, the ownership and permissions of the function
   do not change.  All other function properties are assigned the
   values specified or implied in the command.  You must own the function
   to replace it (this includes being a member of the owning role).
  </para>

  <para>
   If you drop and then recreate a function, the new function is not
   the same entity as the old; you will have to drop existing rules, views,
   triggers, etc. that refer to the old function.  Use
   <command>CREATE OR REPLACE FUNCTION</command> to change a function
   definition without breaking objects that refer to the function.
   Also, <command>ALTER FUNCTION</> can be used to change most of the
   auxiliary properties of an existing function.
  </para>

  <para>
   The user that creates the function becomes the owner of the function.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

   <variablelist>

    <varlistentry>
     <term><replaceable class="parameter">name</replaceable></term>

     <listitem>
      <para>
       The name (optionally schema-qualified) of the function to create.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">argmode</replaceable></term>

     <listitem>
      <para>
       The mode of an argument: <literal>IN</>, <literal>OUT</>,
       <literal>INOUT</>, or <literal>VARIADIC</>.
       If omitted, the default is <literal>IN</>.
       Only <literal>OUT</> arguments can follow a <literal>VARIADIC</> one.
       Also, <literal>OUT</> and <literal>INOUT</> arguments cannot be used
       together with the <literal>RETURNS TABLE</> notation.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">argname</replaceable></term>

     <listitem>
      <para>
       The name of an argument. Some languages (currently only PL/pgSQL) let
       you use the name in the function body.  For other languages the
       name of an input argument is just extra documentation, so far as
       the function itself is concerned; but you can use input argument names
       when calling a function to improve readability (see <xref
       linkend="sql-syntax-calling-funcs">).  In any case, the name
       of an output argument is significant, because it defines the column
       name in the result row type.  (If you omit the name for an output
       argument, the system will choose a default column name.)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">argtype</replaceable></term>

     <listitem>
      <para>
       The data type(s) of the function's arguments (optionally
       schema-qualified), if any. The argument types can be base, composite,
       or domain types, or can reference the type of a table column.
      </para>
      <para>
       Depending on the implementation language it might also be allowed
       to specify <quote>pseudotypes</> such as <type>cstring</>.
       Pseudotypes indicate that the actual argument type is either
       incompletely specified, or outside the set of ordinary SQL data types.
      </para>
      <para>
       The type of a column is referenced by writing
       <literal><replaceable
       class="parameter">table_name</replaceable>.<replaceable
       class="parameter">column_name</replaceable>%TYPE</literal>.
       Using this feature can sometimes help make a function independent of
       changes to the definition of a table.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">default_expr</replaceable></term>

     <listitem>
      <para>
       An expression to be used as default value if the parameter is
       not specified.  The expression has to be coercible to the
       argument type of the parameter.
       Only input (including <literal>INOUT</>) parameters can have a default
        value.  All input parameters following a
       parameter with a default value must have default values as well.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">rettype</replaceable></term>

     <listitem>
      <para>
       The return data type (optionally schema-qualified). The return type
       can be a base, composite, or domain type,
       or can reference the type of a table column.
       Depending on the implementation language it might also be allowed
       to specify <quote>pseudotypes</> such as <type>cstring</>.
       If the function is not supposed to return a value, specify
       <type>void</> as the return type.
      </para>
      <para>
       When there are <literal>OUT</> or <literal>INOUT</> parameters,
       the <literal>RETURNS</> clause can be omitted.  If present, it
       must agree with the result type implied by the output parameters:
       <literal>RECORD</> if there are multiple output parameters, or
       the same type as the single output parameter.
      </para>
      <para>
       The <literal>SETOF</literal>
       modifier indicates that the function will return a set of
       items, rather than a single item.
      </para>
      <para>
       The type of a column is referenced by writing
       <literal><replaceable
       class="parameter">table_name</replaceable>.<replaceable
       class="parameter">column_name</replaceable>%TYPE</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">column_name</replaceable></term>

     <listitem>
      <para>
       The name of an output column in the <literal>RETURNS TABLE</>
       syntax.  This is effectively another way of declaring a named
       <literal>OUT</> parameter, except that <literal>RETURNS TABLE</>
       also implies <literal>RETURNS SETOF</>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">column_type</replaceable></term>

     <listitem>
      <para>
       The data type of an output column in the <literal>RETURNS TABLE</>
       syntax.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">lang_name</replaceable></term>

     <listitem>
      <para>
       The name of the language that the function is implemented in.
       Can be <literal>SQL</literal>, <literal>C</literal>,
       <literal>internal</literal>, or the name of a user-defined
       procedural language.  For backward compatibility,
       the name can be enclosed by single quotes.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>WINDOW</literal></term>

     <listitem>
      <para>
       <literal>WINDOW</literal> indicates that the function is a
       <firstterm>window function</> rather than a plain function.
       This is currently only useful for functions written in C.
       The <literal>WINDOW</> attribute cannot be changed when
       replacing an existing function definition.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>IMMUTABLE</literal></term>
     <term><literal>STABLE</literal></term>
     <term><literal>VOLATILE</literal></term>

     <listitem>
      <para>
       These attributes inform the query optimizer about the behavior
       of the function.  At most one choice
       can be specified.  If none of these appear,
       <literal>VOLATILE</literal> is the default assumption.
      </para>

      <para>
       <literal>IMMUTABLE</literal> indicates that the function
       cannot modify the database and always
       returns the same result when given the same argument values; that
       is, it does not do database lookups or otherwise use information not
       directly present in its argument list.  If this option is given,
       any call of the function with all-constant arguments can be
       immediately replaced with the function value.
      </para>

      <para>
       <literal>STABLE</literal> indicates that the function
       cannot modify the database,
       and that within a single table scan it will consistently
       return the same result for the same argument values, but that its
       result could change across SQL statements.  This is the appropriate
       selection for functions whose results depend on database lookups,
       parameter variables (such as the current time zone), etc.  (It is
       inappropriate for <literal>AFTER</> triggers that wish to
       query rows modified by the current command.)  Also note
       that the <function>current_timestamp</> family of functions qualify
       as stable, since their values do not change within a transaction.
      </para>

      <para>
       <literal>VOLATILE</literal> indicates that the function value can
       change even within a single table scan, so no optimizations can be
       made.  Relatively few database functions are volatile in this sense;
       some examples are <literal>random()</>, <literal>currval()</>,
       <literal>timeofday()</>.  But note that any function that has
       side-effects must be classified volatile, even if its result is quite
       predictable, to prevent calls from being optimized away; an example is
       <literal>setval()</>.
      </para>

      <para>
       For additional details see <xref linkend="xfunc-volatility">.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>CALLED ON NULL INPUT</literal></term>
     <term><literal>RETURNS NULL ON NULL INPUT</literal></term>
     <term><literal>STRICT</literal></term>

     <listitem>
      <para>
       <literal>CALLED ON NULL INPUT</literal> (the default) indicates
       that the function will be called normally when some of its
       arguments are null.  It is then the function author's
       responsibility to check for null values if necessary and respond
       appropriately.
      </para>

      <para>
       <literal>RETURNS NULL ON NULL INPUT</literal> or
       <literal>STRICT</literal> indicates that the function always
       returns null whenever any of its arguments are null.  If this
       parameter is specified, the function is not executed when there
       are null arguments; instead a null result is assumed
       automatically.
      </para>
     </listitem>
    </varlistentry>

   <varlistentry>
    <term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
    <term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>

    <listitem>
     <para>
      <literal>SECURITY INVOKER</literal> indicates that the function
      is to be executed with the privileges of the user that calls it.
      That is the default.  <literal>SECURITY DEFINER</literal>
      specifies that the function is to be executed with the
      privileges of the user that created it.
     </para>

     <para>
      The key word <literal>EXTERNAL</literal> is allowed for SQL
      conformance, but it is optional since, unlike in SQL, this feature
      applies to all functions not only external ones.
     </para>
    </listitem>
   </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">execution_cost</replaceable></term>

     <listitem>
      <para>
       A positive number giving the estimated execution cost for the function,
       in units of <xref linkend="guc-cpu-operator-cost">.  If the function
       returns a set, this is the cost per returned row.  If the cost is
       not specified, 1 unit is assumed for C-language and internal functions,
       and 100 units for functions in all other languages.  Larger values
       cause the planner to try to avoid evaluating the function more often
       than necessary.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">result_rows</replaceable></term>

     <listitem>
      <para>
       A positive number giving the estimated number of rows that the planner
       should expect the function to return.  This is only allowed when the
       function is declared to return a set.  The default assumption is
       1000 rows.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable>configuration_parameter</replaceable></term>
     <term><replaceable>value</replaceable></term>
     <listitem>
      <para>
       The <literal>SET</> clause causes the specified configuration
       parameter to be set to the specified value when the function is
       entered, and then restored to its prior value when the function exits.
       <literal>SET FROM CURRENT</> saves the session's current value of
       the parameter as the value to be applied when the function is entered.
      </para>

      <para>
       If a <literal>SET</> clause is attached to a function, then
       the effects of a <command>SET LOCAL</> command executed inside the
       function for the same variable are restricted to the function: the
       configuration parameter's prior value is still restored at function exit.
       However, an ordinary
       <command>SET</> command (without <literal>LOCAL</>) overrides the
       <literal>SET</> clause, much as it would do for a previous <command>SET
       LOCAL</> command: the effects of such a command will persist after
       function exit, unless the current transaction is rolled back.
      </para>
   
      <para>
       See <xref linkend="sql-set"> and
       <xref linkend="runtime-config">
       for more information about allowed parameter names and values.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">definition</replaceable></term>

     <listitem>
      <para>
       A string constant defining the function; the meaning depends on the
       language.  It can be an internal function name, the path to an
       object file, an SQL command, or text in a procedural language.
      </para>

      <para>
       It is often helpful to use dollar quoting (see <xref
       linkend="sql-syntax-dollar-quoting">) to write the function definition
       string, rather than the normal single quote syntax.  Without dollar
       quoting, any single quotes or backslashes in the function definition must
       be escaped by doubling them.
      </para>

     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></literal></term>

     <listitem>
      <para>
       This form of the <literal>AS</literal> clause is used for
       dynamically loadable C language functions when the function name
       in the C language source code is not the same as the name of
       the SQL function. The string <replaceable
       class="parameter">obj_file</replaceable> is the name of the
       file containing the dynamically loadable object, and
       <replaceable class="parameter">link_symbol</replaceable> is the
       function's link symbol, that is, the name of the function in the C
       language source code.  If the link symbol is omitted, it is assumed
       to be the same as the name of the SQL function being defined.
      </para>

      <para>
       When repeated <command>CREATE FUNCTION</command> calls refer to
       the same object file, the file is only loaded once per session.
       To unload and
       reload the file (perhaps during development), start a new session.
      </para>

     </listitem>
    </varlistentry>

    <varlistentry>
     <term><replaceable class="parameter">attribute</replaceable></term>

     <listitem>
      <para>
       The historical way to specify optional pieces of information
       about the function.  The following attributes can appear here:

      <variablelist>
       <varlistentry>
        <term><literal>isStrict</></term>
        <listitem>
         <para>
          Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><literal>isCachable</></term>
        <listitem>
         <para>
          <literal>isCachable</literal> is an obsolete equivalent of
          <literal>IMMUTABLE</literal>; it's still accepted for
          backwards-compatibility reasons.
         </para>
        </listitem>
       </varlistentry>

      </variablelist>

      Attribute names are not case-sensitive.
     </para>
    </listitem>
   </varlistentry>

   </variablelist>

   <para>
    Refer to <xref linkend="xfunc"> for further information on writing
    functions.
   </para>

 </refsect1>

 <refsect1 id="sql-createfunction-overloading">
  <title>Overloading</title>

   <para>
    <productname>PostgreSQL</productname> allows function
    <firstterm>overloading</firstterm>; that is, the same name can be
    used for several different functions so long as they have distinct
    input argument types.  However, the C names of all functions must be
    different, so you must give overloaded C functions different C
    names (for example, use the argument types as part of the C
    names).
   </para>

   <para>
    Two functions are considered the same if they have the same names and
    <emphasis>input</> argument types, ignoring any <literal>OUT</>
    parameters.  Thus for example these declarations conflict:
<programlisting>
CREATE FUNCTION foo(int) ...
CREATE FUNCTION foo(int, out text) ...
</programlisting>
   </para>

   <para>
    Functions that have different argument type lists will not be considered
    to conflict at creation time, but if defaults are provided they might
    conflict in use.  For example, consider
<programlisting>
CREATE FUNCTION foo(int) ...
CREATE FUNCTION foo(int, int default 42) ...
</programlisting>
    A call <literal>foo(10)</> will fail due to the ambiguity about which
    function should be called.
   </para>

 </refsect1>

 <refsect1 id="sql-createfunction-notes">
  <title>Notes</title>

   <para>
    The full <acronym>SQL</acronym> type syntax is allowed for
    input arguments and return value. However, some details of the
    type specification (e.g., the precision field for
    type <type>numeric</type>) are the responsibility of the
    underlying function implementation and are silently swallowed
    (i.e., not recognized or
    enforced) by the <command>CREATE FUNCTION</command> command.
   </para>

   <para>
    When replacing an existing function with <command>CREATE OR REPLACE
    FUNCTION</>, there are restrictions on changing parameter names.
    You cannot change the name already assigned to any input parameter
    (although you can add names to parameters that had none before).
    If there is more than one output parameter, you cannot change the
    names of the output parameters, because that would change the
    column names of the anonymous composite type that describes the
    function's result.  These restrictions are made to ensure that
    existing calls of the function do not stop working when it is replaced.
   </para>

   <para>
    If a function is declared <literal>STRICT</> with a <literal>VARIADIC</>
    argument, the strictness check tests that the variadic array <emphasis>as
    a whole</> is non-null.  The function will still be called if the
    array has null elements.
   </para>

 </refsect1>

 <refsect1 id="sql-createfunction-examples">
  <title>Examples</title>

  <para>
   Here are some trivial examples to help you get started.  For more
   information and examples, see <xref linkend="xfunc">.
<programlisting>
CREATE FUNCTION add(integer, integer) RETURNS integer
    AS 'select $1 + $2;'
    LANGUAGE SQL
    IMMUTABLE
    RETURNS NULL ON NULL INPUT;
</programlisting>
  </para>

  <para>
   Increment an integer, making use of an argument name, in
   <application>PL/pgSQL</application>:
<programlisting>
CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
        BEGIN
                RETURN i + 1;
        END;
$$ LANGUAGE plpgsql;
</programlisting>
  </para>

  <para>
   Return a record containing multiple output parameters:
<programlisting>
CREATE FUNCTION dup(in int, out f1 int, out f2 text)
    AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
    LANGUAGE SQL;

SELECT * FROM dup(42);
</programlisting>
   You can do the same thing more verbosely with an explicitly named
   composite type:
<programlisting>
CREATE TYPE dup_result AS (f1 int, f2 text);

CREATE FUNCTION dup(int) RETURNS dup_result
    AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
    LANGUAGE SQL;

SELECT * FROM dup(42);
</programlisting>
   Another way to return multiple columns is to use a <literal>TABLE</>
   function:
<programlisting>
CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text)
    AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
    LANGUAGE SQL;

SELECT * FROM dup(42);
</programlisting>
   However, a <literal>TABLE</> function is different from the
   preceding examples, because it actually returns a <emphasis>set</>
   of records, not just one record.
  </para>
 </refsect1>

 <refsect1 id="sql-createfunction-security">
  <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>

   <para>
    Because a <literal>SECURITY DEFINER</literal> function is executed
    with the privileges of the user that created it, care is needed to
    ensure that the function cannot be misused.  For security,
    <xref linkend="guc-search-path"> should be set to exclude any schemas
    writable by untrusted users.  This prevents
    malicious users from creating objects that mask objects used by the
    function.  Particularly important in this regard is the
    temporary-table schema, which is searched first by default, and
    is normally writable by anyone.  A secure arrangement can be had
    by forcing the temporary schema to be searched last.  To do this,
    write <literal>pg_temp</> as the last entry in <varname>search_path</>.
    This function illustrates safe usage:
   </para>

<programlisting>
CREATE FUNCTION check_password(uname TEXT, pass TEXT)
RETURNS BOOLEAN AS $$
DECLARE passed BOOLEAN;
BEGIN
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        RETURN passed;
END;
$$  LANGUAGE plpgsql
    SECURITY DEFINER
    -- Set a secure search_path: trusted schema(s), then 'pg_temp'.
    SET search_path = admin, pg_temp;
</programlisting>

   <para>
    Before <productname>PostgreSQL</productname> version 8.3, the
    <literal>SET</> option was not available, and so older functions may
    contain rather complicated logic to save, set, and restore
    <varname>search_path</>.  The <literal>SET</> option is far easier
    to use for this purpose.
   </para>

   <para>
    Another point to keep in mind is that by default, execute privilege
    is granted to <literal>PUBLIC</> for newly created functions
    (see <xref linkend="sql-grant"> for more
    information).  Frequently you will wish to restrict use of a security
    definer function to only some users.  To do that, you must revoke
    the default <literal>PUBLIC</> privileges and then grant execute
    privilege selectively.  To avoid having a window where the new function
    is accessible to all, create it and set the privileges within a single
    transaction.  For example:
   </para>

<programlisting>
BEGIN;
CREATE FUNCTION check_password(uname TEXT, pass TEXT) ... SECURITY DEFINER;
REVOKE ALL ON FUNCTION check_password(uname TEXT, pass TEXT) FROM PUBLIC;
GRANT EXECUTE ON FUNCTION check_password(uname TEXT, pass TEXT) TO admins;
COMMIT;
</programlisting>

 </refsect1>

 <refsect1 id="sql-createfunction-compat">
  <title>Compatibility</title>

  <para>
   A <command>CREATE FUNCTION</command> command is defined in SQL:1999 and later.
   The <productname>PostgreSQL</productname> version is similar but
   not fully compatible.  The attributes are not portable, neither are the
   different available languages.
  </para>

  <para>
   For compatibility with some other database systems,
   <replaceable class="parameter">argmode</replaceable> can be written
   either before or after <replaceable class="parameter">argname</replaceable>.
   But only the first way is standard-compliant.
  </para>

  <para>
   The SQL standard does not specify parameter defaults.  The syntax
   with the <literal>DEFAULT</literal> key word is from Oracle, and it
   is somewhat in the spirit of the standard: SQL/PSM uses it for
   variable default values.  The syntax with <literal>=</literal> is
   used in T-SQL and Firebird.
  </para>
 </refsect1>


 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-alterfunction"></member>
   <member><xref linkend="sql-dropfunction"></member>
   <member><xref linkend="sql-grant"></member>
   <member><xref linkend="sql-load"></member>
   <member><xref linkend="sql-revoke"></member>
   <member><xref linkend="app-createlang"></member>
  </simplelist>
 </refsect1>

</refentry>
@


1.93
log
@Fix SGML markup.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.92 2010/03/03 03:14:08 momjian Exp $
d7 1
a7 1
  <refentrytitle id="SQL-CREATEFUNCTION-TITLE">CREATE FUNCTION</refentrytitle>
d426 1
a426 1
       See <xref linkend="sql-set" endterm="sql-set-title"> and
d705 1
a705 1
    (see <xref linkend="sql-grant" endterm="sql-grant-title"> for more
d755 6
a760 6
   <member><xref linkend="sql-alterfunction" endterm="sql-alterfunction-title"></member>
   <member><xref linkend="sql-dropfunction" endterm="sql-dropfunction-title"></member>
   <member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
   <member><xref linkend="sql-load" endterm="sql-load-title"></member>
   <member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
   <member><xref linkend="app-createlang" endterm="app-createlang-title"></member>
@


1.92
log
@Restructure CREATE FUNCTION "NOTES" section to be shorter;  move items
into proper sections, per suggestion from Tom.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.91 2010/02/25 22:24:00 momjian Exp $
a52 2
  </para>

d519 5
a525 5
 <para>
  Refer to <xref linkend="xfunc"> for further information on writing
  functions.
 </para>

@


1.91
log
@Document that after triggers that need to see changed rows should not be
marked stable.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.90 2010/02/14 01:01:35 tgl Exp $
d49 4
d77 8
d416 12
d444 9
d472 8
d523 4
a526 7
 <refsect1 id="sql-createfunction-notes">
  <title>Notes</title>

   <para>
    Refer to <xref linkend="xfunc"> for further information on writing
    functions.
   </para>
d528 2
a529 9
   <para>
    The full <acronym>SQL</acronym> type syntax is allowed for
    input arguments and return value. However, some details of the
    type specification (e.g., the precision field for
    type <type>numeric</type>) are the responsibility of the
    underlying function implementation and are silently swallowed
    (i.e., not recognized or
    enforced) by the <command>CREATE FUNCTION</command> command.
   </para>
d563 1
a563 6
   <para>
    When repeated <command>CREATE FUNCTION</command> calls refer to
    the same object file, the file is only loaded once per session.
    To unload and
    reload the file (perhaps during development), start a new session.
   </para>
d565 2
a566 5
   <para>
    Use <xref linkend="sql-dropfunction"
    endterm="sql-dropfunction-title"> to remove user-defined
    functions.
   </para>
d569 7
a575 30
    It is often helpful to use dollar quoting (see <xref
    linkend="sql-syntax-dollar-quoting">) to write the function definition
    string, rather than the normal single quote syntax.  Without dollar
    quoting, any single quotes or backslashes in the function definition must
    be escaped by doubling them.
   </para>

   <para>
    If a <literal>SET</> clause is attached to a function, then
    the effects of a <command>SET LOCAL</> command executed inside the
    function for the same variable are restricted to the function: the
    configuration parameter's prior value is still restored at function exit.
    However, an ordinary
    <command>SET</> command (without <literal>LOCAL</>) overrides the
    <literal>SET</> clause, much as it would do for a previous <command>SET
    LOCAL</> command: the effects of such a command will persist after
    function exit, unless the current transaction is rolled back.
   </para>

   <para>
    To be able to define a function, the user must have the
    <literal>USAGE</literal> privilege on the language.
   </para>

   <para>
    When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
    existing function, the ownership and permissions of the function
    do not change.  All other function properties are assigned the
    values specified or implied in the command.  You must own the function
    to replace it (this includes being a member of the owning role).
@


1.90
log
@Ooops, let's get the non-null vs null bit right ...
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.89 2010/02/14 00:48:12 tgl Exp $
d292 3
a294 1
       parameter variables (such as the current time zone), etc.  Also note
@


1.89
log
@Document the behavior of STRICT VARIADIC functions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.88 2009/10/08 02:39:14 tgl Exp $
d592 1
a592 1
    array has non-null elements.
@


1.88
log
@Support use of function argument names to identify which actual arguments
match which function parameters.  The syntax uses AS, for example
	funcname(value AS arg1, anothervalue AS arg2)

Pavel Stehule
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.87 2009/10/02 18:13:04 tgl Exp $
d588 7
@


1.87
log
@Fix erroneous handling of shared dependencies (ie dependencies on roles)
in CREATE OR REPLACE FUNCTION.  The original code would update pg_shdepend
as if a new function was being created, even if it wasn't, with two bad
consequences: pg_shdepend might record the wrong owner for the function,
and any dependencies for roles mentioned in the function's ACL would be lost.
The fix is very easy: just don't touch pg_shdepend at all when doing a
function replacement.

Also update the CREATE FUNCTION reference page, which never explained
exactly what changes and doesn't change in a function replacement.
In passing, fix the CREATE VIEW reference page similarly; there's no
code bug there, but the docs didn't say what happens.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.86 2009/09/19 10:23:26 petere Exp $
d68 1
a68 1
   parameters, that means you cannot change the names or types of any
d124 5
a128 2
       name of an input argument is just extra documentation.  But the name
       of an output argument is significant, since it defines the column
d576 12
@


1.86
log
@Make the placeholder naming in the synopses of the SQL help more consistent
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.85 2009/09/03 22:11:07 tgl Exp $
d565 8
@


1.85
log
@Make LOAD of an already-loaded library into a no-op, instead of attempting
to unload and re-load the library.

The difficulty with unloading a library is that we haven't defined safe
protocols for doing so.  In particular, there's no safe mechanism for
getting out of a "hook" function pointer unless libraries are unloaded
in reverse order of loading.  And there's no mechanism at all for undefining
a custom GUC variable, so GUC would be left with a pointer to an old value
that might or might not still be valid, and very possibly wouldn't be in
the same place anymore.

While the unload and reload behavior had some usefulness in easing
development of new loadable libraries, it's of no use whatever to normal
users, so just disabling it isn't giving up that much.  Someday we might
care to expend the effort to develop safe unload protocols; but even if
we did, there'd be little certainty that every third-party loadable module
was following them, so some security restrictions would still be needed.

Back-patch to 8.2; before that, LOAD was superuser-only anyway.

Security: unprivileged users could crash backend.  CVE not assigned yet
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.84 2008/12/31 02:25:03 tgl Exp $
d24 1
a24 1
    <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [ { DEFAULT | = } <replaceable class="parameter">defexpr</replaceable> ] [, ...] ] )
d26 2
a27 2
      | RETURNS TABLE ( <replaceable class="parameter">colname</replaceable> <replaceable class="parameter">coltype</replaceable> [, ...] ) ]
  { LANGUAGE <replaceable class="parameter">langname</replaceable>
d150 2
a151 2
       class="parameter">tablename</replaceable>.<replaceable
       class="parameter">columnname</replaceable>%TYPE</literal>.
d159 1
a159 1
     <term><replaceable class="parameter">defexpr</replaceable></term>
d201 2
a202 2
       class="parameter">tablename</replaceable>.<replaceable
       class="parameter">columnname</replaceable>%TYPE</literal>.
d208 1
a208 1
     <term><replaceable class="parameter">colname</replaceable></term>
d221 1
a221 1
     <term><replaceable class="parameter">coltype</replaceable></term>
d232 1
a232 1
     <term><replaceable class="parameter">langname</replaceable></term>
@


1.84
log
@Add a WINDOW attribute to CREATE FUNCTION, and teach pg_dump about it,
so that user-defined window functions are possible.  For the moment you'll
have to write them in C, for lack of any interface to the WindowObject API
in the available PLs, but it's better than no support at all.

There was some debate about the best syntax for this.  I ended up choosing
the "it's an attribute" position --- the other approach will inevitably be
more work, and the likely market for user-defined window functions is
probably too small to justify it.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.83 2008/12/18 18:20:33 tgl Exp $
d531 1
a531 2
    reload the file (perhaps during development), use the <xref
    linkend="sql-load" endterm="sql-load-title"> command.
@


1.84.2.1
log
@Make LOAD of an already-loaded library into a no-op, instead of attempting
to unload and re-load the library.

The difficulty with unloading a library is that we haven't defined safe
protocols for doing so.  In particular, there's no safe mechanism for
getting out of a "hook" function pointer unless libraries are unloaded
in reverse order of loading.  And there's no mechanism at all for undefining
a custom GUC variable, so GUC would be left with a pointer to an old value
that might or might not still be valid, and very possibly wouldn't be in
the same place anymore.

While the unload and reload behavior had some usefulness in easing
development of new loadable libraries, it's of no use whatever to normal
users, so just disabling it isn't giving up that much.  Someday we might
care to expend the effort to develop safe unload protocols; but even if
we did, there'd be little certainty that every third-party loadable module
was following them, so some security restrictions would still be needed.

Back-patch to 8.2; before that, LOAD was superuser-only anyway.

Security: unprivileged users could crash backend.  CVE not assigned yet
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.84 2008/12/31 02:25:03 tgl Exp $
d531 2
a532 1
    reload the file (perhaps during development), start a new session.
@


1.84.2.2
log
@Fix erroneous handling of shared dependencies (ie dependencies on roles)
in CREATE OR REPLACE FUNCTION.  The original code would update pg_shdepend
as if a new function was being created, even if it wasn't, with two bad
consequences: pg_shdepend might record the wrong owner for the function,
and any dependencies for roles mentioned in the function's ACL would be lost.
The fix is very easy: just don't touch pg_shdepend at all when doing a
function replacement.

Also update the CREATE FUNCTION reference page, which never explained
exactly what changes and doesn't change in a function replacement.
In passing, fix the CREATE VIEW reference page similarly; there's no
code bug there, but the docs didn't say what happens.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.84.2.1 2009/09/03 22:11:13 tgl Exp $
a564 8
   <para>
    When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
    existing function, the ownership and permissions of the function
    do not change.  All other function properties are assigned the
    values specified or implied in the command.  You must own the function
    to replace it (this includes being a member of the owning role).
   </para>

@


1.84.2.3
log
@Document the behavior of STRICT VARIADIC functions.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.84.2.2 2009/10/02 18:13:10 tgl Exp $
a572 7
   <para>
    If a function is declared <literal>STRICT</> with a <literal>VARIADIC</>
    argument, the strictness check tests that the variadic array <emphasis>as
    a whole</> is non-null.  The function will still be called if the
    array has non-null elements.
   </para>

@


1.84.2.4
log
@Ooops, let's get the non-null vs null bit right ...
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.84.2.3 2010/02/14 00:48:20 tgl Exp $
d577 1
a577 1
    array has null elements.
@


1.83
log
@Code review for function default parameters patch.  Fix numerous problems as
per recent discussions.  In passing this also fixes a couple of bugs in
the previous variadic-parameters patch.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.82 2008/12/04 17:51:26 petere Exp $
d28 1
d246 14
@


1.82
log
@Default values for function arguments

Pavel Stehule, with some tweaks by Peter Eisentraut
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.81 2008/11/14 10:22:46 petere Exp $
d24 1
a24 1
    <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [ { DEFAULT | = } <replaceable class="parameter">defexpr</replaceable>] [, ...] ] )
d40 1
a40 1
  
d136 1
a136 1
       The data type(s) of the function's arguments (optionally 
d163 5
a167 4
       not specified.  The expression has to be convertable to the
       argument type of the parameter.  All parameters after a
       parameter with default value have to be parameters with default
       values as well.
d177 1
a177 1
       The return data type (optionally schema-qualified). The return type 
d501 12
a679 1
 
@


1.81
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.80 2008/07/18 03:32:52 tgl Exp $
d24 1
a24 1
    <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
d158 14
d684 8
@


1.80
log
@Implement SQL-spec RETURNS TABLE syntax for functions.

(Unlike the original submission, this patch treats TABLE output parameters
as being entirely equivalent to OUT parameters -- tgl)

Pavel Stehule
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.79 2008/07/16 01:30:21 tgl Exp $
d8 1
@


1.79
log
@Support "variadic" functions, which can accept a variable number of arguments
so long as all the trailing arguments are of the same (non-array) type.
The function receives them as a single array argument (which is why they
have to all be the same type).

It might be useful to extend this facility to aggregates, but this patch
doesn't do that.

This patch imposes a noticeable slowdown on function lookup --- a follow-on
patch will fix that by adding a redundant column to pg_proc.

Pavel Stehule
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.78 2007/09/11 00:06:41 tgl Exp $
d24 2
a25 1
    [ RETURNS <replaceable class="parameter">rettype</replaceable> ]
d53 1
a53 1
   with the same argument types in the same schema.  However,
d108 3
d191 24
d468 1
a468 1
    argument types.  However, the C names of all functions must be
d572 12
@


1.78
log
@Arrange for SET LOCAL's effects to persist until the end of the current top
transaction, unless rolled back or overridden by a SET clause for the same
variable attached to a surrounding function call.  Per discussion, these
seem the best semantics.  Note that this is an INCOMPATIBLE CHANGE: in 8.0
through 8.2, SET LOCAL's effects disappeared at subtransaction commit
(leading to behavior that made little sense at the SQL level).

I took advantage of the opportunity to rewrite and simplify the GUC variable
save/restore logic a little bit.  The old idea of a "tentative" value is gone;
it was a hangover from before we had a stack.  Also, we no longer need a stack
entry for every nesting level, but only for those in which a variable's value
actually changed.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.77 2007/09/03 18:46:29 tgl Exp $
d104 3
a106 2
       The mode of an argument: either <literal>IN</>, <literal>OUT</>,
       or <literal>INOUT</>.  If omitted, the default is <literal>IN</>.
@


1.78.2.1
log
@Make LOAD of an already-loaded library into a no-op, instead of attempting
to unload and re-load the library.

The difficulty with unloading a library is that we haven't defined safe
protocols for doing so.  In particular, there's no safe mechanism for
getting out of a "hook" function pointer unless libraries are unloaded
in reverse order of loading.  And there's no mechanism at all for undefining
a custom GUC variable, so GUC would be left with a pointer to an old value
that might or might not still be valid, and very possibly wouldn't be in
the same place anymore.

While the unload and reload behavior had some usefulness in easing
development of new loadable libraries, it's of no use whatever to normal
users, so just disabling it isn't giving up that much.  Someday we might
care to expend the effort to develop safe unload protocols; but even if
we did, there'd be little certainty that every third-party loadable module
was following them, so some security restrictions would still be needed.

Back-patch to 8.2; before that, LOAD was superuser-only anyway.

Security: unprivileged users could crash backend.  CVE not assigned yet
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.78 2007/09/11 00:06:41 tgl Exp $
d459 2
a460 1
    reload the file (perhaps during development), start a new session.
@


1.78.2.2
log
@Fix erroneous handling of shared dependencies (ie dependencies on roles)
in CREATE OR REPLACE FUNCTION.  The original code would update pg_shdepend
as if a new function was being created, even if it wasn't, with two bad
consequences: pg_shdepend might record the wrong owner for the function,
and any dependencies for roles mentioned in the function's ACL would be lost.
The fix is very easy: just don't touch pg_shdepend at all when doing a
function replacement.

Also update the CREATE FUNCTION reference page, which never explained
exactly what changes and doesn't change in a function replacement.
In passing, fix the CREATE VIEW reference page similarly; there's no
code bug there, but the docs didn't say what happens.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.78.2.1 2009/09/03 22:11:22 tgl Exp $
a492 8
   <para>
    When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
    existing function, the ownership and permissions of the function
    do not change.  All other function properties are assigned the
    values specified or implied in the command.  You must own the function
    to replace it (this includes being a member of the owning role).
   </para>

@


1.77
log
@Support SET FROM CURRENT in CREATE/ALTER FUNCTION, ALTER DATABASE, ALTER ROLE.
(Actually, it works as a plain statement too, but I didn't document that
because it seems a bit useless.)  Unify VariableResetStmt with
VariableSetStmt, and clean up some ancient cruft in the representation of
same.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.76 2007/09/03 00:39:13 tgl Exp $
d478 1
a478 1
    If any <literal>SET</> clauses are attached to a function, then
d480 3
a482 3
    function are restricted to the function: the configuration parameter's
    value is restored at function exit.  This is true even for parameters
    not mentioned in the <literal>SET</> clause(s).  However, an ordinary
@


1.76
log
@Implement function-local GUC parameter settings, as per recent discussion.
There are still some loose ends: I didn't do anything about the SET FROM
CURRENT idea yet, and it's not real clear whether we are happy with the
interaction of SET LOCAL with function-local settings.  The documentation
is a bit spartan, too.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.75 2007/04/23 16:52:53 neilc Exp $
d31 1
a31 1
    | SET <replaceable class="parameter">parameter</replaceable> { TO | = } { <replaceable class="parameter">value</replaceable> | DEFAULT }
d327 1
a327 1
     <term><replaceable>parameter</replaceable></term>
d334 2
@


1.75
log
@Fix newly-introduced documentation typo.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.74 2007/04/20 02:37:37 tgl Exp $
d31 1
d75 2
d327 18
d476 12
a565 1
        old_path TEXT;
a566 10
        -- Save old search_path; notice we must qualify current_setting
        -- to ensure we invoke the right function
        old_path := pg_catalog.current_setting('search_path');

        -- Set a secure search_path: trusted schemas, then 'pg_temp'.
        -- We set is_local = true so that the old value will be restored
        -- in event of an error before we reach the function end.
        PERFORM pg_catalog.set_config('search_path', 'admin, pg_temp', true);

        -- Do whatever secure work we came for.
a570 3
        -- Restore caller's search_path
        PERFORM pg_catalog.set_config('search_path', old_path, true);

d573 32
a604 1
$$ LANGUAGE plpgsql SECURITY DEFINER;
@


1.74
log
@Support explicit placement of the temporary-table schema within search_path.
This is needed to allow a security-definer function to set a truly secure
value of search_path.  Without it, a malicious user can use temporary objects
to execute code with the privileges of the security-definer function.  Even
pushing the temp schema to the back of the search path is not quite good
enough, because a function or operator at the back of the path might still
capture control from one nearer the front due to having a more exact datatype
match.  Hence, disable searching the temp schema altogether for functions and
operators.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.73 2007/02/01 19:10:24 momjian Exp $
d521 1
a521 1
    function.  Particularly important is in this regard is the
@


1.73
log
@Wording cleanup for error messages.  Also change can't -> cannot.

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.72 2007/01/31 23:26:03 momjian Exp $
d511 48
@


1.72
log
@Update reference documentation on may/can/might:

Standard English uses "may", "can", and "might" in different ways:

        may - permission, "You may borrow my rake."

        can - ability, "I can lift that log."

        might - possibility, "It might rain today."

Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice.  Similarly, "It may crash" is better stated, "It might crash".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.71 2007/01/22 01:35:19 tgl Exp $
d64 1
a64 1
   parameters, that means you can't change the names or types of any
@


1.71
log
@Add COST and ROWS options to CREATE/ALTER FUNCTION, plus underlying pg_proc
columns procost and prorows, to allow simple user adjustment of the estimated
cost of a function call, as well as control of the estimated number of rows
returned by a set-returning function.  We might eventually wish to extend this
to allow function-specific estimation routines, but there seems to be
consensus that we should try a simple constant estimate first.  In particular
this provides a relatively simple way to control the order in which different
WHERE clauses are applied in a plan node, which is a Good Thing in view of the
fact that the recent EquivalenceClass planner rewrite made that much less
predictable than before.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.70 2006/11/10 20:52:18 tgl Exp $
d52 1
a52 1
   functions of different argument types may share a name (this is
d128 2
a129 2
       schema-qualified), if any. The argument types may be base, composite,
       or domain types, or may reference the type of a table column.
d132 1
a132 1
       Depending on the implementation language it may also be allowed
d154 3
a156 3
       may be a base, composite, or domain type,
       or may reference the type of a table column.
       Depending on the implementation language it may also be allowed
d163 1
a163 1
       the <literal>RETURNS</> clause may be omitted.  If present, it
d188 1
a188 1
       May be <literal>SQL</literal>, <literal>C</literal>,
d191 1
a191 1
       the name may be enclosed by single quotes.
d205 1
a205 1
       may be specified.  If none of these appear,
d329 1
a329 1
       language.  It may be an internal function name, the path to an
d360 1
a360 1
       about the function.  The following attributes may appear here:
@


1.70
log
@Emphasize that immutable and stable functions are not allowed to modify
the database.  xfunc.sgml was already pretty definite on the point, but
it doesn't hurt to make it clear here too.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.69 2006/11/03 07:17:36 tgl Exp $
d29 2
d57 1
a57 1
   To update the definition of an existing function, use
d295 29
d434 2
a435 1
    the same object file, the file is only loaded once.  To unload and
@


1.70.2.1
log
@Support explicit placement of the temporary-table schema within search_path.
This is needed to allow a security-definer function to set a truly secure
value of search_path.  Without it, a malicious user can use temporary objects
to execute code with the privileges of the security-definer function.  Even
pushing the temp schema to the back of the search path is not quite good
enough, because a function or operator at the back of the path might still
capture control from one nearer the front due to having a more exact datatype
match.  Hence, disable searching the temp schema altogether for functions and
operators.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.70 2006/11/10 20:52:18 tgl Exp $
a478 48
 <refsect1 id="sql-createfunction-security">
  <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>

   <para>
    Because a <literal>SECURITY DEFINER</literal> function is executed
    with the privileges of the user that created it, care is needed to
    ensure that the function cannot be misused.  For security,
    <xref linkend="guc-search-path"> should be set to exclude any schemas
    writable by untrusted users.  This prevents
    malicious users from creating objects that mask objects used by the
    function.  Particularly important is in this regard is the
    temporary-table schema, which is searched first by default, and
    is normally writable by anyone.  A secure arrangement can be had
    by forcing the temporary schema to be searched last.  To do this,
    write <literal>pg_temp</> as the last entry in <varname>search_path</>.
    This function illustrates safe usage:
   </para>

<programlisting>
CREATE FUNCTION check_password(uname TEXT, pass TEXT)
RETURNS BOOLEAN AS $$
DECLARE passed BOOLEAN;
        old_path TEXT;
BEGIN
        -- Save old search_path; notice we must qualify current_setting
        -- to ensure we invoke the right function
        old_path := pg_catalog.current_setting('search_path');

        -- Set a secure search_path: trusted schemas, then 'pg_temp'.
        -- We set is_local = true so that the old value will be restored
        -- in event of an error before we reach the function end.
        PERFORM pg_catalog.set_config('search_path', 'admin, pg_temp', true);

        -- Do whatever secure work we came for.
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        -- Restore caller's search_path
        PERFORM pg_catalog.set_config('search_path', old_path, true);

        RETURN passed;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
</programlisting>

 </refsect1>

@


1.70.2.2
log
@Fix newly-introduced documentation typo.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.70.2.1 2007/04/20 02:37:48 tgl Exp $
d489 1
a489 1
    function.  Particularly important in this regard is the
@


1.70.2.3
log
@Make LOAD of an already-loaded library into a no-op, instead of attempting
to unload and re-load the library.

The difficulty with unloading a library is that we haven't defined safe
protocols for doing so.  In particular, there's no safe mechanism for
getting out of a "hook" function pointer unless libraries are unloaded
in reverse order of loading.  And there's no mechanism at all for undefining
a custom GUC variable, so GUC would be left with a pointer to an old value
that might or might not still be valid, and very possibly wouldn't be in
the same place anymore.

While the unload and reload behavior had some usefulness in easing
development of new loadable libraries, it's of no use whatever to normal
users, so just disabling it isn't giving up that much.  Someday we might
care to expend the effort to develop safe unload protocols; but even if
we did, there'd be little certainty that every third-party loadable module
was following them, so some security restrictions would still be needed.

Back-patch to 8.2; before that, LOAD was superuser-only anyway.

Security: unprivileged users could crash backend.  CVE not assigned yet
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.70.2.2 2007/04/23 16:52:56 neilc Exp $
d403 3
a405 3
    the same object file, the file is only loaded once per session.
    To unload and
    reload the file (perhaps during development), start a new session.
@


1.70.2.4
log
@Fix erroneous handling of shared dependencies (ie dependencies on roles)
in CREATE OR REPLACE FUNCTION.  The original code would update pg_shdepend
as if a new function was being created, even if it wasn't, with two bad
consequences: pg_shdepend might record the wrong owner for the function,
and any dependencies for roles mentioned in the function's ACL would be lost.
The fix is very easy: just don't touch pg_shdepend at all when doing a
function replacement.

Also update the CREATE FUNCTION reference page, which never explained
exactly what changes and doesn't change in a function replacement.
In passing, fix the CREATE VIEW reference page similarly; there's no
code bug there, but the docs didn't say what happens.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.70.2.3 2009/09/03 22:11:30 tgl Exp $
a426 8
   <para>
    When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
    existing function, the ownership and permissions of the function
    do not change.  All other function properties are assigned the
    values specified or implied in the command.  You must own the function
    to replace it (this includes being a member of the owning role).
   </para>

@


1.69
log
@Mention 'void' as the proper return type when there's nothing to
return, per suggestion from Joachim Wieland.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.68 2006/09/16 00:30:17 momjian Exp $
d201 2
a202 3
       These attributes inform the system whether it is safe to
       replace multiple evaluations of the function with a single
       evaluation, for run-time optimization.  At most one choice
d208 2
a209 1
       <literal>IMMUTABLE</literal> indicates that the function always
d218 3
a220 2
       <literal>STABLE</literal> indicates that within a single table scan
       the function will consistently
@


1.68
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.67 2005/11/01 21:09:50 tgl Exp $
d156 2
@


1.67
log
@Make an editorial pass over the reference pages.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.66 2005/07/14 06:17:36 neilc Exp $
a509 17

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
@


1.67.2.1
log
@Support explicit placement of the temporary-table schema within search_path.
This is needed to allow a security-definer function to set a truly secure
value of search_path.  Without it, a malicious user can use temporary objects
to execute code with the privileges of the security-definer function.  Even
pushing the temp schema to the back of the search path is not quite good
enough, because a function or operator at the back of the path might still
capture control from one nearer the front due to having a more exact datatype
match.  Hence, disable searching the temp schema altogether for functions and
operators.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.67 2005/11/01 21:09:50 tgl Exp $
a475 48
 <refsect1 id="sql-createfunction-security">
  <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>

   <para>
    Because a <literal>SECURITY DEFINER</literal> function is executed
    with the privileges of the user that created it, care is needed to
    ensure that the function cannot be misused.  For security,
    <xref linkend="guc-search-path"> should be set to exclude any schemas
    writable by untrusted users.  This prevents
    malicious users from creating objects that mask objects used by the
    function.  Particularly important is in this regard is the
    temporary-table schema, which is searched first by default, and
    is normally writable by anyone.  A secure arrangement can be had
    by forcing the temporary schema to be searched last.  To do this,
    write <literal>pg_temp</> as the last entry in <varname>search_path</>.
    This function illustrates safe usage:
   </para>

<programlisting>
CREATE FUNCTION check_password(uname TEXT, pass TEXT)
RETURNS BOOLEAN AS $$
DECLARE passed BOOLEAN;
        old_path TEXT;
BEGIN
        -- Save old search_path; notice we must qualify current_setting
        -- to ensure we invoke the right function
        old_path := pg_catalog.current_setting('search_path');

        -- Set a secure search_path: trusted schemas, then 'pg_temp'.
        -- We set is_local = true so that the old value will be restored
        -- in event of an error before we reach the function end.
        PERFORM pg_catalog.set_config('search_path', 'admin, pg_temp', true);

        -- Do whatever secure work we came for.
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        -- Restore caller's search_path
        PERFORM pg_catalog.set_config('search_path', old_path, true);

        RETURN passed;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
</programlisting>

 </refsect1>

@


1.67.2.2
log
@Fix newly-introduced documentation typo.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.67.2.1 2007/04/20 02:38:04 tgl Exp $
d486 1
a486 1
    function.  Particularly important in this regard is the
@


1.67.2.3
log
@Fix erroneous handling of shared dependencies (ie dependencies on roles)
in CREATE OR REPLACE FUNCTION.  The original code would update pg_shdepend
as if a new function was being created, even if it wasn't, with two bad
consequences: pg_shdepend might record the wrong owner for the function,
and any dependencies for roles mentioned in the function's ACL would be lost.
The fix is very easy: just don't touch pg_shdepend at all when doing a
function replacement.

Also update the CREATE FUNCTION reference page, which never explained
exactly what changes and doesn't change in a function replacement.
In passing, fix the CREATE VIEW reference page similarly; there's no
code bug there, but the docs didn't say what happens.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.67.2.2 2007/04/23 16:52:58 neilc Exp $
a423 8
   <para>
    When <command>CREATE OR REPLACE FUNCTION</> is used to replace an
    existing function, the ownership and permissions of the function
    do not change.  All other function properties are assigned the
    values specified or implied in the command.  You must own the function
    to replace it (this includes being a member of the owning role).
   </para>

@


1.66
log
@This doc patch replaces all inappropriate references to SQL:1999 when it
is used as if it were the latest (and/or still valid) SQL standard.
SQL:2003 is used in its place. Patch from Simon Riggs.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.65 2005/03/31 22:45:59 tgl Exp $
d231 3
a233 3
       <literal>timeofday()</>.  Note that any function that has side-effects
       must be classified volatile, even if its result is quite predictable,
       to prevent calls from being optimized away; an example is
d282 3
a284 3
      The key word <literal>EXTERNAL</literal> is present for SQL
      conformance but is optional since, unlike in SQL, this feature
      does not only apply to external functions.
d481 1
a481 1
   A <command>CREATE FUNCTION</command> command is defined in SQL:2003.
@


1.65
log
@First phase of OUT-parameters project.  We can now define and use SQL
functions with OUT parameters.  The various PLs still need work, as does
pg_dump.  Rudimentary docs and regression tests included.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.64 2005/01/04 00:39:53 tgl Exp $
d481 1
a481 1
   A <command>CREATE FUNCTION</command> command is defined in SQL:1999 and later.
@


1.64
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.63 2004/11/27 21:27:07 petere Exp $
d22 3
a24 2
CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> ( [ [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">rettype</replaceable>
d61 3
a63 1
   you must drop and recreate the function.
d95 11
d112 4
a115 1
       argument name is just extra documentation.
d158 7
d389 10
d430 1
a430 1
   Here is a trivial example to help you get started.  For more
a443 1

d452 22
d486 7
@


1.64.4.1
log
@Support explicit placement of the temporary-table schema within search_path.
This is needed to allow a security-definer function to set a truly secure
value of search_path.  Without it, a malicious user can use temporary objects
to execute code with the privileges of the security-definer function.  Even
pushing the temp schema to the back of the search path is not quite good
enough, because a function or operator at the back of the path might still
capture control from one nearer the front due to having a more exact datatype
match.  Hence, disable searching the temp schema altogether for functions and
operators.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.64 2005/01/04 00:39:53 tgl Exp $
a420 48
 <refsect1 id="sql-createfunction-security">
  <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>

   <para>
    Because a <literal>SECURITY DEFINER</literal> function is executed
    with the privileges of the user that created it, care is needed to
    ensure that the function cannot be misused.  For security,
    <xref linkend="guc-search-path"> should be set to exclude any schemas
    writable by untrusted users.  This prevents
    malicious users from creating objects that mask objects used by the
    function.  Particularly important is in this regard is the
    temporary-table schema, which is searched first by default, and
    is normally writable by anyone.  A secure arrangement can be had
    by forcing the temporary schema to be searched last.  To do this,
    write <literal>pg_temp</> as the last entry in <varname>search_path</>.
    This function illustrates safe usage:
   </para>

<programlisting>
CREATE FUNCTION check_password(uname TEXT, pass TEXT)
RETURNS BOOLEAN AS $$
DECLARE passed BOOLEAN;
        old_path TEXT;
BEGIN
        -- Save old search_path; notice we must qualify current_setting
        -- to ensure we invoke the right function
        old_path := pg_catalog.current_setting('search_path');

        -- Set a secure search_path: trusted schemas, then 'pg_temp'.
        -- We set is_local = true so that the old value will be restored
        -- in event of an error before we reach the function end.
        PERFORM pg_catalog.set_config('search_path', 'admin, pg_temp', true);

        -- Do whatever secure work we came for.
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        -- Restore caller's search_path
        PERFORM pg_catalog.set_config('search_path', old_path, true);

        RETURN passed;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;
</programlisting>

 </refsect1>

@


1.64.4.2
log
@Fix newly-introduced documentation typo.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.64.4.1 2007/04/20 02:38:29 tgl Exp $
d431 1
a431 1
    function.  Particularly important in this regard is the
@


1.63
log
@Update of conformance information to SQL:2003
by Troels Arvin, Simon Riggs, Elein Mustain

Make spelling of SQL standard names uniform.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.62 2004/10/01 02:00:44 neilc Exp $
d65 2
a66 2
   the same entity as the old; you will break existing rules, views,
   triggers, etc. that referred to the old function.  Use
d109 8
a116 2
       schema-qualified), if any. The argument types may be base, complex, or 
       domains, or copy the type of an existing column.
d122 2
a123 2
       class="parameter">columnname</replaceable>%TYPE</literal>;
       using this can sometimes help make a function independent from
a125 6
      <para>
       Depending on the implementation language it may also be allowed
       to specify <quote>pseudotypes</> such as <type>cstring</>.
       Pseudotypes indicate that the actual argument type is either
       incompletely specified, or outside the set of ordinary SQL data types.
      </para>
d135 4
a138 4
       may be a base type, complex type, or a domain,
       or may be specified to copy the type of an existing column. See the description
       under <literal>argtype</literal> above on how to reference the type
       of an existing column.
a140 2
       Depending on the implementation language it may also be allowed
       to specify <quote>pseudotypes</> such as <type>cstring</>.
d145 6
d162 1
a162 2
       procedural language.  (See also <xref linkend="app-createlang"
       endterm="app-createlang-title">.)  For backward compatibility,
d309 1
a309 1
          Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>
d400 1
a400 1
    AS $$select $1 + $2;$$
d412 1
a412 1
CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS '
d415 2
a416 1
        END;' LANGUAGE plpgsql;
d434 1
a434 1
 <refsect1 id="sql-createfunction-seealso">
d437 8
a444 8
  <para>
   <xref linkend="sql-alterfunction" endterm="sql-alterfunction-title">,
   <xref linkend="sql-dropfunction" endterm="sql-dropfunction-title">,
   <xref linkend="sql-grant" endterm="sql-grant-title">,
   <xref linkend="sql-load" endterm="sql-load-title">,
   <xref linkend="sql-revoke" endterm="sql-revoke-title">,
   <xref linkend="app-createlang">
  </para>
@


1.62
log
@Remove more traces of libpgtcl from the source tree. Also, make some
semi-related SGML cleanup. Original patch from ljb220@@mindspring.com,
additional cleanup by Neil Conway.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.61 2004/09/20 22:48:29 tgl Exp $
d422 1
a422 1
   A <command>CREATE FUNCTION</command> command is defined in SQL99.
@


1.61
log
@Some editorializing on the docs for the dollar-quoting feature: fix
grammar, don't drop discussions into the middle of unrelated discussions,
etc.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.60 2004/09/16 04:16:08 neilc Exp $
d405 2
a406 1
   Increment an integer, making use of an argument name, in PL/PgSQL:
@


1.60
log
@Minor doc tweak: mention that function names can be optionally schema-
qualified.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.59 2004/09/13 20:05:38 tgl Exp $
d267 1
a267 1
       A string defining the function; the meaning depends on the
d269 1
a269 8
       object file, an SQL command, or text in a procedural
       language. When this string contains the text of a procedural
       language function definition, it may be helpful to use dollar
       quoting to specify this string, rather than the normal single
       quote syntax (this avoids the need to escape any single quotes
       that occur in the function definition itself). For more
       information on dollar quoting, see <xref
       linkend="sql-syntax-strings">.
d374 7
a380 4
  <para>
   Unless dollar quoting is used, any single quotes or backslashes in
   the function definition must be escaped by doubling them.
  </para>
d409 3
a411 3
	BEGIN
		RETURN i + 1;
	END;' LANGUAGE plpgsql;
@


1.59
log
@Redesign query-snapshot timing so that volatile functions in READ COMMITTED
mode see a fresh snapshot for each command in the function, rather than
using the latest interactive command's snapshot.  Also, suppress fresh
snapshots as well as CommandCounterIncrement inside STABLE and IMMUTABLE
functions, instead using the snapshot taken for the most closely nested
regular query.  (This behavior is only sane for read-only functions, so
the patch also enforces that such functions contain only SELECT commands.)
As per my proposal of 6-Sep-2004; I note that I floated essentially the
same proposal on 19-Jun-2002, but that discussion tailed off without any
action.  Since 8.0 seems like the right place to be taking possibly
nontrivial backwards compatibility hits, let's get it done now.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.58 2004/07/11 23:23:43 momjian Exp $
d86 1
a86 1
       The name of a function to create.
@


1.58
log
@Example for create function using argument names

Gavin Sherry
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.57 2004/06/25 07:05:34 dennis Exp $
d175 1
a175 1
       should be specified.  If none of these appear,
d209 4
@


1.57
log
@Add argument name to syntax.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.56 2004/05/16 23:22:07 neilc Exp $
d401 11
@


1.56
log
@Add documentation for the new "dollar quoting" feature, and update existing
examples to use dollar quoting when appropriate. Original patch from David
Fetter, additional work and editorializing by Neil Conway.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.55 2003/11/29 19:51:38 pgsql Exp $
d22 1
a22 1
CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
d27 1
a27 1
    | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
d87 12
@


1.55
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.54 2003/11/12 22:47:47 petere Exp $
d57 4
a60 4
   tried, you'd just be creating a new, distinct function).  Also,
   <command>CREATE OR REPLACE FUNCTION</command> will not let you
   change the return type of an existing function.  To do that, you
   must drop and recreate the function.
d253 8
a260 1
       object file, an SQL command, or text in a procedural language.
d360 3
a362 2
    Use <command>DROP FUNCTION</command>
    to remove user-defined functions.
d366 2
a367 2
   Any single quotes or backslashes in the function definition must be
   escaped by doubling them.
d385 1
a385 1
    AS 'select $1 + $2;'
@


1.54
log
@Documentation cleanup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.53 2003/10/26 04:34:05 momjian Exp $
@


1.53
log
@Add mention of quotes on function body to NOTES section.

Oliver Elphick
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.52 2003/09/11 21:42:20 momjian Exp $
d98 1
a98 1
       domain types, or copy the type of an existing column.
d123 2
a124 2
       may be specified as a base, complex, or domain type,
       or may copy the type of an existing column. See the description
@


1.53.2.1
log
@Documentation cleanup
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.53 2003/10/26 04:34:05 momjian Exp $
d98 1
a98 1
       domains, or copy the type of an existing column.
d123 2
a124 2
       may be a base type, complex type, or a domain,
       or may be specified to copy the type of an existing column. See the description
@


1.53.2.2
log
@Support explicit placement of the temporary-table schema within search_path.
This is needed to allow a security-definer function to set a truly secure
value of search_path.  Without it, a malicious user can use temporary objects
to execute code with the privileges of the security-definer function.  Even
pushing the temp schema to the back of the search path is not quite good
enough, because a function or operator at the back of the path might still
capture control from one nearer the front due to having a more exact datatype
match.  Hence, disable searching the temp schema altogether for functions and
operators.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.53.2.1 2003/11/12 20:05:15 petere Exp $
a384 48
 <refsect1 id="sql-createfunction-security">
  <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>

   <para>
    Because a <literal>SECURITY DEFINER</literal> function is executed
    with the privileges of the user that created it, care is needed to
    ensure that the function cannot be misused.  For security,
    <xref linkend="guc-search-path"> should be set to exclude any schemas
    writable by untrusted users.  This prevents
    malicious users from creating objects that mask objects used by the
    function.  Particularly important is in this regard is the
    temporary-table schema, which is searched first by default, and
    is normally writable by anyone.  A secure arrangement can be had
    by forcing the temporary schema to be searched last.  To do this,
    write <literal>pg_temp</> as the last entry in <varname>search_path</>.
    This function illustrates safe usage:
   </para>

<programlisting>
CREATE FUNCTION check_password(TEXT, TEXT)
RETURNS BOOLEAN AS '
DECLARE passed BOOLEAN;
        old_path TEXT;
BEGIN
        -- Save old search_path; notice we must qualify current_setting
        -- to ensure we invoke the right function
        old_path := pg_catalog.current_setting(''search_path'');

        -- Set a secure search_path: trusted schemas, then ''pg_temp''.
        -- We set is_local = true so that the old value will be restored
        -- in event of an error before we reach the function end.
        PERFORM pg_catalog.set_config(''search_path'', ''admin, pg_temp'', true);

        -- Do whatever secure work we came for.
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        -- Restore caller''s search_path
        PERFORM pg_catalog.set_config(''search_path'', old_path, true);

        RETURN passed;
END;
' LANGUAGE plpgsql SECURITY DEFINER;
</programlisting>

 </refsect1>

@


1.53.2.3
log
@Fix markup.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.53.2.2 2007/04/20 02:38:44 tgl Exp $
d392 1
a392 1
    <varname>search_path</> should be set to exclude any schemas
@


1.53.2.4
log
@Fix newly-introduced documentation typo.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.53.2.3 2007/04/20 03:10:51 tgl Exp $
d395 1
a395 1
    function.  Particularly important in this regard is the
@


1.52
log
@This patch fixes a few missed GUC variables that were still upper case,
makes a few more small improvements to runtime.sgml, and makes some SGML
conventions more consistent.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.51 2003/09/10 20:13:45 momjian Exp $
d358 2
a359 2
   To be able to define a function, the user must have the
   <literal>USAGE</literal> privilege on the language.
d361 6
@


1.51
log
@This patch fixes a trivial typo in the CREATE FUNCTION ref page.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.50 2003/09/09 18:28:52 tgl Exp $
d385 1
a385 1
   The <application>PostgreSQL</application> version is similar but
@


1.50
log
@Remove a bunch of content-free Diagnostics sections, as per previous
discussion.  (Still have some work to do editing the remainder.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.49 2003/08/31 17:32:22 petere Exp $
d367 1
a367 1
   Here is a trivial example to help you get startet.  For more
@


1.49
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.48 2003/06/27 14:45:26 petere Exp $
a314 15
 </refsect1>

 <refsect1>
  <title>Diagnostics</title>

  <variablelist>
   <varlistentry>
    <term><computeroutput>CREATE FUNCTION</computeroutput></term>
    <listitem>
     <para>
      Message returned if the function was successfully created.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
@


1.48
log
@First batch of object rename commands.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.47 2003/04/22 10:08:08 petere Exp $
d15 4
@


1.48.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.49 2003/08/31 17:32:22 petere Exp $
a14 4

 <indexterm zone="sql-createfunction">
  <primary>CREATE FUNCTION</primary>
 </indexterm>
@


1.47
log
@More editing of reference pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.46 2003/03/25 16:15:39 petere Exp $
d407 1
@


1.46
log
@Merge documentation into one book.  (Build with "make html".)  Replace
vague cross-references with real links.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.45 2003/03/20 04:41:13 momjian Exp $
d41 27
d70 4
a75 1
    <title>Parameters</title>
d82 1
a82 8
       The name of a function to create.  If a schema name is included,
       then the function is created in the
       specified schema.  Otherwise it is created in the current schema (the
       one at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
       The name of the new function must not match any existing function
       with the same argument types in the same schema.  However, functions of
       different argument types may share a name (this is called
       <firstterm>overloading</>).
d93 2
a94 2
       schema-qualified), if any. The input types may be base, complex, or 
       domain types, or the same as the type of an existing column.
d97 2
a98 1
       The type of a column is referenced by writing <replaceable
d100 1
a100 1
       class="parameter">columnname</replaceable><literal>%TYPE</literal>;
d106 2
a107 2
       to specify <quote>pseudo-types</> such as <type>cstring</>.
       Pseudo-types indicate that the actual argument type is either
d119 2
a120 2
       may be specified as a base, complex, domain type 
       or the same as the type of an existing column. See the description
d126 2
a127 2
       to specify <quote>pseudo-types</> such as <type>cstring</>.
       The <literal>setof</literal>
d150 3
a152 3
     <term>IMMUTABLE</term>
     <term>STABLE</term>
     <term>VOLATILE</term>
d167 1
a167 1
       directly present in its parameter list.  If this option is given,
d179 1
a179 1
       that the <literal>CURRENT_TIMESTAMP</> family of functions qualify
d197 3
a199 3
     <term>CALLED ON NULL INPUT</term>
     <term>RETURNS NULL ON NULL INPUT</term>
     <term>STRICT</term>
d213 1
a213 1
       returns NULL whenever any of its arguments are NULL.  If this
d215 1
a215 1
       are NULL arguments; instead a NULL result is assumed
d222 2
a223 2
    <term><optional>EXTERNAL</optional> SECURITY INVOKER</term>
    <term><optional>EXTERNAL</optional> SECURITY DEFINER</term>
d236 1
a236 1
      compatibility but is optional since, unlike in SQL, this feature
d249 1
a249 1
       object file, an SQL query, or text in a procedural language.
d255 1
a255 1
     <term><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></term>
d260 1
a260 1
       dynamically linked C language functions when the function name
d266 3
a268 2
       object's link symbol, that is, the name of the function in the C
       language source code.
d313 15
d333 1
a333 1
    external functions.
d340 1
a340 1
    <type>numeric</type> types) are the responsibility of the
d347 7
a353 23
    <productname>PostgreSQL</productname> allows function <firstterm>overloading</firstterm>;
    that is, the same name can be used for several different functions
    so long as they have distinct argument types.  This facility must
    be used with caution for internal and C-language functions, however.    
   </para>

   <para>
    Two <literal>internal</literal>
    functions cannot have the same C name without causing
    errors at link time.  To get around that, give them different C names
    (for example, use the argument types as part of the C names), then
    specify those names in the AS clause of <command>CREATE FUNCTION</command>.
    If the AS clause is left empty, then <command>CREATE FUNCTION</command>
    assumes the C name of the function is the same as the SQL name.
   </para>

   <para>
    Similarly, when overloading SQL function names with multiple C-language
    functions, give
    each C-language instance of the function a distinct name, then use
    the alternative form of the <command>AS</command> clause in the
    <command>CREATE FUNCTION</command> syntax to select the appropriate
    C-language implementation of each overloaded SQL function.
a367 18
   <para>
    To update the definition of an existing function, use
    <command>CREATE OR REPLACE FUNCTION</command>.  Note that it is
    not possible to change the name or argument types of a function
    this way (if you tried, you'd just be creating a new, distinct
    function).  Also, <command>CREATE OR REPLACE FUNCTION</command>
    will not let you change the return type of an existing function.
    To do that, you must drop and re-create the function.
   </para>

   <para>
    If you drop and then re-create a function, the new function is not
    the same entity as the old; you will break existing rules, views,
    triggers, etc that referred to the old function.  Use 
    <command>CREATE OR REPLACE FUNCTION</command> to change a function
    definition without breaking objects that refer to the function.
   </para>

a371 7

  <para>
   By default, only the owner (creator) of the function has the right
   to execute it.  Other users must be granted the
   <literal>EXECUTE</literal> privilege on the function to be able to
   use it.
  </para>
d378 2
a379 25
   To create a simple SQL function:

<programlisting>
CREATE FUNCTION one() RETURNS integer
    AS 'SELECT 1 AS RESULT;'
    LANGUAGE SQL;

SELECT one() AS answer;
<computeroutput>
 answer 
--------
      1
</computeroutput>
</programlisting>
  </para>

  <para>
   The next example creates a C function by calling a routine from a
   user-created shared library named <filename>funcs.so</> (the extension
   may vary across platforms).  The shared library file is sought in the
   server's dynamic library search path.  This particular routine calculates
   a check digit and returns true if the check digit in the function
   parameters is correct.  It is intended for use in a CHECK
   constraint.

d381 5
a385 10
CREATE FUNCTION ean_checkdigit(char, char) RETURNS boolean
    AS 'funcs' LANGUAGE C;
    
CREATE TABLE product (
    id        char(8) PRIMARY KEY,
    eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
                      REFERENCES brandname(ean_prefix),
    eancode   char(6) CHECK (eancode ~ '[0-9]{6}'),
    CONSTRAINT ean    CHECK (ean_checkdigit(eanprefix, eancode))
);
a387 37

  <para>
   The next example creates a function that does type conversion from the
   user-defined type complex to the built-in type point.  The
   function is implemented by a dynamically loaded object that was
   compiled from C source (we illustrate the now-deprecated alternative
   of specifying the absolute file name to the shared object file).
   For <productname>PostgreSQL</productname> to
   find a type conversion function automatically, the SQL function has
   to have the same name as the return type, and so overloading is
   unavoidable.  The function name is overloaded by using the second
   form of the <command>AS</command> clause in the SQL definition:

<programlisting>
CREATE FUNCTION point(complex) RETURNS point
    AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
    LANGUAGE C STRICT;
</programlisting>

  The C declaration of the function could be:

<programlisting>
Point * complex_to_point (Complex *z)
{
    Point *p;

    p = (Point *) palloc(sizeof(Point));
    p->x = z->x;
    p->y = z->y;
        
    return p;
}
</programlisting>

   Note that the function is marked <quote>strict</>; this allows us
   to skip checking for NULL input in the function body.
  </para>    
@


1.45
log
@Minor doc patch: create function

Gavin Sherry
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.44 2003/01/19 00:13:29 momjian Exp $
d292 2
a293 4
    Refer to the chapter in the &cite-programmer;
    on the topic of extending
    <productname>PostgreSQL</productname> via functions 
    for further information on writing external functions.
d477 1
a477 2
   <xref linkend="app-createlang">,
   &cite-programmer;
@


1.44
log
@This patch includes a lot of minor cleanups to the SGML documentation,
including:

- replacing all the appropriate usages of <citetitle>PostgreSQL
...</citetitle> with &cite-user;, &cite-admin;, and so on

- fix an omission in the EXECUTE documentation

- add some more text to the EXPLAIN documentation

- improve the PL/PgSQL RETURN NEXT documentation (more work to do here)

- minor markup fixes


Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.43 2002/09/21 18:32:54 petere Exp $
d69 16
a84 12
       The data type(s) of the function's arguments, if any.  The
       input types may be base, complex, or domain types,
       or the same as the type of an existing column.
	The type of a column is referenced by writing <replaceable
	class="parameter">tablename</replaceable>.<replaceable
	class="parameter">columnname</replaceable><literal>%TYPE</literal>;
	using this can sometimes help make a function independent from
	changes to the definition of a table.
	Depending on the implementation language it may also be allowed
	to specify <quote>pseudo-types</> such as <type>cstring</>.
	Pseudo-types indicate that the actual argument type is either
	incompletely specified, or outside the set of ordinary SQL data types.
d94 7
a100 3
       The return data type.  The return type may be specified as a
       base, complex, or domain type, or the same as the type of an
       existing column.
d443 1
a443 1
	Point *p;
d445 5
a449 5
	p = (Point *) palloc(sizeof(Point));
	p->x = z->x;
	p->y = z->y;
		
	return p;
@


1.43
log
@Add more appropriate markup.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.42 2002/08/22 00:01:40 tgl Exp $
d284 1
a284 2
    Refer to the chapter in the
    <citetitle>PostgreSQL Programmer's Guide</citetitle>
d472 1
a472 1
   <citetitle>PostgreSQL Programmer's Guide</citetitle>
@


1.43.2.1
log
@Support explicit placement of the temporary-table schema within search_path.
This is needed to allow a security-definer function to set a truly secure
value of search_path.  Without it, a malicious user can use temporary objects
to execute code with the privileges of the security-definer function.  Even
pushing the temp schema to the back of the search path is not quite good
enough, because a function or operator at the back of the path might still
capture control from one nearer the front due to having a more exact datatype
match.  Hence, disable searching the temp schema altogether for functions and
operators.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.43 2002/09/21 18:32:54 petere Exp $
a450 48
 <refsect1 id="sql-createfunction-security">
  <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title>

   <para>
    Because a <literal>SECURITY DEFINER</literal> function is executed
    with the privileges of the user that created it, care is needed to
    ensure that the function cannot be misused.  For security,
    <xref linkend="guc-search-path"> should be set to exclude any schemas
    writable by untrusted users.  This prevents
    malicious users from creating objects that mask objects used by the
    function.  Particularly important is in this regard is the
    temporary-table schema, which is searched first by default, and
    is normally writable by anyone.  A secure arrangement can be had
    by forcing the temporary schema to be searched last.  To do this,
    write <literal>pg_temp</> as the last entry in <varname>search_path</>.
    This function illustrates safe usage:
   </para>

<programlisting>
CREATE FUNCTION check_password(TEXT, TEXT)
RETURNS BOOLEAN AS '
DECLARE passed BOOLEAN;
        old_path TEXT;
BEGIN
        -- Save old search_path; notice we must qualify current_setting
        -- to ensure we invoke the right function
        old_path := pg_catalog.current_setting(''search_path'');

        -- Set a secure search_path: trusted schemas, then ''pg_temp''.
        -- We set is_local = true so that the old value will be restored
        -- in event of an error before we reach the function end.
        PERFORM pg_catalog.set_config(''search_path'', ''admin, pg_temp'', true);

        -- Do whatever secure work we came for.
        SELECT  (pwd = $2) INTO passed
        FROM    pwds
        WHERE   username = $1;

        -- Restore caller''s search_path
        PERFORM pg_catalog.set_config(''search_path'', old_path, true);

        RETURN passed;
END;
' LANGUAGE plpgsql SECURITY DEFINER;
</programlisting>

 </refsect1>

@


1.43.2.2
log
@Fix markup.

Security: CVE-2007-2138
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.43.2.1 2007/04/20 02:38:57 tgl Exp $
d458 1
a458 1
    <varname>search_path</> should be set to exclude any schemas
@


1.43.2.3
log
@Fix newly-introduced documentation typo.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.43.2.2 2007/04/20 03:10:57 tgl Exp $
d461 1
a461 1
    function.  Particularly important in this regard is the
@


1.42
log
@Add a bunch of pseudo-types to replace the behavior formerly associated
with OPAQUE, as per recent pghackers discussion.  I still want to do some
more work on the 'cstring' pseudo-type, but I'm going to commit the bulk
of the changes now before the tree starts shifting under me ...
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_function.sgml,v 1.41 2002/07/24 19:11:07 petere Exp $
d80 1
a80 1
	incompletely specified, or outside the set of ordinary SQL datatypes.
d174 1
a174 1
       responsibility to check for NULLs if necessary and respond
d250 1
a250 1
        <term>isStrict</term>
d259 1
a259 1
        <term>isCachable</term>
@


1.41
log
@Remove unused system table columns:

pg_language.lancompiler
pg_operator.oprprec
pg_operator.oprisleft
pg_proc.proimplicit
pg_proc.probyte_pct
pg_proc.properbyte_cpu
pg_proc.propercall_cpu
pg_proc.prooutin_ratio
pg_shadow.usetrace
pg_type.typprtlen
pg_type.typreceive
pg_type.typsend

Attempts to use the obsoleted attributes of pg_operator or pg_proc
in the CREATE commands will be greeted by a warning.  For pg_type,
there is no warning (yet) because pg_dump scripts still contain these
attributes.

Also remove new but already obsolete spellings
isVolatile, isStable, isImmutable in WITH clause.  (Use new syntax
instead.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.40 2002/07/18 23:11:27 petere Exp $
d70 3
a72 6
       input types may be base or complex types,
       <literal>opaque</literal>, or the same as the type of an
       existing column.  <literal>Opaque</literal> indicates
       that the function accepts arguments of a non-SQL type such as
       <type>char *</type>.
	The type of a column is indicated using <replaceable
d77 4
d91 1
a91 2
       base type, complex type, <literal>setof</literal> type,
       <literal>opaque</literal>, or the same as the type of an
d93 2
d97 1
a97 4
       items, rather than a single item.  Functions with a declared
       return type of <literal>opaque</literal> do not return a value.
       These cannot be called directly; trigger functions make use of
       this feature.
@


1.40
log
@pg_cast table, and standards-compliant CREATE/DROP CAST commands, plus
extension to create binary compatible casts.  Includes dependency tracking
as well.

pg_proc.proimplicit is now defunct, but will be removed in a separate
commit.

pg_dump provides a migration path from the previous scheme to declare
casts.  Dumping binary compatible casts is currently impossible, though.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.39 2002/05/18 13:47:59 petere Exp $
a259 1
        <term>isImmutable</term>
a260 2
        <term>isStable</term>
        <term>isVolatile</term>
a262 2
          Equivalent to <literal>IMMUTABLE</literal>,
          <literal>STABLE</literal>, <literal>VOLATILE</literal>.
d264 1
a264 1
          <literal>isImmutable</literal>; it's still accepted for
@


1.39
log
@Allow functions to be executed with the privileges of the function owner.
I took the opportunity to remove the pg_proc.proistrusted field.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.38 2002/05/17 18:32:52 petere Exp $
a22 1
    | IMPLICIT CAST
a189 12
    <varlistentry>
     <term><literal>IMPLICIT CAST</literal</term>

     <listitem>
      <para>
       Indicates that the function may be used for implicit type
       conversions.  See <xref linkend="sql-createfunction-cast-functions"
       endterm="sql-createfunction-cast-functions-title"> for more detail.
      </para>
     </listitem>
    </varlistentry>

a274 8
       <varlistentry>
        <term>implicitCoercion</term>
        <listitem>
         <para>
          Same as <literal>IMPLICIT CAST</literal>
         </para>
        </listitem>
       </varlistentry>
a375 49
 <refsect1 id="sql-createfunction-cast-functions">
  <title id="sql-createfunction-cast-functions-title">
   Type Cast Functions
  </title>
  <para>
   A function that has one argument and is named the same as its return
   data type (including the schema name) is considered to be a <firstterm>type
   casting function</>: it can be invoked to convert a value of its input
   data type into a value 
   of its output datatype.  For example,
<programlisting>
SELECT CAST(42 AS text);
</programlisting>
   converts the integer constant 42 to text by invoking a function
   <literal>text(int4)</>, if such a function exists and returns type
   text.  (If no suitable conversion function can be found, the cast fails.)
  </para>

  <para>
   If a potential cast function is marked <literal>IMPLICIT CAST</>,
   then it can be invoked implicitly in any context where the
   conversion it defines is required.  Cast functions not so marked
   can be invoked only by explicit <literal>CAST</>,
   <replaceable>x</><literal>::</><replaceable>typename</>, or
   <replaceable>typename</>(<replaceable>x</>) constructs.  For
   example, supposing that <literal>foo.f1</literal> is a column of
   type <type>text</type>, then
<programlisting>
INSERT INTO foo(f1) VALUES(42);
</programlisting>
   will be allowed if <literal>text(int4)</> is marked
   <literal>IMPLICIT CAST</>, otherwise not.
  </para>

  <para>
   It is wise to be conservative about marking cast functions as
   implicit casts.  An overabundance of implicit casting paths can
   cause <productname>PostgreSQL</productname> to choose surprising
   interpretations of commands, or to be unable to resolve commands at
   all because there are multiple possible interpretations.  A good
   rule of thumb is to make cast implicitly invokable only for
   information-preserving transformations between types in the same
   general type category.  For example, <type>int2</type> to
   <type>int4</type> casts can reasonably be implicit, but be wary of
   marking <type>int4</type> to <type>text</type> or
   <type>float8</type> to <type>int4</type> as implicit casts.
  </para>
 </refsect1>
  
@


1.38
log
@Extend syntax of CREATE FUNCTION to resemble SQL99.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.37 2002/04/23 02:07:15 tgl Exp $
d24 1
d203 21
d397 1
a397 1
 <refsect1 id="sql-createfunction-cast-function">
@


1.37
log
@Update SQL-command reference pages for schema features.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.36 2002/04/11 19:59:55 tgl Exp $
d20 7
a26 7
    AS '<replaceable class="parameter">definition</replaceable>'
    LANGUAGE <replaceable class="parameter">langname</replaceable>
    [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">rettype</replaceable>
    AS '<replaceable class="parameter">obj_file</replaceable>', '<replaceable class="parameter">link_symbol</replaceable>'
    LANGUAGE <replaceable class="parameter">langname</replaceable>
d36 7
a42 2
   <command>CREATE OR REPLACE FUNCTION</command> will either create
   a new function, or replace an existing definition.
d89 1
a89 1
       The return data type.  The output type may be specified as a
d104 99
d233 1
a233 1
     <term><replaceable class="parameter">langname</replaceable></term>
d237 2
a238 11
       May be <literal>SQL</literal>, <literal>C</literal>,
       <literal>internal</literal>, or <replaceable
       class="parameter">plname</replaceable>, where <replaceable
       class="parameter">plname</replaceable> is the name of a
       created procedural language. See
       <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
       for details.  For backward compatibility, the name may be
       enclosed by single quotes.
      </para>
     </listitem>
    </varlistentry>
d240 40
a279 10
    <varlistentry>
     <term><replaceable class="parameter">attribute</replaceable></term>

     <listitem>
      <para>
       An optional piece of information about the function, used for
       optimization.  See below for details.
      </para>
     </listitem>
    </varlistentry>
a281 81
  </para>

  <para>
   The user that creates the function becomes the owner of the function.
  </para>

  <para>
    The following attributes may appear in the WITH clause:

    <variablelist>
     <varlistentry>
      <term>isStrict</term>
      <listitem>
       <para>
	<option>isStrict</option> indicates that the function always
	returns NULL whenever any of its arguments are NULL.  If this
	attribute is specified, the function is not executed when there
	are NULL arguments; instead a NULL result is assumed automatically.
	When <option>isStrict</option> is not specified, the function will
	be called for NULL inputs.  It is then the function author's
	responsibility to check for NULLs if necessary and respond
	appropriately.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>isImmutable</term>
      <term>isCachable</term>
      <term>isStable</term>
      <term>isVolatile</term>
      <listitem>
       <para>
        These attributes inform the system whether it is safe to replace
	multiple evaluations of the function with a single evaluation.
	At most one choice should be specified.  (If none of these appear,
	<option>isVolatile</option> is the default assumption.)
	<option>isImmutable</option> indicates that the function always
	returns the same result when given the same argument values; that
	is, it does not do database lookups or otherwise use information not
	directly present in its parameter list.  If this option is given,
	any call of the function with all-constant arguments can be
	immediately replaced with the function value.
	<option>isCachable</option> is an
	obsolete equivalent of <option>isImmutable</option>; it's still
	accepted for backwards-compatibility reasons.
	<option>isStable</option> indicates that within a single table scan
	the function will consistently
	return the same result for the same argument values, but that its
	result could change across SQL statements.  This is the appropriate
	selection for functions whose results depend on database lookups,
	parameter variables (such as the current timezone), etc.  Also note
	that the <literal>CURRENT_TIMESTAMP</> family of functions qualify
	as stable, since their values do not change within a transaction.
	<option>isVolatile</option> indicates that the function value can
	change even within a single table scan, so no optimizations can be
	made.  Relatively few database functions are volatile in this sense;
	some examples are <literal>random()</>, <literal>currval()</>,
	<literal>timeofday()</>.  Note that any function that has side-effects
	must be classified volatile, even if its result is quite predictable,
	to prevent calls from being optimized away; an example is
	<literal>setval()</>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>implicitCoercion</term>
      <listitem>
       <para>
	<option>implicitCoercion</option> indicates that the function 
	may be used for implicit type conversions.
	See <xref linkend="coercion-functions"
	endterm="coercion-functions-title"> for more detail.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

    Attribute names are not case-sensitive.
  </para>
d375 3
a377 6
 <refsect1 id="COERCION-FUNCTIONS">
  <refsect1info>
   <date>2002-04-11</date>
  </refsect1info>
  <title id="coercion-functions-title">
   Type Coercion Functions
d380 4
a383 4
   A function that has one parameter and is named the same as its output
   datatype (including the schema name) is considered to be a <firstterm>type
   coercion function</>: it can be invoked to convert a value of its input
   datatype into a value 
d386 1
a386 1
	SELECT CAST(42 AS text);
d394 8
a401 7
   If a potential coercion function is marked <literal>implicitCoercion</>,
   then it can be invoked in any context where the conversion it defines
   is required.  Coercion functions not so marked can be invoked only by
   explicit <literal>CAST</>,
   <replaceable>x</><literal>::</><replaceable>typename</>,
   or <replaceable>typename</>(<replaceable>x</>) constructs.
   For example, supposing that foo.f1 is a column of type text, then
d403 1
a403 1
	INSERT INTO foo(f1) VALUES(42);
d406 1
a406 1
   <literal>implicitCoercion</>, otherwise not.
d410 11
a420 10
   It is wise to be conservative about marking coercion functions as
   implicit coercions.  An overabundance of implicit coercion paths
   can cause <productname>PostgreSQL</productname> to choose surprising
   interpretations of commands, 
   or to be unable to resolve commands at all because there are multiple
   possible interpretations.  A good rule of thumb is to make coercions
   implicitly invokable only for information-preserving transformations
   between types in the same general type category.  For example, int2
   to int4 coercion can reasonably be implicit, but be wary of marking
   int4 to text or float8 to int4 as implicit coercions.
d449 1
a449 1
   a check digit and returns TRUE if the check digit in the function
d468 1
a468 1
   This example creates a function that does type conversion from the
d482 1
a482 1
    LANGUAGE C WITH (isStrict);
d512 1
a512 1
   not compatible.  The attributes are not portable, neither are the
d522 5
a526 4
   <xref linkend="sql-dropfunction">,
   <xref linkend="sql-grant">,
   <xref linkend="sql-load">,
   <xref linkend="sql-revoke">,
@


1.36
log
@Restructure representation of aggregate functions so that they have pg_proc
entries, per pghackers discussion.  This fixes aggregates to live in
namespaces, and also simplifies/speeds up lookup in parse_func.c.
Also, add a 'proimplicit' flag to pg_proc that controls whether a type
coercion function may be invoked implicitly, or only explicitly.  The
current settings of these flags are more permissive than I would like,
but we will need to debate and refine the behavior; for now, I avoided
breaking regression tests as much as I could.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.35 2002/04/05 00:31:24 tgl Exp $
d47 8
a54 3
       The name of a function to create.  The name need not be unique,
       because functions may be overloaded, but functions with the
       same name must have different argument types.
d340 3
a342 2
   datatype is considered to be a <firstterm>type coercion function</>:
   it can be invoked to convert a value of its input datatype into a value
@


1.35
log
@Divide functions into three volatility classes (immutable, stable, and
volatile), rather than the old cachable/noncachable distinction.  This
allows indexscan optimizations in many places where we formerly didn't.
Also, add a pronamespace column to pg_proc (it doesn't do anything yet,
however).
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.34 2002/03/22 19:20:37 petere Exp $
d217 12
d326 48
d419 2
a420 2
   This example creates a function that does type conversion between the
   user-defined type complex, and the internal type point.  The
@


1.34
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.33 2002/03/01 20:38:12 momjian Exp $
d163 1
a163 1
      <term>iscachable</term>
d166 8
a173 6
	<option>Iscachable</option> indicates that the function always
	returns the same result when given the same argument values (i.e.,
	it does not do database lookups or otherwise use information not
	directly present in its parameter list).  The optimizer uses
	<option>iscachable</option> to know whether it is safe to
	pre-evaluate a call of the function.
d179 4
a182 1
      <term>isstrict</term>
d185 29
a213 8
	<option>isstrict</option> indicates that the function always
	returns NULL whenever any of its arguments are NULL.  If this
	attribute is specified, the function is not executed when there
	are NULL arguments; instead a NULL result is assumed automatically.
	When <option>isstrict</option> is not specified, the function will
	be called for NULL inputs.  It is then the function author's
	responsibility to check for NULLs if necessary and respond
	appropriately.
d218 2
d373 1
a373 1
    LANGUAGE C;
d390 3
@


1.33
log
@Revert quotes, 7.2 doesn't need them for CREATE FUNCTION.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.32 2002/03/01 19:01:22 momjian Exp $
d335 1
a335 1
   of specifying the exact pathname to the shared object file).
@


1.32
log
@Oops, we didn't have single quotes around 'langname' in CREATE FUNCTION
manual page;  pointed out by IRC user.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.31 2002/02/18 23:11:02 petere Exp $
d21 1
a21 1
    LANGUAGE '<replaceable class="parameter">langname</replaceable>'
d26 1
a26 1
    LANGUAGE '<replaceable class="parameter">langname</replaceable>'
@


1.31
log
@Privileges on functions and procedural languages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.30 2001/12/08 03:24:34 thomas Exp $
d21 1
a21 1
    LANGUAGE <replaceable class="parameter">langname</replaceable>
d26 1
a26 1
    LANGUAGE <replaceable class="parameter">langname</replaceable>
@


1.30
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.29 2001/11/18 20:35:02 petere Exp $
d273 11
d383 1
d385 1
@


1.29
log
@Initial round of tweakage for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.28 2001/10/26 21:17:03 tgl Exp $
d203 1
a203 1
    <productname>Postgres</productname> via functions 
d218 1
a218 1
    <productname>Postgres</productname> allows function <firstterm>overloading</firstterm>;
@


1.28
log
@More cleanup of CREATE FUNCTION examples.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.27 2001/10/02 21:39:35 tgl Exp $
d7 1
a7 1
  <refentrytitle>CREATE FUNCTION</refentrytitle>
d133 1
a133 1
       <xref linkend="sql-createlanguage">
d247 1
a247 1
    linkend="sql-load"> command.
@


1.27
log
@Add CREATE OR REPLACE FUNCTION syntax to allow replacing a function
definition without changing the function's OID, thereby not breaking
rules, views, triggers, etc that depend on it.  From Gavin Sherry.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.26 2001/09/03 12:57:49 petere Exp $
d298 4
a301 2
   user-created shared library.  This particular routine calculates a
   check digit and returns TRUE if the check digit in the function
d307 1
a307 1
    AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE C;
d323 3
a325 1
   compiled from C source.  For <productname>PostgreSQL</productname> to
@


1.26
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.25 2001/08/13 21:34:51 petere Exp $
d18 1
a18 1
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
d23 1
a23 1
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argtype</replaceable> [, ...] ] )
d36 2
a207 5
    Use <command>DROP FUNCTION</command>
    to remove user-defined functions.
   </para>

   <para>
d248 23
@


1.25
log
@Make LANCOMPILER clause in CREATE LANGUAGE optional.  Allow "identifier"
syntax for language names (instead of 'string').

createlang now handles the case where a second language uses the same call
handler as an already installed language (e.g., plperl/plperlu).

droplang now handles the reverse case, i.e., dropping a language where
the call handler is still used by another language.  Moreover, droplang
can now be used to drop any user-defined language, not just the supplied
ones.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.24 2001/06/04 23:27:23 momjian Exp $
d13 1
a13 1
  <refpurpose>Defines a new function</refpurpose>
@


1.24
log
@This patch adds support for %TYPE in CREATE FUNCTION argument and return
types.  This version has an elog() to remind the user the type
resolution is not dynamic.

Ian Lance Taylor
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.23 2001/05/19 09:01:10 petere Exp $
d21 1
a21 1
    LANGUAGE '<replaceable class="parameter">langname</replaceable>'
d26 1
a26 1
    LANGUAGE '<replaceable class="parameter">langname</replaceable>'
d126 4
a129 4
       May be '<literal>sql</literal>', '<literal>C</literal>',
       '<literal>internal</literal>', or '<replaceable
       class="parameter">plname</replaceable>', where '<replaceable
       class="parameter">plname</replaceable>' is the name of a
d132 2
a133 1
       for details.
d265 1
a265 1
    LANGUAGE 'sql';
d285 1
a285 1
    AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
d310 1
a310 1
    LANGUAGE 'c';
@


1.23
log
@Allow special '$libdir' macro to show up in object file path in CREATE
FUNCTION command.  Guard against trying to load a directory.  Update
documentation some.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.22 2001/04/28 13:59:07 momjian Exp $
d58 3
a60 2
       input types may be base or complex types, or
       <literal>opaque</literal>.  <literal>Opaque</literal> indicates
d63 5
d78 4
a81 2
       base type, complex type, <literal>setof</literal> type, or
       <literal>opaque</literal>.  The <literal>setof</literal>
@


1.22
log
@In create_function there is a remark concerning SQL/PSM not
being ratified as yet. This is certainly no longer true, it wasn't
even true in Q2/1998 when I did a little research for Date's book.
SQL/PSM had been published on 1996-12-15 as ISO/IEC 9075:4. So you
might want to update that section.


Frank Wegmann
@
text
@d2 1
a2 2
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.21 2000/12/25 23:15:26 petere Exp $
Postgres documentation
d7 1
a7 3
  <refentrytitle id="sql-createfunction-title">
   CREATE FUNCTION
  </refentrytitle>
d10 1
d12 2
a13 6
  <refname>
   CREATE FUNCTION
  </refname>
  <refpurpose>
   Defines a new function
  </refpurpose>
d15 1
d17 4
a20 7
  <refsynopsisdivinfo>
   <date>2000-03-25</date>
  </refsynopsisdivinfo>
  <synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">rtype</replaceable>
    AS <replaceable class="parameter">definition</replaceable>   
d23 4
a26 4
CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )
    RETURNS <replaceable class="parameter">rtype</replaceable>
    AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>  
    LANGUAGE 'langname'
d28 2
a29 1
  </synopsis>
d31 8
a38 8
  <refsect2 id="R2-SQL-CREATEFUNCTION-1">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
d40 2
a41 87
    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">name</replaceable></term>
      <listitem>
       <para>
	The name of a function to create.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">ftype</replaceable></term>
      <listitem>
       <para>
	The data type(s) of the function's arguments, if any.
	The input types may be base or complex types, or
	<firstterm>opaque</firstterm>.
	<literal>Opaque</literal> indicates that the function
	accepts arguments of a non-SQL type such as <type>char *</type>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">rtype</replaceable></term>
      <listitem>
       <para>
	The return data type.
	The output type may be specified as a base type, complex type, 
	<option>setof type</option>,
	or <option>opaque</option>.
	The <option>setof</option>
	modifier indicates that the function will return a set of items,
	rather than a single item.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">attribute</replaceable></term>
      <listitem>
       <para>
        An optional piece of information about the function, used for
	optimization.  See below for details.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">definition</replaceable></term>
      <listitem>
       <para>
	A string defining the function; the meaning depends on the language.
	It may be an internal function name, the path to an object file,
	an SQL query, or text in a procedural language.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable></term>
      <listitem>
       <para>
	This form of the <command>AS</command> clause is used for
	dynamically linked, C language functions when the function name in
	the C language source code is not the same as the name of the SQL
	function. The string <replaceable
	class="parameter">obj_file</replaceable> is the name of the file
	containing the dynamically loadable object, and <replaceable
	class="parameter">link_symbol</replaceable> is the object's link
	symbol, that is the name of the function in the C
	language source code.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">langname</replaceable></term>
      <listitem>
       <para>
	May be '<literal>sql</literal>',
	'<literal>C</literal>', '<literal>internal</literal>',
	or '<replaceable class="parameter">plname</replaceable>',
	where '<replaceable class="parameter">plname</replaceable>'
	is the name of a created procedural language. See
	<xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
	for details.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
d43 96
a138 8
  <refsect2 id="R2-SQL-CREATEFUNCTION-2">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>
d140 2
a141 15
    <variablelist>
     <varlistentry>
      <term><computeroutput>
CREATE
       </computeroutput></term>
      <listitem>
       <para>
	This is returned if the command completes successfully.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>
a142 7
 <refsect1 id="R1-SQL-CREATEFUNCTION-1">
  <refsect1info>
   <date>2000-03-25</date>
  </refsect1info>
  <title>
   Description
  </title>
d144 1
a144 5
   <command>CREATE FUNCTION</command> allows a
   <productname>Postgres</productname> user
   to register a function
   with the database. Subsequently, this user is considered the
   owner of the function.
d147 2
a148 10
  <refsect2 id="R2-SQL-CREATEFUNCTION-3">
   <refsect2info>
    <date>2000-08-24</date>
   </refsect2info>
   <title>
    Function Attributes
   </title>

   <para>
    The following items may appear in the WITH clause:
d181 1
a181 1
   </para>
d183 1
a183 1
  </refsect2>
d185 2
a186 7
  <refsect2 id="R2-SQL-CREATEFUNCTION-4">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    Notes
   </title>
d202 1
a202 1
    The full <acronym>SQL92</acronym> type syntax is allowed for
d212 1
a212 1
    <productname>Postgres</productname> allows function "overloading";
d237 7
a243 1
  </refsect2>
d245 1
d247 3
a249 4
 <refsect1 id="R1-SQL-CREATEFUNCTION-2">
  <title>
   Usage
  </title>
d253 3
a255 3
   <programlisting>
CREATE FUNCTION one() RETURNS int4
    AS 'SELECT 1 AS RESULT'
d257 1
d259 1
a259 2

    <computeroutput>
d263 2
a264 2
    </computeroutput>
   </programlisting>
d268 8
a275 7
   This example creates a C function by calling a routine from a user-created
   shared library.  This particular routine calculates a check
   digit and returns TRUE if the check digit in the function parameters
   is correct. It is intended for use in a CHECK contraint.
  </para>
  <programlisting>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS boolean
d285 2
a286 2
  </programlisting>

d292 2
a293 2
   compiled from C source. For <productname>Postgres</productname> to
   find a type conversion function automatically, the sql function has
d297 2
a298 2
  </para>
  <programlisting>
d302 5
a306 5
  </programlisting>
  <para>
  The C declaration of the function is:
  </para>
  <programlisting>
d317 3
a319 1
  </programlisting>
d321 10
a330 1
    
a331 13
 
 <refsect1 id="R1-SQL-CREATEFUNCTION-4">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-CREATEFUNCTION-5">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    SQL92
   </title>
a332 5
   <para>
    <command>CREATE FUNCTION</command> is
    a <productname>Postgres</productname> language extension.
   </para>
  </refsect2>
d334 2
a335 8
  <refsect2 id="R2-SQL-CREATEFUNCTION-6">
   <refsect2info>
    <date>2000-03-25</date>
   </refsect2info>
   <title>
    SQL/PSM
   </title>
   <para>
d337 5
a341 18
    <note>
     <para>
      PSM stands for Persistent Stored Modules. It is a procedural
      language.  SQL/PSM is a standard to enable function extensibility.
     </para>
    </note>

    SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:
    <synopsis>
CREATE FUNCTION <replaceable class="parameter">name</replaceable>
    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">type</replaceable> [, ...] ] )
     RETURNS <replaceable class="parameter">rtype</replaceable>
     LANGUAGE '<replaceable class="parameter">langname</replaceable>'
     ESPECIFIC <replaceable class="parameter">routine</replaceable>
     <replaceable class="parameter">SQL-statement</replaceable>
    </synopsis>
   </para>
  </refsect2>
d343 1
@


1.21
log
@Refine some things to create better looking man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.20 2000/11/20 20:36:46 tgl Exp $
d387 1
a387 4
      language and it was originally hoped that PSM would be ratified
      as an official standard by late 1996. As of mid-1998, this
      has not yet happened, but it is hoped that PSM will
      eventually become a standard.
@


1.20
log
@Revise handling of oldstyle/newstyle functions per recent discussions
in pghackers list.  Support for oldstyle internal functions is gone
(no longer needed, since conversion is complete) and pg_language entry
'internal' now implies newstyle call convention.  pg_language entry
'newC' is gone; both old and newstyle dynamically loaded C functions
are now called language 'C'.  A newstyle function must be identified
by an associated info routine.  See src/backend/utils/fmgr/README.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.19 2000/11/02 19:26:44 momjian Exp $
d126 1
a126 1
	<xref linkend="sql-createlanguage-title" endterm="sql-createlanguage-title">
@


1.19
log
@Change bool to boolean in docs.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.18 2000/10/05 19:48:17 momjian Exp $
d122 1
a122 2
	'<literal>C</literal>', '<literal>newC</literal>',
	'<literal>internal</literal>', '<literal>newinternal</literal>',
d260 1
a260 1
    Two <literal>internal</literal> or <literal>newinternal</literal>
@


1.18
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.17 2000/08/25 15:17:50 thomas Exp $
d310 1
a310 1
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
@


1.17
log
@Fix typos and inconsistancies found by He Weiping
 (aka Henry) <laser@@zhangmai.com.cn>.
Fix new problems in insert.sgml and create_function.sgml which kept jade
 from completing.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.16 2000/08/24 23:36:29 tgl Exp $
d63 1
a63 1
	<literal>opaque</literal> indicates that the function
d74 1
a74 1
	<option>setof <replaceable class="parameter">type</replaceable></option>,
d106 1
a106 1
	dynamically-linked, C language functions when the function name in
d121 1
a121 1
	may be '<literal>sql</literal>',
d192 1
a192 1
	<option>iscachable</option> indicates that the function always
d246 1
a246 1
    type specification (e.g. the precision field for
d266 1
a266 1
    If the AS clause is left empty then <command>CREATE FUNCTION</command>
d325 1
a325 1
   user defined type complex, and the internal type point.  The
@


1.16
log
@Documentation updates to reflect TOAST and new-style fmgr.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.15 2000/07/22 04:30:27 momjian Exp $
d74 3
a76 3
	<literal>setof <replaceable class="parameter">type</replaceable></literal>,
	or <literal>opaque</literal>.
	The <literal>setof</literal>
d189 1
a189 1
      <literal>iscachable</literal>
d192 1
a192 1
	<literal>iscachable</literal> indicates that the function always
d196 1
a196 1
	<literal>iscachable</literal> to know whether it is safe to
d203 1
a203 1
      <literal>isstrict</literal>
d206 1
a206 1
	<literal>isstrict</literal> indicates that the function always
d210 1
a210 1
	When <literal>isstrict</literal> is not specified, the function will
@


1.15
log
@spell cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.14 2000/07/22 02:39:10 momjian Exp $
d34 1
a34 1
    LANGUAGE 'C'
d60 1
a60 1
	The data type of function arguments.
d64 1
a64 1
	accepts arguments of an invalid type such as <type>char *</type>.
d87 1
a87 8
	optimization.  The only attribute currently supported is
	<literal>iscachable</literal>.
	<literal>iscachable</literal> indicates that the function always
	returns the same result when given the same input values (i.e.,
	it does not do database lookups or otherwise use information not
	directly present in its parameter list).  The optimizer uses
	<literal>iscachable</literal> to know whether it is safe to
	pre-evaluate a call of the function.
d111 2
a112 2
	class="parameter">link_symbol</replaceable>, is the object's link
	symbol which is the same as the name of the function in the C
d121 3
a123 2
	may be '<literal>C</literal>', '<literal>sql</literal>',
	'<literal>internal</literal>'
d172 1
a172 1
   with a database. Subsequently, this user is considered the
d175 1
a175 1
  
d178 46
a243 8
    <productname>Postgres</productname> allows function "overloading";
    that is, the same name can be used for several different functions
    so long as they have distinct argument types.  This facility must
    be used with caution for <literal>internal</literal> and
    C-language functions, however.    
   </para>

   <para>
d249 1
a249 1
    (e.g. not recognized or
d254 8
a261 1
    Two <literal>internal</literal>
d271 3
a273 2
    When overloading SQL functions with C-language functions, give
    each C-language instance of the function a distinct name, and use
d275 2
a276 3
    <command>CREATE FUNCTION</command> syntax to ensure that
    overloaded SQL functions names are resolved to the correct
    dynamically linked objects.
a278 4

   <para>
    A C function cannot return a set of values.
   </para>
d329 1
a329 1
   to have the same name as the return type, and overloading is
d362 1
a362 1
  <refsect2 id="R2-SQL-CREATEFUNCTION-4">
d376 1
a376 1
  <refsect2 id="R2-SQL-CREATEFUNCTION-5">
@


1.14
log
@Cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.13 2000/03/27 17:14:42 thomas Exp $
d304 1
a304 1
  The C decalaration of the function is:
@


1.13
log
@Start updating for the v7.0 release.
Use "generic functions" for math and other routines.
Use SQL92 "type 'literal'" syntax rather than Postgres "'literal'::type".
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.12 2000/03/26 18:32:27 petere Exp $
d296 1
a296 1
   form of the <command>AS</command> clause in the SQL definition
@


1.12
log
@Updated user's guide to match new psql's output format
Fixed bug in createdb/alternative location
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.11 1999/10/02 21:27:49 tgl Exp $
d23 1
a23 1
   <date>1999-10-02</date>
a27 1
    [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
d30 1
a30 2


a32 1
    [ WITH ( <replaceable class="parameter">attribute</replaceable> [, ...] ) ]
d35 1
d40 1
a40 1
    <date>1998-09-09</date>
d144 1
a144 1
    <date>1998-09-09</date>
d169 1
a169 1
   <date>1998-09-09</date>
d178 1
a178 1
   with a database. Subsequently, this user is treated as the
d184 1
a184 1
    <date>1998-09-09</date>
d189 1
d191 3
a193 3
    Refer to the chapter in
    the <citetitle>PostgreSQL Programmer's Guide</citetitle>
    on extending
d200 1
a200 1
    to drop user-defined functions.
d209 11
a219 1
	</para>
d254 1
a254 1
<programlisting>
d260 1
a260 1
<computeroutput>
d264 2
a265 2
</computeroutput>
</programlisting>
d329 1
a329 1
    <date>1998-04-15</date>
d343 1
a343 1
    <date>1998-09-09</date>
d376 1
a376 1
mode: sgml
d386 1
a386 1
sgml-local-catalogs:"/usr/lib/sgml/catalog"
@


1.11
log
@Document formerly-undocumented WITH clause of CREATE FUNCTION.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.10 1999/09/28 04:34:39 momjian Exp $
d245 1
a245 1
  <programlisting>
d251 6
a256 6
   <computeroutput>
    answer 
    ------
    1
   </computeroutput>
  </programlisting>
@


1.10
log
@   I have been working with user defined types and user defined c
functions.  One problem that I have encountered with the function
manager is that it does not allow the user to define type conversion
functions that convert between user types. For instance if mytype1,
mytype2, and mytype3 are three Postgresql user types, and if I wish to
define Postgresql conversion functions like

I run into problems, because the Postgresql dynamic loader would look
for a single link symbol, mytype3, for both pieces of object code.  If
I just change the name of one of the Postgresql functions (to make the
symbols distinct), the automatic type conversion that Postgresql uses,
for example, when matching operators to arguments no longer finds the
type conversion function.

The solution that I propose, and have implemented in the attatched
patch extends the CREATE FUNCTION syntax as follows. In the first case
above I use the link symbol mytype2_to_mytype3 for the link object
that implements the first conversion function, and define the
Postgresql operator with the following syntax

The patch includes changes to the parser to include the altered
syntax, changes to the ProcedureStmt node in nodes/parsenodes.h,
changes to commands/define.c to handle the extra information in the AS
clause, and changes to utils/fmgr/dfmgr.c that alter the way that the
dynamic loader figures out what link symbol to use.  I store the
string for the link symbol in the prosrc text attribute of the pg_proc
table which is currently unused in rows that reference dynamically
loaded
functions.


Bernie Frankpitt
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $
d23 1
a23 1
   <date>1999-07-20</date>
d28 1
d35 1
d37 1
a37 1
    LANGUAGE 'c'
d85 16
d134 1
a134 2
	is the name of a created procedural
	language. See
@


1.9
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
d28 1
a28 1
    AS <replaceable class="parameter">definition</replaceable>
d30 6
d93 16
d190 4
a193 4
    so long as they have distinct argument types.  This facility must be
    used with caution for <literal>internal</literal>
    and C-language functions, however.
   </para>
d206 6
a211 10
    For dynamically-loaded C functions, the SQL name of the function must
    be the same as the C function name, because the AS clause is used to
    give the path name of the object file containing the C code.  In this
    situation it is best not to try to overload SQL function names.  It
    might work to load a C function that has the same C name as an internal
    function or another dynamically-loaded function --- or it might not.
    On some platforms the dynamic loader may botch the load in interesting
    ways if there is a conflict of C function names.  So, even if it works
    for you today, you might regret overloading names later when you try
    to run the code somewhere else.
d214 1
a248 1
   <userinput>
a258 1
   </userinput>
d260 34
d337 1
a337 2
    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">eter</replaceable>eable>eable> <replaceable
      class="parameter">type</replaceable> [, ...] ] )
@


1.8
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 5
d8 1
a8 1
  <refentrytitle>
d23 1
a23 1
   <date>1998-09-09</date>
d55 4
d67 6
d95 3
a97 1
	language. See <command>CREATE LANGUAGE</command> for details.
d153 5
a157 3
    Refer to the chapter on functions 
in the <citetitle>PostgreSQL Programmer's Guide</citetitle>
    for further information.
d159 1
d165 17
a181 6
  <para>
   <productname>Postgres</productname> allows function "overloading";
   that is, the same name can be used for several different functions
   so long as they have distinct argument types.  This facility must be
   used with caution for INTERNAL and C-language functions, however.
  </para>
d183 12
a194 8
  <para>
   Two INTERNAL functions cannot have the same C name without causing
   errors at link time.  To get around that, give them different C names
   (for example, use the argument types as part of the C names), then
   specify those names in the AS clause of <command>CREATE FUNCTION</command>.
   If the AS clause is left empty then <command>CREATE FUNCTION</command>
   assumes the C name of the function is the same as the SQL name.
  </para>
d196 3
a198 12
  <para>
   For dynamically-loaded C functions, the SQL name of the function must
   be the same as the C function name, because the AS clause is used to
   give the path name of the object file containing the C code.  In this
   situation it is best not to try to overload SQL function names.  It
   might work to load a C function that has the same C name as an internal
   function or another dynamically-loaded function --- or it might not.
   On some platforms the dynamic loader may botch the load in interesting
   ways if there is a conflict of C function names.  So, even if it works
   for you today, you might regret overloading names later when you try
   to run the code somewhere else.
  </para>
d224 1
a224 1
   To create a C function, calling a routine from a user-created
a244 9
 <refsect1 id="R1-SQL-CREATEFUNCTION-3">
  <title>
   Bugs
  </title>
  <para>
   A C function cannot return a set of values.
  </para>
 </refsect1>

d249 12
a260 3
  <para>
   <command>CREATE FUNCTION</command> is
   a <productname>Postgres</productname> language extension.
d262 1
d264 1
a264 1
  <refsect2 id="R2-SQL-CREATEFUNCTION-4">
@


1.7
log
@Minor updates for release.
Split reference pages for CREATE TABLE AS and SELECT INTO to allow psgml
 (the emacs parser) to handle parsing.
@
text
@d35 28
a62 35
       <variablelist>
	<varlistentry>
	 <term>
	  <replaceable class="parameter">name</replaceable>
	 </term>
	 <listitem>
	  <para>
           The name of a function to create.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  <replaceable class="parameter">ftype</replaceable>
	 </term>
	 <listitem>
	  <para>
           The data type of function arguments.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  <replaceable class="parameter">rtype</replaceable>
	 </term>
	 <listitem>
	  <para>
           The return data type.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  <replaceable class="parameter">definition</replaceable>
      </term>
d72 1
a72 3
      <term>
       <replaceable class="parameter">langname</replaceable>
      </term>
d87 1
a87 1
  
d96 1
a96 1
    
d99 3
a101 3
      <term>
       <returnvalue>CREATE</returnvalue>
      </term>
d112 1
a112 1
 
d182 1
a182 1
  </para>
d184 5
a188 6
   CREATE FUNCTION one() RETURNS int4
   AS 'SELECT 1 AS RESULT'
   LANGUAGE 'sql';
   
   SELECT one() AS answer;
   
d195 2
d205 2
a206 2
    CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
        AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
d208 1
a208 1
    CREATE TABLE product (
d214 1
a214 1
    );
d227 1
a227 1
 
d232 3
a234 3
   <para>
    <command>CREATE FUNCTION</command> is
 a <productname>Postgres</productname> language extension.
d236 1
a236 1
  
d246 1
a246 1
<note>
d251 1
a251 1
has not yet happened, but it is hoped that PSM will
d254 1
a254 1
</note>
d256 2
a257 2
SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:
<synopsis>
d259 1
a259 1
    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">eter</replaceable>eable> <replaceable
d265 1
a265 2
</synopsis>

@


1.6
log
@Update CREATE FUNCTION docs: mention use of AS clause with
INTERNAL functions, add a warning about trying to overload function names
for dynamically loaded C functions (from old man page).
@
text
@d1 3
a3 3
<REFENTRY ID="SQL-CREATEFUNCTION">
 <REFMETA>
  <REFENTRYTITLE>
d5 5
a9 5
  </REFENTRYTITLE>
  <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
d11 2
a12 2
  </REFNAME>
  <REFPURPOSE>
d14 1
a14 1
  </REFPURPOSE>
d16 5
a20 5
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-09</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
d25 1
a25 1
  </SYNOPSIS>
d27 5
a31 5
  <REFSECT2 ID="R2-SQL-CREATEFUNCTION-1">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d33 5
a37 5
   </TITLE>
   <PARA>
       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
d39 3
a41 3
	 </TERM>
	 <LISTITEM>
	  <PARA>
d43 5
a47 5
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
d49 3
a51 3
	 </TERM>
	 <LISTITEM>
	  <PARA>
d53 5
a57 5
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
d59 3
a61 3
	 </TERM>
	 <LISTITEM>
	  <PARA>
d63 5
a67 5
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
d69 3
a71 3
      </TERM>
      <LISTITEM>
       <PARA>
d75 5
a79 5
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
     <VARLISTENTRY>
      <TERM>
d81 3
a83 3
      </TERM>
      <LISTITEM>
       <PARA>
d90 3
a92 3
       </PARA>
      </LISTITEM>
     </VARLISTENTRY>
d95 1
a95 1
  </REFSECT2>
d97 5
a101 5
  <REFSECT2 ID="R2-SQL-CREATEFUNCTION-2">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d103 2
a104 2
   </TITLE>
   <PARA>
d106 7
a112 7
    <VARIABLELIST>
     <VARLISTENTRY>
      <TERM>
       <ReturnValue>CREATE</ReturnValue>
      </TERM>
      <LISTITEM>
       <PARA>
d117 1
a117 1
    </VARIABLELIST>
d119 2
a120 2
  </REFSECT2>
 </REFSYNOPSISDIV>
d122 5
a126 5
 <REFSECT1 ID="R1-SQL-CREATEFUNCTION-1">
  <REFSECT1INFO>
   <DATE>1998-09-09</DATE>
  </REFSECT1INFO>
  <TITLE>
d128 2
a129 2
  </TITLE>
  <PARA>
d135 1
a135 1
  </PARA>
d137 5
a141 5
  <REFSECT2 ID="R2-SQL-CREATEFUNCTION-3">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d143 2
a144 2
   </TITLE>
   <PARA>
d148 2
a149 2
   </PARA>
   <PARA>
d152 1
a152 1
   </PARA>
d154 1
a154 1
  <PARA>
d159 1
a159 1
  </PARA>
d161 1
a161 1
  <PARA>
d168 1
a168 1
  </PARA>
d170 1
a170 1
  <PARA>
d181 2
a182 2
  </PARA>
  </REFSECT2>
d185 2
a186 2
 <REFSECT1 ID="R1-SQL-CREATEFUNCTION-2">
  <TITLE>
d188 2
a189 2
  </TITLE>
  <PARA>
d191 2
a192 2
  </PARA>
  <ProgramListing>
d204 1
a204 1
  </ProgramListing>
d214 1
a214 1
    AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
d216 8
a223 8
    CREATE TABLE product
    (
    id              char(8)         PRIMARY KEY,
    eanprefix       char(8)         CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
    REFERENCES brandname(ean_prefix),
    eancode         char(6)         CHECK (eancode ~ '[0-9]{6}'),
    CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
    );</userinput>
d225 1
a225 1
 </REFSECT1>
d227 2
a228 2
 <REFSECT1 ID="R1-SQL-CREATEFUNCTION-3">
  <TITLE>
d230 2
a231 2
  </TITLE>
  <PARA>
d233 2
a234 2
  </PARA>
 </REFSECT1>
d236 2
a237 2
 <REFSECT1 ID="R1-SQL-CREATEFUNCTION-4">
  <TITLE>
d239 2
a240 2
  </TITLE>
   <PARA>
d243 1
a243 1
   </PARA>
d245 5
a249 5
  <REFSECT2 ID="R2-SQL-CREATEFUNCTION-4">
   <REFSECT2INFO>
    <DATE>1998-09-09</DATE>
   </REFSECT2INFO>
   <TITLE>
d251 1
a251 1
   </TITLE>
d267 2
a268 1
    ( [ [ IN | OUT | INOUT ] <replaceable class="parameter">parm</replaceable> <replaceable class="parameter">type</replaceable> [, ...] ] )
d278 1
a278 1
</REFENTRY>
d283 1
a283 1
sgml-omittag:t
@


1.5
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d23 1
a23 1
    AS <replaceable class="parameter">path</replaceable>
d68 1
a68 1
	  <replaceable class="parameter">path</replaceable>
d72 3
a74 2
	May be either an SQL-query or an absolute path to an
	object file.
d153 29
@


1.4
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d15 1
a15 1
  
d69 25
a93 24
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   May be either an SQL-query or an absolute path to an
           object file.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
	<VARLISTENTRY>
	 <TERM>
	  <replaceable class="parameter">langname</replaceable>
	 </TERM>
	 <LISTITEM>
	  <PARA>
           may be '<literal>C</literal>', '<literal>sql</literal>',
 '<literal>internal</literal>'
 or '<replaceable class="parameter">plname</replaceable>',
 where '<replaceable class="parameter">plname</replaceable>'
 is the name of a created procedural
           language. See <command>CREATE LANGUAGE</command> for details.
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
       </variablelist>
d104 14
a117 10

       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	  <ReturnValue>CREATE</ReturnValue>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   This is returned if the command completes successfully.
   </VARIABLELIST>
d130 2
a131 2
<productname>Postgres</productname> user
to register a function
d146 1
a146 1
 for further information.
d153 1
d163 11
a173 11
CREATE FUNCTION one() RETURNS int4
    AS 'SELECT 1 AS RESULT'
    LANGUAGE 'sql';

SELECT one() AS answer;

<computeroutput>
answer 
------
1
</computeroutput>
d182 2
a183 2
<userinput>
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
d185 9
a193 9

CREATE TABLE product
(
     id              char(8)         PRIMARY KEY,
     eanprefix       char(8)         CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
                                     REFERENCES brandname(ean_prefix),
     eancode         char(6)         CHECK (eancode ~ '[0-9]{6}'),
     CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);</userinput>
@


1.3
log
@Markup and editing adjustments...
@
text
@d103 1
a103 8
   </PARA>
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
<replaceable>status</replaceable>
     </TERM>
     <LISTITEM>
      <PARA>
a111 6
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
       </variablelist>
     </LISTITEM>
    </VARLISTENTRY>
@


1.2
log
@Very minor formatting fixup in the refentry id field to remove
 the trailing "-1". This makes a cleaner html output file name.
Clean up a few refpurpose fields.
@
text
@d18 1
a18 1
   <DATE>1998-04-15</DATE>
d21 4
a24 4
   CREATE FUNCTION <replaceable class="parameter">name</replaceable> ([<replaceable class="parameter">ftype</replaceable> [, ...]])
             RETURNS <replaceable class="parameter">rtype</replaceable>
             AS <replaceable class="parameter">path</replaceable>
             LANGUAGE '<replaceable class="parameter">langname</replaceable>'
d29 1
a29 1
    <DATE>1998-04-15</DATE>
a34 7
   </PARA>
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
     </TERM>
     <LISTITEM>
      <PARA>
d83 6
a88 3
           may be '<literal>c</literal>', '<literal>sql</literal>', '<literal>internal</literal>' or '<replaceable class="parameter">plname</replaceable>'.
           (where '<replaceable class="parameter">plname</replaceable>' is the language name of a created procedural
           language. See <command>CREATE LANGUAGE</command> for details).
a92 3
     </LISTITEM>
    </VARLISTENTRY>
   </VARIABLELIST>
d97 1
a97 1
    <DATE>1998-04-15</DATE>
d107 1
d131 1
a131 1
   <DATE>1998-04-15</DATE>
d137 4
a140 2
   With this command, a PostgreSQL user can register a function
   with PostgreSQL. Subsequently, this user is treated as the
d146 1
a146 1
    <DATE>1998-04-15</DATE>
d152 3
a154 2
    Refer to <citetitle>PostgreSQL User's Guide</citetitle> chapter 6 for further information.
    <comment>This reference needs to be corrected.</comment>
d157 2
a158 3
    Refer to the <citerefentry>
     <refentrytitle>DROP FUNCTION</refentrytitle>
    </citerefentry> statement to drop functions.
d170 11
a180 9
   CREATE FUNCTION one() RETURNS int4
            AS 'SELECT 1 AS RESULT'
                LANGUAGE 'sql';

   SELECT one() AS answer;

   <computeroutput>answer 
   ------
   1   </computeroutput>
d189 3
a191 2
   <userinput>CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
                AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
d193 8
a200 8
   CREATE TABLE product
   (
        id              char(8)         PRIMARY KEY,
        eanprefix       char(8)         CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
                                        REFERENCES brandname(ean_prefix),
        eancode         char(6)         CHECK (eancode ~ '[0-9]{6}'),
        CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
   );</userinput>
d218 2
a219 1
    The CREATE FUNCTION statement is a PostgreSQL language extension.
d224 1
a224 1
    <DATE>1998-04-15</DATE>
d227 5
a231 1
    SQL/PSM<footnote>
d233 1
a233 1
      PSM stands for Persistent Stored Modules, it is a procedural
d235 2
a236 1
      as an official standard by late 1996. However PSM will
d239 12
a250 12
    </footnote>
   </TITLE>
   <para>
    The SQL/PSM CREATE FUNCTION statement has the following syntax:
   <programlisting>
     CREATE FUNCTION <replaceable class="parameter">name</replaceable>
            ( [ [IN|OUT|INOUT] <replaceable class="parameter">parm</replaceable> <replaceable class="parameter">type</replaceable> [, ...] ])
            RETURNS <replaceable class="parameter">rtype</replaceable>
            LANGUAGE '<replaceable class="parameter">langname</replaceable>'
            ESPECIFIC <replaceable class="parameter">routine</replaceable>
            <replaceable class="parameter">SQL-statement</replaceable>
   </programlisting>
a254 1

@


1.1
log
@First files for reference pages.
@
text
@d1 1
a1 1
<REFENTRY ID="SQL-CREATEFUNCTION-1">
@
