head	1.27;
access;
symbols
	REL9_0_0:1.27
	REL9_1_ALPHA1:1.27
	REL9_0_RC1:1.27
	REL9_0_BETA4:1.27
	REL9_0_STABLE:1.27.0.2
	REL9_0_BETA3:1.27
	REL9_0_BETA2:1.27
	REL7_4_29:1.19
	REL8_0_25:1.21
	REL8_1_21:1.21
	REL8_2_17:1.23.2.1
	REL8_3_11:1.24.2.1
	REL8_4_4:1.25.2.1
	REL9_0_BETA1:1.27
	REL9_0_ALPHA5_BRANCH:1.26.0.8
	REL9_0_ALPHA5:1.26
	REL7_4_28:1.19
	REL8_0_24:1.21
	REL8_1_20:1.21
	REL8_2_16:1.23.2.1
	REL8_3_10:1.24.2.1
	REL8_4_3:1.25.2.1
	REL9_0_ALPHA4:1.26
	REL9_0_ALPHA4_BRANCH:1.26.0.6
	REL8_5_ALPHA3:1.26
	REL8_5_ALPHA3_BRANCH:1.26.0.4
	REL7_4_27:1.19
	REL8_0_23:1.21
	REL8_1_19:1.21
	REL8_2_15:1.23.2.1
	REL8_3_9:1.24.2.1
	REL8_4_2:1.25.2.1
	REL8_5_ALPHA2:1.26
	REL8_5_ALPHA2_BRANCH:1.26.0.2
	REL7_4_26:1.19
	REL8_0_22:1.21
	REL8_1_18:1.21
	REL8_2_14:1.23.2.1
	REL8_3_8:1.24.2.1
	REL8_4_1:1.25.2.1
	REL8_5_ALPHA1:1.25
	REL8_5_ALPHA1_BRANCH:1.25.0.4
	REL8_4_STABLE:1.25.0.2
	REL8_4_0:1.25
	REL8_4_RC2:1.25
	REL8_4_RC1:1.25
	REL8_4_BETA2:1.25
	REL8_4_BETA1:1.25
	REL7_4_25:1.19
	REL8_0_21:1.21
	REL8_1_17:1.21
	REL8_2_13:1.23
	REL8_3_7:1.24
	REL7_4_24:1.19
	REL8_0_20:1.21
	REL8_1_16:1.21
	REL8_2_12:1.23
	REL8_3_6:1.24
	REL7_4_23:1.19
	REL8_0_19:1.21
	REL8_1_15:1.21
	REL8_2_11:1.23
	REL8_3_5:1.24
	REL7_4_22:1.19
	REL8_0_18:1.21
	REL8_1_14:1.21
	REL8_2_10:1.23
	REL8_3_4:1.24
	REL7_4_21:1.19
	REL8_0_17:1.21
	REL8_1_13:1.21
	REL8_2_9:1.23
	REL8_3_3:1.24
	REL7_4_20:1.19
	REL8_0_16:1.21
	REL8_1_12:1.21
	REL8_2_8:1.23
	REL8_3_2:1.24
	REL8_2_7:1.23
	REL8_3_1:1.24
	REL8_3_STABLE:1.24.0.2
	REL8_3_0:1.24
	REL8_3_RC2:1.24
	REL7_3_21:1.12.4.1
	REL7_4_19:1.19
	REL8_0_15:1.21
	REL8_1_11:1.21
	REL8_2_6:1.23
	REL8_3_RC1:1.24
	REL8_3_BETA4:1.24
	REL8_3_BETA3:1.24
	REL8_3_BETA2:1.24
	REL8_3_BETA1:1.24
	REL7_3_20:1.12.4.1
	REL7_4_18:1.19
	REL8_0_14:1.21
	REL8_1_10:1.21
	REL8_2_5:1.23
	REL7_3_19:1.12.4.1
	REL7_4_17:1.19
	REL8_0_13:1.21
	REL8_1_9:1.21
	REL8_2_4:1.23
	REL8_0_12:1.21
	REL8_1_8:1.21
	REL8_2_3:1.23
	REL7_3_18:1.12.4.1
	REL7_4_16:1.19
	REL8_0_11:1.21
	REL8_1_7:1.21
	REL8_2_2:1.23
	REL8_0_10:1.21
	REL8_1_6:1.21
	REL8_2_1:1.23
	REL7_4_15:1.19
	REL7_3_17:1.12.4.1
	REL8_2_STABLE:1.23.0.2
	REL8_2_0:1.23
	REL8_2_RC1:1.23
	REL8_2_BETA3:1.23
	REL8_2_BETA2:1.23
	REL8_1_5:1.21
	REL8_0_9:1.21
	REL7_4_14:1.19
	REL7_3_16:1.12.4.1
	REL8_2_BETA1:1.23
	REL7_3_15:1.12.4.1
	REL7_4_13:1.19
	REL8_0_8:1.21
	REL8_1_4:1.21
	REL7_3_14:1.12.4.1
	REL7_4_12:1.19
	REL8_0_7:1.21
	REL8_1_3:1.21
	REL7_3_13:1.12.4.1
	REL7_4_11:1.19
	REL8_0_6:1.21
	REL8_1_2:1.21
	REL7_3_12:1.12.4.1
	REL7_4_10:1.19
	REL8_0_5:1.21
	REL8_1_1:1.21
	REL8_1_STABLE:1.21.0.6
	REL8_1_0:1.21
	REL8_1_0RC1:1.21
	REL8_1_0BETA4:1.21
	REL8_1_0BETA3:1.21
	REL7_3_11:1.12.4.1
	REL7_4_9:1.19
	REL8_0_4:1.21
	REL8_1_0BETA2:1.21
	REL8_1_0BETA1:1.21
	REL7_2_8:1.12
	REL7_3_10:1.12.4.1
	REL7_4_8:1.19
	REL8_0_3:1.21
	REL8_0_2:1.21
	REL7_2_7:1.12
	REL7_3_9:1.12.4.1
	REL7_4_7:1.19
	REL8_0_1:1.21
	REL8_0_STABLE:1.21.0.4
	REL8_0_0:1.21.0.2
	REL8_0_0RC5:1.21
	REL8_0_0RC4:1.21
	REL8_0_0RC3:1.20
	REL8_0_0RC2:1.20
	REL8_0_0RC1:1.20
	REL8_0_0BETA5:1.20
	REL8_0_0BETA4:1.20
	REL7_4_6:1.19
	REL7_3_8:1.12.4.1
	REL7_2_6:1.12
	REL8_0_0BETA3:1.20
	REL8_0_0BETA2:1.20
	REL7_2_5:1.12
	REL7_4_5:1.19
	REL7_3_7:1.12.4.1
	REL7_4_4:1.19
	REL8_0_0BETA1:1.20
	REL7_4_3:1.19
	REL7_4_2:1.19
	REL7_3_6:1.12.4.1
	REL7_4_1:1.19
	REL7_3_5:1.12.4.1
	REL7_4:1.19
	REL7_4_RC2:1.19
	REL7_4_STABLE:1.19.0.2
	REL7_4_RC1:1.19
	REL7_4_BETA5:1.19
	REL7_4_BETA4:1.19
	REL7_4_BETA3:1.19
	REL7_4_BETA2:1.17
	WIN32_DEV:1.17.0.2
	REL7_4_BETA1:1.17
	REL7_3_4:1.12.4.1
	REL7_3_2:1.12.4.1
	REL7_2_4:1.12
	REL7_3_STABLE:1.12.0.4
	REL7_2_3:1.12
	REL7_2_STABLE:1.12.0.2
	REL7_2:1.12
	REL7_2_RC2:1.12
	REL7_2_RC1:1.12
	REL7_2_BETA5:1.11
	REL7_2_BETA4:1.11
	REL7_2_BETA3:1.11
	REL7_2_BETA2:1.10
	REL7_2_BETA1:1.9
	REL7_1_2:1.7
	REL7_1_STABLE:1.7.0.4
	REL7_1_BETA:1.7
	REL7_1_BETA3:1.7
	REL7_1_BETA2:1.7
	REL7_1:1.7
	REL7_0_PATCHES:1.7.0.2
	REL7_0:1.7
	REL6_5_PATCHES:1.6.0.2
	REL6_5:1.6
	REL6_4:1.4.0.2;
