==================== Changes in man-pages-3.52 ==================== Released: 2013-07-04, Munich Contributors ------------ The following people contributed patches/fixes or (noted in brackets in the changelog below) reports, notes, and ideas that have been incorporated in changes in this release: Adrian Bunk Andrea Remondini Anthony Foiani Brian Norris Cyril Hrubis Dan Jacobson David Prévot Eric S. Raymond Georg Sauthoff Jeff Moyer Jérémie Galarneau Jon Grant Manuel Traut Марк Коренберг Michael Kerrisk Mike Frysinger Pavel Emelyanov Peng Haitao Peter LaDow Petr Gajdos Regid Siddhesh Poyarekar Simone Piccardi Simon Paillard Vince Weaver Yuri Kozlov Apologies if I missed anyone! Newly documented interfaces in existing pages --------------------------------------------- perf_event_open.2 Vince Weaver Add PERF_IOC_FLAG_GROUP documentation The perf_event_open() ENABLE/DISABLE/RESET ioctls can take an argument, PERF_IOC_FLAG_GROUP. This wasn't documented at all until about a year ago (despite the support being there from the beginning) so I missed this when initially writing the man page. socket.7 Pavel Emelyanov, Michael Kerrisk Document SO_PEEK_OFF option Since Linux 3.4 there appeared an ability to specify the offset in bytes from which the data will be MSG_PEEK-ed. Describe this socket option in the socket(7) page, where all the other socket options are described. Global changes -------------- Various pages Michael Kerrisk Convert inline formatting (\fX...\fP) to dot-directive formatting readdir.2 asprintf. getline.3 getlogin.3 pthread_setname_np.3 readdir.3 strerror.3 Michael Kerrisk [Jon Grant] Clarify that terminating null byte is '\0' Changes to individual pages --------------------------- execve.2 Peter LaDow Add envp to the Linux notes about NULL pointers During the review of static analysis results, we discovered a functional, but non-portable, use of execve(). For example: char *cmd[] = { "/path/to/some/file", NULL }; execve(cmd[0], cmd, NULL); The call succeeds. Yet, the static analysis tool (rightly) pointed out that envp could be dereferenced. But digging into glibc and the kernel, it appears that like argv, envp when NULL is treated as if it were an empty list. So, to clear things up, I'm submitting this patch to update the man page to indicate that envp is treated like argv. fallocate.2 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error io_setup.2 Cyril Hrubis [Jeff Moyer] Clarify the nr_events parameter Currently the io_setup.2 man page describes what the kernel really does, i.e., that the resulting context may be able to hold more than the 'nr_event's operations because the memory allocated in kernel is rounded to be multiple of page size. It is better not to expose this implementation detail and simply state that the resulting context is suitable for 'nr_events' operations. perf_event_open.2 Vince Weaver Clarify the perf_event_open() wakeup_events/wakeup_watermark fields Clarify the perf_event_open() wakeup_events/wakeup_watermark fields a bit, based on info from kernel commit cfeb1d90a1b1. Vince Weaver Update to match the Linux 3.10 release This patch updates the perf_event_open() documentation to include new interfaces added in the 3.10 kernel. It also documents a few [To be documented] instances left over from the 3.7 kernel. Vince Weaver Small correction to description of 'flags' argument prctl.2 Michael Kerrisk Note equivalents of PR_SET_NAME pthread_setname_np() and pthread_getname_np() and /proc/self/task/TID/comm provide access to the same attribute. pread.2 Michael Kerrisk [Марк Коренберг] pread() and pwrite() are especially useful in multithreaded applications recv.2 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error semctl.2 Michael Kerrisk [Simone Piccardi] 'sem_nsems' is 'unsigned long' since Linux 2.4 shmget.2 Michael Kerrisk Rewrite RETURN VALUE and mention that 'errno' is set on error sigaction.2 Michael Kerrisk [Brian Norris] RETURN VALUE: mention that 'errno' is set on error signal.2 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error sigpending.2 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error sigprocmask.2 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error sigsuspend.2 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error syscall.2 Mike Frysinger Document s390/s390x calling convention a64l.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function l64a() is not thread safe. abs.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions abs(), labs(), llabs() and imaxabs() are thread-safe. aio_error.3 Peng Haitao ATTRIBUTES: Note function that is thread-safe The function aio_error() is thread safe. aio_return.3 Peng Haitao ATTRIBUTES: Note function that is thread-safe The function aio_return() is thread safe. alloca.3 Adrian Bunk Correct information on getting non-inlined version with gcc+glibc - remove the incorrect information that -fno-builtin would help - add -std=c11 to the list of strict options - emphasize more that both the gcc option and not including alloca.h are needed - add the #ifdef from the glibc alloca.h to make the situation clearer bindresvport.3 Peng Haitao ATTRIBUTES: Note function that is thread-safe Before glibc 2.17, bindresvport() is not thread-safe. Since glibc 2.17, it is thread-safe, the patch can refer to URL: http://sourceware.org/git/?p=glibc.git;a=commit;h=f6da27e53695ad1cc0e2a9490358decbbfdff5e5 canonicalize_file_name.3 Michael Kerrisk Put CONFORMING TO section in right location catgets.3 Michael Kerrisk [Jon Grant] Clarify that null byte is '\0' ceil.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions ceil(), ceilf() and ceill() are thread safe. cimag.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions cimag(), cimagf() and cimagl() are thread safe. clock_getcpuclockid.3 Peng Haitao ATTRIBUTES: Note function that is thread-safe The function clock_getcpuclockid() is thread safe. conj.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions conj(), conjf() and conjl() are thread safe. crypt.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function crypt() is not thread safe. ctermid.3 Peng Haitao ATTRIBUTES: Note function that is thread safe with exceptions The function ctermid() is thread safe with exceptions. dirfd.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error drand48.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions drand48(), erand48(), lrand48(), nrand48(), mrand48(), jrand48(), srand48(), seed48() and lcong48() are not thread safe. ecvt.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions ecvt() and fcvt() return a string located in a static buffer which is overwritten by the next call to the functions, so they are not thread-safe. encrypt.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions encrypt() and setkey() are not thread safe. ether_aton.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions ether_aton() and ether_ntoa() are not thread safe. fcloseall.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function fcloseall() is not thread safe. ferror.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions ferror(), clearerr(), feof() and fileno() are thread safe. fgetgrent.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error fgetpwent.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error fgetwc.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error fmtmsg.3 Peng Haitao ATTRIBUTES: Note function that is thread-safe Before glibc 2.16, fmtmsg() is not thread-safe. Since glibc 2.16, it is thread-safe, the patch can refer to URL: http://sourceware.org/git/?p=glibc.git;a=commit;h=7724defcf8873116fe4efab256596861eef21a94 fputwc.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error getdate.3 Peng Haitao ATTRIBUTES: Note functions that are and aren't thread-safe getgrent.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function getgrent() is not thread safe. getgrnam.3 Peng Haitao ATTRIBUTES: Note functions that are and aren't thread-safe getline.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error getlogin.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function getlogin() is not thread safe. The function cuserid() is thread-safe with exceptions. Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error getpass.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe getpwent.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function getpwent() is not thread safe. getpwnam.3 Peng Haitao ATTRIBUTES: Note functions that are and aren't thread-safe getspnam.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error getttyent.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe getusershell.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions getusershell(), setusershell() and endusershell() are not thread safe. getutent.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error hsearch.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error hsearch.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions hsearch(), hcreate() and hdestroy() are not thread-safe. localeconv.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The function localeconv() returns a pointer to a structure which might be overwritten by subsequent calls to localeconv() or by calls to setlocale(), so it is not thread-safe. Peng Haitao Add RETURN VALUE section malloc_info.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error mblen.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function mblen() is not thread safe. mbrlen.3 Peng Haitao ATTRIBUTES: Note function that is thread safe with exceptions The function mbrlen() is thread safe with exceptions. mbrtowc.3 Peng Haitao ATTRIBUTES: Note function that is thread safe with exceptions The function mbrtowc() is thread safe with exceptions. mktemp.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error modf.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions modf(), modff() and modfl() are thread safe. popen.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error pthread_attr_setinheritsched.3 Michael Kerrisk Note the scheduling attributes affected by this function pthread_attr_setschedparam.3 pthread_attr_setschedpolicy.3 pthread_attr_setscope.3 Michael Kerrisk [Manuel Traut, Siddhesh Poyarekar] The inherit-scheduler attribute must be set to PTHREAD_EXPLICIT_SCHED In order for the attributes set by these functions to have an effect, the caller must use pthread_attr_setinheritsched(3) to set the inherit-scheduler attribute of the attributes object to PTHREAD_EXPLICIT_SCHED. ptsname.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function ptsname() is not thread safe. putenv.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error putpwent.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error qecvt.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions qecvt() and qfcvt() are not thread-safe. random.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error Michael Kerrisk Add EINVAL error for setstate() Michael Kerrisk BUGS: inistate() does not return NULL on error http://sourceware.org/bugzilla/show_bug.cgi?id=15380 random_r.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error readdir.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The data returned by readdir() may be overwritten by subsequent calls to readdir() for the same directory stream, so it is not thread-safe. re_comp.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions re_comp() and re_exec() are not thread safe. rexec.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions rexec() and rexec_af() are not thread safe. round.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions round(), roundf() and roundl() are thread safe. scalbln.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions scalbn(), scalbnf(), scalbnl(), scalbln(), scalblnf() and scalblnl() are thread safe. scandir.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error siginterrupt.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error signbit.3 Peng Haitao ATTRIBUTES: Note macro that is thread-safe The macro signbit() is thread safe. sigsetops.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error stdio_ext.3 Peng Haitao ATTRIBUTES: Note functions that are not thread-safe The functions __fbufsize(), __fpending(), __fpurge() and __fsetlocking() are not thread safe. strdup.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error strerror.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function strerror() is not thread safe. strftime.3 Michael Kerrisk Clarify details of return value Michael Kerrisk BUGS: 'errno' is not set if the result string would exceed 'max' bytes strtok.3 Peng Haitao ATTRIBUTES: Note function that is not thread-safe The function strtok() is not thread safe. Michael Kerrisk [Georg Sauthoff] Add more detail on the operation of strtok() Add a number of missing details on the operation of strtok() tempnam.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error timegm.3 Jérémie Galarneau copy the string returned by getenv() The example of a portable version of timegm() uses the string returned by getenv() after calling setenv() on the same environment variable. The tz string may be invalid as per getenv.3: "The string pointed to by the return value of getenv() may be statically allocated, and can be modified by a subsequent call to getenv(), putenv(3), setenv(3), or unsetenv(3)." tmpnam.3 Peng Haitao ATTRIBUTES: Note function that is thread safe with exceptions The function tmpnam() is thread safe with exceptions. trunc.3 Peng Haitao ATTRIBUTES: Note functions that are thread-safe The functions trunc(), truncf() and truncl() are thread safe. ttyname.3 Michael Kerrisk ATTRIBUTES: Note functions that are and aren't thread-safe ttyslot.3 Michael Kerrisk ATTRIBUTES: Note functions that are not thread-safe usleep.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error wcsdup.3 Michael Kerrisk RETURN VALUE: mention that 'errno' is set on error core.5 Michael Kerrisk Implicitly adding the PID to a core filename was dropped in 2.6.27 proc.5 Michael Kerrisk Document /proc/[pid]/fd/ anon_inode symlinks Mike Frysinger Document /proc/[pid]/fd/ symlinks a bit more Describe the type:[inode] syntax used in this dir bootparam.7 Michael Kerrisk [Dan Jacobson] Remove outdated text on LILO and LoadLin Strike the discussion of LILO and LoadLin, which are long obsolete, and make a brief mention of GRUB. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=604019 Regid Remove mention of the deprecated rdev(8) The deprecated rdev(8) command was removed from util-linux in 2010. See https://git.kernel.org/?p=utils/util-linux/util-linux.git;a=commit;h=a3e40c14651fccf18e7954f081e601389baefe3fO Andrea Remondini Document the 'resume' boot parameter inotify.7 Michael Kerrisk [Jon Grant] Clarify that null byte is '\0' iso_8859-2.7 Eric S. Raymond Remove incorrect reference to nonexistent groff glyph \[shc] The reference incorrectly attempted to duplicate an actual soft hyphen (hex 0xad) just before it in the file. man-pages.7 Peng Haitao Add description of "ATTRIBUTES" "ATTRIBUTES" section can mention thread safety, cancellation safety, and async-cancel-safety. socket.7 Michael Kerrisk Note that 'optval' for socket options is an 'int' in most cases tcp.7 Michael Kerrisk Note that 'optval' for socket options is an 'int' in most cases udp.7 Michael Kerrisk Note that 'optval' for socket options is an 'int' in most cases