2 /home/james/source/GNU/findutils/git/gnu/findutils/doc/find-maint.info,
3 produced by makeinfo version 4.13 from
4 /home/james/source/GNU/findutils/git/gnu/findutils/doc/find-maint.texi.
6 INFO-DIR-SECTION GNU organization
8 * Maintaining Findutils: (find-maint). Maintaining GNU findutils
11 This manual explains how GNU findutils is maintained, how changes
12 should be made and tested, and what resources exist to help developers.
14 This is edition 4.5.10, for findutils version 4.5.10.
16 Copyright (C) 2007, 2008, 2010 Free Software Foundation, Inc.
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.3 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
22 Texts. A copy of the license is included in the section entitled "GNU
23 Free Documentation License".
26 File: find-maint.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
28 Maintaining GNU Findutils
29 *************************
31 This manual explains how GNU findutils is maintained, how changes should
32 be made and tested, and what resources exist to help developers.
34 This is edition 4.5.10, for findutils version 4.5.10.
36 Copyright (C) 2007, 2008, 2010 Free Software Foundation, Inc.
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.3 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
42 Texts. A copy of the license is included in the section entitled "GNU
43 Free Documentation License".
48 * Maintaining GNU Programs::
50 * Coding Conventions::
52 * Using the GNU Portability Library::
57 * Internationalisation::
60 * GNU Free Documentation License::
63 File: find-maint.info, Node: Introduction, Next: Maintaining GNU Programs, Prev: Top, Up: Top
68 This document explains how to contribute to and maintain GNU Findutils.
69 It concentrates on developer-specific issues. For information about
70 how to use the software please refer to *Note Introduction:
73 This manual aims to be useful without necessarily being verbose.
74 It's also a recent document, so there will be a many areas in which
75 improvements can be made. If you find that the document misses out
76 important information or any part of the document is be so terse as to
77 be unuseful, please ask for help on the <bug-findutils@gnu.org> mailing
78 list. We'll try to improve this document too.
81 File: find-maint.info, Node: Maintaining GNU Programs, Next: Design Issues, Prev: Introduction, Up: Top
83 2 Maintaining GNU Programs
84 **************************
86 GNU Findutils is part of the GNU Project and so there are a number of
87 documents which set out standards for the maintenance of GNU software.
90 GNU Project Coding Standards. All changes to findutils should
91 comply with these standards. In some areas we go somewhat beyond
92 the requirements of the standards, but these cases are explained
96 Information for Maintainers of GNU Software. This document
97 provides guidance for GNU maintainers. Everybody with commit
98 access should read this document. Everybody else is welcome to
102 File: find-maint.info, Node: Design Issues, Next: Coding Conventions, Prev: Maintaining GNU Programs, Up: Top
107 The findutils package is installed on many many systems, usually as a
108 fundamental component. The programs in the package are often used in
109 order to successfully boot or fix the system.
111 This fact means that for findutils we bear in mind considerations
112 that may not apply so much as for other packages. For example, the fact
113 that findutils is often a base component motivates us to
114 * Limit dependencies on libraries
116 * Avoid dependencies on other large packages (for example,
119 * Be conservative when making changes to the 'stable' release branch
121 All those considerations come before functionality. Functional
122 enhancements are still made to findutils, but these are almost
123 exclusively introduced in the 'development' release branch, to allow
124 extensive testing and proving.
126 Sometimes it is useful to have a priority list to provide guidance
127 when making design trade-offs. For findutils, that priority list is:
131 2. Standards compliance
135 4. Backward compatibility
141 For example, we support the `-exec' action because POSIX compliance
142 requires this, even though there are security problems with it and we
143 would otherwise prefer people to use `-execdir'. There are also cases
144 where some performance is sacrificed in the name of security. For
145 example, the sanity checks that `find' performs while traversing a
146 directory tree may slow it down. We adopt functional changes, and
147 functional changes are allowed to make `find' slower, but only if there
148 is no detectable impact on users who don't use the feature.
150 Backward-incompatible changes do get made in order to comply with
151 standards (for example the behaviour of `-perm -...' changed in order
152 to comply with POSIX). However, they don't get made in order to
153 provide better ease of use; for example the semantics of `-size -2G'
154 are almost always unexpected by users, but we retain the current
155 behaviour because of backward compatibility and for its similarity to
156 the block-rounding behaviour of `-size -30'. We might introduce a
157 change which does not have the unfortunate rounding behaviour, but we
158 would choose another syntax (for example `-size '<2G'') for this.
160 In a general sense, we try to do test-driven development of the
161 findutils code; that is, we try to implement test cases for new
162 features and bug fixes before modifying the code to make the test pass.
163 Some features of the code are tested well, but the test coverage for
164 other features is less good. If you are about to modify the code for a
165 predicate and aren't sure about the test coverage, use `grep' on the
166 test directories and measure the coverage with `lcov' or another test
169 You should be able to use the `coverage' Makefile target (it's
170 defined in `maint.mk' to generate a test coverage report for findutils.
171 Due to limitations in `lcov', this only works if your build directory
172 is the same asthe source directory (that is, you're not using a VPATH
173 build configuration).
175 Lastly, we try not to depend on having a "working system". The
176 findutils suite is used for diagnosis of problems, and this applies
177 especially to `find'. We should ensure that `find' still works on
178 relatively broken systems, for example systems with damaged
179 `/etc/passwd' or `/etc/fstab' files. Another interesting example is
180 the case where a system is a client of one or more unresponsive NFS
181 servers. On such a system, if you try to stat all mount points, your
182 program will hang indefinitely, waiting for the remote NFS server to
185 Another interesting but unusual case is broken NFS servers and
186 corrupt filesystems; sometimes they return `impossible' file modes.
187 It's important that find does not entirely fail when encountering such a
191 File: find-maint.info, Node: Coding Conventions, Next: Tools, Prev: Design Issues, Up: Top
196 Coding style documents which set out to establish a uniform look and
197 feel to source code have worthy goals, for example greater ease of
198 maintenance and readability. However, I do not believe that in general
199 coding style guide authors can envisage every situation, and it is
200 always possible that it might on occasion be necessary to break the
201 letter of the style guide in order to honour its spirit, or to better
202 achieve the style guide's goals.
204 I've certainly seen many style guides outside the free software world
205 which make bald statements such as "functions shall have exactly one
206 return statement". The desire to ensure consistency and obviousness of
207 control flow is laudable, but it is all too common for such bald
208 requirements to be followed unthinkingly. Certainly I've seen such
209 coding standards result in unmaintainable code with terrible
210 infelicities such as functions containing `if' statements nested nine
211 levels deep. I suppose such coding standards don't survive in free
212 software projects because they tend to drive away potential
213 contributors or tend to generate heated discussions on mailing lists.
214 Equally, a nine-level-deep function in a free software program would
215 quickly get refactored, assuming it is obvious what the function is
218 Be that as it may, the approach I will take for this document is to
219 explain some idioms and practices in use in the findutils source code,
220 and leave it up to the reader's engineering judgement to decide which
221 considerations apply to the code they are working on, and whether or
222 not there is sufficient reason to ignore the guidance in current
227 * Make the Compiler Find the Bugs::
228 * The File System Is Being Modified::
229 * Don't Trust the File System Contents::
230 * Debugging is For Users Too::
231 * Factor Out Repeated Code::
234 File: find-maint.info, Node: Make the Compiler Find the Bugs, Next: The File System Is Being Modified, Up: Coding Conventions
236 4.1 Make the Compiler Find the Bugs
237 ===================================
239 Finding bugs is tedious. If I have a filesystem containing two million
240 files, and a find command line should print one million of them, but in
241 fact it misses out 1%, you can tell the program is printing the wrong
242 result only if you know the right answer for that filesystem at that
243 time. If you don't know this, you may just not find out about that
244 bug. For this reason it is important to have a comprehensive test
247 The test suite is of course not the only way to find the bugs. The
248 findutils source code makes liberal use of the assert macro. While on
249 the one hand these might be a performance drain, the performance impact
250 of most of these is negligible compared to the time taken to fetch even
251 one sector from a disk drive.
253 Assertions should not be used to check the results of operations
254 which may be affected by the program's external environment. For
255 example, never assert that a file could be opened successfully. Errors
256 relating to problems with the program's execution environment should be
257 diagnosed with a user-oriented error message. An assertion failure
258 should always denote a bug in the program.
260 Don't use `assert' to catch not-fuly-implemented features of your
261 code. Finish the implementation, disable the code, or leave the
262 unfinished version on a local branch.
264 Several programs in the findutils suite perform self-checks. See for
265 example the function `pred_sanity_check' in `find/pred.c'. This is
268 There are also a number of small ways in which we can help the
269 compiler to find the bugs for us.
271 4.1.1 Constants in Equality Testing
272 -----------------------------------
274 It's a common error to write `=' when `==' is meant. Sometimes this
275 happens in new code and is simply due to finger trouble. Sometimes it
276 is the result of the inadvertent deletion of a character. In any case,
277 there is a subset of cases where we can persuade the compiler to
278 generate an error message when we make this mistake; this is where the
279 equality test is with a constant.
281 This is an example of a vulnerable piece of code.
286 A simple typo converts the above into
291 We've introduced a bug; the condition is always true, and the value
292 of `x' has been changed. However, a simple change to our practice
293 would have made us immune to this problem:
298 Usually, the Emacs keystroke `M-t' can be used to swap the operands.
300 4.1.2 Spelling of ASCII NUL
301 ---------------------------
303 Strings in C are just sequences of characters terminated by a NUL. The
304 ASCII NUL character has the numerical value zero. It is normally
305 represented in C code as `\0'. Here is a typical piece of C code:
309 Consider what happens if there is an unfortunate typo:
313 We have changed the meaning of our program and the compiler cannot
314 diagnose this as an error. Our string is no longer terminated. Bad
315 things will probably happen. It would be better if the compiler could
316 help us diagnose this problem.
318 In C, the type of `'\0'' is in fact int, not char. This provides us
319 with a simple way to avoid this error. The constant `0' has the same
320 value and type as the constant `'\0''. However, it is not as
321 vulnerable to typos. For this reason I normally prefer to use this
327 File: find-maint.info, Node: Factor Out Repeated Code, Prev: Debugging is For Users Too, Up: Coding Conventions
329 4.2 Factor Out Repeated Code
330 ============================
332 Repeated code imposes a greater maintenance burden and increases the
333 exposure to bugs. For example, if you discover that something you want
334 to implement has some similarity with an existing piece of code, don't
335 cut and paste it. Instead, factor the code out. The risk of cutting
336 and pasting the code, particularly if you do this several times, is
337 that you end up with several copies of the same code.
339 If the original code had a bug, you now have N places where this
340 needs to be fixed. It's all to easy to miss some out when trying to
341 fix the bug. Equally, it's quite possible that when pasting the code
342 into some function, the pasted code was not quite adapted correctly to
343 its new environment. To pick a contrived example, perhaps it modifies a
344 global variable which it that code shouldn't be touching in its new
345 home. Worse, perhaps it makes some unstated assumption about the
346 nature of the input arguments which is in fact not true for the context
347 of the now duplicated code.
349 A good example of the use of refactoring in findutils is the
350 `collect_arg' function in `find/parser.c'. A less clear-cut but larger
351 example is the factoring out of code which would otherwise have been
352 duplicated between `find/find.c' and `find/ftsfind.c'.
354 The findutils test suite is comprehensive enough that refactoring
355 code should not generally be a daunting prospect from a testing point of
356 view. Nevertheless there are some areas which are only lightly-tested:
358 1. Tests on the ages of files
360 2. Code which deals with the values returned by operating system
361 calls (for example handling of ENOENT)
363 3. Code dealing with OS limits (for example, limits on path length or
366 4. Code relating to features not all systems have (for example
369 Please exercise caution when working in those areas.
372 File: find-maint.info, Node: Debugging is For Users Too, Next: Factor Out Repeated Code, Prev: Don't Trust the File System Contents, Up: Coding Conventions
374 4.3 Debugging is For Users Too
375 ==============================
377 Debug and diagnostic code is often used to verify that a program is
378 working in the way its author thinks it should be. But users are often
379 uncertain about what a program is doing, too. Exposing them a little
380 more diagnostic information can help. Much of the diagnostic code in
381 `find', for example, is controlled by the `-D' flag, as opposed to C
382 preprocessor directives.
384 Making diagnostic messages available to users also means that the
385 phrasing of the diagnostic messages becomes important, too.
388 File: find-maint.info, Node: Don't Trust the File System Contents, Next: Debugging is For Users Too, Prev: The File System Is Being Modified, Up: Coding Conventions
390 4.4 Don't Trust the File System Contents
391 ========================================
393 People use `find' to search in directories created by other people.
394 Sometimes they do this to check to suspicious activity (for example to
395 look for new setuid binaries). This means that it would be bad if
396 `find' were vulnerable to, say, a security problem exploitable by
397 constructing a specially-crafted filename. The same consideration
398 would apply to `locate' and `updatedb'.
400 Henry Spencer said this well in his fifth commandment:
402 Thou shalt check the array bounds of all strings (indeed, all
403 arrays), for surely where thou typest `foo' someone someday shall
404 type `supercalifragilisticexpialidocious'.
406 Symbolic links can often be a problem. If `find' calls `lstat' on
407 something and discovers that it is a directory, it's normal for `find'
408 to recurse into it. Even if the `chdir' system call is used
409 immediately, there is still a window of opportunity between the `lstat'
410 and the `chdir' in which a malicious person could rename the directory
411 and substitute a symbolic link to some other directory.
414 File: find-maint.info, Node: The File System Is Being Modified, Next: Don't Trust the File System Contents, Prev: Make the Compiler Find the Bugs, Up: Coding Conventions
416 4.5 The File System Is Being Modified
417 =====================================
419 The filesystem gets modified while you are traversing it. For,
420 example, it's normal for files to get deleted while `find' is
421 traversing a directory. Issuing an error message seems helpful when a
422 file is deleted from the one directory you are interested in, but if
423 `find' is searching 15000 directories, such a message becomes less
426 Bear in mind also that it is possible for the directory `find' is
427 currently searching could be moved to another point in the filesystem,
428 and that the directory in which `find' was started could be deleted.
430 Henry Spencer's sixth commandment is also apposite here:
432 If a function be advertised to return an error code in the event of
433 difficulties, thou shalt check for that code, yea, even though the
434 checks triple the size of thy code and produce aches in thy typing
435 fingers, for if thou thinkest "it cannot happen to me", the gods
436 shall surely punish thee for thy arrogance.
438 There are a lot of files out there. They come in all dates and
439 sizes. There is a condition out there in the real world to exercise
440 every bit of the code base. So we try to test that code base before
441 someone falls over a bug.
444 File: find-maint.info, Node: Tools, Next: Using the GNU Portability Library, Prev: Coding Conventions, Up: Top
449 Most of the tools required to build findutils are mentioned in the file
450 `README-hacking'. We also use some other tools:
453 Much of the execution time of find is spent waiting for filesystem
454 operations. A system call trace (for example, that provided by
455 `strace') shows what system calls are being made. Using this
456 information we can work to remove unnecessary file system
460 Valgrind is a tool which dynamically verifies the memory accesses a
461 program makes to ensure that they are valid (for example, that the
462 behaviour of the program does not in any way depend on the
463 contents of uninitialised memory).
466 DejaGnu is the test framework used to run the findutils test suite
467 (the `runtest' program is part of DejaGnu). It would be ideal if
468 everybody building `findutils' also ran the test suite, but many
469 people don't have DejaGnu installed. When changes are made to
470 findutils, DejaGnu is invoked a lot. *Note Testing::, for more
474 File: find-maint.info, Node: Using the GNU Portability Library, Next: Documentation, Prev: Tools, Up: Top
476 6 Using the GNU Portability Library
477 ***********************************
479 The Gnulib library (`http://www.gnu.org/software/gnulib/') makes a
480 variety of systems look more like a GNU/Linux system and also applies a
481 bunch of automatic bug fixes and workarounds. Some of these also apply
482 to GNU/Linux systems too. For example, the Gnulib regex implementation
483 is used when we determine that we are building on a GNU libc system
484 with a bug in the regex implementation.
486 6.1 How and Why we Import the Gnulib Code
487 =========================================
489 Gnulib does not have a release process which results in a source
490 tarball you can download. Instead, the code is simply made available
491 by GIT. The code is also available via `git-cvspserver', but we
492 decided not to use this, since `import-gnulib.sh' depended on `cvs
493 update -D', which at the time `git-cvspserver' did not support.
495 GNU projects vary in how they interact with Gnulib. Many import a
496 selection of code from Gnulib into the working directory and then check
497 the updated files into the repository for their project. The coreutils
498 project does this, for example.
500 At the last maintainer changeover for findutils (2003) it turned out
501 that there was a lot of material in findutils in common with Gnulib,
502 but it had not been updated in a long time. It was difficult to figure
503 out which source files were intended to track external sources and
504 which were intended to contain incompatible changes, or diverge for
507 To reduce this uncertainty, I decided to treat Gnulib much like
508 Automake. Files supplied by Automake are simply absent from the
509 findutils source tree. When Automake is run with `automake
510 --add-missing --copy', it adds in all the files it thinks should be
511 there which aren't there already.
513 An analogous approach is taken with Gnulib. The Gnulib code is
514 imported from the git repository for Gnulib with a findutils helper
515 script, `import-gnulib.sh'. That script fetches a copy of the Gnulib
516 code into the subdirectory `gnulib-git' and then runs `gnulib-tool'.
517 The `gnulib-tool' program copies the required parts of Gnulib into the
518 findutils source tree in the subdirectory `gnulib'. This process gives
519 us the property that the code in `gnulib' and `gnulib-git' is not
520 included in the findutils git tree. Both directories are listed in
521 `.gitignore' and so git ignores them.
523 Findutils does not use all the Gnulib code. The modules we need are
524 listed in the file `import-gnulib.config'. The same file also
525 indicates the version of Gnulib that we want to use. Since Gnulib has
526 no actual release process, we just use a date. Both `import-gnulib.sh'
527 and `import-gnulib.config' are in the findutils git repository.
529 The upshot of all this is that we can use the findutils git
530 repository to track which version of Gnulib every findutils release
531 uses. That information is also provided when the user invokes a
532 findutils program with the `--version' option.
534 A small number of files are installed by automake and will therefore
535 vary according to which version of automake was used to generate a
536 release. This includes for example boiler-plate GNU files such as
537 `ABOUT-NLS', `INSTALL' and `COPYING'.
539 6.2 How We Fix Gnulib Bugs
540 ==========================
542 If we always directly import the Gnulib code directly from the git
543 repository in this way, it is impossible to maintain a locally
544 different copy of Gnulib. This is often a benefit in that accidental
545 version skew is prevented.
547 However, sometimes we want deliberate version skew in order to use a
548 findutils-specific patched version of a Gnulib file, for example
549 because we fixed a bug.
551 Gnulib is used by quite a number of GNU projects, and this means that
552 it gets plenty of testing. Therefore there are relatively few bugs in
553 the Gnulib code, but it does happen from time to time.
555 However, since there is no waiting around for a Gnulib source release
556 tarball, Gnulib bugs are generally fixed quickly. Here is an outline
557 of the way we would contribute a fix to Gnulib (assuming you know it is
558 not already fixed in the current Gnulib git tree):
560 Check you already completed a copyright assignment for Gnulib
562 Begin with a vanilla git tree
563 Download the Findutils source code from git (or use the tree you
566 Check out a copy of the Gnulib source
567 Check out a copy of the Gnulib source tree. The
568 `import-gnulib.sh' script may have generated a shallow git clone
569 as opposed to a normal, full clone in the directory `gnulib-git'.
570 This means that you may not be able to clone the repository that
571 `import-gnulib.sh' generates. However, you can make a normal
572 (full) clone with `git clone
573 git_repo="git://git.savannah.gnu.org/gnulib.git"'. Do this
574 somewhere outside the findutils source tree.
576 Import Gnulib from your local copy
577 The `import-gnulib.sh' tool has a `-d' option which you can use to
578 import the code from a local copy of Gnulib.
581 Build findutils and run the test suite, which should pass. In our
582 example we assume you have just noticed a bug in Gnulib, not that
583 recent Gnulib changes broke the findutils regression tests.
586 If in fact Gnulib did break the findutils regression tests, you
587 can probably skip this step, since you already have a test case
588 demonstrating the problem. Otherwise, write a findutils test case
589 for the bug and/or a Gnulib test case.
592 Make sure your editor follows symbolic links so that your changes
593 to `gnulib/...' actually affect the files in the git working
594 directory you checked out earlier. Observe that your test now
597 Prepare a Gnulib patch
598 Use `git format-patch' to prepare the patch. Follow the normal
599 usage for checkin comments (take a look at the output of `git
600 log'). Check that the patch conforms with the GNU coding
601 standards, and email it to the Gnulib mailing list.
603 Wait for the patch to be applied
604 Once your bug fix has been applied, you can update your local
605 directory from git, re-import the code into Findutils (still using
606 the `-d' option), and re-run the tests. This verifies that the
607 fix the Gnulib team made actually fixes your problem.
609 Reimport the Gnulib code
610 Update the findutils file `import-gnulib.config' to specify git
611 commit which is after the point at which the bug fix was committed
612 to Gnulib. You can do this with `git rev-parse HEAD'. Finally,
613 re-import the Gnulib code directly from git by using
614 `import-gnulib.sh' without the `-d' option, and run the tests
615 again. This verifies that there was no remaining local change
616 that we were relying on to fix the bug. Make sure you checked
617 everything in by running `git status'.
619 There is an alternative to the method above; it is possible to store
620 local diffs to be patched into gnulib beneath the `gnulib-local'.
621 Normally however, there is no need for this, since gnulib updates are
625 File: find-maint.info, Node: Documentation, Next: Testing, Prev: Using the GNU Portability Library, Up: Top
630 The findutils git tree includes several different types of
633 7.1 User Documentation
634 ======================
636 User-oriented documentation is provided as manual pages and in Texinfo.
637 See *note Introduction: (find)Introduction.
639 Please make sure both sets of documentation are updated if you make a
640 change to the code. The GNU coding standards do not normally call for
641 maintaining manual pages on the grounds of effort duplication.
642 However, the manual page format is more convenient for quick reference,
643 and so it's worth maintaining both types of documentation. However,
644 the manual pages are normally rather more terse than the Texinfo
645 documentation. The manual pages are suitable for reference use, but
646 the Texinfo manual should also include introductory and tutorial
653 Describes the Free Translation Project, the translation status of
654 various GNU projects, and how to participate by translating an
658 Lists the authors of findutils.
661 The copyright license covering findutils; currently, the GNU GPL,
665 Generic installation instructions for installing GNU programs.
668 Information about how to compile findutils in particular
671 A README file which is included with testing releases of findutils.
674 Describes how to build findutils from the code in git.
677 Thanks for people who contributed to findutils. Generally, if
678 someone's contribution was significant enough to need a copyright
679 assignment, their name should go in here.
684 7.3 Release Information
685 =======================
688 Enumerates the user-visible change in each release. Typical
689 changes are fixed bugs, functionality changes and documentation
690 changes. Include the date when a release is made.
693 This file enumerates all changes to the findutils source code (with
694 the possible exception of `.cvsignore' and `.gitignore' changes).
695 The level of detail used for this file should be sufficient to
696 answer the questions "what changed?" and "why was it changed?".
697 If a change fixes a bug, always give the bug reference number in
698 both the `ChangeLog' and `NEWS' files and of course also in the
699 checkin message. In general, it should be possible to enumerate
700 all material changes to a function by searching for its name in
701 `ChangeLog'. Mention when each release is made.
704 File: find-maint.info, Node: Testing, Next: Bugs, Prev: Documentation, Up: Top
709 This chapter will explain the general procedures for adding tests to
710 the test suite, and the functions defined in the findutils-specific
711 DejaGnu configuration. Where appropriate references will be made to
712 the DejaGnu documentation.
715 File: find-maint.info, Node: Bugs, Next: Distributions, Prev: Testing, Up: Top
720 Bugs are logged in the Savannah bug tracker
721 `http://savannah.gnu.org/bugs/?group=findutils'. The tracker offers
722 several fields but their use is largely obvious. The life-cycle of a
726 Someone, usually a maintainer, a distribution maintainer or a user,
727 creates a bug by filling in the form. They fill in field values
728 as they see fit. This will generate an email to
729 <bug-findutils@gnu.org>.
732 The bug hangs around with `Status=None' until someone begins to
733 work on it. At that point they set the "Assigned To" field and
734 will sometimes set the status to `In Progress', especially if the
735 bug will take a while to fix.
738 Quite a lot of reports are not actually bugs; for these the usual
739 procedure is to explain why the problem is not a bug, set the
740 status to `Invalid' and close the bug. Make sure you set the
741 `Assigned to' field to yourself before closing the bug.
744 When you commit a bug fix into git (or in the case of a contributed
745 patch, commit the change), mark the bug as `Fixed'. Make sure you
746 include a new test case where this is relevant. If you can figure
747 out which releases are affected, please also set the `Release'
748 field to the earliest release which is affected by the bug.
749 Indicate which source branch the fix is included in (for example,
750 4.2.x or 4.3.x). Don't close the bug yet.
753 When a release is made which includes the bug fix, make sure the
754 bug is listed in the NEWS file. Once the release is made, fill in
755 the `Fixed Release' field and close the bug.
758 File: find-maint.info, Node: Distributions, Next: Internationalisation, Prev: Bugs, Up: Top
763 Almost all GNU/Linux distributions include findutils, but only some of
764 them have a package maintainer who is a member of the mailing list.
765 Distributions don't often feed back patches to the
766 <bug-findutils@gnu.org> list, but on the other hand many of their
767 patches relate only to standards for file locations and so forth, and
768 are therefore distribution specific. On an irregular basis I check the
769 current patches being used by one or two distributions, but the total
770 number of GNU/Linux distributions is large enough that we could not
771 hope to cover them all.
773 Often, bugs are raised against a distribution's bug tracker instead
774 of GNU's. Periodically (about every six months) I take a look at some
775 of the more accessible bug trackers to indicate which bugs have been
778 Many distributions include both findutils and the slocate package,
779 which provides a replacement `locate'.
782 File: find-maint.info, Node: Internationalisation, Next: Security, Prev: Distributions, Up: Top
784 11 Internationalisation
785 ***********************
787 Translation is essentially automated from the maintainer's point of
788 view. The TP mails the maintainer when a new PO file is available, and
789 we just download it and check it in. We copy the `.po' files into the
790 git repository. For more information, please see
791 `http://translationproject.org/domain/findutils.html'.
794 File: find-maint.info, Node: Security, Next: Making Releases, Prev: Internationalisation, Up: Top
799 See *note Security Considerations: (find)Security Considerations, for a
800 full description of the findutils approach to security considerations
801 and discussion of particular tools.
803 If someone reports a security bug publicly, we should fix this as
804 rapidly as possible. If necessary, this can mean issuing a fixed
805 release containing just the one bug fix. We try to avoid issuing
806 releases which include both significant security fixes and functional
809 Where someone reports a security problem privately, we generally try
810 to construct and test a patch without pushing the intermediate code to
811 the public repository.
813 Once everything has been tested, this allows us to make a release and
814 push the patch. The advantage of doing things this way is that we
815 avoid situations where people watching for git commits can figure out
816 and exploit a security problem before a fixed release is available.
818 It's important that security problems be fixed promptly, but don't
819 rush so much that things go wrong. Make sure the new release really
820 fixes the problem. It's usually best not to include functional changes
821 in your security-fix release.
823 If the security problem is serious, send an alert to
824 <vendor-sec@lst.de>. The members of the list include most GNU/Linux
825 distributions. The point of doing this is to allow them to prepare to
826 release your security fix to their customers, once the fix becomes
827 available. Here is an example alert:-
829 GNU findutils heap buffer overrun (potential privilege escalation)
836 GNU findutils is a set of programs which search for files on Unix-like
837 systems. It is maintained by the GNU Project of the Free Software
838 Foundation. For more information, see
839 `http://www.gnu.org/software/findutils'.
845 When GNU locate reads filenames from an old-format locate database,
846 they are read into a fixed-length buffer allocated on the heap.
847 Filenames longer than the 1026-byte buffer can cause a buffer overrun.
848 The overrunning data can be chosen by any person able to control the
849 names of filenames created on the local system. This will normally
850 include all local users, but in many cases also remote users (for
851 example in the case of FTP servers allowing uploads).
856 Findutils supports three different formats of locate database, its
857 native format "LOCATE02", the slocate variant of LOCATE02, and a
858 traditional ("old") format that locate uses on other Unix systems.
860 When locate reads filenames from a LOCATE02 database (the default
861 format), the buffer into which data is read is automatically extended
862 to accomodate the length of the filenames.
864 This automatic buffer extension does not happen for old-format
865 databases. Instead a 1026-byte buffer is used. When a longer
866 pathname appears in the locate database, the end of this buffer is
867 overrun. The buffer is allocated on the heap (not the stack).
869 If the locate database is in the default LOCATE02 format, the locate
870 program does perform automatic buffer extension, and the program is
871 not vulnerable to this problem. The software used to build the
872 old-format locate database is not itself vulnerable to the same
875 Most installations of GNU findutils do not use the old database
876 format, and so will not be vulnerable.
884 All existing releases of findutils are affected.
890 To discover the longest path name on a given system, you can use the
891 following command (requires GNU findutils and GNU coreutils):
893 find / -print0 | tr -c '\0' 'x' | tr '\0' '\n' | wc -L
899 This section includes a shell script which determines which of a list
900 of locate binaries is vulnerable to the problem. The shell script has
901 been tested only on glibc based systems having a mktemp binary.
903 NOTE: This script deliberately overruns the buffer in order to
904 determine if a binary is affected. Therefore running it on your
905 system may have undesirable effects. We recommend that you read the
906 script before running it.
910 if vanilla_db="$(mktemp nicedb.XXXXXX)" ; then
911 if updatedb --prunepaths="" --old-format --localpaths="/tmp" \
912 --output="$@{vanilla_db@}" ; then
915 rm -f "$@{vanilla_db@}"
917 echo "Failed to create old-format locate database; skipping the sanity checks" >&2
922 # Start with a valid database
923 cat "$@{vanilla_db@}"
924 # Make the final entry really long
925 dd if=/dev/zero bs=1 count=1500 2>/dev/null | tr '\000' 'x'
932 usage() @{ echo "usage: $0 binary [binary...]" >&2; exit $1; @}
933 [ $# -eq 0 ] && usage 1
938 if dbfile="$(mktemp nasty.XXXXXX)"
940 make_overrun_db > "$dbfile"
942 ver="$locate = $("$locate" --version | head -1)"
943 if [ -z "$vanilla_db" ] || "$locate" -d "$vanilla_db" "" >/dev/null ; then
944 "$locate" -d "$dbfile" "" >/dev/null
945 if [ $? -gt 128 ] ; then
953 # the regular locate failed
955 buggy, may or may not be vulnerable: $ver"
958 rm -f "$@{dbfile@}" "$@{vanilla_db@}"
959 # good: unaffected. bad: affected (vulnerable).
960 # ugly: doesn't even work for a normal old-format database.
975 The GNU project discovered the problem while 'locate' was being worked
976 on; this is the first public announcement of the problem.
978 The GNU findutils mantainer has issued a patch as p[art of this
979 announcement. The patch appears below.
981 A source release of findutils-4.2.31 will be issued on 2007-05-30.
982 That release will of course include the patch. The patch will be
983 committed to the public CVS repository at the same time. Public
984 announcements of the release, including a description of the bug, will
985 be made at the same time as the release.
987 A release of findutils-4.3.x will follow and will also include the
994 This patch should apply to findutils-4.2.23 and later.
995 Findutils-4.2.23 was released almost two years ago.
996 Index: locate/locate.c
997 ===================================================================
998 RCS file: /cvsroot/findutils/findutils/locate/locate.c,v
999 retrieving revision 1.58.2.2
1000 diff -u -p -r1.58.2.2 locate.c
1001 --- locate/locate.c 22 Apr 2007 16:57:42 -0000 1.58.2.2
1002 +++ locate/locate.c 28 May 2007 10:18:16 -0000
1003 @@@@ -124,9 +124,9 @@@@ extern int errno;
1005 #include "locatedb.h"
1006 #include <getline.h>
1007 -#include "../gnulib/lib/xalloc.h"
1008 -#include "../gnulib/lib/error.h"
1009 -#include "../gnulib/lib/human.h"
1010 +#include "xalloc.h"
1013 #include "dirname.h"
1014 #include "closeout.h"
1015 #include "nextelem.h"
1016 @@@@ -468,10 +468,36 @@@@ visit_justprint_unquoted(struct process_
1017 return VISIT_CONTINUE;
1021 +toolong (struct process_data *procdata)
1023 + error (EXIT_FAILURE, 0,
1024 + _("locate database %s contains a "
1025 + "filename longer than locate can handle"),
1026 + procdata->dbfile);
1030 +extend (struct process_data *procdata, size_t siz1, size_t siz2)
1032 + /* Figure out if the addition operation is safe before performing it. */
1033 + if (SIZE_MAX - siz1 < siz2)
1035 + toolong (procdata);
1037 + else if (procdata->pathsize < (siz1+siz2))
1039 + procdata->pathsize = siz1+siz2;
1040 + procdata->original_filename = x2nrealloc (procdata->original_filename,
1041 + &procdata->pathsize,
1047 visit_old_format(struct process_data *procdata, void *context)
1050 + register size_t i;
1053 /* Get the offset in the path where this path info starts. */
1054 @@@@ -479,20 +505,35 @@@@ visit_old_format(struct process_data *pr
1055 procdata->count += getw (procdata->fp) - LOCATEDB_OLD_OFFSET;
1057 procdata->count += procdata->c - LOCATEDB_OLD_OFFSET;
1058 + assert(procdata->count > 0);
1060 - /* Overlay the old path with the remainder of the new. */
1061 - for (s = procdata->original_filename + procdata->count;
1062 + /* Overlay the old path with the remainder of the new. Read
1063 + * more data until we get to the next filename.
1065 + for (i=procdata->count;
1066 (procdata->c = getc (procdata->fp)) > LOCATEDB_OLD_ESCAPE;)
1067 - if (procdata->c < 0200)
1068 - *s++ = procdata->c; /* An ordinary character. */
1071 - /* Bigram markers have the high bit set. */
1072 - procdata->c &= 0177;
1073 - *s++ = procdata->bigram1[procdata->c];
1074 - *s++ = procdata->bigram2[procdata->c];
1078 + if (procdata->c < 0200)
1080 + /* An ordinary character. */
1081 + extend (procdata, i, 1u);
1082 + procdata->original_filename[i++] = procdata->c;
1086 + /* Bigram markers have the high bit set. */
1087 + extend (procdata, i, 2u);
1088 + procdata->c &= 0177;
1089 + procdata->original_filename[i++] = procdata->bigram1[procdata->c];
1090 + procdata->original_filename[i++] = procdata->bigram2[procdata->c];
1094 + /* Consider the case where we executed the loop body zero times; we
1095 + * still need space for the terminating null byte.
1097 + extend (procdata, i, 1u);
1098 + procdata->original_filename[i] = 0;
1100 procdata->munged_filename = procdata->original_filename;
1107 Thanks to Rob Holland <rob@inversepath.com> and Tavis Ormandy.
1110 VIII. CVE INFORMATION
1111 =====================
1113 No CVE candidate number has yet been assigned for this vulnerability.
1114 If someone provides one, I will include it in the public announcement
1117 The original announcement above was sent out with a cleartext PGP
1118 signature, of course, but that has been omitted from the example.
1120 Once a fixed release is available, announce the new release using the
1121 normal channels. Any CVE number assigned for the problem should be
1122 included in the `ChangeLog' and `NEWS' entries. See
1123 `http://cve.mitre.org/' for an explanation of CVE numbers.
1126 File: find-maint.info, Node: Making Releases, Next: GNU Free Documentation License, Prev: Security, Up: Top
1131 This section will explain how to make a findutils release. For the
1132 time being here is a terse description of the main steps:
1134 1. Commit changes; make sure your working directory has no
1135 uncommitted changes.
1137 2. Test; make sure that all changes you have made have tests, and
1138 that the tests pass. Verify this with `make distcheck'.
1140 3. Bugs; make sure all Savannah bug entries fixed in this release are
1143 4. NEWS; make sure that the NEWS and configure.in file are updated
1144 with the new release number (and checked in).
1146 5. Build the release tarball; do this with `make distcheck'. Copy
1147 the tarball somewhere safe.
1149 6. Tag the release; findutils releases are tagged like this for
1150 example: v4.5.5. Previously a different format was in use:
1151 FINDUTILS_4_3_8-1. You can create a tag with the a command like
1152 this: `git tag -s -m "Findutils release v4.5.7" v4.5.7'.
1154 7. Prepare the upload and upload it. *Note Automated FTP Uploads:
1155 (maintain)Automated FTP Uploads, for detailed upload instructions.
1157 8. Make a release announcement; include an extract from the NEWS file
1158 which explains what's changed. Announcements for test releases
1159 should just go to <bug-findutils@gnu.org>. Announcements for
1160 stable releases should go to <info-gnu@gnu.org> as well.
1162 9. Bump the release numbers in git; edit the `configure.in' and
1163 `NEWS' files to advance the release numbers. For example, if you
1164 have just released `4.6.2', bump the release number to
1165 `4.6.3-git'. The point of the `-git' suffix here is that a
1166 findutils binary built from git will bear a release number
1167 indicating it's not built from the "official" source release.
1169 10. Close bugs; any bugs recorded on Savannah which were fixed in this
1170 release should now be marked as closed. Update the `Fixed
1171 Release' field of these bugs appropriately and make sure the
1172 `Assigned to' field is populated.
1175 File: find-maint.info, Node: GNU Free Documentation License, Prev: Making Releases, Up: Top
1177 Appendix A GNU Free Documentation License
1178 *****************************************
1180 Version 1.3, 3 November 2008
1182 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
1185 Everyone is permitted to copy and distribute verbatim copies
1186 of this license document, but changing it is not allowed.
1190 The purpose of this License is to make a manual, textbook, or other
1191 functional and useful document "free" in the sense of freedom: to
1192 assure everyone the effective freedom to copy and redistribute it,
1193 with or without modifying it, either commercially or
1194 noncommercially. Secondarily, this License preserves for the
1195 author and publisher a way to get credit for their work, while not
1196 being considered responsible for modifications made by others.
1198 This License is a kind of "copyleft", which means that derivative
1199 works of the document must themselves be free in the same sense.
1200 It complements the GNU General Public License, which is a copyleft
1201 license designed for free software.
1203 We have designed this License in order to use it for manuals for
1204 free software, because free software needs free documentation: a
1205 free program should come with manuals providing the same freedoms
1206 that the software does. But this License is not limited to
1207 software manuals; it can be used for any textual work, regardless
1208 of subject matter or whether it is published as a printed book.
1209 We recommend this License principally for works whose purpose is
1210 instruction or reference.
1212 1. APPLICABILITY AND DEFINITIONS
1214 This License applies to any manual or other work, in any medium,
1215 that contains a notice placed by the copyright holder saying it
1216 can be distributed under the terms of this License. Such a notice
1217 grants a world-wide, royalty-free license, unlimited in duration,
1218 to use that work under the conditions stated herein. The
1219 "Document", below, refers to any such manual or work. Any member
1220 of the public is a licensee, and is addressed as "you". You
1221 accept the license if you copy, modify or distribute the work in a
1222 way requiring permission under copyright law.
1224 A "Modified Version" of the Document means any work containing the
1225 Document or a portion of it, either copied verbatim, or with
1226 modifications and/or translated into another language.
1228 A "Secondary Section" is a named appendix or a front-matter section
1229 of the Document that deals exclusively with the relationship of the
1230 publishers or authors of the Document to the Document's overall
1231 subject (or to related matters) and contains nothing that could
1232 fall directly within that overall subject. (Thus, if the Document
1233 is in part a textbook of mathematics, a Secondary Section may not
1234 explain any mathematics.) The relationship could be a matter of
1235 historical connection with the subject or with related matters, or
1236 of legal, commercial, philosophical, ethical or political position
1239 The "Invariant Sections" are certain Secondary Sections whose
1240 titles are designated, as being those of Invariant Sections, in
1241 the notice that says that the Document is released under this
1242 License. If a section does not fit the above definition of
1243 Secondary then it is not allowed to be designated as Invariant.
1244 The Document may contain zero Invariant Sections. If the Document
1245 does not identify any Invariant Sections then there are none.
1247 The "Cover Texts" are certain short passages of text that are
1248 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
1249 that says that the Document is released under this License. A
1250 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
1251 be at most 25 words.
1253 A "Transparent" copy of the Document means a machine-readable copy,
1254 represented in a format whose specification is available to the
1255 general public, that is suitable for revising the document
1256 straightforwardly with generic text editors or (for images
1257 composed of pixels) generic paint programs or (for drawings) some
1258 widely available drawing editor, and that is suitable for input to
1259 text formatters or for automatic translation to a variety of
1260 formats suitable for input to text formatters. A copy made in an
1261 otherwise Transparent file format whose markup, or absence of
1262 markup, has been arranged to thwart or discourage subsequent
1263 modification by readers is not Transparent. An image format is
1264 not Transparent if used for any substantial amount of text. A
1265 copy that is not "Transparent" is called "Opaque".
1267 Examples of suitable formats for Transparent copies include plain
1268 ASCII without markup, Texinfo input format, LaTeX input format,
1269 SGML or XML using a publicly available DTD, and
1270 standard-conforming simple HTML, PostScript or PDF designed for
1271 human modification. Examples of transparent image formats include
1272 PNG, XCF and JPG. Opaque formats include proprietary formats that
1273 can be read and edited only by proprietary word processors, SGML or
1274 XML for which the DTD and/or processing tools are not generally
1275 available, and the machine-generated HTML, PostScript or PDF
1276 produced by some word processors for output purposes only.
1278 The "Title Page" means, for a printed book, the title page itself,
1279 plus such following pages as are needed to hold, legibly, the
1280 material this License requires to appear in the title page. For
1281 works in formats which do not have any title page as such, "Title
1282 Page" means the text near the most prominent appearance of the
1283 work's title, preceding the beginning of the body of the text.
1285 The "publisher" means any person or entity that distributes copies
1286 of the Document to the public.
1288 A section "Entitled XYZ" means a named subunit of the Document
1289 whose title either is precisely XYZ or contains XYZ in parentheses
1290 following text that translates XYZ in another language. (Here XYZ
1291 stands for a specific section name mentioned below, such as
1292 "Acknowledgements", "Dedications", "Endorsements", or "History".)
1293 To "Preserve the Title" of such a section when you modify the
1294 Document means that it remains a section "Entitled XYZ" according
1297 The Document may include Warranty Disclaimers next to the notice
1298 which states that this License applies to the Document. These
1299 Warranty Disclaimers are considered to be included by reference in
1300 this License, but only as regards disclaiming warranties: any other
1301 implication that these Warranty Disclaimers may have is void and
1302 has no effect on the meaning of this License.
1306 You may copy and distribute the Document in any medium, either
1307 commercially or noncommercially, provided that this License, the
1308 copyright notices, and the license notice saying this License
1309 applies to the Document are reproduced in all copies, and that you
1310 add no other conditions whatsoever to those of this License. You
1311 may not use technical measures to obstruct or control the reading
1312 or further copying of the copies you make or distribute. However,
1313 you may accept compensation in exchange for copies. If you
1314 distribute a large enough number of copies you must also follow
1315 the conditions in section 3.
1317 You may also lend copies, under the same conditions stated above,
1318 and you may publicly display copies.
1320 3. COPYING IN QUANTITY
1322 If you publish printed copies (or copies in media that commonly
1323 have printed covers) of the Document, numbering more than 100, and
1324 the Document's license notice requires Cover Texts, you must
1325 enclose the copies in covers that carry, clearly and legibly, all
1326 these Cover Texts: Front-Cover Texts on the front cover, and
1327 Back-Cover Texts on the back cover. Both covers must also clearly
1328 and legibly identify you as the publisher of these copies. The
1329 front cover must present the full title with all words of the
1330 title equally prominent and visible. You may add other material
1331 on the covers in addition. Copying with changes limited to the
1332 covers, as long as they preserve the title of the Document and
1333 satisfy these conditions, can be treated as verbatim copying in
1336 If the required texts for either cover are too voluminous to fit
1337 legibly, you should put the first ones listed (as many as fit
1338 reasonably) on the actual cover, and continue the rest onto
1341 If you publish or distribute Opaque copies of the Document
1342 numbering more than 100, you must either include a
1343 machine-readable Transparent copy along with each Opaque copy, or
1344 state in or with each Opaque copy a computer-network location from
1345 which the general network-using public has access to download
1346 using public-standard network protocols a complete Transparent
1347 copy of the Document, free of added material. If you use the
1348 latter option, you must take reasonably prudent steps, when you
1349 begin distribution of Opaque copies in quantity, to ensure that
1350 this Transparent copy will remain thus accessible at the stated
1351 location until at least one year after the last time you
1352 distribute an Opaque copy (directly or through your agents or
1353 retailers) of that edition to the public.
1355 It is requested, but not required, that you contact the authors of
1356 the Document well before redistributing any large number of
1357 copies, to give them a chance to provide you with an updated
1358 version of the Document.
1362 You may copy and distribute a Modified Version of the Document
1363 under the conditions of sections 2 and 3 above, provided that you
1364 release the Modified Version under precisely this License, with
1365 the Modified Version filling the role of the Document, thus
1366 licensing distribution and modification of the Modified Version to
1367 whoever possesses a copy of it. In addition, you must do these
1368 things in the Modified Version:
1370 A. Use in the Title Page (and on the covers, if any) a title
1371 distinct from that of the Document, and from those of
1372 previous versions (which should, if there were any, be listed
1373 in the History section of the Document). You may use the
1374 same title as a previous version if the original publisher of
1375 that version gives permission.
1377 B. List on the Title Page, as authors, one or more persons or
1378 entities responsible for authorship of the modifications in
1379 the Modified Version, together with at least five of the
1380 principal authors of the Document (all of its principal
1381 authors, if it has fewer than five), unless they release you
1382 from this requirement.
1384 C. State on the Title page the name of the publisher of the
1385 Modified Version, as the publisher.
1387 D. Preserve all the copyright notices of the Document.
1389 E. Add an appropriate copyright notice for your modifications
1390 adjacent to the other copyright notices.
1392 F. Include, immediately after the copyright notices, a license
1393 notice giving the public permission to use the Modified
1394 Version under the terms of this License, in the form shown in
1397 G. Preserve in that license notice the full lists of Invariant
1398 Sections and required Cover Texts given in the Document's
1401 H. Include an unaltered copy of this License.
1403 I. Preserve the section Entitled "History", Preserve its Title,
1404 and add to it an item stating at least the title, year, new
1405 authors, and publisher of the Modified Version as given on
1406 the Title Page. If there is no section Entitled "History" in
1407 the Document, create one stating the title, year, authors,
1408 and publisher of the Document as given on its Title Page,
1409 then add an item describing the Modified Version as stated in
1410 the previous sentence.
1412 J. Preserve the network location, if any, given in the Document
1413 for public access to a Transparent copy of the Document, and
1414 likewise the network locations given in the Document for
1415 previous versions it was based on. These may be placed in
1416 the "History" section. You may omit a network location for a
1417 work that was published at least four years before the
1418 Document itself, or if the original publisher of the version
1419 it refers to gives permission.
1421 K. For any section Entitled "Acknowledgements" or "Dedications",
1422 Preserve the Title of the section, and preserve in the
1423 section all the substance and tone of each of the contributor
1424 acknowledgements and/or dedications given therein.
1426 L. Preserve all the Invariant Sections of the Document,
1427 unaltered in their text and in their titles. Section numbers
1428 or the equivalent are not considered part of the section
1431 M. Delete any section Entitled "Endorsements". Such a section
1432 may not be included in the Modified Version.
1434 N. Do not retitle any existing section to be Entitled
1435 "Endorsements" or to conflict in title with any Invariant
1438 O. Preserve any Warranty Disclaimers.
1440 If the Modified Version includes new front-matter sections or
1441 appendices that qualify as Secondary Sections and contain no
1442 material copied from the Document, you may at your option
1443 designate some or all of these sections as invariant. To do this,
1444 add their titles to the list of Invariant Sections in the Modified
1445 Version's license notice. These titles must be distinct from any
1446 other section titles.
1448 You may add a section Entitled "Endorsements", provided it contains
1449 nothing but endorsements of your Modified Version by various
1450 parties--for example, statements of peer review or that the text
1451 has been approved by an organization as the authoritative
1452 definition of a standard.
1454 You may add a passage of up to five words as a Front-Cover Text,
1455 and a passage of up to 25 words as a Back-Cover Text, to the end
1456 of the list of Cover Texts in the Modified Version. Only one
1457 passage of Front-Cover Text and one of Back-Cover Text may be
1458 added by (or through arrangements made by) any one entity. If the
1459 Document already includes a cover text for the same cover,
1460 previously added by you or by arrangement made by the same entity
1461 you are acting on behalf of, you may not add another; but you may
1462 replace the old one, on explicit permission from the previous
1463 publisher that added the old one.
1465 The author(s) and publisher(s) of the Document do not by this
1466 License give permission to use their names for publicity for or to
1467 assert or imply endorsement of any Modified Version.
1469 5. COMBINING DOCUMENTS
1471 You may combine the Document with other documents released under
1472 this License, under the terms defined in section 4 above for
1473 modified versions, provided that you include in the combination
1474 all of the Invariant Sections of all of the original documents,
1475 unmodified, and list them all as Invariant Sections of your
1476 combined work in its license notice, and that you preserve all
1477 their Warranty Disclaimers.
1479 The combined work need only contain one copy of this License, and
1480 multiple identical Invariant Sections may be replaced with a single
1481 copy. If there are multiple Invariant Sections with the same name
1482 but different contents, make the title of each such section unique
1483 by adding at the end of it, in parentheses, the name of the
1484 original author or publisher of that section if known, or else a
1485 unique number. Make the same adjustment to the section titles in
1486 the list of Invariant Sections in the license notice of the
1489 In the combination, you must combine any sections Entitled
1490 "History" in the various original documents, forming one section
1491 Entitled "History"; likewise combine any sections Entitled
1492 "Acknowledgements", and any sections Entitled "Dedications". You
1493 must delete all sections Entitled "Endorsements."
1495 6. COLLECTIONS OF DOCUMENTS
1497 You may make a collection consisting of the Document and other
1498 documents released under this License, and replace the individual
1499 copies of this License in the various documents with a single copy
1500 that is included in the collection, provided that you follow the
1501 rules of this License for verbatim copying of each of the
1502 documents in all other respects.
1504 You may extract a single document from such a collection, and
1505 distribute it individually under this License, provided you insert
1506 a copy of this License into the extracted document, and follow
1507 this License in all other respects regarding verbatim copying of
1510 7. AGGREGATION WITH INDEPENDENT WORKS
1512 A compilation of the Document or its derivatives with other
1513 separate and independent documents or works, in or on a volume of
1514 a storage or distribution medium, is called an "aggregate" if the
1515 copyright resulting from the compilation is not used to limit the
1516 legal rights of the compilation's users beyond what the individual
1517 works permit. When the Document is included in an aggregate, this
1518 License does not apply to the other works in the aggregate which
1519 are not themselves derivative works of the Document.
1521 If the Cover Text requirement of section 3 is applicable to these
1522 copies of the Document, then if the Document is less than one half
1523 of the entire aggregate, the Document's Cover Texts may be placed
1524 on covers that bracket the Document within the aggregate, or the
1525 electronic equivalent of covers if the Document is in electronic
1526 form. Otherwise they must appear on printed covers that bracket
1527 the whole aggregate.
1531 Translation is considered a kind of modification, so you may
1532 distribute translations of the Document under the terms of section
1533 4. Replacing Invariant Sections with translations requires special
1534 permission from their copyright holders, but you may include
1535 translations of some or all Invariant Sections in addition to the
1536 original versions of these Invariant Sections. You may include a
1537 translation of this License, and all the license notices in the
1538 Document, and any Warranty Disclaimers, provided that you also
1539 include the original English version of this License and the
1540 original versions of those notices and disclaimers. In case of a
1541 disagreement between the translation and the original version of
1542 this License or a notice or disclaimer, the original version will
1545 If a section in the Document is Entitled "Acknowledgements",
1546 "Dedications", or "History", the requirement (section 4) to
1547 Preserve its Title (section 1) will typically require changing the
1552 You may not copy, modify, sublicense, or distribute the Document
1553 except as expressly provided under this License. Any attempt
1554 otherwise to copy, modify, sublicense, or distribute it is void,
1555 and will automatically terminate your rights under this License.
1557 However, if you cease all violation of this License, then your
1558 license from a particular copyright holder is reinstated (a)
1559 provisionally, unless and until the copyright holder explicitly
1560 and finally terminates your license, and (b) permanently, if the
1561 copyright holder fails to notify you of the violation by some
1562 reasonable means prior to 60 days after the cessation.
1564 Moreover, your license from a particular copyright holder is
1565 reinstated permanently if the copyright holder notifies you of the
1566 violation by some reasonable means, this is the first time you have
1567 received notice of violation of this License (for any work) from
1568 that copyright holder, and you cure the violation prior to 30 days
1569 after your receipt of the notice.
1571 Termination of your rights under this section does not terminate
1572 the licenses of parties who have received copies or rights from
1573 you under this License. If your rights have been terminated and
1574 not permanently reinstated, receipt of a copy of some or all of
1575 the same material does not give you any rights to use it.
1577 10. FUTURE REVISIONS OF THIS LICENSE
1579 The Free Software Foundation may publish new, revised versions of
1580 the GNU Free Documentation License from time to time. Such new
1581 versions will be similar in spirit to the present version, but may
1582 differ in detail to address new problems or concerns. See
1583 `http://www.gnu.org/copyleft/'.
1585 Each version of the License is given a distinguishing version
1586 number. If the Document specifies that a particular numbered
1587 version of this License "or any later version" applies to it, you
1588 have the option of following the terms and conditions either of
1589 that specified version or of any later version that has been
1590 published (not as a draft) by the Free Software Foundation. If
1591 the Document does not specify a version number of this License,
1592 you may choose any version ever published (not as a draft) by the
1593 Free Software Foundation. If the Document specifies that a proxy
1594 can decide which future versions of this License can be used, that
1595 proxy's public statement of acceptance of a version permanently
1596 authorizes you to choose that version for the Document.
1600 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
1601 World Wide Web server that publishes copyrightable works and also
1602 provides prominent facilities for anybody to edit those works. A
1603 public wiki that anybody can edit is an example of such a server.
1604 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
1605 site means any set of copyrightable works thus published on the MMC
1608 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
1609 license published by Creative Commons Corporation, a not-for-profit
1610 corporation with a principal place of business in San Francisco,
1611 California, as well as future copyleft versions of that license
1612 published by that same organization.
1614 "Incorporate" means to publish or republish a Document, in whole or
1615 in part, as part of another Document.
1617 An MMC is "eligible for relicensing" if it is licensed under this
1618 License, and if all works that were first published under this
1619 License somewhere other than this MMC, and subsequently
1620 incorporated in whole or in part into the MMC, (1) had no cover
1621 texts or invariant sections, and (2) were thus incorporated prior
1622 to November 1, 2008.
1624 The operator of an MMC Site may republish an MMC contained in the
1625 site under CC-BY-SA on the same site at any time before August 1,
1626 2009, provided the MMC is eligible for relicensing.
1629 ADDENDUM: How to use this License for your documents
1630 ====================================================
1632 To use this License in a document you have written, include a copy of
1633 the License in the document and put the following copyright and license
1634 notices just after the title page:
1636 Copyright (C) YEAR YOUR NAME.
1637 Permission is granted to copy, distribute and/or modify this document
1638 under the terms of the GNU Free Documentation License, Version 1.3
1639 or any later version published by the Free Software Foundation;
1640 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
1641 Texts. A copy of the license is included in the section entitled ``GNU
1642 Free Documentation License''.
1644 If you have Invariant Sections, Front-Cover Texts and Back-Cover
1645 Texts, replace the "with...Texts." line with this:
1647 with the Invariant Sections being LIST THEIR TITLES, with
1648 the Front-Cover Texts being LIST, and with the Back-Cover Texts
1651 If you have Invariant Sections without Cover Texts, or some other
1652 combination of the three, merge those two alternatives to suit the
1655 If your document contains nontrivial examples of program code, we
1656 recommend releasing these examples in parallel under your choice of
1657 free software license, such as the GNU General Public License, to
1658 permit their use in free software.
1664 Node: Introduction
\7f2066
1665 Node: Maintaining GNU Programs
\7f2815
1666 Node: Design Issues
\7f3617
1667 Node: Coding Conventions
\7f7568
1668 Node: Make the Compiler Find the Bugs
\7f9535
1669 Node: Factor Out Repeated Code
\7f13092
1670 Node: Debugging is For Users Too
\7f15118
1671 Node: Don't Trust the File System Contents
\7f15849
1672 Node: The File System Is Being Modified
\7f17132
1674 Node: Using the GNU Portability Library
\7f19770
1675 Node: Documentation
\7f26951
1676 Node: Testing
\7f29669
1678 Node: Distributions
\7f31754
1679 Node: Internationalisation
\7f32789
1680 Node: Security
\7f33258
1681 Node: Making Releases
\7f44621
1682 Node: GNU Free Documentation License
\7f46746