locks; strict;
comment	@# @;


1.27
date	2010.04.03.07.23.01;	author petere;	state Exp;
branches;
next	1.26;

1.26
date	2009.09.03.22.11.07;	author tgl;	state Exp;
branches;
next	1.25;

1.25
date	2008.11.14.10.22.47;	author petere;	state Exp;
branches
	1.25.2.1;
next	1.24;

1.24
date	2007.01.31.23.26.04;	author momjian;	state Exp;
branches
	1.24.2.1;
next	1.23;

1.23
date	2006.09.16.00.30.19;	author momjian;	state Exp;
branches
	1.23.2.1;
next	1.22;

1.22
date	2006.08.15.18.26.58;	author tgl;	state Exp;
branches;
next	1.21;

1.21
date	2005.01.04.00.39.53;	author tgl;	state Exp;
branches;
next	1.20;

1.20
date	2003.11.29.19.51.39;	author pgsql;	state Exp;
branches;
next	1.19;

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

1.18
date	2003.08.31.17.32.23;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2003.04.26.23.56.51;	author petere;	state Exp;
branches
	1.17.2.1;
next	1.16;

1.16
date	2003.03.25.16.15.42;	author petere;	state Exp;
branches;
next	1.15;

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

1.14
date	2002.11.21.23.34.43;	author petere;	state Exp;
branches;
next	1.13;

