home *** CD-ROM | disk | FTP | other *** search
/ Il CD di internet / CD.iso / SOURCE / N / CNEWS / _CNEWS.TAR / usr / doc / cnews / docs / config < prev    next >
Encoding:
Text File  |  1994-09-02  |  6.5 KB  |  169 lines
  1. .Ch "Configuration Mechanisms in C News"
  2. .Ix configuration
  3. .SH
  4. Intro
  5. .LP
  6. There is an overall problem with news stuff in that some pathnames
  7. and such are site-specific.
  8. In C News this hits both shell files and C programs, the former a
  9. particular inconvenience because they are not compiled and hence can't
  10. easily pick it up from a library at compile time.
  11. It's easy to edit shell files, but there are too many of them for this
  12. to be very convenient.
  13. .LP
  14. Several mechanisms are needed to solve the entire problem..
  15. .SH
  16. Configuration Parameters
  17. .LP
  18. Although there are many things that theoretically could be site-specific,
  19. there are only a few that really crop up constantly,
  20. are highly likely to change,
  21. and have to be known to running code.
  22. Here's a tentative list, with internal names and common defaults:
  23. .Ix configuration variables
  24. .TS
  25. lll.
  26. NEWSARTS    pathname of the article database    /usr/spool/news
  27. NEWSCTL    pathname of the control-file directory    /usr/lib/news
  28. NEWSBIN    pathname of the program directory    /usr/lib/newsbin
  29. NEWSPATH    shell PATH setting for news    /bin:/usr/bin
  30. NEWSUMASK    default umask for file creation    002
  31. NEWSMASTER    where to send mail about trouble    usenet
  32. NEWSCONFIG    see "Subst" section    /usr/lib/news/bin/config
  33. .TE
  34. .SH
  35. Environment Variables
  36. .LP
  37. All C News programs
  38. that care about configuration parameters are expected to look at
  39. environment variables with the same names as the parameters, and to
  40. use the environment values to override internal defaults.
  41. This is primarily aimed at testing and special purposes rather than
  42. production use, as there is a fundamental problem:
  43. the environment is insecure.
  44. The environment variables are nevertheless very useful.
  45. .LP
  46. There is a need for a canned interface to the environment variables,
  47. to simplify their use.
  48. There is also a requirement for centrally-set defaults for normal
  49. production use.
  50. These requirements are addressed differently for C and shell programs.
  51. .SH
  52. C Interface
  53. .LP
  54. \fILibcnews\fR provides a set of inquiry functions:
  55. .Ix configuration library
  56. .LP
  57. .RS
  58. .IP "char *fullartfile(char *name);"
  59. Returns a full pathname for the NEWSARTS-relative file \fIname\fR;
  60. if \fIname\fR is NULL, returns the value of NEWSARTS.
  61. .IP "char *ctlfile(char *name);"
  62. Returns a full pathname for the NEWSCTL-relative file \fIname\fR;
  63. if \fIname\fR is NULL, returns the value of NEWSCTL.
  64. .IP "char *binfile(char *name);"
  65. Returns a full pathname for the NEWSBIN-relative file \fIname\fR;
  66. if \fIname\fR is NULL, returns the value of NEWSBIN.
  67. .IP "char *newspath(void);"
  68. Returns the value of the NEWSPATH parameter.
  69. .IP "int newsumask(void);"
  70. Returns the value of the NEWSUMASK parameter.
  71. .IP "char *newsmaster(void);"
  72. Returns the value of NEWSMASTER.
  73. .RE
  74. .LP
  75. Functions which return string values return pointers to areas which they
  76. may later re-use, so the values should be copied if they are to persist
  77. past later calls.
  78. There is also a function \fIartfile\fR which returns a relative pathname,
  79. as a special-purpose optimization,
  80. and a function \fIcd\fR which does a \fIchdir\fR and notes the location
  81. for future use by \fIartfile\fR.
  82. .LP
  83. The first inquiry function to be invoked automatically initializes
  84. their internal housekeeping.
  85. Against the possibility of malicious setting of environment variables,
  86. if any environment variables are in fact present to override default
  87. values, and at least one value in fact differs from the default,
  88. this initialization includes a call to a function the user must supply:
  89. .LP
  90. .RS
  91. .IP "void unprivileged(char *reason);"
  92. Drop any special powers that should not be available to a normal user
  93. program,
  94. e.g. those obtained by set-uid bit.
  95. .I Reason
  96. is the name of the first environment variable that caused trouble.
  97. .RE
  98. .LP
  99. Programs that do not use the set-uid bit can normally have a null
  100. implementation of \fIunprivileged\fR, but to encourage thought about
  101. the matter this is \fInot\fR provided as a default.
  102. .LP
  103. Suitable external declarations for all these functions can be found
  104. in the include file \fIconfig.h\fR in the C News include directory.
  105. .Ix config.h
  106. .SH
  107. Shell interface
  108. .LP
  109. All shell files that want to know configuration parameters should
  110. execute NEWSCTL/bin/config using the `.' command;
  111. .Ix config
  112. it sets shell variables with the same names as the parameters.
  113. Note that it does not export these variables, so subordinate shell
  114. files need to pick up \fIconfig\fR themselves.
  115. This is to preserve the property that subordinate programs see environment
  116. variables set only if the user set them.
  117. .SH
  118. Subst
  119. .LP
  120. .Ix subst
  121. The alert mind will have noticed a circularity in the previous section:
  122. it's not possible to find NEWSCTL/bin/config until one knows where NEWSCTL is.
  123. There are also occasional annoyances in that documentation and such wants
  124. to know the local defaults, and can't get them from either the C or shell
  125. interface.
  126. Hence the use of \fIsubst\fR.
  127. .LP
  128. \fISubst\fR does substitutions into source files (including shell files)
  129. in such a way that it is not necessary to maintain two versions of the file.
  130. In the top-level directory of the C News sources are four files:
  131. \fIsubst\fR itself, the \fIsubstitutions\fR file defining the values of
  132. the configuration parameters, and \fIsubst.hs\fR and \fIsubst.gc\fR,
  133. which are lists of files (relative to the top-level source directory)
  134. that need substitutions done.
  135. (The use of two `list' files reflects C News's dual authorship.)
  136. See the \fIsubst\fR(1) manual page for the gory details of the syntax.
  137. The only C program affected is the configuration-inquiry part of the
  138. library, but all shell files that need any of the configuration parameters
  139. need to be in one of the lists.
  140. .SH
  141. Program startup
  142. .LP
  143. As a result of all this, a C program which needs to know a configuration
  144. parameter simply calls the appropriate inquiry function,
  145. and is prepared for a return call to \fIunprivileged\fR.
  146. A shell program has to do a bit more work; it should start with something
  147. on the order of:
  148. .Ix configuration "shell scripts"
  149. .DS
  150. .ft B
  151. #! /bin/sh
  152. # foobar \- does foo, bar, and bletch
  153.  
  154. # =()<\&. ${NEWSCONFIG\-@<NEWSCONFIG>@}>()=
  155. \&. ${NEWSCONFIG\-/usr/lib/news/bin/config}
  156.  
  157. PATH=$NEWSCTL/bin:$NEWSBIN/xxx:$NEWSBIN:$NEWSPATH ; export PATH
  158. umask $NEWSUMASK
  159. .ft
  160. .DE
  161. (A prototype for this is in conf/proto.sh.)
  162. (See an accompanying document for the logic of the PATH setting.)
  163. The NEWSCONFIG configuration parameter specifies the location of the
  164. configurer shell program, which is then executed to set up the rest
  165. of the parameters.
  166. The reason for doing it this way is to ensure that new parameters
  167. can be added without having to change every shell file.
  168. .Ix NEWSCONFIG
  169.