gnustandards standards.texi

[Richard M. Stallman]

CVSROOT:        /sources/gnustandards
Module name:    gnustandards
Changes by:     Richard M. Stallman <rms>       19/08/09 19:17:03

Modified files:
        .              : standards.texi 

Log message:
        (Finding Program Files): New node.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnustandards/standards.texi?cvsroot=gnustandards&r1=1.262&r2=1.263

Patches:
Index: standards.texi
===================================================================
RCS file: /sources/gnustandards/gnustandards/standards.texi,v
retrieving revision 1.262
retrieving revision 1.263
diff -u -b -r1.262 -r1.263
--- standards.texi      9 Aug 2019 23:15:30 -0000       1.262
+++ standards.texi      9 Aug 2019 23:17:03 -0000       1.263
@@ -531,6 +531,8 @@
 * Libraries::                   Library behavior.
 * Errors::                      Formatting error messages.
 * User Interfaces::             Standards about interfaces generally.
+* Finding Program Files::       How to find the program's executable
+                                  and other files that go with it.
 * Graphical Interfaces::        Standards for graphical interfaces.
 * Command-Line Interfaces::     Standards for command line interfaces.
 * Dynamic Plug-In Interfaces::  Standards for dynamic plug-in interfaces.
@@ -857,6 +859,72 @@
 like @code{ls} except that its default output format is always
 multi-column format.
 
+@node Finding Program Files
+@section Finding the Program's Executable and Associated Files
+
+A program may need to find the executable file it was started with, so
+as to relaunch the same program.  It may need to find associated
+files, either source files or files constructed by building, that 
+it uses at run time.
+
+The way to find them starts with looking at @code{argv[0]}.
+
+If that string contains a slash, it is by convention the file name of
+the executable and its directory part is the directory that contained
+the executable.  This is the case when the program was not found
+through @env{PATH}, which normally means it was built but not
+installed, and run from the build directory.  The program can use the
+@code{argv[0]} file name to relaunch itself, and can look in its
+directory part for associated files.  If that file name is not
+absolute, then it is relative to the working directory in which the
+program started.
+
+If @code{argv[0]} does not contain a slash, it is a command name whose
+executable was found via @env{PATH}.  The program should search for
+that name in the directories in @env{PATH}, interpreting @file{.} as
+the working directory that was current when the program started.
+
+If this procedure finds the executable, we call the directory it was
+found in the @dfn{iinvocation directory}.  The program should check
+for the presence in that directory of the associated files it needs.
+
+If the program's executable is normally built in a subdirectory of the
+main build directory, and the main build directory contains associated
+files (perhaps including subdirectories), the program should look at
+the parent of the invocation directory, checking for the associated
+files and subdirectories the main build directory should contain.
+
+If the invocation directory doesn't contain what's needed, but the
+executable file name is a symbolic link, the program should try using
+the link target's containing directory as the invocation directory.
+
+If this procedure doesn't come up with an invocation directory that is
+valid---normally the case for an installed program that was found via
+@env{PATH}---the program should look for the associated files in the
+directories where the program's makefile installs them.
+@xref{Directory Variables}.
+
+Providing valid information in @code{argv[0]} is a convention, not
+guaranteed.  Well-behaved programs that launch other programs, such as
+shells, follow the convention; your code should follow it too, when
+launching other programs.  But it is always possible to launch the
+program and give a nonsensical value in @code{argv[0]}.
+
+Therefore, any program that needs to know the location of its
+executable, or that of of other associated files, should offer the
+user environment variables to specify those locations explicitly.
+
+@strong{Don't give special privilege, such as with the @code{setuid}
+bit, to programs that will search heuristically for associated files
+or for their own executables when invoked that way.}  Limit that
+privilege to programs that find associated files in hard-coded
+installed locations such as under @file{/usr} and @file{/etc}.
+
+@c ??? Is even that safe, in a setuid program?
+
+@xref{Bourne Shell Variables,,, Bash, Bash Reference Manual},
+for more information about @env{PATH}.
+
 @node Graphical Interfaces
 @section Standards for Graphical Interfaces
 @cindex graphical user interface