1.13
date	2002.11.15.03.11.18;	author momjian;	state Exp;
branches;
next	1.12;

1.12
date	2002.01.20.22.19.57;	author petere;	state Exp;
branches
	1.12.4.1;
next	1.11;

1.11
date	2001.11.18.20.35.02;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2001.10.26.19.58.12;	author tgl;	state Exp;
branches;
next	1.9;

1.9
date	2001.09.03.12.57.50;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2001.05.19.09.01.10;	author petere;	state Exp;
branches;
next	1.7;

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

1.6
date	99.07.06.17.16.39;	author thomas;	state Exp;
branches;
next	1.5;

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

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

1.3
date	98.10.15.05.47.01;	author momjian;	state Exp;
branches;
next	1.2;

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

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

1.12.4.1
date	2002.11.21.23.31.58;	author petere;	state Exp;
branches;
next	;

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

1.23.2.1
date	2009.09.03.22.11.30;	author tgl;	state Exp;
branches;
next	;

1.24.2.1
date	2009.09.03.22.11.22;	author tgl;	state Exp;
branches;
next	;

1.25.2.1
date	2009.09.03.22.11.13;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.27
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/load.sgml,v 1.26 2009/09/03 22:11:07 tgl Exp $
-->

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

 <refnamediv>
  <refname>LOAD</refname>
  <refpurpose>load a shared library file</refpurpose>
 </refnamediv>

 <indexterm zone="sql-load">
  <primary>LOAD</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
LOAD '<replaceable class="PARAMETER">filename</replaceable>'
</synopsis>
 </refsynopsisdiv>

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

  <para>
   This command loads a shared library file into the <productname>PostgreSQL</>
   server's address space.  If the file has been loaded already,
   the command does nothing.  Shared library files that contain C functions
   are automatically loaded whenever one of their functions is called.
   Therefore, an explicit <command>LOAD</> is usually only needed to
   load a library that modifies the server's behavior through <quote>hooks</>
   rather than providing a set of functions.
  </para>

  <para>
   The file name is specified in the same way as for shared library
   names in <xref linkend="sql-createfunction">; in particular, one
   can rely on a search path and automatic addition of the system's standard
   shared library file name extension.  See <xref linkend="xfunc-c"> for
   more information on this topic.
  </para>

  <indexterm>
   <primary><filename>$libdir/plugins</></primary>
  </indexterm>

  <para>
   Non-superusers can only apply <command>LOAD</> to library files
   located in <filename>$libdir/plugins/</> &mdash; the specified
   <replaceable class="PARAMETER">filename</replaceable> must begin
   with exactly that string.  (It is the database administrator's
   responsibility to ensure that only <quote>safe</> libraries
   are installed there.)
  </para>
 </refsect1>

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

  <para>
   <command>LOAD</command> is a <productname>PostgreSQL</productname>
   extension.
  </para>
 </refsect1>


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

  <para>
   <xref linkend="sql-createfunction">
  </para>
 </refsect1>
</refentry>
@


1.26
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/load.sgml,v 1.25 2008/11/14 10:22:47 petere Exp $
d7 1
a7 1
  <refentrytitle id="SQL-LOAD-TITLE">LOAD</refentrytitle>
