| Age | Commit message (Collapse) | Author | Files | Lines | |
|---|---|---|---|---|---|
| 2024-05-02 | man/, share/mk/: Move man*/ to man/ | Alejandro Colomar | 1 | -1067/+0 | |
| This is a scripted change: $ mkdir man/; $ mv man* man/; $ ln -st . man/man*; $ find share/mk/ -type f \ | xargs grep -l '^MANDIR *:=' \ | xargs sed -i '/^MANDIR *:=/s,$,/man,'; $ find share/mk/dist/ -type f \ | xargs grep -l man \ | xargs sed -i 's,man%,man/%,g'; Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/> Cc: Petr Vorel <pvorel@suse.cz> Cc: Jakub Wilk <jwilk@jwilk.net> Cc: Stefan Puiu <stefan.puiu@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2024-04-29 | mount_setattr.2: Update supported file-systems | Rodrigo Campos | 1 | -0/+12 | |
| Let's update the list with the latest file-systems that added support. You can easily verify this by "git grep FS_ALLOW_IDMAP" on the given Linux version to see that the fs is listed and then checkout the previous Linux version to see that it is not listed, therefore it was added in that version. $ diff -w -U0 \ <(git grep FS_ALLOW_IDMAP v6.8 | sed 's/^v6.8://') \ <(git grep FS_ALLOW_IDMAP v6.9-rc4 | sed 's/^v6.9-rc4://') \ | tail -n+4; +fs/hugetlbfs/inode.c: .fs_flags = FS_ALLOW_IDMAP, $ diff -w -U0 \ <(git grep FS_ALLOW_IDMAP v6.6 | sed 's/^v6.6://') \ <(git grep FS_ALLOW_IDMAP v6.7 | sed 's/^v6.7://') \ | tail -n+4; +fs/ceph/super.c: .fs_flags = FS_RENAME_DOES_D_MOVE | FS_ALLOW_IDMAP, $ diff -w -U0 \ <(git grep FS_ALLOW_IDMAP v6.2 | sed 's/^v6.2://') \ <(git grep FS_ALLOW_IDMAP v6.3 | sed 's/^v6.3://') \ | tail -n+4; +mm/shmem.c: .fs_flags = FS_USERNS_MOUNT | FS_ALLOW_IDMAP, $ diff -w -U0 \ <(git grep FS_ALLOW_IDMAP v6.1 | sed 's/^v6.1://') \ <(git grep FS_ALLOW_IDMAP v6.2 | sed 's/^v6.2://') \ | tail -n+4; +fs/squashfs/super.c: .fs_flags = FS_REQUIRES_DEV | FS_ALLOW_IDMAP, Signed-off-by: Rodrigo Campos <rodrigo@sdfg.com.ar> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-10-31 | man*/: srcfix (Use .P instead of .PP or .LP) | Alejandro Colomar | 1 | -30/+30 | |
| We're trying to "standardize" on a paragraphing macro from the three equivalent ones (P, PP, LP). We (somewhat arbitrarily) agreed on P. Scripted change: $ find man* -type f | xargs sed -i '/\.PP/s/PP/P/' $ find man* -type f | xargs sed -i '/\.LP/s/LP/P/' Suggested-by: "G. Branden Robinson" <branden@debian.org> Cc: Ingo Schwarze <schwarze@openbsd.org> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-05-03 | man*/, man.ignore.grep: srcfix; warn about blank lines | Alejandro Colomar | 1 | -22/+20 | |
| - Use the dummy character to avoid warnings in examples. - Re-enable the warning. Suggested-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-04-23 | man*/: wfix | Günther Noack | 1 | -1/+1 | |
| Fix spelling of "run time", as documented in man-pages(7): - "run time" in two words when used as a noun - "run-time" with hyphen when used as an adjective There is another occurrence in bpf-helpers.7, but that content gets generated from the kernel source and should be fixed there. Signed-off-by: Günther Noack <gnoack3000@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-04-01 | mount_setattr.2: ffix | Patrick Reader | 1 | -3/+3 | |
| Signed-off-by: Patrick Reader <_@pxeger.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-03-30 | man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY: Reorganize sections | Alejandro Colomar | 1 | -6/+4 | |
| - Add a new HISTORY section that covers the history of an API, both regarding implementations and regarding old standards. This was previously covered in VERSIONS, and in some cases in STANDARDS. - Repurpose VERSIONS to cover differing implementations in _current_ systems. - STANDARDS is reduced to only cover current versions of standards. That basically means only C11 (C99 has been superseeded by C11; C17 is just a bugfix of C11, so not really a new version), and POSIX.1-2008 (*-2001 was superseeded by *-2008; *-2017 was just a bugfix for *-2008). The section also mentions for example 'Linux', 'GNU' or 'BSD' when a non-standard API is Linux- or GNU-only or if it's (de-facto) standard in the BSDs. - In some cases content that should go into one of these sections was in NOTES. Move it from there to where it corresponds. - In the SYNOPSIS, I added [[deprecated]] in some functions that I found are deprecated by the relevant standards. - A few other related changes... Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-03-08 | man*/: srcfix (IP) | Alejandro Colomar | 1 | -3/+2 | |
| Two consecutive IPs without text don't make sense, since they are paragraph separators. The reason we needed it was that PD 0 was misplaced. This extra IP was also causing another problem: we needed to specify again the indentation of the outer list. Reported-by: mandoc(1) (make lint-man-mandoc) Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-02-10 | man2/: srcfix (hyphens used as C operators) | G. Branden Robinson | 1 | -4/+4 | |
| Escape hyphens used as parts of C `->` operators. Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-02-05 | Many pages: Use \[bu] instead of \(bu | Alejandro Colomar | 1 | -28/+28 | |
| Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-02-05 | Many pages: Use \[em] instead of \(em | Alejandro Colomar | 1 | -1/+1 | |
| Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-02-05 | Many pages: Use \[aq] instead of \(aq | Alejandro Colomar | 1 | -18/+18 | |
| This improves readability in the source code, since it delimits where the escape sequence ends. Cc: наб <nabijaczleweli@nabijaczleweli.xyz> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Brian Inglis <Brian.Inglis@Shaw.ca> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2023-01-26 | Various pages: EXAMPLES: Fix -Wdeclaration-after-statement errors | Alejandro Colomar | 1 | -5/+8 | |
| Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2022-10-30 | Many pages: Use correct letter case in page titles (TH) | Alejandro Colomar | 1 | -1/+1 | |
| Scripted change: $ find man* -type f \ | xargs grep -L '\.so' \ | while read f; do P=$(basename $f); T=$(grep '\.TH ' $f | cut -f2,3 -d' ' | sed 's/ /./'); p=$(echo $P | tr '[:upper:]' '[:lower:]'); t=$(echo $T | tr '[:upper:]' '[:lower:]'); Tn=$(echo $T | sed 's/\.[^.]\+$//') Pn=$(echo $P | sed 's/\.[^.]\+$//') N=$(man_section $f NAME \ | sed -n '/NAME/,/ - /p' \ | sed 's/ - .*//' \ | grep -v '^NAME$' \ | tr ', ' '\n' \ | grep -i "^$Pn$" \ | head -n1) test $P = $T \ && test -n $N \ && continue; if test "x$p" != "x$t"; then echo 1 $P $T $N; elif test -z "$N"; then echo 2 $P $T $N; else sed -i "/\.TH /s/$Tn/$N/" $f; fi; done; On 10/30/22 23:00, G. Branden Robinson wrote: > For those to whom this change is coming as an unpleasant surprise, the > forthcoming groff 1.23.0 features an option that will reverse this > change at rendering time. > > From groff_man(7): > > -rCT=1 Capitalize titles, setting the man page title (the first > argument to .TH) in full capitals in headers and footers. > This transformation is off by default because it discards > case distinction information. > > This register can also be set in a site-local "man.local" file to force > it on for all pages. On Debian-based systems, this file is in > /etc/groff. The following line will do the trick. > > .nr CT 1 > > The groff_man_style(7) man page offers further examples of such > rendering customization. > > /usr/local/share/groff/site-tmac/man.local > Put site‐local changes and customizations into this file. > > .\" Use narrower indentation on terminals and similar. > .if n .nr IN 4n > .\" Put only one space after the end of a sentence. > .ss 12 0 \" See groff(7). > .\" Keep pages narrow even on wide terminals. > .if n .if \n[LL]>78n .nr LL 78n > .\" Ensure hyperlinks are enabled for terminals. > .nr U 1 > > On multi‐user systems, it is more considerate to users whose > preferences may differ from the administrator’s to be less > aggressive with such settings, or to permit their override > with a user‐specific man.local file. This can be achieved by > placing one or both of following requests at the end of the > site‐local file. > .soquiet \V[XDG_CONFIG_HOME]/man.local > .soquiet \V[HOME]/.man.local > However, a security‐sandboxed man(1) program may lack > permission to open such files. Cc: Ingo Schwarze <schwarze@openbsd.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2022-10-29 | Many pages: Use a consistent style for lists | Alejandro Colomar | 1 | -2/+2 | |
| There are different kinds of lists: Tagged paragraphs These are fixed in a separate commit (the previous one). They are used for a list of tags and their descriptions. An example is this commit message itself. Ordered lists Elements are preceeded by a number in parentheses. These represent a set of steps that have an order. When there are substeps, they will be numbered like (4.2). Positional lists Elements are preceeded by a number in square brackets (index). These represent fields in a set. The index will start at: 0 fields of a C data structure, to be consistent with arrays. 1 fields of a file, to be consistent with tools like cut(1). Alternatives list Elements are preceeded by a letter in parentheses. These represent a set of (normally) exclusive alternatives. Bullet lists Elements are preceeded by bullet symbols. Anything that doesn't fit elsewhere usually is covered by this type of list. Notes Not really a list, but the syntax is identical to "positional lists". There should always be 2 spaces between the list symbol and the elements. This doesn't apply to "tagged paragraphs", which use the default indentation rules. Reported-by: Mike Frysinger <vapier@gentoo.org> Cc: <groff@gnu.org> Acked-by: Douglas McIlroy <douglas.mcilroy@dartmouth.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2022-10-09 | dist.mk, All pages: .TH: Generate date at 'make dist' | Alejandro Colomar | 1 | -1/+1 | |
| Replace the date by a placeholder (date) in the repo, as we're doing with the version (unreleased). It will be filled when the tarball is generated with 'make dist' (or equivalent) with the date of the most recent git commit that modifies the page (as was done previously by update_timestamps.sh, which has been removed). Scripted change (mostly): $ find man* -type f \ | xargs sed -Ei '/^\.TH /s/.TH +([^ ]+ +[^ ]+) +[^ ]+ +(.*)/.TH \1 (date) \2/' Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2022-10-09 | getent.1, iconv.1, intro.1, ldd.1, locale.1, localedef.1, memusage.1, ↵ | Alejandro Colomar | 1 | -1/+1 | |
| memusagestat.1, mtrace.1, pldd.1, sprof.1, time.1, _exit.2, _syscall.2, accept.2, access.2, acct.2, add_key.2, adjtimex.2, alarm.2, alloc_hugepages.2, arch_prctl.2, bdflush.2, bind.2, bpf.2, brk.2, cacheflush.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, clock_getres.2, clock_nanosleep.2, clone.2, close.2, close_range.2, connect.2, copy_file_range.2, create_module.2, delete_module.2, dup.2, epoll_create.2, epoll_ctl.2, epoll_wait.2, eventfd.2, execve.2, execveat.2, exit_group.2, fallocate.2, fanotify_init.2, fanotify_mark.2, fcntl.2, flock.2, fork.2, fsync.2, futex.2, futimesat.2, get_kernel_syms.2, get_mempolicy.2, get_robust_list.2, getcpu.2, getdents.2, getdomainname.2, getgid.2, getgroups.2, gethostname.2, getitimer.2, getpagesize.2, getpeername.2, getpid.2, getpriority.2, getrandom.2, getresuid.2, getrlimit.2, getrusage.2, getsid.2, getsockname.2, getsockopt.2, gettid.2, gettimeofday.2, getuid.2, getunwind.2, getxattr.2, idle.2, init_module.2, inotify_add_watch.2, inotify_init.2, inotify_rm_watch.2, intro.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, ioctl.2, ioctl_console.2, ioctl_fat.2, ioctl_ficlonerange.2, ioctl_fideduperange.2, ioctl_fslabel.2, ioctl_getfsmap.2, ioctl_iflags.2, ioctl_ns.2, ioctl_tty.2, ioctl_userfaultfd.2, ioperm.2, iopl.2, ioprio_set.2, ipc.2, kcmp.2, kexec_load.2, keyctl.2, kill.2, landlock_add_rule.2, landlock_create_ruleset.2, landlock_restrict_self.2, link.2, listen.2, listxattr.2, llseek.2, lookup_dcookie.2, lseek.2, madvise.2, mbind.2, membarrier.2, memfd_create.2, memfd_secret.2, migrate_pages.2, mincore.2, mkdir.2, mknod.2, mlock.2, mmap.2, mmap2.2, modify_ldt.2, mount.2, mount_setattr.2, move_pages.2, mprotect.2, mq_getsetattr.2, mremap.2, msgctl.2, msgget.2, msgop.2, msync.2, nanosleep.2, nfsservctl.2, nice.2, open.2, open_by_handle_at.2, openat2.2, outb.2, pause.2, pciconfig_read.2, perf_event_open.2, perfmonctl.2, personality.2, pidfd_getfd.2, pidfd_open.2, pidfd_send_signal.2, pipe.2, pivot_root.2, pkey_alloc.2, poll.2, posix_fadvise.2, prctl.2, pread.2, process_madvise.2, process_vm_readv.2, ptrace.2, query_module.2, quotactl.2, read.2, readahead.2, readdir.2, readlink.2, readv.2, reboot.2, recv.2, recvmmsg.2, remap_file_pages.2, removexattr.2, rename.2, request_key.2, restart_syscall.2, rmdir.2, rt_sigqueueinfo.2, s390_guarded_storage.2, s390_pci_mmio_write.2, s390_runtime_instr.2, s390_sthyi.2, sched_get_priority_max.2, sched_rr_get_interval.2, sched_setaffinity.2, sched_setattr.2, sched_setparam.2, sched_setscheduler.2, sched_yield.2, seccomp.2, seccomp_unotify.2, select.2, select_tut.2, semctl.2, semget.2, semop.2, send.2, sendfile.2, sendmmsg.2, set_mempolicy.2, set_thread_area.2, set_tid_address.2, seteuid.2, setfsgid.2, setfsuid.2, setgid.2, setns.2, setpgid.2, setresuid.2, setreuid.2, setsid.2, setuid.2, setup.2, setxattr.2, sgetmask.2, shmctl.2, shmget.2, shmop.2, shutdown.2, sigaction.2, sigaltstack.2, signal.2, signalfd.2, sigpending.2, sigprocmask.2, sigreturn.2, sigsuspend.2, sigwaitinfo.2, socket.2, socketcall.2, socketpair.2, splice.2, spu_create.2, spu_run.2, stat.2, statfs.2, statx.2, stime.2, subpage_prot.2, swapon.2, symlink.2, sync.2, sync_file_range.2, syscall.2, syscalls.2, sysctl.2, sysfs.2, sysinfo.2, syslog.2, tee.2, time.2, timer_create.2, timer_delete.2, timer_getoverrun.2, timer_settime.2, timerfd_create.2, times.2, tkill.2, truncate.2, umask.2, umount.2, uname.2, unimplemented.2, unlink.2, unshare.2, uselib.2, userfaultfd.2, ustat.2, utime.2, utimensat.2, vfork.2, vhangup.2, vm86.2, vmsplice.2, wait.2, wait4.2, write.2, open_how.2type, CPU_SET.3, FILE.3, INFINITY.3, MAX.3, MB_CUR_MAX.3, MB_LEN_MAX.3, _Generic.3, __ppc_get_timebase.3, __ppc_set_ppr_med.3, __ppc_yield.3, __setfpucw.3, a64l.3, abort.3, abs.3, acos.3, acosh.3, addseverity.3, adjtime.3, aio_cancel.3, aio_error.3, aio_fsync.3, aio_init.3, aio_read.3, aio_return.3, aio_suspend.3, aio_write.3, alloca.3, argz_add.3, asin.3, asinh.3, asprintf.3, assert.3, assert_perror.3, atan.3, atan2.3, atanh.3, atexit.3, atof.3, atoi.3, backtrace.3, basename.3, bcmp.3, bcopy.3, bindresvport.3, bsd_signal.3, bsearch.3, bstring.3, bswap.3, btowc.3, btree.3, byteorder.3, bzero.3, cabs.3, cacos.3, cacosh.3, canonicalize_file_name.3, carg.3, casin.3, casinh.3, catan.3, catanh.3, catgets.3, catopen.3, cbrt.3, ccos.3, ccosh.3, ceil.3, cexp.3, cexp2.3, cfree.3, cimag.3, circleq.3, clearenv.3, clock.3, clock_getcpuclockid.3, clog.3, clog10.3, clog2.3, closedir.3, cmsg.3, confstr.3, conj.3, copysign.3, cos.3, cosh.3, cpow.3, cproj.3, creal.3, crypt.3, csin.3, csinh.3, csqrt.3, ctan.3, ctanh.3, ctermid.3, ctime.3, daemon.3, dbopen.3, des_crypt.3, difftime.3, dirfd.3, div.3, dl_iterate_phdr.3, dladdr.3, dlerror.3, dlinfo.3, dlopen.3, dlsym.3, drand48.3, drand48_r.3, duplocale.3, dysize.3, ecvt.3, ecvt_r.3, encrypt.3, end.3, endian.3, envz_add.3, erf.3, erfc.3, err.3, errno.3, error.3, ether_aton.3, euidaccess.3, exec.3, exit.3, exp.3, exp10.3, exp2.3, expm1.3, fabs.3, fclose.3, fcloseall.3, fdim.3, fenv.3, ferror.3, fexecve.3, fflush.3, ffs.3, fgetc.3, fgetgrent.3, fgetpwent.3, fgetwc.3, fgetws.3, fileno.3, finite.3, flockfile.3, floor.3, fma.3, fmax.3, fmemopen.3, fmin.3, fmod.3, fmtmsg.3, fnmatch.3, fopen.3, fopencookie.3, fpathconf.3, fpclassify.3, fpurge.3, fputwc.3, fputws.3, fread.3, frexp.3, fseek.3, fseeko.3, ftime.3, ftok.3, fts.3, ftw.3, futimes.3, fwide.3, gamma.3, gcvt.3, get_nprocs_conf.3, get_phys_pages.3, getaddrinfo.3, getaddrinfo_a.3, getauxval.3, getcontext.3, getcwd.3, getdate.3, getdirentries.3, getdtablesize.3, getentropy.3, getenv.3, getfsent.3, getgrent.3, getgrent_r.3, getgrnam.3, getgrouplist.3, gethostbyname.3, gethostid.3, getifaddrs.3, getipnodebyname.3, getline.3, getloadavg.3, getlogin.3, getmntent.3, getnameinfo.3, getnetent.3, getnetent_r.3, getopt.3, getpass.3, getprotoent.3, getprotoent_r.3, getpt.3, getpw.3, getpwent.3, getpwent_r.3, getpwnam.3, getrpcent.3, getrpcent_r.3, getrpcport.3, gets.3, getservent.3, getservent_r.3, getspnam.3, getsubopt.3, getttyent.3, getusershell.3, getutent.3, getutmp.3, getw.3, getwchar.3, glob.3, gnu_get_libc_version.3, grantpt.3, group_member.3, gsignal.3, hash.3, hsearch.3, hypot.3, iconv.3, iconv_close.3, iconv_open.3, if_nameindex.3, if_nametoindex.3, ilogb.3, index.3, inet.3, inet_net_pton.3, inet_ntop.3, inet_pton.3, initgroups.3, insque.3, intro.3, isalpha.3, isatty.3, isfdtype.3, isgreater.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, j0.3, key_setsecret.3, killpg.3, ldexp.3, lgamma.3, lio_listio.3, list.3, localeconv.3, lockf.3, log.3, log10.3, log1p.3, log2.3, logb.3, login.3, lrint.3, lround.3, lsearch.3, lseek64.3, makecontext.3, makedev.3, mallinfo.3, malloc.3, malloc_get_state.3, malloc_hook.3, malloc_info.3, malloc_stats.3, malloc_trim.3, malloc_usable_size.3, mallopt.3, matherr.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mcheck.3, memccpy.3, memchr.3, memcmp.3, memcpy.3, memfrob.3, memmem.3, memmove.3, mempcpy.3, memset.3, mkdtemp.3, mkfifo.3, mkstemp.3, mktemp.3, modf.3, mpool.3, mq_close.3, mq_getattr.3, mq_notify.3, mq_open.3, mq_receive.3, mq_send.3, mq_unlink.3, mtrace.3, nan.3, netlink.3, newlocale.3, nextafter.3, nextup.3, nl_langinfo.3, ntp_gettime.3, offsetof.3, on_exit.3, open_memstream.3, opendir.3, openpty.3, perror.3, popen.3, posix_fallocate.3, posix_madvise.3, posix_memalign.3, posix_openpt.3, posix_spawn.3, pow.3, pow10.3, printf.3, profil.3, program_invocation_name.3, psignal.3, pthread_atfork.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setsigmask_np.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_cleanup_push_defer_np.3, pthread_create.3, pthread_detach.3, pthread_equal.3, pthread_exit.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_join.3, pthread_kill.3, pthread_kill_other_threads_np.3, pthread_mutex_consistent.3, pthread_mutexattr_getpshared.3, pthread_mutexattr_init.3, pthread_mutexattr_setrobust.3, pthread_rwlockattr_setkind_np.3, pthread_self.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_setschedprio.3, pthread_sigmask.3, pthread_sigqueue.3, pthread_spin_init.3, pthread_spin_lock.3, pthread_testcancel.3, pthread_tryjoin_np.3, pthread_yield.3, ptsname.3, putenv.3, putgrent.3, putpwent.3, puts.3, putwchar.3, qecvt.3, qsort.3, raise.3, rand.3, random.3, random_r.3, rcmd.3, re_comp.3, readdir.3, readdir_r.3, realpath.3, recno.3, regex.3, remainder.3, remove.3, remquo.3, resolver.3, rewinddir.3, rexec.3, rint.3, round.3, rpc.3, rpmatch.3, rtime.3, rtnetlink.3, scalb.3, scalbln.3, scandir.3, scanf.3, sched_getcpu.3, seekdir.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, setaliasent.3, setbuf.3, setenv.3, setjmp.3, setlocale.3, setlogmask.3, setnetgrent.3, shm_open.3, siginterrupt.3, signbit.3, significand.3, sigpause.3, sigqueue.3, sigset.3, sigsetops.3, sigvec.3, sigwait.3, sin.3, sincos.3, sinh.3, sleep.3, slist.3, sockatmark.3, sqrt.3, stailq.3, statvfs.3, stdarg.3, stdin.3, stdio.3, stdio_ext.3, stpcpy.3, stpncpy.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strdup.3, strerror.3, strfmon.3, strfromd.3, strfry.3, strftime.3, string.3, strlen.3, strnlen.3, strpbrk.3, strptime.3, strsep.3, strsignal.3, strspn.3, strstr.3, strtod.3, strtoimax.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, strxfrm.3, swab.3, sysconf.3, syslog.3, system.3, sysv_signal.3, tailq.3, tan.3, tanh.3, tcgetpgrp.3, tcgetsid.3, telldir.3, tempnam.3, termios.3, tgamma.3, timegm.3, timeradd.3, tmpfile.3, tmpnam.3, toascii.3, toupper.3, towctrans.3, towlower.3, towupper.3, trunc.3, tsearch.3, ttyname.3, ttyslot.3, tzset.3, ualarm.3, ulimit.3, undocumented.3, ungetwc.3, unlocked_stdio.3, unlockpt.3, updwtmp.3, uselocale.3, usleep.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstoimax.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wordexp.3, wprintf.3, xcrypt.3, xdr.3, y0.3, NULL.3const, sysexits.h.3head, aiocb.3type, blkcnt_t.3type, blksize_t.3type, cc_t.3type, clock_t.3type, clockid_t.3type, dev_t.3type, div_t.3type, double_t.3type, epoll_event.3type, fenv_t.3type, id_t.3type, intN_t.3type, intmax_t.3type, intptr_t.3type, iovec.3type, itimerspec.3type, lconv.3type, mode_t.3type, off_t.3type, ptrdiff_t.3type, regex_t.3type, size_t.3type, sockaddr.3type, stat.3type, time_t.3type, timer_t.3type, timespec.3type, timeval.3type, tm.3type, va_list.3type, void.3type, cciss.4, console_codes.4, cpuid.4, dsp56k.4, fd.4, full.4, fuse.4, hd.4, hpsa.4, initrd.4, intro.4, lirc.4, loop.4, lp.4, mem.4, mouse.4, msr.4, null.4, pts.4, ram.4, random.4, rtc.4, sd.4, sk98lin.4, smartpqi.4, st.4, tty.4, ttyS.4, vcs.4, veth.4, wavelan.4, acct.5, charmap.5, core.5, dir_colors.5, elf.5, filesystems.5, ftpusers.5, gai.conf.5, group.5, host.conf.5, hosts.5, hosts.equiv.5, intro.5, issue.5, locale.5, motd.5, networks.5, nologin.5, nscd.conf.5, nss.5, nsswitch.conf.5, passwd.5, proc.5, protocols.5, repertoiremap.5, resolv.conf.5, rpc.5, securetty.5, services.5, shells.5, slabinfo.5, sysfs.5, termcap.5, tmpfs.5, ttytype.5, tzfile.5, utmp.5, intro.6, address_families.7, aio.7, armscii-8.7, arp.7, ascii.7, attributes.7, boot.7, bootparam.7, bpf-helpers.7, capabilities.7, cgroup_namespaces.7, cgroups.7, charsets.7, complex.7, cp1251.7, cp1252.7, cpuset.7, credentials.7, ddp.7, environ.7, epoll.7, fanotify.7, feature_test_macros.7, fifo.7, futex.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, intro.7, ip.7, ipc_namespaces.7, ipv6.7, iso_8859-1.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-15.7, iso_8859-16.7, iso_8859-2.7, iso_8859-3.7, iso_8859-4.7, iso_8859-5.7, iso_8859-6.7, iso_8859-7.7, iso_8859-8.7, iso_8859-9.7, kernel_lockdown.7, keyrings.7, koi8-r.7, koi8-u.7, landlock.7, libc.7, locale.7, mailaddr.7, man-pages.7, man.7, math_error.7, mount_namespaces.7, mq_overview.7, namespaces.7, netdevice.7, netlink.7, network_namespaces.7, nptl.7, numa.7, operator.7, packet.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, posixoptions.7, process-keyring.7, pthreads.7, pty.7, queue.7, random.7, raw.7, regex.7, rtld-audit.7, rtnetlink.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, sigevent.7, signal-safety.7, signal.7, sock_diag.7, socket.7, spufs.7, standards.7, suffixes.7, symlink.7, system_data_types.7, sysvipc.7, tcp.7, termio.7, thread-keyring.7, time.7, time_namespaces.7, udp.7, udplite.7, unicode.7, units.7, unix.7, uri.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, uts_namespaces.7, vdso.7, vsock.7, x25.7, xattr.7, iconvconfig.8, intro.8, ld.so.8, ldconfig.8, nscd.8, sln.8, tzselect.8: tstamp Signed-off-by: Alejandro Colomar <alx@kernel.org> | |||||
| 2022-09-17 | Various pages: EXAMPLES: Align variable declarations | Alex Colomar | 1 | -5/+5 | |
| Also, move some declarations to the top of functions. Signed-off-by: Alex Colomar <alx.manpages@gmail.com> | |||||
| 2022-09-13 | mount_setattr.2: EXAMPLES: Remove unused include | Alex Colomar | 1 | -1/+0 | |
| Reported-by: iwyu(1) Signed-off-by: Alex Colomar <alx.manpages@gmail.com> | |||||
| 2022-09-13 | Various pages: EXAMPLES: Use <err.h> functions | Alex Colomar | 1 | -12/+7 | |
| When reporting errors, prefer using conventional <err.h> functions, rather than home-made macros. Home-made macros are necessary for portable programs, so in documentation about portable functions, keep using the macros. However, in the documentation for functions that are only available in GNU/Linux and/or BSD systems, prefer <err.h>, which is available in both systems. Do the same in example programs documenting portable functions but in which we already require _GNU_SOURCE for some other reason. Signed-off-by: Alex Colomar <alx.manpages@gmail.com> | |||||
| 2022-09-09 | Revert "src.mk, All pages: Move man* to man/" | Alejandro Colomar | 1 | -0/+1063 | |
| This reverts commit 70ac1c4785fc1e158ab2349a962dba2526bf4fbc. Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/> Reported-by: Petr Vorel <pvorel@suse.cz> Reported-by: Jakub Wilk <jwilk@jwilk.net> Cc: Stefan Puiu <stefan.puiu@gmail.com> Signed-off-by: Alex Colomar <alx.manpages@gmail.com> | |||||
| 2022-09-05 | src.mk, All pages: Move man* to man/ | Alejandro Colomar | 1 | -1063/+0 | |
| The root of the repository is becoming a bit overpopulated and unorganized, due to the recent addition of more mandirs, and more informative and configuration files too. Let's create a specific mandir <man/> that contains the mandirs <man[1-8]*>. Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-08-25 | Revert "Many pages: Document fixed-width types with ISO C naming" | Alejandro Colomar | 1 | -4/+4 | |
| This reverts commit 2294974b3a1341e457edb682c08c5f4b2d14675e. Reported-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-08-24 | Many pages: Document fixed-width types with ISO C namingman-pages-6.0-rc1 | Alejandro Colomar | 1 | -4/+4 | |
| Kernel __u64 and similar types are ABI-compatible, and mostly API-compatible with ISO C types. User-space programmers don't care about kernel details, and should only use libc types. Document syscalls and structures provided by the Linux kernel as if they used libc types. There's work in the kernel to remove this small API incompatibility, which is only for pointers or printf specifiers. Since I couldn't find any structure that uses pointers, there shouldn't be any issues here. Also, the only pointer I found was in a syscall parameter, but since syscall(2) doesn't check its arguments' types, we're also safe there. This patch doesn't go without controversy. Check the discussions in the links below. Found with: $ grep -rn '\b_*[su][8136][624]*\b' man* \ | grep -v -e /bpf-helpers.7 -e /proc.5 -e /epoll_event.3type -e /wcscmp.3 \ -e /crypt.3 -e /mempcpy.3 -e /memcmp.3 -e /string.3 -e /wcsncmp.3 \ -e /wcscasecmp.3 -e /wmemcmp.3 -e /strcasecmp.3 -e /bcmp.3 \ -e /bstring.3 -e /endian.3 -e /strverscmp.3 -e /wcsncasecmp.3 \ -e /strcoll.3 -e /strcmp.3 \ | tee /dev/tty \ | wc -l; Link: <https://lore.kernel.org/linux-man/20210423230609.13519-1-alx.manpages@gmail.com/T/> Link: <https://lore.kernel.org/lkml/YZvIlz7J6vOEY+Xu@yuki/T/> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Nacked-by: Alexei Starovoitov <ast@kernel.org> Nacked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Nacked-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Zack Weinberg <zackw@panix.com> Cc: LKML <linux-kernel@vger.kernel.org> Cc: glibc <libc-alpha@sourceware.org> Cc: GCC <gcc-patches@gcc.gnu.org> Cc: bpf <bpf@vger.kernel.org> Cc: LTP List <ltp@lists.linux.it> Cc: Linux API <linux-api@vger.kernel.org> Cc: linux-arch <linux-arch@vger.kernel.org> Cc: David Laight <David.Laight@ACULAB.COM> Cc: Joseph Myers <joseph@codesourcery.com> Cc: Florian Weimer <fweimer@redhat.com> Cc: Daniel Borkmann <daniel@iogearbox.net> Cc: Cyril Hrubis <chrubis@suse.cz> Cc: David Howells <dhowells@redhat.com> Cc: Arnd Bergmann <arnd@arndb.de> Cc: Florian Weimer <fweimer@redhat.com> Cc: Rich Felker <dalias@libc.org> Cc: Adhemerval Zanella <adhemerval.zanella@linaro.org> | |||||
| 2022-08-21 | All pages: Remove the 5th argument to .TH | Alejandro Colomar | 1 | -1/+1 | |
| Now that we have the LIBRARY section, and a 4th argument that already tells that it's a page from the Linux man-pages project, the 5th argument isn't telling any information that the default value wouldn't. So let's just remove it. Scripted change: $ find man* -type f \ | xargs sed -Ei '/^.TH /s/(.TH +[^ ]+ +[^ ]+ +[^ ]+ +"[^"]+") .*/\1/' Acked-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Cc: Ingo Schwarze <schwarze@openbsd.de> Cc: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2022-08-21 | All pages: Replace the 4th argument to .TH by "Linux man-pages (unreleased)" | Alejandro Colomar | 1 | -1/+1 | |
| On 8/20/22 13:57, Alejandro Colomar wrote: > On 8/20/22 07:43, G. Branden Robinson wrote: >> >> In my opinion it would benefit readers of the Linux man-pages if the >> fourth argument to `TH` were what it is in many other man pages: an >> identifier for the name and version number of the release originating >> them. In every page it would be clear what version of the man-pages was >> being viewed. Little sophistication would be demanded of the user to >> check the Web to determine the relative age of the pages, independently >> of the modification date of the particular page. Such usage would be >> congruent with the argument's purpose in AT&T and BSD Unix, where this >> datum was "7th Edition", "System III", or "4.2 Berkeley Distribution", >> or similar. > > I thought about it in the past... That field was the only thing that > said where a function came from. If we removed GNU (or something else), > how would someone know where does the function or whatever comes from?? > > I guess that's also why the colophon was appended to the pages by > Michael. Since we couldn't use the 4th field for that, we had to have a > COLOPHON section. > > However, the addition of the LIBRARY section seems to fix this issue, > and so now we have an even more precise way to determine where a given > function comes from (including the library file name, and the linker > option). > > This gives me another argument for those who don't like to have a > LIBRARY section for libc stuff (since -lc is unnecessary), and consider > it noise. > >> >> Further, as the libc-related man pages in this project expand coverage >> to other libcs than GNU's, the alternatives to the empty string >> proferred in man-pages(7) seem less and less appropriate. > > Agree. LIBRARY seems much more appropriate for that purpose. > > And this helps remove the COLOPHON section (or at least, we don't need > to autogenerate it, since the version number now comes in .TH, and the > COLOPHON is static; so I can even move it to a smaller REPORTING BUGS > section). Scripted change: $ find man* -type f \ |xargs sed -Ei '/^.TH /s/(.TH +[^ ]+ +[^ ]+ +[^ ]+) +"[^"]*"/\1 "Linux man-pages (unreleased)"/' $ find man* -type f \ |xargs sed -Ei '/^.TH /s/(.TH +[^ ]+ +[^ ]+ +[^ ]+) +[^" ]+/\1 "Linux man-pages (unreleased)"/' $ git restore man5/tzfile.5 $ git restore man8/zdump.8 $ git restore man8/zic.8 $ git restore man7/bpf-helpers.7 Link: <https://lore.kernel.org/linux-man/20220819180323.dbsgxh5qvcjabjm6@jwilk.net/T/#u> Reported-by: Jakub Wilk <jwilk@jwilk.net> Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Cc: Ingo Schwarze <schwarze@openbsd.de> Cc: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2022-08-02 | fanotify_init.2, mount_setattr.2: ffix | Alejandro Colomar | 1 | -1/+0 | |
| mandoc: man2/fanotify_init.2:332:2: WARNING: skipping paragraph macro: PP empty mandoc: man2/mount_setattr.2:677:2: WARNING: skipping paragraph macro: PP empty Reported-by: 'make lint-man' Reported-by: mandoc(1) Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-08-01 | Various pages: EXAMPLES: tfix | Alejandro Colomar | 1 | -14/+14 | |
| Use escape sequences that produce the correct output, suitable for copy&paste into real C programs. Reported-by: 'make lint-c' Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-07-29 | Many pages: Use STANDARDS instead of CONFORMING TO | Alejandro Colomar | 1 | -1/+1 | |
| STANDARDS seems to be much more extended than CONFORMING TO. For consistency across the whole manual pages corpus, let's try to unify, by following the most commonly used section name. On 7/27/22 12:49, Ingo Schwarze wrote: > Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200: > > We use CONFORMING TO in Linux. Don't know why; just history, I guess. > > See man-pages(7). > > Weird. > > I failed to find a single instance of "CONFORMING TO" in AT&T UNIX > (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in > any version of UCB CSRG BSD. So considering that System V and BSD are > widely considered the two main original branches of the development > of Unix-like operating systems and Linux is often considered to have > drawn inspiration from both, the section name "CONFORMING TO" does > not appear to be a UNIX thing. For example, Aeleen Frisch, "Essential > System Administration", O'Reilly, Cambridge 1995, considers Linux > as slightly more influenced by 4.3BSD than by System V Release 3. > > STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990). > > 4.3BSD-Reno predates the first version of the Linux kernel by more than > a year, and the first Linux manual pages probably for longer than that. > > So i have no idea where "CONFORMING TO" may have come from. Scripted change: $ find man* -type f | xargs sed -i 's/CONFORMING TO/STANDARDS/' plus a few manual fixes to the following files: - man2/getrlimit.2 - man3/syslog.3 - scripts/bash_aliases Reported-by: Ingo Schwarze <schwarze@openbsd.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-06-08 | mount_setattr.2: Minor tweaks to Christian's patch set | Alejandro Colomar | 1 | -6/+6 | |
| Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-06-08 | mount_setattr.2: ffix | Christian Brauner | 1 | -1/+1 | |
| Fix a typo in my name. Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-06-08 | mount_setattr.2: update list of supported filesystems | Christian Brauner | 1 | -7/+36 | |
| Update list of filesystems that support ID-mapped mounts. Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-06-08 | mount_setattr.2: update conditions to create ID-mapped mounts | Christian Brauner | 1 | -4/+5 | |
| Newer kernels in principle support the creation of ID-mapped mounts for filesystems mountable in non-initial user namespaces. Currently, no such filesystem has been ported to support this though. But we should nonetheless update the conditions. Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-06-08 | mount_setattr.2: add and explain missing EBUSY error | Christian Brauner | 1 | -0/+10 | |
| In order to ID-map a mount it must not have any writers. If the mount has writers and the caller tries to ID-map the mount EBUSY will be returned. Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-04-30 | Many pages: EXAMPLES: Add wrapper comments SRC BEGIN and SRC END | Alejandro Colomar | 1 | -0/+2 | |
| Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-03-20 | Many pages: Fix style issues reported by `make lint-groff` | Alejandro Colomar | 1 | -1/+1 | |
| Plus some other found in the process. Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-03-06 | Many pages: LIBRARY: srcfix | Alejandro Colomar | 1 | -1/+1 | |
| Escape '-' in -l option to cc(1). Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-02-25 | mount_setattr.2: Add LIBRARY section | Alejandro Colomar | 1 | -0/+3 | |
| Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2022-02-25 | Various pages: [Linux-man-pages-copyleft] Use SPDX-License-Identifier | Alejandro Colomar | 1 | -21/+1 | |
| Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> | |||||
| 2021-08-27 | iconv.1, ldd.1, accept.2, access.2, add_key.2, arch_prctl.2, bpf.2, chmod.2, ↵ | Michael Kerrisk | 1 | -1/+1 | |
| chown.2, close_range.2, copy_file_range.2, execve.2, execveat.2, fanotify_mark.2, futex.2, futimesat.2, getpriority.2, intro.2, ioctl_tty.2, keyctl.2, link.2, membarrier.2, mkdir.2, mknod.2, mlock.2, mount.2, mount_setattr.2, open.2, open_by_handle_at.2, perf_event_open.2, pidfd_open.2, readlink.2, readv.2, rename.2, request_key.2, seccomp.2, sigaction.2, stat.2, statx.2, symlink.2, syscalls.2, umount.2, unlink.2, utimensat.2, wait.2, bsearch.3, fflush.3, getaddrinfo.3, getauxval.3, getopt.3, getsubopt.3, mkfifo.3, pthread_mutex_consistent.3, pthread_setname_np.3, pthread_tryjoin_np.3, scandir.3, sem_wait.3, stailq.3, strlen.3, strstr.3, termios.3, tsearch.3, wcslen.3, wcstok.3, wordexp.3, proc.5, capabilities.7, cgroups.7, fanotify.7, mount_namespaces.7, namespaces.7, path_resolution.7, pipe.7, posixoptions.7, user_namespaces.7, vdso.7, iconvconfig.8, ld.so.8: tstamp Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-18 | intro.2, mount_setattr.2, seccomp_unotify.2, fflush.3, ↵ | Michael Kerrisk | 1 | -2/+2 | |
| pthread_mutex_consistent.3: Place SEE ALSO entries in correct order Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-13 | mount_setattr.2: srcfix: add note explaining Christian's use of -ve dirfd values | Michael Kerrisk | 1 | -0/+12 | |
| From email with Christian Brauner: >>>>>> int fd_tree = open_tree(-EBADF, source, >>>>>> OPEN_TREE_CLONE | OPEN_TREE_CLOEXEC | >>>>>> AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0)); >>>>> >>>>> ??? >>>>> What is the significance of -EBADF here? As far as I can tell, it >>>>> is not meaningful to open_tree()? >>>> >>>> I always pass -EBADF for similar reasons to [2]. Feel free to just use -1. >>> >>> ???? >>> But here, both -EBADF and -1 seem to be wrong. This argument >>> is a dirfd, and so should either be a file descriptor or the >>> value AT_FDCWD, right? >> >> [1]: In this code "source" is expected to be absolute. If it's not >> absolute we should fail. This can be achieved by passing -1/-EBADF, >> afaict. > > D'oh! Okay. I hadn't considered that use case for an invalid dirfd. > (And now I've done some adjustments to openat(2),which contains a > rationale for the *at() functions.) > > So, now I understand your purpose, but still the code is obscure, > since > > * You use a magic value (-EBADF) rather than (say) -1. > * There's no explanation (comment about) of the fact that you want > to prevent relative pathnames. > > So, I've changed the code to use -1, not -EBADF, and I've added some > comments to explain that the intent is to prevent relative pathnames. > Okay? Sounds good. > > But, there is still the meta question: what's the problem with using > a relative pathname? Nothing per se. Ok, you asked so it's your fault: When writing programs I like to never use relative paths with AT_FDCWD because. Because making assumptions about the current working directory of the calling process is just too easy to get wrong; especially when pivot_root() or chroot() are in play. My absolut preference (joke intended) is to open a well-known starting point with an absolute path to get a dirfd and then scope all future operations beneath that dirfd. This already works with old-style openat() and _very_ cautious programming but openat2() and its resolve-flag space have made this **chef's kiss**. If I can't operate based on a well-known dirfd I use absolute paths with a -EBADF dirfd passed to *at() functions. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-13 | mount_setattr.2: ffix | Michael Kerrisk | 1 | -1/+2 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-12 | mount_setattr.2: Further tweaks after feedback from Christian Brauner | Michael Kerrisk | 1 | -9/+22 | |
| Reported-by: Christian Brauner <christian.brauner@ubuntu.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-12 | mount_setattr.2: Clarify the description of "detached" mounts | Michael Kerrisk | 1 | -2/+6 | |
| From email: >> Thanks. I made it "detached". Elsewhere, the page already explains >> that a detached mount is one that: >> >> must have been created by calling open_tree(2) with the >> OPEN_TREE_CLONE flag and it must not already have been >> visible in the filesystem. >> >> Which seems a fine explanation. >> >> ???? >> But, just a thought... "visible in the filesystem" seems not quite accurate. >> What you really mean I guess is that it must not already have been >> /visible in the filesystem hierarchy/previously mounted/something else/, >> right? I suppose that I should have clarified that my main problem was that you were using the word "filesystem" in a way that I find unconventional/ambiguous. I mean, I normally take the term "filesystem" to be "a storage system for folding files". Here, you are using "filesystem" to mean something else, what I might call like "the single directory hierarchy" or "the filesystem hierarchy" or "the list of mount points". > A detached mount is created via the OPEN_TREE_CLONE flag. It is a > separate new mount so "previously mounted" is not applicable. > A detached mount is _related_ to what the MS_BIND flag gives you with > mount(2). However, they differ conceptually and technically. A MS_BIND > mount(2) is always visible in the fileystem when mount(2) returns, i.e. > it is discoverable by regular path-lookup starting within the > filesystem. > > However, a detached mount can be seen as a split of MS_BIND into two > distinct steps: > 1. fd_tree = open_tree(OPEN_TREE_CLONE): create a new mount > 2. move_mount(fd_tree, <somewhere>): attach the mount to the filesystem > > 1. and 2. together give you the equivalent of MS_BIND. > In between 1. and 2. however the mount is detached. For the kernel > "detached" means that an anonymous mount namespace is attached to it > which doen't appear in proc and has a 0 sequence number (Technically, > there's a bit of semantical argument to be made that "attached" and > "detached" are ambiguous as they could also be taken to mean "does or > does not have a parent mount". This ambiguity e.g. appears in > do_move_mount(). That's why the kernel itself calls it an "anonymous > mount". However, an OPEN_TREE_CLONE-detached mount of course doesn't > have a parent mount so it works.). > > For userspace it's better to think of detached and attached in terms of > visibility in the filesystem or in a mount namespace. That's more > straightfoward, more relevant, and hits the target in 90% of the cases. > > However, the better and clearer picture is to say that a > OPEN_TREE_CLONE-detached mount is a mount that has never been > move_mount()ed. Which in turn can be defined as the detached mount has > never been made visible in a mount namespace. Once that has happened the > mount is irreversibly an attached mount. > > I keep thinking that maybe we should just say "anonymous mount" > everywhere. So changing the wording to: I'm not against the word "detached". To user space, I think it is a little more meaningful than "anonymous". For the moment, I'll stay with "detached", but if you insist on "anonymous", I'll probably change it. > [...] > EINVAL The mount that is to be ID mapped is not an anonymous mount; > that is, the mount has already been visible in a mount namespace. I like that text *a lot* better! Thanks very much for suggesting wordings. It makes my life much easier. I've made the text: EINVAL The mount that is to be ID mapped is not a detached mount; that is, the mount has not previously been visible in a mount namespace. > [...] > The mount must be an anonymous mount; that is, it must have been > created by calling open_tree(2) with the OPEN_TREE_CLONE flag and it > must not already have been visible in a mount namespace, i.e. it must > not have been attached to the filesystem hierarchy with syscalls such > as move_mount() syscall. And that too! I've made the text: • The mount must be a detached mount; that is, it must have been created by calling open_tree(2) with the OPEN_TREE_CLONE flag and it must not already have been visible in a mount namespace. (To put things another way: the mount must not have been attached to the filesystem hierarchy with a system call such as move_mount(2).) Reported-by: Christian Brauner <christian.brauner@ubuntu.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-12 | mount_setattr.2: EXAMPLES: use -1 rather than -EBADF | Michael Kerrisk | 1 | -2/+8 | |
| From email with Christian Braner: > [1]: In this code "source" is expected to be absolute. If it's not > absolute we should fail. This can be achieved by passing -1/-EBADF, > afaict. D'oh! Okay. I hadn't considered that use case for an invalid dirfd. (And now I've done some adjustments to openat(2),which contains a rationale for the *at() functions.) So, now I understand your purpose, but still the code is obscure, since * You use a magic value (-EBADF) rather than (say) -1. * There's no explanation (comment about) of the fact that you want to prevent relative pathnames. So, I've changed the code to use -1, not -EBADF, and I've added some comments to explain that the intent is to prevent relative pathnames. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-12 | fanotify_mark.2, futimesat.2, mount_setattr.2, statx.2, symlink.2, mkfifo.3: ↵ | Michael Kerrisk | 1 | -0/+5 | |
| Refer the reader to openat(2) for explanation of why 'dirfd' is useful Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-12 | access.2, chmod.2, chown.2, execveat.2, futimesat.2, link.2, mkdir.2, ↵ | Michael Kerrisk | 1 | -1/+5 | |
| mknod.2, mount_setattr.2, open.2, open_by_handle_at.2, readlink.2, rename.2, stat.2, statx.2, symlink.2, unlink.2, utimensat.2, mkfifo.3, scandir.3: Fix EBADF error description Make the description of the EBADF error for invalid 'dirfd' more uniform. In particular, note that the error only occurs when the pathname is relative, and that it occurs when the 'dirfd' is neither valid *nor* has the value AT_FDCWD. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-12 | mount_setattr.2: Rename 'path' to 'pathname' | Michael Kerrisk | 1 | -10/+10 | |
| For consistency with other pages Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-11 | mount_setattr.2: Minor fixes | Michael Kerrisk | 1 | -10/+9 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Changes after review feedback from Christian Brauner | Michael Kerrisk | 1 | -24/+35 | |
| Reviewed-by: Christian Brauner <christian.brauner@ubuntu.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Rework the discussion of MOUNT_ATTR__ATIME | Michael Kerrisk | 1 | -10/+14 | |
| Phrases such as "In the new mount API" will date fast. Remove it. Also: * Make it clear that MOUNT_ATTR__ATIME expresses a bit field. * Replace 'enum' with 'enumeration'. * Clarify what is meant by "partially" set MOUNT_ATTR__ATIME. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Remove description of propagation types | Michael Kerrisk | 1 | -20/+2 | |
| These types are already well described in mount_namespaces(7); indeed, much of the text from that page seems to have just been cut and pasted into this page! Simply referring the reader to mount_namespaces(7) is sufficient. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Reword the description of the 'propagation field' | Michael Kerrisk | 1 | -4/+3 | |
| Point out that this field can have the value zero, meaning no change. And avoid discussions of 'enum', and simply say that otherwise the field has one of the MS_* values. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: wfix | Michael Kerrisk | 1 | -1/+1 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Move the discussion of ID-mapped mounts to NOTES | Michael Kerrisk | 1 | -167/+164 | |
| Having this discussion under DESCRIPTION clutters that section, and has the effect of burying the discussion of propagation. Move the discussion to NOTES, to make the page more readable. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Add a reference to mount_namespaces(7) in discussion of ↵ | Michael Kerrisk | 1 | -0/+3 | |
| propagation types The mount_namespaces(7) page has some further relevant details. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Rename 'dfd' to 'dirfd' | Michael Kerrisk | 1 | -15/+15 | |
| 'dirfd' is the name consistently used in other pages. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Remove some unnecessary intermediate variables | Michael Kerrisk | 1 | -5/+3 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Minor clean-ups in example program | Michael Kerrisk | 1 | -34/+32 | |
| - Change some instances of "-" to "\" - Use C99 style (declare variables nearer use in code) - Add a bit of white space - Remove one 'const...const' added by Alex that caused compiler warnings - Use "reverse Christmas tree" form for declarations in main() - Other minor changes Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: SEE ALSO: place entries in correct order | Michael Kerrisk | 1 | -5/+5 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: SEE ALSO: remove unneeded entries | Michael Kerrisk | 1 | -4/+1 | |
| We don't really need ext4(5) and xfs(5) here. They provide no further info that is directly relevant to the reader of mount_setattr(2). clone3(2) isn't necessary because it is the same page as clone(2). Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Minor wording, grammar, and formatting fixes | Michael Kerrisk | 1 | -117/+117 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: wfix: "idmapped/idmapping" is not natural English | Michael Kerrisk | 1 | -30/+31 | |
| Let's use ID mapped, ID mapping, etc. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: srcfix | Michael Kerrisk | 1 | -2/+1 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Minor formatting fixes | Michael Kerrisk | 1 | -12/+12 | |
| Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: Minor tweaks to Christian's patch | Alejandro Colomar | 1 | -221/+225 | |
| - Fix SYNOPSIS to fit in 78 columns Also, we don't show when an include is included for a specific type, unless that header is included _only_ for the type, or there might be confusion (e.g., termios). Instead, that type should be documented in system_data_types(7), with a link page mount_attr-struct(3). - Fix references to mount_setattr(). See man-pages(7): Any reference to the subject of the current manual page should be writ‐ ten with the name in bold followed by a pair of parentheses in Roman (normal) font. For example, in the fcntl(2) man page, references to the subject of the page would be written as: fcntl(). The preferred way to write this in the source file is: .BR fcntl () - Fix line breaks according to semantic newline rules (and add some commas) - Fix wrong usage of .IR when .RI should have been used - Fix formatting of variable part in FOO<number>: - Make italic the variable part (as groff_man(7) recommends) - Remove <> - Use syntax recommended by G. Branden Robinson (groff) - Fix unnecessary uses of .BR or .IR when .B or .I would suffice - Fix formatting of punctuation In some cases, it was in italics or bold, and it should always be in roman. - Use uppercase to begin text, even in bullet points, since those were multi-sentence. - Simplify usage of .RS/.RE in combination with .IP - s/fat/FAT/ as fs(7) does - Slightly reword some sentences for consistency - Use Linux-specific for consistency with other pages (in VERSIONS) - EXAMPLES: Place the return type in a line of its own (as in other pages) - Fix alignment of code - Replace unnecessary use of the GNU extension ({}) by do {} while (0) In that case, there was no return value (moreover, it's a noreturn). - Break complex declaration lines into a line for each variable The variables were being initialized, some to non-zero values, so for clarity, a line for each one seems more appropriate. - Add const to pointers when possible - s/\\/\e/ - Remove unmatched groff commands Cc: Christian Brauner <brauner@kernel.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
| 2021-08-10 | mount_setattr.2: New manual page documenting the mount_setattr() system call | Christian Brauner | 1 | -0/+1002 | |
| Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com> Cc: Christoph Hellwig <hch@infradead.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com> | |||||
 |
index : man-pages/man-pages.git | |
| Linux man pages Sections 2, 3, 4, 5, and 7 | Michael Timothy Kerrisk |
| aboutsummaryrefslogtreecommitdiffstats |