Import BSDDB 4.7.25 (as of svn r89086)

docs_src/m4/m4.utility

@@ -0,0 +1,66 @@
+dnl $Id: m4.utility,v 10.17 2002/08/24 18:24:55 bostic Exp $
+
+dnl m4_utilenv --
+dnl	-h environment section
+dnl	#1: utility name
+define(m4_utilenv, [dnl
+m4_tagbegin
+m4_tag(DB_HOME, [dnl
+If the m4_option(h) option is not specified and the environment variable
+DB_HOME is set, it is used as the path of the database home, as described
+in m4_ref(dbenv_open).])
+m4_tagend])
+
+define(m4_hflag, [dnl
+m4_tagopt(h, [Specify a home directory for the database environment; by
+default, the current working directory is used.])])
+
+dnl m4_Lflag --
+dnl	Log-the-pid option.
+dnl	#1: utility name
+define(m4_Lflag, [dnl
+m4_tagopt(L, [dnl
+Log the execution of the m4_ref($1) utility to the specified file in the
+following format, where m4_italic([###]) is the process ID, and the date
+is the time the utility was started.
+m4_indent([$1: [###] Wed Jun 15 01:23:45 EDT 1995])
+This file will be removed if the m4_ref($1) utility exits gracefully.])])
+
+define(m4_Nflag, [dnl
+m4_tagopt(N, [dnl
+Do not acquire shared region mutexes while running.  Other problems,
+such as potentially fatal errors in m4_db, will be ignored as well.
+This option is intended only for debugging errors, and should not be
+used under any other circumstances.])])
+
+define(m4_Pflag, [dnl
+m4_tagopt(P, [dnl
+Specify an environment password.  Although m4_db utilities overwrite
+password strings as soon as possible, be aware there may be a window of
+vulnerability on systems where unprivileged users can see command-line
+arguments or where utilities are not able to overwrite the memory
+containing the command-line arguments.])])
+
+define(m4_Vflag, [dnl
+m4_tagopt(V, [dnl
+Write the library version number to the standard output, and exit.])])
+
+dnl m4_utilexit --
+dnl	Exit macro.
+dnl	#1: utility name
+define(m4_utilexit, [m4_p([dnl
+The m4_ref($1) utility exits 0 on success, and __GT__0 if an error occurs.])])
+
+dnl m4_detach --
+dnl	Detaching from the environment paragraph.
+dnl	#1: utility name
+dnl	#2: "uses" or "may be used with"
+define(m4_detach, [m4_p([dnl
+The m4_ref($1) utility $2 a m4_db environment (as described for the
+m4_option(h) option, the environment variable m4_envvar(DB_HOME), or
+because the utility was run in a directory containing a m4_db
+environment).  In order to avoid environment corruption when using a
+m4_db environment, m4_ref($1) should always be given the chance to
+detach from the environment and exit gracefully.  To cause m4_ref($1)
+to release all environment resources and exit cleanly, send it an
+interrupt signal (SIGINT).])])