d42 1
a42 1
   names in <xref linkend="sql-createfunction" endterm="sql-createfunction-title">; in particular, one
d76 1
a76 1
   <xref linkend="sql-createfunction" endterm="sql-createfunction-title">
@


1.25
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/load.sgml,v 1.24 2007/01/31 23:26:04 momjian Exp $
d14 1
a14 1
  <refpurpose>load or reload a shared library file</refpurpose>
d32 6
a37 7
   server's address space.  If the file had been loaded previously,
   it is first unloaded.  This command is primarily useful to unload
   and reload a shared library file that has been changed since the
   server first loaded it.  To make use of the shared library,
   function(s) in it need to be declared using the <xref
   linkend="sql-createfunction" endterm="sql-createfunction-title">
   command.
@


1.25.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/load.sgml,v 1.25 2008/11/14 10:22:47 petere Exp $
d14 1
a14 1
  <refpurpose>load a shared library file</refpurpose>
d32 7
a38 6
   server's address space.  If the file has been loaded already,
   the command does nothing.  Shared library files that contain C functions
   are automatically loaded whenever one of their functions is called.
   Therefore, an explicit <command>LOAD</> is usually only needed to
   load a library that modifies the server's behavior through <quote>hooks</>
   rather than providing a set of functions.
@


1.24
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/load.sgml,v 1.23 2006/09/16 00:30:19 momjian Exp $
d8 1
@


1.24.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/load.sgml,v 1.24 2007/01/31 23:26:04 momjian Exp $
d13 1
a13 1
  <refpurpose>load a shared library file</refpurpose>
d31 7
a37 6
   server's address space.  If the file has been loaded already,
   the command does nothing.  Shared library files that contain C functions
   are automatically loaded whenever one of their functions is called.
   Therefore, an explicit <command>LOAD</> is usually only needed to
   load a library that modifies the server's behavior through <quote>hooks</>
   rather than providing a set of functions.
@


1.23
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.22 2006/08/15 18:26:58 tgl Exp $
d43 1
a43 1
   may rely on a search path and automatic addition of the system's standard
d53 1
a53 1
   Non-superusers may only apply <command>LOAD</> to library files
@


1.23.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/load.sgml,v 1.23 2006/09/16 00:30:19 momjian Exp $
d13 1
a13 1
  <refpurpose>load a shared library file</refpurpose>
d31 7
a37 6
   server's address space.  If the file has been loaded already,
   the command does nothing.  Shared library files that contain C functions
   are automatically loaded whenever one of their functions is called.
   Therefore, an explicit <command>LOAD</> is usually only needed to
   load a library that modifies the server's behavior through <quote>hooks</>
   rather than providing a set of functions.
@


1.22
log
@Add server support for "plugin" libraries that can be used for add-on tasks
such as debugging and performance measurement.  This consists of two features:
a table of "rendezvous variables" that allows separately-loaded shared
libraries to communicate, and a new GUC setting "local_preload_libraries"
that allows libraries to be loaded into specific sessions without explicit
cooperation from the client application.  To make local_preload_libraries
as flexible as possible, we do not restrict its use to superusers; instead,
it is restricted to load only libraries stored in $libdir/plugins/.  The
existing LOAD command has also been modified to allow non-superusers to
LOAD libraries stored in this directory.

This patch also renames the existing GUC variable preload_libraries to
shared_preload_libraries (after a suggestion by Simon Riggs) and does some
code refactoring in dfmgr.c to improve clarity.

Korry Douglas, with a little help from Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.21 2005/01/04 00:39:53 tgl Exp $
a79 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.21
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/load.sgml,v 1.20 2003/11/29 19:51:39 pgsql Exp $
d47 13
@


1.20
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/load.sgml,v 1.19 2003/09/11 21:42:20 momjian Exp $
d44 1
a44 1
   shared library file name extension.  See <xref linkend="xfunc"> for
@


1.19
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/load.sgml,v 1.18 2003/08/31 17:32:23 petere Exp $
@


1.18
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/load.sgml,v 1.17 2003/04/26 23:56:51 petere Exp $
d53 1
a53 1
   <command>LOAD</command> is a <application>PostgreSQL</application>
@


1.17
log
@Editing of more reference pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/load.sgml,v 1.16 2003/03/25 16:15:42 petere Exp $
d15 4
@


