Remove a longstanding mystery in the text of the page, by
explaining a case where the value returned for a symbol may be
NULL. (However, there are presumably other cases, since the text
in the dlsym(3) manual page pre-dates the invention of IFUNCs.)
See also
https://stackoverflow.com/questions/13941944/why-can-the-value-of-the-symbol-returned-by-dlsym-be-null
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Quoting Branden:
*roff escape sequences may sometimes look like C escapes, but that
is misleading. *roff is in part a macro language and that means
recursive expansion to arbitrary depths.
You can get away with "\\" in a context where no macro expansion
is taking place, but try to spell a literal backslash this way in
the argument to a macro and you will likely be unhappy with
results.
Try viewing the attached file with "man -l".
"\e" is the preferred and portable way to get a portable "escape
literal" going back to CSTR #54, the original Bell Labs troff
paper.
groff(7) discusses the issue:
\\ reduces to a single backslash; useful to delay its
interpretation as escape character in copy mode. For a
printable backslash, use \e, or even better \[rs], to be
independent from the current escape character.
As of groff 1.22.4, groff_man(7) does as well:
\e Widely used in man pages to represent a backslash output
glyph. It works reliably as long as the .ec request is
not used, which should never happen in man pages, and it
is slightly more portable than the more exact ‘\(rs’
(“reverse solidus”) escape sequence.
People not concerned with portability to extremely old troffs should
probably just use \(rs (or \[rs]), as it means "the backslash
glyph", not "the glyph corresponding to whatever the current escape
character is".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Quoting Branden:
*roff systems will interpret the period in the unpatched
page as sentence-ending punctuation and put inter-sentence
spacing after it. (This might not be visible on
nroff/terminal devices, but it is more likely to be on
typesetter/PostScript/PDF output).
groff_man(7) in groff 1.22.4 attempts to throw man page
writers a bone here:
\& Zero‐width space. Append to an input line to prevent
an end‐of‐ sentence punctuation sequence from being
recognized as such, or insert at the beginning of an
input line to prevent a dot or apostrophe from being
interpreted as the beginning of a roff request.
Reported-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Use a single-font-style macro (".B", ".I") for a single argument.
Remove unneeded quotation marks (").
The output from "nroff" and "groff" is unchanged, except for the change
1) '-1' to '\-1' in the file "timegm.3"
2) to separate ',' from a word in the file "uselocale.3".
Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Historically, at least FIFOs and pipes yielded the error EINVAL.
Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
According to the latest glibc, the bsd_signal() function is just
declared when POSIX.1-2008 (or newer) instead of POSIX.1-2001 is
not set since glibc v2.26.
Please see the following code from signal/signal.h:
-----------------------------------------------------------------
/* The X/Open definition of `signal' conflicts with the BSD version.
So they defined another function `bsd_signal'. */
extern __sighandler_t bsd_signal (int __sig, __sighandler_t __handler)
__THROW;
-----------------------------------------------------------------
Signed-off-by: Xiao Yang <yangx.jy@cn.fujitsu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The notes in pthread_rwlockattr_setkind_np.3 imply there is a bug
in glibc's implementation of PTHREAD_RWLOCK_PREFER_WRITER_NP (a
non-portable constant anyway), but this is not true. The
implementation of PTHREAD_RWLOCK_PREFER_WRITER_NP is made almost
impossible by the POSIX standard requirement that reader locks be
allowed to be recursive, and that requirement makes writer
preference deadlock without an impossibly complex requirement that
we track all reader locks. Therefore the only sensible solution
was to add PTHREAD_RWLOCK_PREFER_WRITER_NONRECURSIVE_NP and
disallow recursive reader locks if you want writer preference.
This patch removes the bug description and documents the current
state and recommendations for glibc. I have also updated bug 7057
with this information, answering Steven Munroe's almost 10 year
old question :-) I hope Steven is enjoying his much earned
retirement.
Should we move the glibc discussion to some footnote? Some libc
may be able to implement the requirement to avoid deadlocks in the
future, but I doubt it (fundamental CS stuff).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The strfry(3) function does not use rand(). The original version
from 1995 did, but it was changed to use a different PRNG in glibc
commit 4770745624b7f7f25623f1f10d46a4c4d6aec25c, 1996-12-04.
This C program demonstrates the behavior. By not calling srand(),
it gets the same values for successive calls to rand(), but
strfry() returns a different value each time the program is run.
If strfry() called srand(), it would alter the sequence of numbers
return by rand().
int main(void) {
printf("%d\n", rand());
char alphabet[] = "abcdefghijklmnopqrstuvwxyz";
puts(strfry(alphabet));
printf("%d\n", rand());
}
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This doesn't actually matter on any C library I know of --- they
all just do a NULL check and forward to fclose(3). (The actual
mistake I saw was someone not realizing that they had to call
*anything*.)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since adding checking to Android's bionic for file descriptor
double-closes, we've found that the most common cause of these
bugs is incorrect use of fileno(3). There appears to be a common
misconception that it transfers ownership of the file descriptor
to the caller.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Ian Turner: The exact return calls are at the discretion of the
underlying VFS, but I'm pretty sure that EINTR is a possibility.
Or, if it's not, then the flock() manpage should be amended
accordingly, since the two share the same underlying
implementation.
mtk: lockf(3) is implemented on top of fcntl() locking, so
EINTR is of course a possibility.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add text to CONFORMING TO explaining that the "_np"
suffix is because these functions are non-portable.
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Perhaps some people might misunderstand memory allocated by
alloca() to be like other memory allocated on the stack: that when
the allocation (or the pointer to the allocation) goes out of
scope, the memory is freed. Add some text to prevent that
misunderstanding.
Reported-by: Robin Kuzmin <kuzmin.robin@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There is not an acceptable reason to use these functions ever in
new code. For example, just observe the implementation of the
KDF:
/*
* Turn password into DES key
*/
void
passwd2des_internal (char *pw, char *key)
{
int i;
memset (key, 0, 8);
for (i = 0; *pw && i < 8; ++i)
key[i] ^= *pw++ << 1;
des_setparity (key);
}
This kind of nonsense isn't okay in the year 2017. Therefore, we
enlighten our poor users.
[Note from mtk: I think Jason knows that of which he talks.]
Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
There's a detailed explanation in glob(7), so reuse the same text
glob(3) uses to redirect the reader, rather than inlining a short
explanation.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The double negative is a little confusing, but required. But try
to make the semantics a little clearer in the wording (which is
now closer to the wording in the C standard).
Reported-by: Eric Benton <erbenton@comcast.net>
Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Indicate that strcmp() does not take the locale into account.
Provide a link to strcoll().
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This is inline with POSIX terminology. See also the earlier
commit a00b7454b8 (in 2012)
which fixed most of these cases.
Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
LC_GLOBAL_HANDLE is not defined anywhere, the doc meant LC_GLOBAL_LOCALE
instead.
Reported-by: Solal Pirelli <solal.pirelli@gmail.com>
Signed-off-by: Antonio Ospite <ao2@ao2.it>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
When initializing a new buffer (e.g., that will be sent with
sendmsg(2)), that buffer must first be zero-initialized to
ensure the correct operation of CMSG_NXTHDR().
Verified by experiment, and also by inspection of the glibc
source code:
_EXTERN_INLINE struct cmsghdr *
__NTH (__cmsg_nxthdr (struct msghdr *__mhdr, struct cmsghdr *__cmsg))
{
if ((size_t) __cmsg->cmsg_len < sizeof (struct cmsghdr))
/* The kernel header does this so there may be a reason. */
return (struct cmsghdr *) 0;
[1] __cmsg = (struct cmsghdr *) ((unsigned char *) __cmsg
+ CMSG_ALIGN (__cmsg->cmsg_len));
if ((unsigned char *) (__cmsg + 1) > ((unsigned char *) __mhdr->msg_control
+ __mhdr->msg_controllen)
[2] || ((unsigned char *) __cmsg + CMSG_ALIGN (__cmsg->cmsg_len) // <---
> ((unsigned char *) __mhdr->msg_control + __mhdr->msg_controllen)))
/* No more entries. */
return (struct cmsghdr *) 0;
return __cmsg;
}
At point [1], __cmsg has been updated to point to the next
cmsghdr. The subsequent check at [2] relies on 'cmsg_len'
in the next cmsghdr having some "sensible" value (e.g., 0).
See also https://stackoverflow.com/questions/27601849/cmsg-nxthdr-returns-null-even-though-there-are-more-cmsghdr-objects
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Make it cleared that all of the library functions
described on this page will use the getcwd() system call
if it is present. (The text previously implied that only
the getcwd() library function made use of the system call,
but looking in the glibc source code shows that all of the
functions make use of a generic implementation (__getcwd())
that uses the system call if it is present.)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The existing text on some of the oddities of the Linux getcwd()
implementation was placed somewhat obtrusively in the DESCRIPTION.
Shift the text to NOTES, and at the same time move the related
discussion of glibc nonconformance to POSIX into BUGS.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The example code currently passes `buflen - 1` to `strncpy`,
however the length parameter to `strncpy` is `size_t`, which is
unsigned. This means that when `buflen` is zero, the cast of `-1`
to unsigned will result in passing `UINT_MAX` as the length.
Obviously, that would be incorrect and could cause `strncpy` to
write well beyond the buffer passed.
The easy solution is to wrap the whole code in the `buflen > 0`
check, rather then just the part of the code that applies the null
terminator.
Signed-off-by: Matthew Kilgore <mattkilgore12@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Since the BSD header has been imported to other C libraries (including
glibc), note that here so people know it isn't BSD-specific.
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
* man3/termios.3 (.B TABDLY): Reference to the BUGS section.
(.SH BUGS): New section. Describe an issue on alpha where the XTABS
macro was defined to a value outside TABDLY mask.
Signed-off-by: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The distribution may choose not to support _XOPEN_CRYPT in the
case that the distribution has transitioned from glibc crypt to
libxcrypt.
Signed-off-by: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
With glibc fix 52a713fdd0a30e1bd79818e2e3c4ab44ddca1a94 for
CVE-2018-1000001 (Sourceware BZ #22679) the implementation in the
just released glibc 2.27 has been changed such that instead of
returning "(unreachable)" the implementation now returns ENOENT
as it would have if the current directory had been unlinked.
I see that in 2015 the quirk was documented in commit
a2ac97c78b, and this is no longer
true with glibc 2.27, but may continue to be true in other C libraries,
so I reference NOTES from the paragraph in the central text.
Signed-off-by: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I am trying to fix a FIXME in the pthread_create.3 manpage.
It says info about default thread stack size should be put in
pthread_attr_setstacksize.3.
And pthread_attr_setstacksize.3 says "For details on the default
stack size of new threads, see pthread_create(3)".
So I list the default values for several architectures, starting
from glibc 2.12 (and still valid on current git glibc).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The manpage claimed that tsearch() returns a pointer to a data
item. This is incorrect; tsearch() returns a pointer to the
corresponding tree node, which can also be interpreted as a
pointer to a pointer to the data item.
Since this API is quite unintuitive, also add a clarifying
sentence.
Signed-off-by: Jann Horn <jannh@google.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
The period after the function call is incorrectly marked with bold.
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As noted by Pradeep (and I tested also the code on OpenBSD):
The man page for fts library call states both the following:
short fts_pathlen; /* strlen(fts_path) */
fts_pathlen The length of the string referenced by fts_path
However, for the structures returned from fts_children() function,
fts_pathlen is strlen(fts_path) + strlen(fts_name), which contradicts
the man page statement. So I believe that there is either a bug in the
man page or the fts_children() library call.
The following program can be used for verification:
int main() {
struct passwd *pwd_entry = getpwuid(getuid());
char *paths[] = {pwd_entry->pw_dir, NULL};
FTS* fts = fts_open(paths, FTS_LOGICAL, NULL);
FTSENT* ftsent = fts_read(fts);
FTSENT* child = fts_children(fts, 0);
while (child != NULL) {
printf("\n %s %s %d %lu", child->fts_path, child->fts_name,
child->fts_pathlen, strlen(child->fts_path));
child = child->fts_link;
}
return 0;
}
Reported-by: Pradeep Kumar <pradeepsixer@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Compile warning with glibc 2.25:
warning: In the GNU C Library, "makedev" is defined by
<sys/sysmacros.h>. For historical compatibility, it is
currently defined by <sys/types.h> as well, but we plan to
remove this soon. To use "makedev", include <sys/sysmacros.h>
directly. If you did not intend to use a system-defined macro
"makedev", you should undefine it after including
<sys/types.h>.
Background: glibc commit dbab6577c6684c62bd2521c1c29dc25c3cac966f
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Recast the advice against manually declaring 'errno' to
a more modern perspective. It's 13 years since the original
text was added, and even then it was describing old behavior.
Cast the description to be about behavior further away in
time, and note more clearly that manual declaration will
cause problems with modern C libraries.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Added after a patch from Wesley Aptekar-Cassels that proposed
to add error numbers to the text.
Reported-by: Wesley Aptekar-Cassels <w.aptekar@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
POSIX.1-2008 noted the explicitly the change (to align with
the C standards) that error numbers are positive, rather
than nonzero.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Restructure the text and add some subheadings for better
readability. No (intentional) content changes.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Based on comparing the filtered content of the two main
kernel errno files:
cat include/uapi/asm-generic/errno.h \
include/uapi/asm-generic/errno-base.h | grep define | \
grep -v 'define _' | awk '{print $2}' | sort -u
to see what is absent from this page, and used in either kernel
or glibc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Document the glibc 2.24 change that dropped CWD from the default
search path employed by execlp(), execvp() and execvpe() when
PATH is not defined.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
I'm not sure what compiler is referred to by "pc(1)",
but "dnf whatprovides" and web searches turn up no
mention of a compiler by that name.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
People seem to be using "cf." ("confere"), which means "compare",
to mean "see" instead, for which the Latin abbreviation would be
"q.v." ("quod vide" -> "which see").
In some cases "cf." might actually be the correct term but it's
still not clear what specific aspects of a function/system call
one is supposed to be comparing.
I left one use in place in hope of obtaining clarification,
because it looks like it might be useful there, if contextualized.
Migrate these uses to English and add them to the list of
abbreviations to be avoided.
If the patch to vfork(2) is not accepted, then the cf. still needs
an \& after it because it is at the end of the line but not the
end of a sentence.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This function was in libc4 and libc5, but never part
of glibc. It ceased to be relevant nearly 20 years
ago. Time to remove the page.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Add a page descrbing pthread_spin_lock(3), pthread_spin_unlock(3),
and pthread_spin_trylock(3).
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
When referring to the architecture, consistently use "x86-64",
not "x86_64". Hitherto, there was a mixture of usages, with
"x86-64" predominant.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Remove reference to non-standard "tlpi_hdr.h" and replace calls to
functions that were declared in this header.
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Currently, the backtrace(3) manual page says this about backtrace_symbols_fd():
back‐
trace_symbols_fd() does not call malloc(3), and so can be
employed in situations where the latter function might fail.
However, I watched a video of a presentation about signal handling and
the speaker was saying that calling backtrace() can trigger a call to
malloc - indirectly. That happens because the backtrace*() functions
are part of libgcc, which gets dynamically loaded whenever needed;
dynamic loading would, in turn, trigger a malloc. The talk can be
found here: http://free-electrons.com/pub/video/2008/ols/ols2008-gilad-ben-yossef-fault-handlers.ogg
I decided to test it out, and it seems that this is still true (at
least on Ubuntu 12.04). I compiled the attached program (I used
CXXFLAGS = '-Wall -g -std=c++0x', the -std= part is not really needed)
and ran it through gdb, putting a breakpoint on the line where
backtrace is called. When that breakpoint is hit, I set a breakpoint
on malloc, continued and voila:
Breakpoint 2, __GI___libc_malloc (bytes=36) at malloc.c:2910
2910 malloc.c: No such file or directory.
(gdb) bt
"/lib/x86_64-linux-gnu/libgcc_s.so.1") at dl-load.c:162
"libgcc_s.so.1", type=2, trace_mode=0, mode=-1879048191,
nsid=<optimized out>) at dl-load.c:2473
errstring=0x7fffffffdd00, mallocedp=0x7fffffffdd0f,
operate=0x7ffff7ded700 <dl_open_worker>, args=0x7fffffffdcb0) at
dl-error.c:178
"libgcc_s.so.1", mode=-2147483647, caller_dlopen=0x7ffff7b260a9,
nsid=-2, argc=1, argv=<optimized out>, env=0x7fffffffe068) at
dl-open.c:639
errstring=0x7fffffffded0, mallocedp=0x7fffffffdeef,
operate=0x7ffff7b4bc20 <do_dlopen>, args=0x7fffffffdeb0) at
dl-error.c:178
operate=0x7ffff7b4bc20 <do_dlopen>) at dl-libc.c:48
out>) at dl-libc.c:165
../sysdeps/x86_64/../ia64/backtrace.c:104
Reviewed-by: Walter Harms <wharms@bfs.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
As reported by Rahul, the existing sentence could be read as
meaning that resources of joined and terminated detached
threads are freed at only at process termination. Eliminate
that possible misreading.
Reported-by: Rahul Bedarkar <rpal143@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Starting with Linux kernel 4.5 and 84638335900f1995
(mm: rework virtual memory accounting) RLIMIT_DATA affects
mmap(2). With d977d56ce5b3e88 (mm: warn about VmData over
RLIMIT_DATA) only warnings are emmitted when going over the
specified RLIMIT_DATA in 4.5.
As of 4.7 and f4fcd55841fc9 (mm: enable RLIMIT_DATA by default
with workaround for valgrind) going over RLIMIT_DATA through
mmap(2) is forbidden.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Jakub Wilk