==================== Changes in man-pages-2.80 ==================== Released: 2008-06-05 Contributors ------------ The following people contributed notes, ideas, or patches that have been incorporated in changes in this release: Adrian Bunk Alain Portal Andreas Herrmann Andrew Morton Andries E. Brouwer Anoop Aurelien Gerome Daniel Burr Davide Libenzi Felix Kater Folkert van Heusden Hamaji Shinichiro Heikki Orsila Ingo Molnar Justin Pryzby Karsten Weiss Martin Pitt Marty Leisner Nicolas François Nick Piggin Petter Reinholdtsen Reuben Thomas Sam Varshavchik Stuart Brady Theodoros V. Kalamatianos Thomas Huriaux Tim Stoakes Timothy Baldwin Tolga Dalman Apologies if I missed anyone! Global changes -------------- bdflush.2 inotify_add_watch.2 mprotect.2 sigprocmask.2 ctime.3 getusershell.3 setbuf.3 st.4 ip.7 packet.7 mtk Replace "(il)legal" by "(not) permitted" or "(in)valid". read.2 utime.2 filesystems.5 packet.7 mtk s/time stamp/timestamp/, for consistency with majority use in other pages, and in POSIX.1. madvise.2 mbind.2 mincore.2 mmap.2 mmap2.2 msync.2 remap_file_pages.2 mtk Change name of 'start' argument to 'addr' for consistency with: * other memory-related interfaces * POSIX specification (for those interfaces in POSIX) * Linux and glibc source code (in at least some cases) Various pages mtk s/filesystem/file system/, for consistency with majority use in other pages, and in POSIX.1. Various pages mtk s/zeroes/zeros/, for consistency with majority use in other pages, and in POSIX.1. abs.3 proc.5 mtk s/builtin/built-in/, for consistency with majority use in other pages, and in POSIX.1. mknod.2 ftw.3 mtk s/normal file/regular file/ Various pages mtk s/nonempty/non-empty/ Various pages mtk s/nonzero/non-zero/ Various pages mtk s/realtime/real-time/, for consistency with majority usage. Various pages mtk s/command line/command-line/ when used attributively. Various pages mtk Use "run time" when non-attributive, "run-time" when attributive. Various pages mtk Various pages that I wrote carried a slightly modified version of the "verbatim" license. In the interests of minimizing license proliferation, I've reverted the modified form so that the license is exactly the same as on other pages carrying the verbatim license. epoll_ctl.2 getitimer.2 getrlimit.2 unix.7 mtk s/since kernel x.y.z/since Linux x.y.z/ wait.2 inotify.7 mtk Reformat kernel version information for flags. Typographical or grammatical errors have been corrected in several places. (Special thanks to Nicolas François.) New pages --------- random_r.3 mtk, after a suggestion by aeb Documents random_r(3), srandom_r(3), initstate_r(2), and setstate_r(3), which are the reentrant equivalents of random(3), srandom(3), initstate(3), and setstate(3). New links --------- lutimes.3 mtk Link to futimes.3. initstate_r.3 setstate_r.3 srandom_r.3 mtk Links to random_r.3. daylight.3 timezone.3 tzname.3 mtk Links to tzset.3. isnanf.3 isnanl.3 mtk Links to finite.3. encrypt_r.3 setkey_r.3 mtk Links to encrypt.3. Changes to individual pages --------------------------- clone.2 mtk Added note that CLONE_STOPPED (which no-one uses anyway) is now deprecated. epoll_create.2 mtk Add NOTES section pointing out that 'size' argument is unused since kernel 2.6.8. epoll_ctl.2 mtk Added portability note to BUGS text for EPOLL_CTL_DEL. epoll_wait.2 mtk If the 'sigmask' is NULL, then epoll_pwait() is equivalent to epoll_wait(). fork.2 mtk NOTES: since glibc 2.3.3, the glibc NPTL fork() wrapper bypasses the fork() system call to invoke clone() with flags providing equivalent functionality. futex.2 mtk, after a note from Adrian Bunk FUTEX_FD has been removed, as of kernel 2.6.26. futimesat.2 mtk Note that this system call is made obsolete by utimensat(2). getgroups.2 Petter Reinholdtsen SEE ALSO: Add getgrouplist(3). as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284. mtk NGROUPS_MAX increased in kernel 2.6.4. SEE ALSO: Add credentials(7). mtk Reformat DESCRIPTION and RETURN VALUE sections to be more consistent with man-pages style. Add some more detail to descriptions of system calls. Clarified what happens if caller of getgroups() is a member of more than 'size' supplementary groups. ERRORS: Add ENOMEM. getpriority.2 mtk, after a note from Ingo Molnar Add text in NOTES about the punchier effect of nice values in kernel 2.6.23 and later. Add Documentation/scheduler/sched-nice-design.txt to SEE ALSO list. gettid.2 mtk Added VERSIONS section noting that this system call first appeared in 2.4.11. kill.2 Marty Leisner / mtk Add text explicitly noting that sig==0 can be used to check for the existence of a PID or PGID. mtk A few minor rewordings. mbind.2 mtk The location of the numactl package has changed. mmap.2 mtk Added some .SS headings to make structure of page a little more obvious. mtk, with input from Nick Piggin MAP_POPULATE supports both file and anonymous mappings. Since 2.6.23, MAP_POPULATE supports private mappings. Since 2.6.23, MAP_NONBLOCK causes MAP_POPULATE to be a no-op. mtk NOTES: Added details on mapping address that is selected by kernel when MAP_FIXED is / isn't specified. mount.2 mtk The MS_REMOUNT changes in 2.4 were at 2.4.10 (not 2.4). mtk Minor wording change. msgctl.2 mtk Clarify that "unused" fields in msginfo structure are "unused within the kernel". msginfo.msgpool is measured in kilobytes, not bytes. Minor rewordings in comments for msginfo structure. msgop.2 mtk Various minor rewordings and restructurings for clarity. mtk, after a note from Reuben Thomas Remove "msgop" from NAME section. mkdir.2 mtk Clarify meaning of "BSD group semantics". SEE ALSO: add chown(2). mknod.2 mtk SEE ALSO: add chown(2) and chmod(2). mmap.2 mtk SEE ALSO: add mprotect(2) and shmat(2). mprotect.2 Hamaji Shinichiro SYNOPSIS: s/size_t \*len/size_t len/ open.2 mtk Note that O_CLOEXEC should be in the next POSIX.1 revision. mtk More than just ext2 supports "mount -o bsdgroups" nowadays, so make the discussion about group ownership of new files a bit more generic. mtk SEE ALSO: add chown(2) and chmod(2). poll.2 mtk If the 'sigmask' is NULL, then ppoll() is equivalent to poll() with respect to signal mask manipulations. posix_fadvise.2 mtk s/posix_madvise (2)/posix_madvise (3)/; (The referred-to page still doesn't exist yet, but hopefully will do sometime soon.) ptrace.2 Anoop, Acked by Roland McGrath. Re PTRACE_PEEKUSER: the offsets and data returned might not match with the definition of struct user. See also http://lkml.org/lkml/2008/5/8/375 recv.2 Felix Kater / mtk Improve wording for EAGAIN error in discussion of MSG_DONTWAIT. rmdir.2 Martin Pitt POSIX.1 also allows EEXIST for the ENOTEMPTY error condition. as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=467552. sched_setscheduler.2 mtk, with input from Ingo Molnar Add description of SCHED_IDLE policy (new in 2.6.23). Tweak description of SCHED_BATCH. Minor rewordings. select_tut.2 Justin Pryzby Various wording clean-ups. semctl.2 mtk Clarify that "unused" fields in seminfo structure are "unused within the kernel". Minor rewordings in comments for seminfo structure. semop.2 Aurelien Gerome Small fix in example code. setpgid.2 mtk / Karsten Weiss Clarify description of setpgid() a little. shmctl.2 mtk Clarify that "unused" fields in shminfo structure are "unused within the kernel". Minor rewordings in comments for shminfo structure. shmop.2 mtk, after a note from Reuben Thomas Remove "shmop" from NAME section. signalfd.2 mtk Added BUGS text noting that before kernel 2.6.25, the ssi_int and ssi_ptr fields are not set. Added comments describing fields in signalfd_siginfo structure. Update field names in example program (s/signo/ssi_signo/). Various small fixes, and remove duplicated sentence. Minor edits to structure definition. sigqueue.2 mtk Added some comments to code in NOTES. stat.2 mtk Minor wording change. symlink.2 mtk SEE ALSO: add lchown(2). sync_file_range.2 mtk / Andrew Morton Remove statement that (SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | SYNC_FILE_RANGE_WAIT_AFTER) is a traditional fdatasync(2) operation. See https://bugzilla.mozilla.org/show_bug.cgi?id=421482 comments 129 to 131. syscalls.2 mtk This page is now up to date as at kernel 2.6.25. syslog.2 mtk Small tidy up of language relating to permissions/capabilities. timerfd_create.2 mtk Minor change to example program. Minor wording change. utime.2 Reuben Thomas Remove unnecessary subheading for utimes(). as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=477402. mtk Change description in NAME line ("or" is not correct: these calls always change *both* timestamps). CONFORMING TO: utimes() is in POSIX.1-2001. mtk Rename 'buf' argument of utime() to 'times' (like utimes()). Clarify explanation of EACCES and EPERM errors. Remove BUGS section, since it doesn't seem to add useful information. Clarified discussion of capabilities, and noted that CAP_DAC_OVERRIDE also has a role. Other minor rewordings. wait.2 mtk, after a note by Justin Pryzby Add a sentence clarifying that even though the default disposition of SIGCHLD is "ignore", explicitly setting the disposition to SIG_IGN results in different treatment of zombies. aio_cancel.3 aio_error.3 aio_fsync.3 aio_read.3 aio_return.3 aio_suspend.3 aio_write.3 Kevin O'Gorman Add "Link with -lrt" to SYNOPSIS. backtrace.3 Nicolas François s/backtrace_symbols/backtrace_symbols_fd/ in one sentence. mtk Fix bogus reference to variable 'strings': should be: "the array of pointers". ctime.3 mtk Add warning under NOTES that asctime(), ctime(), gmtime(), and localtime() may each overwrite the static object returned by any of the other calls. Other minor edits. dlopen.3 mtk Add more detail to the description of the fields in the structure returned by dladdr(). fexecve.3 mtk Clean up SYNOPSIS after work by cut-and-paste-Pete: the necessary header file is not ! futimes.3 mtk Add documentation of lutimes(), which appeared in glibc 2.6. mtk Change description in NAME line ("or" is not correct: these calls always change *both* timestamps). CONFORMING TO: futimes() did not come from 4.2BSD. (It came from FreeBSD; see the FreeBSD man page.) getenv.3 mtk Noted that caller must not modify returned value string. Noted that getenv() is not reentrant: the buffer may be statically allocated and overwritten by later calls to getenv(), putenv(), setenv(), or unsetenv(). Other minor rewrites. getgrent.3 Petter Reinholdtsen SEE ALSO: Add getgrouplist(3). as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=479284. gethostbyname.3 mtk Add 'h_errno' to NAME list. getopt.3 mtk Add 'optarg', 'optind', 'opterr', and 'optopt' to NAME section. Add subheading for getopt_long() and getopt_long_only() description. getpt.3 mtk Point out that this function should be avoided in favor of posix_openpt(). Add ERRORS section referring to open(2). getsubopt.3 Daniel Burr SYNOPSIS: Fix declaration of valuep. as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476672. malloc.3 mtk RETURN VALUE: Note circumstances in which successful malloc() and calloc() can return NULL. mq_open.3 mtk, after a note by Marty Leisner Note that is needed for O_* constants and is needed for 'mode' constants. opendir.3 mtk Describe treatment of close-on-exec flag by opendir() and fdopendir(). openpty.3 mtk SEE ALSO: add ttyname(3). raise.3 mtk / Timothy Baldwin Clarify semantics of raise() when called from a multithreaded program. as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=476484. mtk Rewrites and additions to various parts of the page. rand.3 Tolga Dalman / aeb / mtk Remove outdated warning in NOTES; encourage the use of random(3) instead. Folkert van Heusden Clarify wording describing range of values returned by rand(). random.3 aeb / mtk / Tolga Dalman Recommend use or random_r(3) for multithreaded applications that need independent, reproducible sequences of random numbers. Move references to "The Art of Computer Programming" and "Numerical Recipes", formerly in rand(3), to this page. Add drand48(93) to SEE ALSO list. regex.3 Heikki Orsila Clarify description of 'rm_eo' field. sem_open.3 mtk, after a note by Marty Leisner Note that is needed for O_* constants and is needed for 'mode' constants. sem_post.3 mtk Added pointer to example in sem_wait(3). sem_close.3 sem_destroy.3 sem_getvalue.3 sem_init.3 sem_open.3 sem_post.3 sem_unlink.3 sem_wait.3 mtk, after a note from Marty Leisner Add text to SYNOPSIS noting the need to link with "-lrt" or "-pthread". setenv.3 mtk setenv() copies 'name' and 'value' (contrast with putenv()). unsetenv() of a nonexistent variable does nothing and is considered successful. Noted that setenv() and unsetenv() need not be reentrant. shm_open.3 mtk, after a note by Marty Leisner Note that is needed for O_* constants and is needed for 'mode' constants. undocumented.3 mtk initstate_r(3), setkey_r(3), setstate_r(3) are now documented. utmp.5 Nicolas François Small rewording. resolv.conf.5 Nicolas François gethostname() is in Section 2, not section 3. ascii.7 Stuart Brady Fix rendering of ' (backtick) and apostrophe (') in tables charsets.7 Nicolas François s/unicode.com/unicode.org/ credentials.7 mtk NOTES: Pthreads requires that all threads share the same UIDs and GIDs. But the Linux kernel maintains separate UIDs and GIDs for every thread. NPTL does some work to ensure that credential changes by any thread are carried through to all POSIX threads in a process. mtk sysconf(_SC_NGROUPS_MAX) can be used to determine the number of supplementary groups that a process may belong to. Clarify that supplementary group IDs are specified in POSIX.1-2001. epoll.7 mtk, after a note from Sam Varshavchik For answer A2, change "not recommended" to "careful programming may be required". inotify.7 mtk Document SIGIO feature (new in 2.6.25) for inotify file descriptors. mtk Note that select()/poll()/epoll_wait() indicate a ready inotify file descriptor as readable. mtk Document IN_ATTRIB in a little more detail. pthreads.7 Justin Pryzby Grammar fix, plus fix typo in script. mtk Add list of thread-safe functions. standards.7 mtk Add a section on the upcoming POSIX revision. ld.so.8 Justin Pryzby / mtk Various wording improvements.