1.17.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/load.sgml,v 1.18 2003/08/31 17:32:23 petere Exp $
a14 4

 <indexterm zone="sql-load">
  <primary>LOAD</primary>
 </indexterm>
@


1.16
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/load.sgml,v 1.15 2003/01/19 00:13:29 momjian Exp $
d26 2
a27 2
   Loads a shared library file into the <productname>PostgreSQL</>
   backend's address space.  If the file had been loaded previously,
d30 1
a30 1
   backend first loaded it.  To make use of the shared library,
@


1.15
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/load.sgml,v 1.14 2002/11/21 23:34:43 petere Exp $
d40 1
a40 1
   shared library file name extension.  See the &cite-programmer; for
d59 1
a59 2
   <xref linkend="sql-createfunction" endterm="sql-createfunction-title">,
   &cite-programmer;
@


1.14
log
@Fixups for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/load.sgml,v 1.13 2002/11/15 03:11:18 momjian Exp $
d40 2
a41 2
   shared library file name extension.  See the
   <citetitle>Programmer's Guide</citetitle> for more detail.
d60 1
a60 1
   <citetitle>PostgreSQL Programmer's Guide</citetitle>
@


1.13
log
@SGML improvements.

Neil Conway
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/load.sgml,v 1.12 2002/01/20 22:19:57 petere Exp $
d59 1
a59 1
   <xref linkend="sql-createfunction">,
@


1.12
log
@Spell-check and markup police
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.11 2001/11/18 20:35:02 petere Exp $
d26 8
a33 7
   Loads a shared library file into the PostgreSQL backend's address
   space.  If the file had been loaded previously, it is first
   unloaded.  This command is primarily useful to unload and reload a
   shared library file that has been changed since the backend first
   loaded it.  To make use of the
   shared library, function(s) in it need to be declared using the <xref
   linkend="sql-createfunction" endterm="sql-createfunction-title"> command.
@


1.12.4.1
log
@Fixups for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/load.sgml,v 1.12 2002/01/20 22:19:57 petere Exp $
d58 1
a58 1
   <xref linkend="sql-createfunction" endterm="sql-createfunction-title">,
@


1.11
log
@Initial round of tweakage for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.10 2001/10/26 19:58:12 tgl Exp $
d36 1
a36 1
   The filename is specified in the same way as for shared library
d39 1
a39 1
   shared library filename extension.  See the
@


1.10
log
@Editorial work on xfunc chapter --- better explanations about SQL
functions handling composite types and sets, various minor cleanups.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/load.sgml,v 1.9 2001/09/03 12:57:50 petere Exp $
d7 1
a7 1
  <refentrytitle>LOAD</refentrytitle>
d32 1
a32 1
   linkend="sql-createfunction"> command.
d37 1
a37 1
   names in <xref linkend="sql-createfunction">; in particular, one
@


1.9
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/load.sgml,v 1.8 2001/05/19 09:01:10 petere Exp $
d13 1
a13 1
  <refpurpose>load or reload a shared object file</refpurpose>
d26 1
a26 1
   Loads a shared object file into the PostgreSQL backend's address
d29 3
a31 2
   shared object file if it has been changed.  To make use of the
   shared object, a function needs to be declared using the <xref
d33 8
@


1.8
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/load.sgml,v 1.7 1999/07/22 15:09:12 thomas Exp $
d13 1
a13 1
  <refpurpose>Loads a shared object file</refpurpose>
@


1.7
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 2
$Header$
Postgres documentation
d7 1
a7 3
  <refentrytitle id="SQL-LOAD-TITLE">
   LOAD
  </refentrytitle>
d10 1
d12 2
a13 6
  <refname>
   LOAD
  </refname>
  <refpurpose>
   Dynamically loads an object file
  </refpurpose>
d15 1
d17 1
a17 4
  <refsynopsisdivinfo>
   <date>1999-07-20</date>
  </refsynopsisdivinfo>
  <synopsis>
d19 1
a19 58
  </synopsis>

  <refsect2 id="R2-SQL-LOAD-1">
   <refsect2info>
    <date>1998-09-01</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>
    <variablelist>
     <varlistentry>
      <term><replaceable class="PARAMETER">filename</replaceable></term>
      <listitem>
       <para>
	Object file for dynamic loading.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-LOAD-2">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
LOAD
       </computeroutput></term>
      <listitem>
       <para>
	Message returned on successful completion.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><computeroutput>
ERROR:  LOAD: could not open file '<replaceable class="PARAMETER">filename</replaceable>'
       </computeroutput></term>
      <listitem>
       <para>
	Message returned if the specified file is not found. The file must be visible
	<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
	with the appropriate full path name specified, to avoid this message.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
d22 2
a23 7
 <refsect1 id="R1-SQL-LOAD-1">
  <refsect1info>
   <date>1998-09-24</date>
  </refsect1info>
  <title>
   Description
  </title>
d26 6
a31 4
   Loads an object (or ".o") file into the 
   <productname>Postgres</productname> backend address space.  Once a
   file is loaded, all functions in that file can be accessed.  This
   function is used in support of user-defined types and functions.
d33 4
d39 2
a40 8
   If a file is not loaded using
   <command>LOAD</command>, 
   the file will be loaded automatically the first time the
   function is called by <productname>Postgres</productname>.
   <command>LOAD</command>
   can also be used to reload an object file if it has been edited and
   recompiled.  Only objects created from C language files are supported
   at this time.
d42 1
a43 38
  <refsect2 id="R2-SQL-LOAD-3">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    Notes
   </title>

   <para>
    Functions in loaded object files should not call functions in other
    object files loaded through the
    <command>LOAD</command>
    command. For example, all functions in file <literal>A</literal> should
    call each other, functions in the standard or math libraries, or in
    Postgres itself.  They should not call functions defined in a different
    loaded file <literal>B</literal>.
    This is because if <literal>B</literal> is reloaded, the Postgres loader is
    not able to relocate the calls from the functions in
    <literal>A</literal> into
    the new address space of <literal>B</literal>.
    If <literal>B</literal> is not reloaded, however, there will
    not be a problem.
   </para>
   <para>
    Object files must be compiled to contain position independent code.
    For example, 
    on DECstations you must use
    <application>/bin/cc</application>
    with the <literal>-G 0</literal> option when compiling object files to be
    loaded.
   </para>
   <para>
    Note that if you are porting <productname>Postgres</productname>
    to a new platform, <command>LOAD</command>
    will have to work in order to support ADTs.
   </para>
  </refsect2>
 </refsect1>
d45 3
a47 4
 <refsect1 id="R1-SQL-LOAD-2">
  <title>
   Usage
  </title>
d49 2
a50 5
   Load the file <filename>/usr/postgres/demo/circle.o</filename>:

   <programlisting>
LOAD '/usr/postgres/demo/circle.o'
   </programlisting>
a51 18
 </refsect1>

 <refsect1 id="R1-SQL-LOAD-3">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-LOAD-4">
   <refsect2info>
    <date>1998-09-24</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
   </para>
  </refsect2>
@


1.6
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-24</date>
d94 1
d101 1
d112 1
d120 1
a168 2
  <para>
  </para>
@


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
@d1 192
a192 179
<REFENTRY ID="SQL-LOAD">
  <REFMETA>
	<REFENTRYTITLE>
	  LOAD
	</REFENTRYTITLE>
	<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
  </REFMETA>
  <REFNAMEDIV>
	<REFNAME>
	  LOAD
	</REFNAME>
	<REFPURPOSE>
	  Dynamically loads an object file
	</REFPURPOSE>
  </refnamediv>
  <REFSYNOPSISDIV>
	<REFSYNOPSISDIVINFO>
	  <DATE>1998-09-24</DATE>
	</REFSYNOPSISDIVINFO>
	<SYNOPSIS>
	  <REPLACEABLE CLASS="PARAMETER">
	  </REPLACEABLE>
	  LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'
	</SYNOPSIS>

	<REFSECT2 ID="R2-SQL-LOAD-1">
	  <REFSECT2INFO>
		<DATE>1998-09-01</DATE>
	  </REFSECT2INFO>
	  <TITLE>
		Inputs
	  </TITLE>
	  <PARA>
	  </PARA>
	  <VARIABLELIST>
		<VARLISTENTRY>
		  <TERM>
			<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
		  </TERM>
		  <LISTITEM>
			<PARA>
			  Object file for dynamic loading.
			</para>
		  </listitem>
		</varlistentry>
	  </VARIABLELIST>

	</REFSECT2>

	<REFSECT2 ID="R2-SQL-LOAD-2">
	  <REFSECT2INFO>
		<DATE>1998-09-24</DATE>
	  </REFSECT2INFO>
	  <TITLE>
		Outputs
	  </TITLE>
	  <PARA>
		
		<VARIABLELIST>
		  <VARLISTENTRY>
			<TERM>
			  <returnvalue>LOAD</returnvalue>
			</TERM>
			<LISTITEM>
			  <PARA>
				Message returned on successful completion.
			  </para>
			</listitem>
		  </varlistentry>
		  <VARLISTENTRY>
			<TERM>
			  <returnvalue>ERROR:  LOAD: could not open file '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'</returnvalue>
			</TERM>
			<LISTITEM>
			  <PARA>
				Message returned if the specified file is not found. The file must be visible
				<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
				with the appropriate full path name specified, to avoid this message.
			  </para>
			</listitem>
		  </varlistentry>
		</VARIABLELIST>
	  </para>
	</REFSECT2>
  </REFSYNOPSISDIV>
  
  <REFSECT1 ID="R1-SQL-LOAD-1">
	<REFSECT1INFO>
	  <DATE>1998-09-24</DATE>
	</REFSECT1INFO>
	<TITLE>
	  Description
	</TITLE>
	<PARA>
	  Loads an object (or ".o") file into the 
	  <productname>Postgres</productname> backend address space.  Once a
	  file is loaded, all functions in that file can be accessed.  This
	  function is used in support of user-defined types and functions.
	</para>
	<para>
	  If a file is not loaded using
	  <command>LOAD</command>, 
	  the file will be loaded automatically the first time the
	  function is called by <productname>Postgres</productname>.
	  <command>LOAD</command>
	  can also be used to reload an object file if it has been edited and
	  recompiled.  Only objects created from C language files are supported
	  at this time.
	</para>
	<REFSECT2 ID="R2-SQL-LOAD-3">
	  <REFSECT2INFO>
		<DATE>1998-09-24</DATE>
	  </REFSECT2INFO>
	  <TITLE>
		Notes
	  </TITLE>
	  <PARA>
		Functions in loaded object files should not call functions in other
		object files loaded through the
		<command>LOAD</command>
		command. For example, all functions in file <literal>A</literal> should
		call each other, functions in the standard or math libraries, or in
		Postgres itself.  They should not call functions defined in a different
		loaded file <literal>B</literal>.
		This is because if <literal>B</literal> is reloaded, the Postgres loader is
		not able to relocate the calls from the functions in <literal>A</literal> into
		the new address space of <literal>B</literal>.
		If <literal>B</literal> is not reloaded, however, there will
		not be a problem.
	  </para>
	  <para>
		Object files must be compiled to contain position independent code.
		For example, 
		on DECstations you must use
		<application>/bin/cc</application>
		with the <literal>-G 0</literal> option when compiling object files to be
		loaded.
	  </para>
	  <para>
		Note that if you are porting <productname>Postgres</productname>
		to a new platform, <command>LOAD</command>
		will have to work in order to support ADTs.
	  </para>
	</REFSECT2>
  </refsect1>

  <REFSECT1 ID="R1-SQL-LOAD-2">
	<TITLE>
	  Usage
	</TITLE>
	<PARA>
	  <ProgramListing>
		--Load the file /usr/postgres/demo/circle.o
		--
		LOAD '/usr/postgres/demo/circle.o'
	  </ProgramListing>
	</para>
  </REFSECT1>
  
  <REFSECT1 ID="R1-SQL-LOAD-3">
	<TITLE>
	  Compatibility
	</TITLE>
	<PARA>
	</PARA>
	
	<REFSECT2 ID="R2-SQL-LOAD-4">
	  <REFSECT2INFO>
		<DATE>1998-09-24</DATE>
	  </REFSECT2INFO>
	  <TITLE>
		SQL92
	  </TITLE>
	  <PARA>
		There is no <command>LOAD</command> in <acronym>SQL92</acronym>.
	  </para>
	</refsect2>
  </refsect1>
</REFENTRY>
@


1.4
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d2 177
a178 168
<REFMETA>
<REFENTRYTITLE>
LOAD
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
LOAD
</REFNAME>
<REFPURPOSE>
Dynamically loads an object file
</REFPURPOSE>

<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
LOAD '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'
</SYNOPSIS>

<REFSECT2 ID="R2-SQL-LOAD-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Object file for dynamic loading.

</VARIABLELIST>

</REFSECT2>

<REFSECT2 ID="R2-SQL-LOAD-2">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<returnvalue>LOAD</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned on successful completion.

<VARLISTENTRY>
<TERM>
<returnvalue>ERROR:  LOAD: could not open file '<REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>'</returnvalue>
</TERM>
<LISTITEM>
<PARA>
Message returned if the specified file is not found. The file must be visible
<emphasis>to the <productname>Postgres</productname> backend</emphasis>,
with the appropriate full path name specified, to avoid this message.

</VARIABLELIST>

</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-SQL-LOAD-1">
<REFSECT1INFO>
<DATE>1998-09-24</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
Loads an object (or ".o") file into the 
<productname>Postgres</productname> backend address space.  Once a
file is loaded, all functions in that file can be accessed.  This
function is used in support of user-defined types and functions.

<para>
If a file is not loaded using
<command>LOAD</command>, 
the file will be loaded automatically the first time the
function is called by <productname>Postgres</productname>.
<command>LOAD</command>
can also be used to reload an object file if it has been edited and
recompiled.  Only objects created from C language files are supported
at this time.

<REFSECT2 ID="R2-SQL-LOAD-3">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
Functions in loaded object files should not call functions in other
object files loaded through the
<command>LOAD</command>
command. For example, all functions in file <literal>A</literal> should
call each other, functions in the standard or math libraries, or in
Postgres itself.  They should not call functions defined in a different
loaded file <literal>B</literal>.
  This is because if <literal>B</literal> is reloaded, the Postgres loader is
not able to relocate the calls from the functions in <literal>A</literal> into
the new address space of <literal>B</literal>.
If <literal>B</literal> is not reloaded, however, there will
not be a problem.

<para>
Object files must be compiled to contain position independent code.
For example, 
on DECstations you must use
<application>/bin/cc</application>
with the <literal>-G 0</literal> option when compiling object files to be
loaded.

<para>
Note that if you are porting <productname>Postgres</productname>
 to a new platform, <command>LOAD</command>
will have to work in order to support ADTs.

</REFSECT2>

<REFSECT1 ID="R1-SQL-LOAD-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
--Load the file /usr/postgres/demo/circle.o
--
LOAD '/usr/postgres/demo/circle.o'
</ProgramListing>
        
</REFSECT1>

<REFSECT1 ID="R1-SQL-LOAD-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
</PARA>

<REFSECT2 ID="R2-SQL-LOAD-4">
<REFSECT2INFO>
<DATE>1998-09-24</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <command>LOAD</command> in <acronym>SQL92</acronym>.

@


1.3
log
@SGML updates from post 6.3.2 manual changes.  Added pg_upgrade man page.
@
text
@a59 8
<replaceable>status</replaceable>
</TERM>
<LISTITEM>
<PARA>

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
a75 1
</VARIABLELIST>
@


1.2
log
@Cleanup markup and minor editing to prepare for first release.
@
text
@d157 1
a157 1
LOAD "/usr/postgres/demo/circle.o"
@


1.1
log
@Add more new pages.
@
text
@d18 1
a18 1
<DATE>1998-09-01</DATE>
d50 1
a50 1
<DATE>1998-04-15</DATE>
d56 9
a64 1
</PARA>
d68 9
a76 1
LOAD
d80 3
d85 1
d92 1
a92 1
<DATE>1998-04-15</DATE>
d101 1
a101 1
function is used in support of ADT's.
d115 1
a115 1
<DATE>1998-04-15</DATE>
d124 1
a124 1
command, meaning, for example, that all functions in file A should
d127 5
a131 3
loaded file B.  This is because if B is reloaded, the Postgres loader is
not able to relocate the calls from the functions in A into
the new address space of B.  If B is not reloaded, however, there will
d139 1
a139 1
with the "-G 0" option when compiling object files to be
d155 3
a157 3
   --Load the file /usr/postgres/demo/circle.o
   --
   LOAD "/usr/postgres/demo/circle.o"
d171 1
a171 1
<DATE>1998-04-15</DATE>
d177 1
a177 1
There is no LOAD statement in <acronym>SQL92</acronym>.
@
