From 9a6ff5bc53dedbaa601a1a76cbaf8a76afd60c9f Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:41:06 +0200 Subject: Adding upstream version 6.7. Signed-off-by: Daniel Baumann --- .checkpatch.conf | 34 +- .gitignore | 2 +- CONTRIBUTING | 219 +- CONTRIBUTING.d/bugs | 28 + CONTRIBUTING.d/external_pages | 17 + CONTRIBUTING.d/lint | 40 + CONTRIBUTING.d/mail | 67 + CONTRIBUTING.d/patches | 94 + CONTRIBUTING.d/style | 21 + CPPLINT.cfg | 3 +- Changes | 207 +- Changes.old | 587 ++ GNUmakefile | 66 + INSTALL | 71 +- LICENSES/BSD-2-Clause.txt | 2 +- LICENSES/BSD-3-Clause.txt | 2 +- LICENSES/LGPL-3.0-linking-exception.txt | 16 + LICENSES/LGPL-3.0-or-later.txt | 304 + LICENSES/Linux-man-pages-copyleft-var.txt | 18 +- Makefile | 234 - README | 26 +- RELEASE | 21 +- etc/checkpatch/checkpatch.conf | 36 + etc/checkpatch/config | 33 - etc/clang-tidy/config.yaml | 13 + etc/cppcheck/cppcheck.suppress | 4 + etc/cpplint/CPPLINT.cfg | 2 - etc/cpplint/cpplint.cfg | 2 + lsm | 6 +- man1/getent.1 | 35 +- man1/iconv.1 | 48 +- man1/intro.1 | 44 +- man1/ldd.1 | 32 +- man1/locale.1 | 54 +- man1/localedef.1 | 32 +- man1/memusage.1 | 10 +- man1/memusagestat.1 | 4 +- man1/mtrace.1 | 4 +- man1/pldd.1 | 18 +- man1/sprof.1 | 74 +- man1/time.1 | 30 +- man2/_exit.2 | 24 +- man2/_syscall.2 | 18 +- man2/accept.2 | 30 +- man2/access.2 | 69 +- man2/acct.2 | 10 +- man2/add_key.2 | 38 +- man2/adjtimex.2 | 31 +- man2/alarm.2 | 14 +- man2/alloc_hugepages.2 | 20 +- man2/arch_prctl.2 | 32 +- man2/bdflush.2 | 16 +- man2/bind.2 | 20 +- man2/bpf.2 | 78 +- man2/brk.2 | 18 +- man2/cacheflush.2 | 18 +- man2/capget.2 | 24 +- man2/chdir.2 | 14 +- man2/chmod.2 | 36 +- man2/chown.2 | 38 +- man2/chroot.2 | 24 +- man2/clock_getres.2 | 85 +- man2/clock_nanosleep.2 | 54 +- man2/clone.2 | 127 +- man2/close.2 | 44 +- man2/close_range.2 | 35 +- man2/connect.2 | 18 +- man2/copy_file_range.2 | 20 +- man2/create_module.2 | 8 +- man2/delete_module.2 | 18 +- man2/dup.2 | 22 +- man2/epoll_create.2 | 10 +- man2/epoll_ctl.2 | 16 +- man2/epoll_wait.2 | 36 +- man2/eventfd.2 | 35 +- man2/execve.2 | 115 +- man2/execveat.2 | 22 +- man2/exit_group.2 | 6 +- man2/fallocate.2 | 40 +- man2/fanotify_init.2 | 30 +- man2/fanotify_mark.2 | 41 +- man2/fcntl.2 | 202 +- man2/flock.2 | 38 +- man2/fork.2 | 14 +- man2/fsync.2 | 47 +- man2/futex.2 | 66 +- man2/futimesat.2 | 20 +- man2/get_kernel_syms.2 | 18 +- man2/get_mempolicy.2 | 22 +- man2/get_robust_list.2 | 24 +- man2/getcpu.2 | 12 +- man2/getdents.2 | 46 +- man2/getdomainname.2 | 14 +- man2/getgid.2 | 8 +- man2/getgroups.2 | 34 +- man2/gethostname.2 | 16 +- man2/getitimer.2 | 38 +- man2/getpagesize.2 | 14 +- man2/getpeername.2 | 6 +- man2/getpid.2 | 10 +- man2/getpriority.2 | 24 +- man2/getrandom.2 | 26 +- man2/getresuid.2 | 6 +- man2/getrlimit.2 | 59 +- man2/getrusage.2 | 30 +- man2/getsid.2 | 8 +- man2/getsockname.2 | 6 +- man2/getsockopt.2 | 16 +- man2/gettid.2 | 6 +- man2/gettimeofday.2 | 40 +- man2/getuid.2 | 12 +- man2/getunwind.2 | 16 +- man2/getxattr.2 | 16 +- man2/idle.2 | 6 +- man2/init_module.2 | 44 +- man2/inotify_add_watch.2 | 8 +- man2/inotify_init.2 | 8 +- man2/inotify_rm_watch.2 | 6 +- man2/intro.2 | 12 +- man2/io_cancel.2 | 10 +- man2/io_destroy.2 | 10 +- man2/io_getevents.2 | 20 +- man2/io_setup.2 | 12 +- man2/io_submit.2 | 18 +- man2/ioctl.2 | 88 +- man2/ioctl_console.2 | 34 +- man2/ioctl_fat.2 | 46 +- man2/ioctl_ficlonerange.2 | 14 +- man2/ioctl_fideduperange.2 | 24 +- man2/ioctl_fslabel.2 | 6 +- man2/ioctl_getfsmap.2 | 46 +- man2/ioctl_iflags.2 | 12 +- man2/ioctl_ns.2 | 48 +- man2/ioctl_pagemap_scan.2 | 206 + man2/ioctl_pipe.2 | 4 +- man2/ioctl_tty.2 | 53 +- man2/ioctl_userfaultfd.2 | 340 +- man2/ioperm.2 | 10 +- man2/iopl.2 | 10 +- man2/ioprio_set.2 | 36 +- man2/ipc.2 | 8 +- man2/kcmp.2 | 26 +- man2/kexec_load.2 | 28 +- man2/keyctl.2 | 38 +- man2/kill.2 | 24 +- man2/landlock_add_rule.2 | 10 +- man2/landlock_create_ruleset.2 | 10 +- man2/landlock_restrict_self.2 | 12 +- man2/link.2 | 32 +- man2/listen.2 | 12 +- man2/listxattr.2 | 26 +- man2/llseek.2 | 14 +- man2/lookup_dcookie.2 | 12 +- man2/lseek.2 | 22 +- man2/madvise.2 | 18 +- man2/mbind.2 | 53 +- man2/membarrier.2 | 46 +- man2/memfd_create.2 | 40 +- man2/memfd_secret.2 | 24 +- man2/migrate_pages.2 | 18 +- man2/mincore.2 | 16 +- man2/mkdir.2 | 26 +- man2/mknod.2 | 34 +- man2/mlock.2 | 50 +- man2/mmap.2 | 62 +- man2/mmap2.2 | 12 +- man2/modify_ldt.2 | 28 +- man2/mount.2 | 74 +- man2/mount_setattr.2 | 62 +- man2/move_pages.2 | 26 +- man2/mprotect.2 | 32 +- man2/mq_getsetattr.2 | 6 +- man2/mremap.2 | 33 +- man2/msgctl.2 | 40 +- man2/msgget.2 | 16 +- man2/msgop.2 | 48 +- man2/msync.2 | 12 +- man2/nanosleep.2 | 39 +- man2/nfsservctl.2 | 6 +- man2/nice.2 | 18 +- man2/open.2 | 109 +- man2/open_by_handle_at.2 | 98 +- man2/openat2.2 | 34 +- man2/outb.2 | 14 +- man2/pause.2 | 4 +- man2/pciconfig_read.2 | 4 +- man2/perf_event_open.2 | 205 +- man2/perfmonctl.2 | 16 +- man2/personality.2 | 10 +- man2/pidfd_getfd.2 | 16 +- man2/pidfd_open.2 | 16 +- man2/pidfd_send_signal.2 | 20 +- man2/pipe.2 | 18 +- man2/pivot_root.2 | 38 +- man2/pkey_alloc.2 | 14 +- man2/poll.2 | 74 +- man2/posix_fadvise.2 | 26 +- man2/prctl.2 | 141 +- man2/pread.2 | 20 +- man2/process_madvise.2 | 61 +- man2/process_vm_readv.2 | 36 +- man2/ptrace.2 | 348 +- man2/query_module.2 | 12 +- man2/quotactl.2 | 48 +- man2/read.2 | 22 +- man2/readahead.2 | 6 +- man2/readdir.2 | 16 +- man2/readlink.2 | 30 +- man2/readv.2 | 48 +- man2/reboot.2 | 51 +- man2/recv.2 | 54 +- man2/recvmmsg.2 | 34 +- man2/remap_file_pages.2 | 18 +- man2/removexattr.2 | 14 +- man2/rename.2 | 42 +- man2/request_key.2 | 50 +- man2/restart_syscall.2 | 10 +- man2/rmdir.2 | 4 +- man2/rt_sigqueueinfo.2 | 20 +- man2/s390_guarded_storage.2 | 18 +- man2/s390_pci_mmio_write.2 | 8 +- man2/s390_runtime_instr.2 | 12 +- man2/s390_sthyi.2 | 22 +- man2/sched_get_priority_max.2 | 12 +- man2/sched_rr_get_interval.2 | 6 +- man2/sched_setaffinity.2 | 44 +- man2/sched_setattr.2 | 36 +- man2/sched_setparam.2 | 14 +- man2/sched_setscheduler.2 | 28 +- man2/sched_yield.2 | 10 +- man2/seccomp.2 | 78 +- man2/seccomp_unotify.2 | 124 +- man2/select.2 | 74 +- man2/select_tut.2 | 18 +- man2/semctl.2 | 62 +- man2/semget.2 | 30 +- man2/semop.2 | 44 +- man2/send.2 | 40 +- man2/sendfile.2 | 41 +- man2/sendmmsg.2 | 24 +- man2/set_mempolicy.2 | 22 +- man2/set_thread_area.2 | 60 +- man2/set_tid_address.2 | 16 +- man2/seteuid.2 | 20 +- man2/setfsgid.2 | 10 +- man2/setfsuid.2 | 14 +- man2/setgid.2 | 8 +- man2/setns.2 | 28 +- man2/setpgid.2 | 48 +- man2/setresuid.2 | 18 +- man2/setreuid.2 | 26 +- man2/setsid.2 | 14 +- man2/setuid.2 | 18 +- man2/setup.2 | 8 +- man2/setxattr.2 | 16 +- man2/sgetmask.2 | 14 +- man2/shmctl.2 | 48 +- man2/shmget.2 | 24 +- man2/shmop.2 | 48 +- man2/shutdown.2 | 4 +- man2/sigaction.2 | 111 +- man2/sigaltstack.2 | 39 +- man2/signal.2 | 36 +- man2/signalfd.2 | 34 +- man2/sigpending.2 | 14 +- man2/sigprocmask.2 | 40 +- man2/sigreturn.2 | 12 +- man2/sigsuspend.2 | 14 +- man2/sigwaitinfo.2 | 30 +- man2/socket.2 | 42 +- man2/socketcall.2 | 12 +- man2/socketpair.2 | 12 +- man2/splice.2 | 22 +- man2/spu_create.2 | 16 +- man2/spu_run.2 | 22 +- man2/stat.2 | 46 +- man2/statfs.2 | 32 +- man2/statx.2 | 38 +- man2/stime.2 | 12 +- man2/subpage_prot.2 | 14 +- man2/swapon.2 | 29 +- man2/symlink.2 | 34 +- man2/sync.2 | 24 +- man2/sync_file_range.2 | 16 +- man2/syscall.2 | 38 +- man2/syscalls.2 | 39 +- man2/sysctl.2 | 22 +- man2/sysfs.2 | 8 +- man2/sysinfo.2 | 16 +- man2/syslog.2 | 16 +- man2/tee.2 | 10 +- man2/time.2 | 47 +- man2/timer_create.2 | 46 +- man2/timer_delete.2 | 8 +- man2/timer_getoverrun.2 | 14 +- man2/timer_settime.2 | 24 +- man2/timerfd_create.2 | 50 +- man2/times.2 | 28 +- man2/tkill.2 | 14 +- man2/truncate.2 | 26 +- man2/umask.2 | 30 +- man2/umount.2 | 14 +- man2/uname.2 | 12 +- man2/unimplemented.2 | 6 +- man2/unlink.2 | 32 +- man2/unshare.2 | 20 +- man2/uselib.2 | 14 +- man2/userfaultfd.2 | 104 +- man2/ustat.2 | 10 +- man2/utime.2 | 26 +- man2/utimensat.2 | 74 +- man2/vfork.2 | 26 +- man2/vhangup.2 | 8 +- man2/vm86.2 | 8 +- man2/vmsplice.2 | 10 +- man2/wait.2 | 58 +- man2/wait4.2 | 36 +- man2/write.2 | 30 +- man2type/open_how.2type | 6 +- man3/CPU_SET.3 | 60 +- man3/INFINITY.3 | 14 +- man3/MAX.3 | 8 +- man3/MB_CUR_MAX.3 | 2 +- man3/MB_LEN_MAX.3 | 2 +- man3/TIMESPEC_TO_TIMEVAL.3 | 1 + man3/TIMEVAL_TO_TIMESPEC.3 | 32 + man3/_Generic.3 | 8 +- man3/__ppc_get_timebase.3 | 8 +- man3/__ppc_set_ppr_med.3 | 13 +- man3/__ppc_yield.3 | 13 +- man3/__setfpucw.3 | 10 +- man3/a64l.3 | 21 +- man3/abort.3 | 11 +- man3/abs.3 | 21 +- man3/acos.3 | 21 +- man3/acosh.3 | 23 +- man3/addseverity.3 | 11 +- man3/adjtime.3 | 21 +- man3/aio_cancel.3 | 15 +- man3/aio_error.3 | 5 +- man3/aio_fsync.3 | 15 +- man3/aio_init.3 | 10 +- man3/aio_read.3 | 23 +- man3/aio_return.3 | 9 +- man3/aio_suspend.3 | 17 +- man3/aio_write.3 | 23 +- man3/alloca.3 | 19 +- man3/arc4random.3 | 15 +- man3/argz_add.3 | 55 +- man3/asin.3 | 19 +- man3/asinh.3 | 19 +- man3/asprintf.3 | 5 +- man3/assert.3 | 13 +- man3/assert_perror.3 | 5 +- man3/atan.3 | 17 +- man3/atan2.3 | 35 +- man3/atanh.3 | 23 +- man3/atexit.3 | 17 +- man3/atof.3 | 9 +- man3/atoi.3 | 17 +- man3/backtrace.3 | 17 +- man3/basename.3 | 25 +- man3/bcmp.3 | 6 +- man3/bcopy.3 | 7 +- man3/bindresvport.3 | 11 +- man3/bsd_signal.3 | 17 +- man3/bsearch.3 | 9 +- man3/bstring.3 | 24 +- man3/bswap.3 | 6 +- man3/btowc.3 | 7 +- man3/btree.3 | 26 +- man3/byteorder.3 | 15 +- man3/bzero.3 | 17 +- man3/cabs.3 | 5 +- man3/cacos.3 | 9 +- man3/cacosh.3 | 9 +- man3/canonicalize_file_name.3 | 11 +- man3/carg.3 | 21 +- man3/casin.3 | 9 +- man3/casinh.3 | 9 +- man3/catan.3 | 13 +- man3/catanh.3 | 9 +- man3/catgets.3 | 9 +- man3/catopen.3 | 13 +- man3/cbrt.3 | 20 +- man3/ccos.3 | 9 +- man3/ccosh.3 | 8 +- man3/ceil.3 | 17 +- man3/cexp.3 | 9 +- man3/cexp2.3 | 6 +- man3/cfree.3 | 29 +- man3/cimag.3 | 9 +- man3/circleq.3 | 60 +- man3/clearenv.3 | 23 +- man3/clock.3 | 11 +- man3/clock_getcpuclockid.3 | 13 +- man3/clog.3 | 13 +- man3/clog10.3 | 17 +- man3/clog2.3 | 10 +- man3/closedir.3 | 5 +- man3/cmsg.3 | 28 +- man3/confstr.3 | 19 +- man3/conj.3 | 9 +- man3/copysign.3 | 15 +- man3/cos.3 | 17 +- man3/cosh.3 | 23 +- man3/cpow.3 | 5 +- man3/cproj.3 | 7 +- man3/creal.3 | 9 +- man3/crypt.3 | 57 +- man3/csin.3 | 9 +- man3/csinh.3 | 9 +- man3/csqrt.3 | 5 +- man3/ctan.3 | 9 +- man3/ctanh.3 | 9 +- man3/ctermid.3 | 11 +- man3/ctime.3 | 55 +- man3/daemon.3 | 15 +- man3/dbopen.3 | 40 +- man3/des_crypt.3 | 15 +- man3/difftime.3 | 28 +- man3/dirfd.3 | 11 +- man3/div.3 | 21 +- man3/dl_iterate_phdr.3 | 39 +- man3/dladdr.3 | 17 +- man3/dlerror.3 | 11 +- man3/dlinfo.3 | 9 +- man3/dlopen.3 | 63 +- man3/dlsym.3 | 17 +- man3/drand48.3 | 43 +- man3/drand48_r.3 | 17 +- man3/duplocale.3 | 14 +- man3/dysize.3 | 15 +- man3/ecvt.3 | 11 +- man3/ecvt_r.3 | 11 +- man3/encrypt.3 | 25 +- man3/end.3 | 8 +- man3/endian.3 | 28 +- man3/envz_add.3 | 31 +- man3/erf.3 | 27 +- man3/erfc.3 | 29 +- man3/err.3 | 29 +- man3/errno.3 | 34 +- man3/error.3 | 23 +- man3/ether_aton.3 | 27 +- man3/euidaccess.3 | 11 +- man3/exec.3 | 35 +- man3/exit.3 | 25 +- man3/exp.3 | 23 +- man3/exp10.3 | 9 +- man3/exp2.3 | 15 +- man3/expm1.3 | 31 +- man3/fabs.3 | 17 +- man3/fclose.3 | 7 +- man3/fcloseall.3 | 9 +- man3/fdim.3 | 15 +- man3/fenv.3 | 55 +- man3/ferror.3 | 13 +- man3/fexecve.3 | 13 +- man3/fflush.3 | 17 +- man3/ffs.3 | 17 +- man3/fgetc.3 | 25 +- man3/fgetgrent.3 | 13 +- man3/fgetpwent.3 | 13 +- man3/fgetwc.3 | 11 +- man3/fgetws.3 | 13 +- man3/fileno.3 | 11 +- man3/finite.3 | 25 +- man3/flockfile.3 | 23 +- man3/floor.3 | 17 +- man3/fma.3 | 27 +- man3/fmax.3 | 13 +- man3/fmemopen.3 | 45 +- man3/fmin.3 | 13 +- man3/fmod.3 | 50 +- man3/fmtmsg.3 | 53 +- man3/fnmatch.3 | 7 +- man3/fopen.3 | 45 +- man3/fopencookie.3 | 25 +- man3/fpathconf.3 | 13 +- man3/fpclassify.3 | 17 +- man3/fpurge.3 | 11 +- man3/fputwc.3 | 11 +- man3/fputws.3 | 9 +- man3/fread.3 | 15 +- man3/frexp.3 | 22 +- man3/fseek.3 | 23 +- man3/fseeko.3 | 11 +- man3/ftime.3 | 15 +- man3/ftok.3 | 13 +- man3/fts.3 | 61 +- man3/ftw.3 | 37 +- man3/futimes.3 | 13 +- man3/fwide.3 | 14 +- man3/gamma.3 | 21 +- man3/gcvt.3 | 9 +- man3/get_nprocs.3 | 13 +- man3/get_phys_pages.3 | 10 +- man3/getaddrinfo.3 | 53 +- man3/getaddrinfo_a.3 | 109 +- man3/getauxval.3 | 15 +- man3/getcontext.3 | 25 +- man3/getcwd.3 | 31 +- man3/getdate.3 | 41 +- man3/getdirentries.3 | 9 +- man3/getdtablesize.3 | 11 +- man3/getentropy.3 | 16 +- man3/getenv.3 | 21 +- man3/getfsent.3 | 23 +- man3/getgrent.3 | 29 +- man3/getgrent_r.3 | 26 +- man3/getgrnam.3 | 31 +- man3/getgrouplist.3 | 27 +- man3/gethostbyname.3 | 56 +- man3/gethostid.3 | 17 +- man3/getifaddrs.3 | 27 +- man3/getipnodebyname.3 | 18 +- man3/getline.3 | 21 +- man3/getloadavg.3 | 9 +- man3/getlogin.3 | 32 +- man3/getmntent.3 | 47 +- man3/getnameinfo.3 | 43 +- man3/getnetent.3 | 26 +- man3/getnetent_r.3 | 19 +- man3/getopt.3 | 51 +- man3/getpass.3 | 15 +- man3/getprotoent.3 | 24 +- man3/getprotoent_r.3 | 19 +- man3/getpt.3 | 9 +- man3/getpw.3 | 15 +- man3/getpwent.3 | 22 +- man3/getpwent_r.3 | 26 +- man3/getpwnam.3 | 35 +- man3/getrpcent.3 | 21 +- man3/getrpcent_r.3 | 17 +- man3/getrpcport.3 | 5 +- man3/gets.3 | 11 +- man3/getservent.3 | 24 +- man3/getservent_r.3 | 19 +- man3/getspnam.3 | 52 +- man3/getsubopt.3 | 23 +- man3/getttyent.3 | 21 +- man3/getusershell.3 | 13 +- man3/getutent.3 | 62 +- man3/getutmp.3 | 5 +- man3/getw.3 | 11 +- man3/getwchar.3 | 9 +- man3/glob.3 | 32 +- man3/gnu_get_libc_version.3 | 9 +- man3/grantpt.3 | 15 +- man3/group_member.3 | 8 +- man3/gsignal.3 | 15 +- man3/hash.3 | 22 +- man3/hsearch.3 | 45 +- man3/hypot.3 | 25 +- man3/iconv.3 | 19 +- man3/iconv_close.3 | 5 +- man3/iconv_open.3 | 11 +- man3/if_nameindex.3 | 17 +- man3/if_nametoindex.3 | 13 +- man3/ilogb.3 | 19 +- man3/index.3 | 8 +- man3/inet.3 | 43 +- man3/inet_net_pton.3 | 48 +- man3/inet_ntop.3 | 9 +- man3/inet_pton.3 | 9 +- man3/initgroups.3 | 11 +- man3/insque.3 | 25 +- man3/intro.3 | 10 +- man3/isalpha.3 | 35 +- man3/isatty.3 | 5 +- man3/isfdtype.3 | 8 +- man3/isgreater.3 | 13 +- man3/iswalnum.3 | 17 +- man3/iswalpha.3 | 19 +- man3/iswblank.3 | 15 +- man3/iswcntrl.3 | 9 +- man3/iswctype.3 | 7 +- man3/iswdigit.3 | 17 +- man3/iswgraph.3 | 13 +- man3/iswlower.3 | 21 +- man3/iswprint.3 | 9 +- man3/iswpunct.3 | 15 +- man3/iswspace.3 | 11 +- man3/iswupper.3 | 21 +- man3/iswxdigit.3 | 15 +- man3/j0.3 | 25 +- man3/key_setsecret.3 | 21 +- man3/killpg.3 | 12 +- man3/ldexp.3 | 23 +- man3/lgamma.3 | 34 +- man3/lio_listio.3 | 23 +- man3/list.3 | 58 +- man3/localeconv.3 | 5 +- man3/lockf.3 | 26 +- man3/log.3 | 23 +- man3/log10.3 | 19 +- man3/log1p.3 | 27 +- man3/log2.3 | 19 +- man3/logb.3 | 30 +- man3/login.3 | 12 +- man3/lrint.3 | 19 +- man3/lround.3 | 19 +- man3/lsearch.3 | 7 +- man3/lseek64.3 | 41 +- man3/makecontext.3 | 15 +- man3/makedev.3 | 15 +- man3/mallinfo.3 | 26 +- man3/malloc.3 | 47 +- man3/malloc_get_state.3 | 15 +- man3/malloc_hook.3 | 26 +- man3/malloc_info.3 | 17 +- man3/malloc_stats.3 | 5 +- man3/malloc_trim.3 | 11 +- man3/malloc_usable_size.3 | 5 +- man3/mallopt.3 | 28 +- man3/matherr.3 | 53 +- man3/mblen.3 | 11 +- man3/mbrlen.3 | 11 +- man3/mbrtowc.3 | 17 +- man3/mbsinit.3 | 21 +- man3/mbsnrtowcs.3 | 21 +- man3/mbsrtowcs.3 | 46 +- man3/mbstowcs.3 | 43 +- man3/mbtowc.3 | 13 +- man3/mcheck.3 | 21 +- man3/memccpy.3 | 7 +- man3/memchr.3 | 17 +- man3/memcmp.3 | 9 +- man3/memcpy.3 | 7 +- man3/memfrob.3 | 7 +- man3/memmem.3 | 5 +- man3/memmove.3 | 5 +- man3/mempcpy.3 | 13 +- man3/memset.3 | 5 +- man3/mkdtemp.3 | 11 +- man3/mkfifo.3 | 25 +- man3/mkstemp.3 | 31 +- man3/mktemp.3 | 11 +- man3/modf.3 | 15 +- man3/mpool.3 | 38 +- man3/mq_close.3 | 7 +- man3/mq_getattr.3 | 23 +- man3/mq_notify.3 | 29 +- man3/mq_open.3 | 19 +- man3/mq_receive.3 | 19 +- man3/mq_send.3 | 21 +- man3/mq_unlink.3 | 5 +- man3/mtrace.3 | 23 +- man3/nan.3 | 19 +- man3/netlink.3 | 4 +- man3/newlocale.3 | 34 +- man3/nextafter.3 | 33 +- man3/nextup.3 | 15 +- man3/nl_langinfo.3 | 29 +- man3/ntp_gettime.3 | 15 +- man3/offsetof.3 | 10 +- man3/on_exit.3 | 13 +- man3/open_memstream.3 | 23 +- man3/opendir.3 | 15 +- man3/openpty.3 | 19 +- man3/perror.3 | 23 +- man3/popen.3 | 29 +- man3/posix_fallocate.3 | 15 +- man3/posix_madvise.3 | 12 +- man3/posix_memalign.3 | 43 +- man3/posix_openpt.3 | 17 +- man3/posix_spawn.3 | 64 +- man3/pow.3 | 61 +- man3/pow10.3 | 7 +- man3/powerof2.3 | 8 +- man3/printf.3 | 107 +- man3/profil.3 | 11 +- man3/program_invocation_name.3 | 8 +- man3/psignal.3 | 13 +- man3/pthread_atfork.3 | 12 +- man3/pthread_attr_init.3 | 19 +- man3/pthread_attr_setaffinity_np.3 | 11 +- man3/pthread_attr_setdetachstate.3 | 15 +- man3/pthread_attr_setguardsize.3 | 21 +- man3/pthread_attr_setinheritsched.3 | 15 +- man3/pthread_attr_setschedparam.3 | 17 +- man3/pthread_attr_setschedpolicy.3 | 13 +- man3/pthread_attr_setscope.3 | 13 +- man3/pthread_attr_setsigmask_np.3 | 17 +- man3/pthread_attr_setstack.3 | 21 +- man3/pthread_attr_setstackaddr.3 | 11 +- man3/pthread_attr_setstacksize.3 | 15 +- man3/pthread_cancel.3 | 17 +- man3/pthread_cleanup_push.3 | 35 +- man3/pthread_cleanup_push_defer_np.3 | 22 +- man3/pthread_cond_init.3 | 264 + man3/pthread_condattr_init.3 | 48 + man3/pthread_create.3 | 48 +- man3/pthread_detach.3 | 15 +- man3/pthread_equal.3 | 5 +- man3/pthread_exit.3 | 15 +- man3/pthread_getattr_default_np.3 | 13 +- man3/pthread_getattr_np.3 | 31 +- man3/pthread_getcpuclockid.3 | 7 +- man3/pthread_join.3 | 17 +- man3/pthread_key_create.3 | 178 + man3/pthread_kill.3 | 13 +- man3/pthread_kill_other_threads_np.3 | 5 +- man3/pthread_mutex_consistent.3 | 14 +- man3/pthread_mutex_init.3 | 241 + man3/pthread_mutexattr_getpshared.3 | 12 +- man3/pthread_mutexattr_init.3 | 10 +- man3/pthread_mutexattr_setkind_np.3 | 52 + man3/pthread_mutexattr_setrobust.3 | 26 +- man3/pthread_once.3 | 44 + man3/pthread_rwlockattr_setkind_np.3 | 10 +- man3/pthread_self.3 | 11 +- man3/pthread_setaffinity_np.3 | 19 +- man3/pthread_setcancelstate.3 | 17 +- man3/pthread_setconcurrency.3 | 17 +- man3/pthread_setname_np.3 | 15 +- man3/pthread_setschedparam.3 | 36 +- man3/pthread_setschedprio.3 | 7 +- man3/pthread_sigmask.3 | 15 +- man3/pthread_sigqueue.3 | 11 +- man3/pthread_spin_init.3 | 24 +- man3/pthread_spin_lock.3 | 20 +- man3/pthread_testcancel.3 | 7 +- man3/pthread_tryjoin_np.3 | 15 +- man3/pthread_yield.3 | 7 +- man3/ptsname.3 | 19 +- man3/putenv.3 | 25 +- man3/putgrent.3 | 9 +- man3/putpwent.3 | 13 +- man3/puts.3 | 21 +- man3/putwchar.3 | 9 +- man3/qecvt.3 | 11 +- man3/qsort.3 | 19 +- man3/raise.3 | 15 +- man3/rand.3 | 27 +- man3/random.3 | 23 +- man3/random_r.3 | 19 +- man3/rcmd.3 | 33 +- man3/re_comp.3 | 11 +- man3/readdir.3 | 31 +- man3/readdir_r.3 | 15 +- man3/realpath.3 | 25 +- man3/recno.3 | 20 +- man3/regex.3 | 37 +- man3/remainder.3 | 33 +- man3/remove.3 | 13 +- man3/remquo.3 | 25 +- man3/resolver.3 | 71 +- man3/rewinddir.3 | 5 +- man3/rexec.3 | 17 +- man3/rint.3 | 21 +- man3/round.3 | 15 +- man3/roundup.3 | 12 +- man3/rpc.3 | 151 +- man3/rpmatch.3 | 19 +- man3/rtime.3 | 21 +- man3/rtnetlink.3 | 26 +- man3/scalb.3 | 31 +- man3/scalbln.3 | 29 +- man3/scandir.3 | 35 +- man3/scanf.3 | 38 +- man3/sched_getcpu.3 | 17 +- man3/seekdir.3 | 9 +- man3/sem_close.3 | 5 +- man3/sem_destroy.3 | 11 +- man3/sem_getvalue.3 | 7 +- man3/sem_init.3 | 15 +- man3/sem_open.3 | 9 +- man3/sem_post.3 | 5 +- man3/sem_unlink.3 | 5 +- man3/sem_wait.3 | 19 +- man3/setaliasent.3 | 29 +- man3/setbuf.3 | 33 +- man3/setenv.3 | 13 +- man3/setjmp.3 | 35 +- man3/setlocale.3 | 37 +- man3/setlogmask.3 | 17 +- man3/setnetgrent.3 | 18 +- man3/shm_open.3 | 35 +- man3/siginterrupt.3 | 13 +- man3/signbit.3 | 15 +- man3/significand.3 | 16 +- man3/sigpause.3 | 15 +- man3/sigqueue.3 | 17 +- man3/sigset.3 | 39 +- man3/sigsetops.3 | 35 +- man3/sigvec.3 | 43 +- man3/sigwait.3 | 13 +- man3/sin.3 | 17 +- man3/sincos.3 | 13 +- man3/sinh.3 | 23 +- man3/sleep.3 | 7 +- man3/slist.3 | 56 +- man3/sockatmark.3 | 17 +- man3/sqrt.3 | 21 +- man3/sscanf.3 | 70 +- man3/stailq.3 | 64 +- man3/static_assert.3 | 14 +- man3/statvfs.3 | 25 +- man3/stdarg.3 | 33 +- man3/stdin.3 | 18 +- man3/stdio.3 | 30 +- man3/stdio_ext.3 | 25 +- man3/stpecpy.3 | 1 - man3/stpecpyx.3 | 1 - man3/stpncpy.3 | 71 +- man3/strcasecmp.3 | 13 +- man3/strchr.3 | 17 +- man3/strcmp.3 | 21 +- man3/strcoll.3 | 5 +- man3/strcpy.3 | 19 +- man3/strdup.3 | 19 +- man3/strerror.3 | 68 +- man3/strfmon.3 | 27 +- man3/strfromd.3 | 40 +- man3/strfry.3 | 5 +- man3/strftime.3 | 57 +- man3/string.3 | 13 +- man3/strlen.3 | 5 +- man3/strncat.3 | 67 +- man3/strnlen.3 | 9 +- man3/strpbrk.3 | 5 +- man3/strptime.3 | 39 +- man3/strsep.3 | 13 +- man3/strsignal.3 | 23 +- man3/strspn.3 | 9 +- man3/strstr.3 | 13 +- man3/strtod.3 | 27 +- man3/strtoimax.3 | 5 +- man3/strtok.3 | 31 +- man3/strtol.3 | 64 +- man3/strtoul.3 | 35 +- man3/strverscmp.3 | 11 +- man3/strxfrm.3 | 5 +- man3/swab.3 | 7 +- man3/sysconf.3 | 21 +- man3/syslog.3 | 33 +- man3/system.3 | 35 +- man3/sysv_signal.3 | 13 +- man3/tailq.3 | 70 +- man3/tan.3 | 19 +- man3/tanh.3 | 19 +- man3/tcgetpgrp.3 | 13 +- man3/tcgetsid.3 | 7 +- man3/telldir.3 | 13 +- man3/tempnam.3 | 25 +- man3/termios.3 | 89 +- man3/tgamma.3 | 45 +- man3/timegm.3 | 11 +- man3/timeradd.3 | 26 +- man3/tmpfile.3 | 5 +- man3/tmpnam.3 | 19 +- man3/toascii.3 | 9 +- man3/toupper.3 | 29 +- man3/towctrans.3 | 7 +- man3/towlower.3 | 15 +- man3/towupper.3 | 15 +- man3/trunc.3 | 11 +- man3/tsearch.3 | 35 +- man3/ttyname.3 | 5 +- man3/ttyslot.3 | 23 +- man3/tzset.3 | 51 +- man3/ualarm.3 | 23 +- man3/ulimit.3 | 7 +- man3/undocumented.3 | 2 +- man3/ungetwc.3 | 13 +- man3/unlocked_stdio.3 | 29 +- man3/unlockpt.3 | 11 +- man3/updwtmp.3 | 11 +- man3/uselocale.3 | 10 +- man3/usleep.3 | 13 +- man3/ustpcpy.3 | 1 - man3/ustr2stp.3 | 1 - man3/wcpcpy.3 | 13 +- man3/wcpncpy.3 | 13 +- man3/wcrtomb.3 | 17 +- man3/wcscasecmp.3 | 9 +- man3/wcscat.3 | 9 +- man3/wcschr.3 | 5 +- man3/wcscmp.3 | 5 +- man3/wcscpy.3 | 9 +- man3/wcscspn.3 | 5 +- man3/wcsdup.3 | 11 +- man3/wcslen.3 | 5 +- man3/wcsncasecmp.3 | 9 +- man3/wcsncat.3 | 9 +- man3/wcsncmp.3 | 5 +- man3/wcsncpy.3 | 9 +- man3/wcsnlen.3 | 9 +- man3/wcsnrtombs.3 | 19 +- man3/wcspbrk.3 | 5 +- man3/wcsrchr.3 | 5 +- man3/wcsrtombs.3 | 13 +- man3/wcsspn.3 | 5 +- man3/wcsstr.3 | 7 +- man3/wcstoimax.3 | 5 +- man3/wcstok.3 | 9 +- man3/wcstombs.3 | 11 +- man3/wcswidth.3 | 5 +- man3/wctob.3 | 9 +- man3/wctomb.3 | 11 +- man3/wctrans.3 | 9 +- man3/wctype.3 | 9 +- man3/wcwidth.3 | 9 +- man3/wmemchr.3 | 5 +- man3/wmemcmp.3 | 5 +- man3/wmemcpy.3 | 9 +- man3/wmemmove.3 | 7 +- man3/wmemset.3 | 5 +- man3/wordexp.3 | 20 +- man3/wprintf.3 | 23 +- man3/xcrypt.3 | 13 +- man3/xdr.3 | 79 +- man3/y0.3 | 35 +- man3/zustr2stp.3 | 1 - man3/zustr2ustp.3 | 1 - man3const/EOF.3const | 6 +- man3const/EXIT_SUCCESS.3const | 4 +- man3const/NULL.3const | 12 +- man3head/printf.h.3head | 16 +- man3head/sysexits.h.3head | 12 +- man3type/FILE.3type | 4 +- man3type/aiocb.3type | 4 +- man3type/blkcnt_t.3type | 4 +- man3type/blksize_t.3type | 4 +- man3type/cc_t.3type | 6 +- man3type/clock_t.3type | 6 +- man3type/clockid_t.3type | 4 +- man3type/dev_t.3type | 4 +- man3type/div_t.3type | 17 +- man3type/double_t.3type | 8 +- man3type/epoll_event.3type | 10 +- man3type/fenv_t.3type | 8 +- man3type/id_t.3type | 16 +- man3type/intN_t.3type | 36 +- man3type/intmax_t.3type | 22 +- man3type/intptr_t.3type | 18 +- man3type/iovec.3type | 4 +- man3type/itimerspec.3type | 13 +- man3type/lconv.3type | 4 +- man3type/mode_t.3type | 4 +- man3type/off_t.3type | 20 +- man3type/ptrdiff_t.3type | 8 +- man3type/sigevent.3type | 143 +- man3type/sigval.3type | 2 +- man3type/size_t.3type | 12 +- man3type/sockaddr.3type | 28 +- man3type/stat.3type | 16 +- man3type/time_t.3type | 18 +- man3type/timer_t.3type | 4 +- man3type/timespec.3type | 6 +- man3type/timeval.3type | 4 +- man3type/tm.3type | 22 +- man3type/va_list.3type | 4 +- man3type/void.3type | 8 +- man4/cciss.4 | 40 +- man4/console_codes.4 | 117 +- man4/cpuid.4 | 28 +- man4/dsp56k.4 | 10 +- man4/fd.4 | 22 +- man4/full.4 | 10 +- man4/fuse.4 | 16 +- man4/hd.4 | 10 +- man4/hpsa.4 | 22 +- man4/initrd.4 | 30 +- man4/intro.4 | 2 +- man4/lirc.4 | 19 +- man4/loop.4 | 18 +- man4/lp.4 | 2 +- man4/mem.4 | 24 +- man4/mouse.4 | 22 +- man4/msr.4 | 8 +- man4/null.4 | 10 +- man4/pts.4 | 14 +- man4/ram.4 | 6 +- man4/random.4 | 42 +- man4/rtc.4 | 66 +- man4/sd.4 | 10 +- man4/sk98lin.4 | 32 +- man4/smartpqi.4 | 268 +- man4/st.4 | 60 +- man4/tty.4 | 8 +- man4/ttyS.4 | 6 +- man4/vcs.4 | 30 +- man4/veth.4 | 22 +- man4/wavelan.4 | 6 +- man5/acct.5 | 22 +- man5/charmap.5 | 20 +- man5/core.5 | 70 +- man5/dir_colors.5 | 50 +- man5/elf.5 | 129 +- man5/erofs.5 | 6 +- man5/filesystems.5 | 12 +- man5/ftpusers.5 | 6 +- man5/gai.conf.5 | 8 +- man5/group.5 | 6 +- man5/host.conf.5 | 6 +- man5/hosts.5 | 14 +- man5/hosts.equiv.5 | 62 +- man5/intro.5 | 4 +- man5/issue.5 | 2 +- man5/locale.5 | 88 +- man5/motd.5 | 4 +- man5/networks.5 | 12 +- man5/nologin.5 | 2 +- man5/nscd.conf.5 | 50 +- man5/nss.5 | 12 +- man5/nsswitch.conf.5 | 40 +- man5/passwd.5 | 20 +- man5/proc.5 | 6772 +-------------------- man5/proc_apm.5 | 17 + man5/proc_buddyinfo.5 | 58 + man5/proc_bus.5 | 35 + man5/proc_cgroups.5 | 16 + man5/proc_cmdline.5 | 22 + man5/proc_config.gz.5 | 40 + man5/proc_cpuinfo.5 | 24 + man5/proc_crypto.5 | 26 + man5/proc_devices.5 | 16 + man5/proc_diskstats.5 | 21 + man5/proc_dma.5 | 16 + man5/proc_driver.5 | 15 + man5/proc_execdomains.5 | 16 + man5/proc_fb.5 | 17 + man5/proc_filesystems.5 | 33 + man5/proc_fs.5 | 18 + man5/proc_ide.5 | 37 + man5/proc_interrupts.5 | 22 + man5/proc_iomem.5 | 15 + man5/proc_ioports.5 | 16 + man5/proc_kallsyms.5 | 25 + man5/proc_kcore.5 | 24 + man5/proc_key-users.5 | 1 + man5/proc_keys.5 | 20 + man5/proc_kmsg.5 | 28 + man5/proc_kpagecgroup.5 | 25 + man5/proc_kpagecount.5 | 24 + man5/proc_kpageflags.5 | 75 + man5/proc_ksyms.5 | 1 + man5/proc_loadavg.5 | 27 + man5/proc_locks.5 | 122 + man5/proc_malloc.5 | 18 + man5/proc_meminfo.5 | 327 + man5/proc_modules.5 | 17 + man5/proc_mounts.5 | 1 + man5/proc_mtrr.5 | 24 + man5/proc_net.5 | 1 + man5/proc_partitions.5 | 16 + man5/proc_pci.5 | 28 + man5/proc_pid.5 | 73 + man5/proc_pid_attr.5 | 137 + man5/proc_pid_autogroup.5 | 17 + man5/proc_pid_auxv.5 | 27 + man5/proc_pid_cgroup.5 | 16 + man5/proc_pid_clear_refs.5 | 87 + man5/proc_pid_cmdline.5 | 49 + man5/proc_pid_comm.5 | 49 + man5/proc_pid_coredump_filter.5 | 16 + man5/proc_pid_cpuset.5 | 17 + man5/proc_pid_cwd.5 | 36 + man5/proc_pid_environ.5 | 48 + man5/proc_pid_exe.5 | 59 + man5/proc_pid_fd.5 | 161 + man5/proc_pid_fdinfo.5 | 300 + man5/proc_pid_gid_map.5 | 1 + man5/proc_pid_io.5 | 100 + man5/proc_pid_limits.5 | 25 + man5/proc_pid_map_files.5 | 72 + man5/proc_pid_maps.5 | 156 + man5/proc_pid_mem.5 | 24 + man5/proc_pid_mountinfo.5 | 124 + man5/proc_pid_mounts.5 | 49 + man5/proc_pid_mountstats.5 | 46 + man5/proc_pid_net.5 | 298 + man5/proc_pid_ns.5 | 20 + man5/proc_pid_numa_maps.5 | 16 + man5/proc_pid_oom_adj.5 | 1 + man5/proc_pid_oom_score.5 | 58 + man5/proc_pid_oom_score_adj.5 | 117 + man5/proc_pid_pagemap.5 | 77 + man5/proc_pid_personality.5 | 23 + man5/proc_pid_projid_map.5 | 17 + man5/proc_pid_root.5 | 75 + man5/proc_pid_seccomp.5 | 36 + man5/proc_pid_setgroups.5 | 16 + man5/proc_pid_smaps.5 | 129 + man5/proc_pid_stack.5 | 25 + man5/proc_pid_stat.5 | 380 ++ man5/proc_pid_statm.5 | 46 + man5/proc_pid_status.5 | 384 ++ man5/proc_pid_syscall.5 | 33 + man5/proc_pid_task.5 | 97 + man5/proc_pid_timers.5 | 82 + man5/proc_pid_timerslack_ns.5 | 41 + man5/proc_pid_uid_map.5 | 20 + man5/proc_pid_wchan.5 | 21 + man5/proc_profile.5 | 24 + man5/proc_scsi.5 | 66 + man5/proc_self.5 | 1 + man5/proc_slabinfo.5 | 18 + man5/proc_stat.5 | 140 + man5/proc_swaps.5 | 17 + man5/proc_sys.5 | 31 + man5/proc_sys_abi.5 | 24 + man5/proc_sys_debug.5 | 17 + man5/proc_sys_dev.5 | 20 + man5/proc_sys_fs.5 | 471 ++ man5/proc_sys_kernel.5 | 691 +++ man5/proc_sys_net.5 | 34 + man5/proc_sys_proc.5 | 17 + man5/proc_sys_sunrpc.5 | 19 + man5/proc_sys_user.5 | 18 + man5/proc_sys_vm.5 | 420 ++ man5/proc_sysrq-trigger.5 | 25 + man5/proc_sysvipc.5 | 25 + man5/proc_thread-self.5 | 1 + man5/proc_tid.5 | 1 + man5/proc_tid_children.5 | 37 + man5/proc_timer_list.5 | 18 + man5/proc_timer_stats.5 | 117 + man5/proc_tty.5 | 16 + man5/proc_uptime.5 | 17 + man5/proc_version.5 | 27 + man5/proc_vmstat.5 | 702 +++ man5/proc_zoneinfo.5 | 17 + man5/protocols.5 | 18 +- man5/repertoiremap.5 | 10 +- man5/resolv.conf.5 | 18 +- man5/rpc.5 | 10 +- man5/securetty.5 | 6 +- man5/services.5 | 28 +- man5/shells.5 | 6 +- man5/slabinfo.5 | 28 +- man5/sysfs.5 | 12 +- man5/termcap.5 | 36 +- man5/tmpfs.5 | 32 +- man5/ttytype.5 | 8 +- man5/tzfile.5 | 112 +- man5/utmp.5 | 42 +- man6/intro.6 | 2 +- man7/address_families.7 | 10 +- man7/aio.7 | 26 +- man7/armscii-8.7 | 2 +- man7/arp.7 | 28 +- man7/ascii.7 | 20 +- man7/attributes.7 | 8 +- man7/boot.7 | 36 +- man7/bootparam.7 | 52 +- man7/bpf-helpers.7 | 169 +- man7/capabilities.7 | 112 +- man7/cgroup_namespaces.7 | 38 +- man7/cgroups.7 | 218 +- man7/charsets.7 | 128 +- man7/complex.7 | 10 +- man7/cp1251.7 | 4 +- man7/cp1252.7 | 4 +- man7/cpuset.7 | 196 +- man7/credentials.7 | 49 +- man7/ddp.7 | 20 +- man7/environ.7 | 26 +- man7/epoll.7 | 24 +- man7/fanotify.7 | 127 +- man7/feature_test_macros.7 | 60 +- man7/fifo.7 | 12 +- man7/futex.7 | 24 +- man7/glob.7 | 56 +- man7/hier.7 | 4 +- man7/hostname.7 | 20 +- man7/icmp.7 | 20 +- man7/inode.7 | 43 +- man7/inotify.7 | 90 +- man7/intro.7 | 2 +- man7/ip.7 | 83 +- man7/ipc_namespaces.7 | 10 +- man7/ipv6.7 | 34 +- man7/iso_8859-1.7 | 50 +- man7/iso_8859-10.7 | 50 +- man7/iso_8859-11.7 | 52 +- man7/iso_8859-13.7 | 50 +- man7/iso_8859-14.7 | 50 +- man7/iso_8859-15.7 | 50 +- man7/iso_8859-16.7 | 50 +- man7/iso_8859-2.7 | 50 +- man7/iso_8859-3.7 | 50 +- man7/iso_8859-4.7 | 50 +- man7/iso_8859-5.7 | 48 +- man7/iso_8859-6.7 | 52 +- man7/iso_8859-7.7 | 50 +- man7/iso_8859-8.7 | 52 +- man7/iso_8859-9.7 | 50 +- man7/kernel_lockdown.7 | 16 +- man7/keyrings.7 | 86 +- man7/koi8-r.7 | 2 +- man7/koi8-u.7 | 2 +- man7/landlock.7 | 73 +- man7/libc.7 | 8 +- man7/locale.7 | 18 +- man7/mailaddr.7 | 28 +- man7/man-pages.7 | 112 +- man7/man.7 | 508 +- man7/math_error.7 | 32 +- man7/mount_namespaces.7 | 202 +- man7/mq_overview.7 | 30 +- man7/namespaces.7 | 22 +- man7/netdevice.7 | 82 +- man7/netlink.7 | 60 +- man7/network_namespaces.7 | 8 +- man7/nptl.7 | 8 +- man7/numa.7 | 14 +- man7/operator.7 | 10 +- man7/packet.7 | 52 +- man7/path_resolution.7 | 46 +- man7/persistent-keyring.7 | 18 +- man7/pid_namespaces.7 | 40 +- man7/pipe.7 | 30 +- man7/pkeys.7 | 26 +- man7/posixoptions.7 | 128 +- man7/process-keyring.7 | 10 +- man7/pthreads.7 | 56 +- man7/pty.7 | 23 +- man7/queue.7 | 20 +- man7/random.7 | 8 +- man7/raw.7 | 42 +- man7/regex.7 | 52 +- man7/rtld-audit.7 | 72 +- man7/rtnetlink.7 | 72 +- man7/sched.7 | 130 +- man7/sem_overview.7 | 10 +- man7/session-keyring.7 | 18 +- man7/shm_overview.7 | 6 +- man7/sigevent.7 | 121 +- man7/signal-safety.7 | 20 +- man7/signal.7 | 76 +- man7/sock_diag.7 | 60 +- man7/socket.7 | 52 +- man7/spufs.7 | 67 +- man7/standards.7 | 12 +- man7/string_copying.7 | 647 +- man7/suffixes.7 | 6 +- man7/symlink.7 | 56 +- man7/system_data_types.7 | 102 +- man7/sysvipc.7 | 8 +- man7/tcp.7 | 38 +- man7/termio.7 | 6 +- man7/thread-keyring.7 | 10 +- man7/time.7 | 16 +- man7/time_namespaces.7 | 56 +- man7/udp.7 | 28 +- man7/udplite.7 | 20 +- man7/unicode.7 | 22 +- man7/units.7 | 16 +- man7/unix.7 | 156 +- man7/uri.7 | 164 +- man7/user-keyring.7 | 18 +- man7/user-session-keyring.7 | 18 +- man7/user_namespaces.7 | 124 +- man7/utf-8.7 | 66 +- man7/uts_namespaces.7 | 6 +- man7/vdso.7 | 50 +- man7/vsock.7 | 32 +- man7/x25.7 | 24 +- man7/xattr.7 | 30 +- man8/iconvconfig.8 | 22 +- man8/intro.8 | 4 +- man8/ld.so.8 | 127 +- man8/ldconfig.8 | 30 +- man8/nscd.8 | 8 +- man8/sln.8 | 8 +- man8/tzselect.8 | 2 +- man8/zdump.8 | 5 +- man8/zic.8 | 83 +- scripts/FIXME_list.sh | 48 +- scripts/LinuxManBook/BuildLinuxMan.pl | 249 - scripts/LinuxManBook/LMBfront.roff | 33 + scripts/LinuxManBook/LMBfront.t | 38 - scripts/LinuxManBook/an-ext.tmac | 282 - scripts/LinuxManBook/an.tmac | 402 +- scripts/LinuxManBook/andoc.tmac | 114 - scripts/LinuxManBook/anmark.tmac | 22 - scripts/LinuxManBook/build.sh | 25 + scripts/LinuxManBook/en.tmac | 77 - scripts/LinuxManBook/gropdf | 3710 ----------- scripts/LinuxManBook/hyphen.en | 5018 --------------- scripts/LinuxManBook/hyphenex.en | 115 - scripts/LinuxManBook/prepare.pl | 248 + scripts/LinuxManBook/troffrc | 71 - scripts/LinuxManBook/utp.mac | 742 --- scripts/README | 2 +- scripts/add_parens_for_own_funcs.sh | 44 +- scripts/convert_to_utf_8.sh | 2 +- scripts/find_dots_no_parens.sh | 20 +- scripts/find_repeated_words.sh | 6 +- scripts/find_slashes_no_parens.sh | 18 +- scripts/man_show_fixme.sh | 2 +- scripts/sortman | 15 + scripts/unformat_parens.sh | 6 +- share/lint/groff/man.ignore.grep | 3 - share/lint/mandoc/man.ignore.grep | 6 - share/lint/mandoc/mdoc.ignore.grep | 5 - share/mk/build/_.mk | 47 +- share/mk/build/book.mk | 42 + share/mk/build/catman.mk | 89 - share/mk/build/catman/_.mk | 13 + share/mk/build/catman/eqn.mk | 27 + share/mk/build/catman/grotty.mk | 25 + share/mk/build/catman/troff.ignore.grep | 3 + share/mk/build/catman/troff.mk | 85 + share/mk/build/examples/_.mk | 28 + share/mk/build/examples/cc.mk | 54 + share/mk/build/examples/ld.mk | 51 + share/mk/build/examples/src.mk | 55 + share/mk/build/groff.mk | 39 - share/mk/build/html.mk | 42 - share/mk/build/html/_.mk | 13 + share/mk/build/html/post-grohtml.mk | 25 + share/mk/build/html/troff.mk | 58 + share/mk/build/pdf.mk | 68 - share/mk/build/pdf/_.mk | 13 + share/mk/build/pdf/eqn.mk | 27 + share/mk/build/pdf/gropdf.mk | 25 + share/mk/build/pdf/troff.mk | 75 + share/mk/build/pre.mk | 47 - share/mk/build/pre/_.mk | 13 + share/mk/build/pre/preconv.mk | 27 + share/mk/build/pre/tbl.mk | 25 + share/mk/build/ps.mk | 68 - share/mk/build/ps/_.mk | 13 + share/mk/build/ps/eqn.mk | 27 + share/mk/build/ps/grops.mk | 25 + share/mk/build/ps/troff.mk | 75 + share/mk/build/src.mk | 117 - share/mk/check/_.mk | 11 +- share/mk/check/catman.mk | 51 - share/mk/check/catman/_.mk | 13 + share/mk/check/catman/col.mk | 25 + share/mk/check/catman/grep.mk | 50 + share/mk/clean.mk | 19 + share/mk/cmd.mk | 40 - share/mk/compress.mk | 40 - share/mk/configure/build-depends/bsdextrautils.mk | 18 + share/mk/configure/build-depends/bzip2.mk | 15 + share/mk/configure/build-depends/cc.mk | 63 + share/mk/configure/build-depends/checkpatch.mk | 19 + share/mk/configure/build-depends/clang-tidy.mk | 22 + share/mk/configure/build-depends/clang.mk | 19 + share/mk/configure/build-depends/coreutils.mk | 32 + share/mk/configure/build-depends/cpp.mk | 20 + share/mk/configure/build-depends/cppcheck.mk | 24 + share/mk/configure/build-depends/cpplint.mk | 19 + share/mk/configure/build-depends/diffoscope.mk | 12 + share/mk/configure/build-depends/findutils.mk | 13 + share/mk/configure/build-depends/git.mk | 12 + share/mk/configure/build-depends/grep.mk | 12 + share/mk/configure/build-depends/groff-base.mk | 72 + share/mk/configure/build-depends/groff.mk | 21 + share/mk/configure/build-depends/gzip.mk | 15 + share/mk/configure/build-depends/iwyu.mk | 17 + share/mk/configure/build-depends/ld.mk | 50 + share/mk/configure/build-depends/libc-bin.mk | 12 + share/mk/configure/build-depends/lzip.mk | 15 + share/mk/configure/build-depends/man.mk | 12 + share/mk/configure/build-depends/mandoc.mk | 15 + share/mk/configure/build-depends/moreutils.mk | 12 + share/mk/configure/build-depends/pkgconf.mk | 27 + share/mk/configure/build-depends/sed.mk | 12 + share/mk/configure/build-depends/tar.mk | 22 + share/mk/configure/build-depends/xz-utils.mk | 15 + share/mk/configure/directory_variables.mk | 29 + share/mk/configure/link_pages.mk | 18 + share/mk/configure/src.mk | 16 + share/mk/configure/verbose.mk | 12 + share/mk/configure/version.mk | 43 + share/mk/configure/xfail.mk | 18 + share/mk/configure/z.mk | 21 + share/mk/dist.mk | 96 - share/mk/dist/_.mk | 25 + share/mk/dist/check/_.mk | 41 + share/mk/dist/check/diffoscope.mk | 26 + share/mk/dist/check/dist.mk | 28 + share/mk/dist/check/tar.mk | 32 + share/mk/dist/files.mk | 62 + share/mk/dist/tar.mk | 37 + share/mk/dist/z.mk | 44 + share/mk/install/_.mk | 21 +- share/mk/install/html.mk | 21 +- share/mk/install/man.mk | 215 +- share/mk/lint/_.mk | 11 +- share/mk/lint/c.mk | 102 - share/mk/lint/c/_.mk | 18 + share/mk/lint/c/checkpatch.mk | 35 + share/mk/lint/c/clang-tidy.mk | 188 + share/mk/lint/c/cppcheck.mk | 74 + share/mk/lint/c/cpplint.mk | 27 + share/mk/lint/c/iwyu.mk | 109 + share/mk/lint/man/_.mk | 11 +- share/mk/lint/man/man.mk | 69 - share/mk/lint/man/mandoc.ignore.grep | 6 + share/mk/lint/man/mandoc.mk | 53 + share/mk/lint/man/mdoc.mk | 44 - share/mk/lint/man/tbl.mk | 48 + share/mk/lint/mdoc/_.mk | 31 + share/mk/lint/mdoc/mandoc.ignore.grep | 5 + share/mk/lint/mdoc/mandoc.mk | 30 + share/mk/src.mk | 65 +- share/mk/verbose.mk | 19 - share/mk/version.mk | 20 - 1407 files changed, 29368 insertions(+), 34701 deletions(-) mode change 100644 => 120000 .checkpatch.conf create mode 100644 CONTRIBUTING.d/bugs create mode 100644 CONTRIBUTING.d/external_pages create mode 100644 CONTRIBUTING.d/lint create mode 100644 CONTRIBUTING.d/mail create mode 100644 CONTRIBUTING.d/patches create mode 100644 CONTRIBUTING.d/style mode change 100644 => 120000 CPPLINT.cfg create mode 100644 GNUmakefile create mode 100644 LICENSES/LGPL-3.0-linking-exception.txt create mode 100644 LICENSES/LGPL-3.0-or-later.txt delete mode 100644 Makefile create mode 100644 etc/checkpatch/checkpatch.conf delete mode 100644 etc/checkpatch/config delete mode 100644 etc/cpplint/CPPLINT.cfg create mode 100644 etc/cpplint/cpplint.cfg create mode 100644 man2/ioctl_pagemap_scan.2 create mode 100644 man3/TIMESPEC_TO_TIMEVAL.3 create mode 100644 man3/TIMEVAL_TO_TIMESPEC.3 create mode 100644 man3/pthread_cond_init.3 create mode 100644 man3/pthread_condattr_init.3 create mode 100644 man3/pthread_key_create.3 create mode 100644 man3/pthread_mutex_init.3 create mode 100644 man3/pthread_mutexattr_setkind_np.3 create mode 100644 man3/pthread_once.3 delete mode 100644 man3/stpecpy.3 delete mode 100644 man3/stpecpyx.3 delete mode 100644 man3/ustpcpy.3 delete mode 100644 man3/ustr2stp.3 delete mode 100644 man3/zustr2stp.3 delete mode 100644 man3/zustr2ustp.3 create mode 100644 man5/proc_apm.5 create mode 100644 man5/proc_buddyinfo.5 create mode 100644 man5/proc_bus.5 create mode 100644 man5/proc_cgroups.5 create mode 100644 man5/proc_cmdline.5 create mode 100644 man5/proc_config.gz.5 create mode 100644 man5/proc_cpuinfo.5 create mode 100644 man5/proc_crypto.5 create mode 100644 man5/proc_devices.5 create mode 100644 man5/proc_diskstats.5 create mode 100644 man5/proc_dma.5 create mode 100644 man5/proc_driver.5 create mode 100644 man5/proc_execdomains.5 create mode 100644 man5/proc_fb.5 create mode 100644 man5/proc_filesystems.5 create mode 100644 man5/proc_fs.5 create mode 100644 man5/proc_ide.5 create mode 100644 man5/proc_interrupts.5 create mode 100644 man5/proc_iomem.5 create mode 100644 man5/proc_ioports.5 create mode 100644 man5/proc_kallsyms.5 create mode 100644 man5/proc_kcore.5 create mode 100644 man5/proc_key-users.5 create mode 100644 man5/proc_keys.5 create mode 100644 man5/proc_kmsg.5 create mode 100644 man5/proc_kpagecgroup.5 create mode 100644 man5/proc_kpagecount.5 create mode 100644 man5/proc_kpageflags.5 create mode 100644 man5/proc_ksyms.5 create mode 100644 man5/proc_loadavg.5 create mode 100644 man5/proc_locks.5 create mode 100644 man5/proc_malloc.5 create mode 100644 man5/proc_meminfo.5 create mode 100644 man5/proc_modules.5 create mode 100644 man5/proc_mounts.5 create mode 100644 man5/proc_mtrr.5 create mode 100644 man5/proc_net.5 create mode 100644 man5/proc_partitions.5 create mode 100644 man5/proc_pci.5 create mode 100644 man5/proc_pid.5 create mode 100644 man5/proc_pid_attr.5 create mode 100644 man5/proc_pid_autogroup.5 create mode 100644 man5/proc_pid_auxv.5 create mode 100644 man5/proc_pid_cgroup.5 create mode 100644 man5/proc_pid_clear_refs.5 create mode 100644 man5/proc_pid_cmdline.5 create mode 100644 man5/proc_pid_comm.5 create mode 100644 man5/proc_pid_coredump_filter.5 create mode 100644 man5/proc_pid_cpuset.5 create mode 100644 man5/proc_pid_cwd.5 create mode 100644 man5/proc_pid_environ.5 create mode 100644 man5/proc_pid_exe.5 create mode 100644 man5/proc_pid_fd.5 create mode 100644 man5/proc_pid_fdinfo.5 create mode 100644 man5/proc_pid_gid_map.5 create mode 100644 man5/proc_pid_io.5 create mode 100644 man5/proc_pid_limits.5 create mode 100644 man5/proc_pid_map_files.5 create mode 100644 man5/proc_pid_maps.5 create mode 100644 man5/proc_pid_mem.5 create mode 100644 man5/proc_pid_mountinfo.5 create mode 100644 man5/proc_pid_mounts.5 create mode 100644 man5/proc_pid_mountstats.5 create mode 100644 man5/proc_pid_net.5 create mode 100644 man5/proc_pid_ns.5 create mode 100644 man5/proc_pid_numa_maps.5 create mode 100644 man5/proc_pid_oom_adj.5 create mode 100644 man5/proc_pid_oom_score.5 create mode 100644 man5/proc_pid_oom_score_adj.5 create mode 100644 man5/proc_pid_pagemap.5 create mode 100644 man5/proc_pid_personality.5 create mode 100644 man5/proc_pid_projid_map.5 create mode 100644 man5/proc_pid_root.5 create mode 100644 man5/proc_pid_seccomp.5 create mode 100644 man5/proc_pid_setgroups.5 create mode 100644 man5/proc_pid_smaps.5 create mode 100644 man5/proc_pid_stack.5 create mode 100644 man5/proc_pid_stat.5 create mode 100644 man5/proc_pid_statm.5 create mode 100644 man5/proc_pid_status.5 create mode 100644 man5/proc_pid_syscall.5 create mode 100644 man5/proc_pid_task.5 create mode 100644 man5/proc_pid_timers.5 create mode 100644 man5/proc_pid_timerslack_ns.5 create mode 100644 man5/proc_pid_uid_map.5 create mode 100644 man5/proc_pid_wchan.5 create mode 100644 man5/proc_profile.5 create mode 100644 man5/proc_scsi.5 create mode 100644 man5/proc_self.5 create mode 100644 man5/proc_slabinfo.5 create mode 100644 man5/proc_stat.5 create mode 100644 man5/proc_swaps.5 create mode 100644 man5/proc_sys.5 create mode 100644 man5/proc_sys_abi.5 create mode 100644 man5/proc_sys_debug.5 create mode 100644 man5/proc_sys_dev.5 create mode 100644 man5/proc_sys_fs.5 create mode 100644 man5/proc_sys_kernel.5 create mode 100644 man5/proc_sys_net.5 create mode 100644 man5/proc_sys_proc.5 create mode 100644 man5/proc_sys_sunrpc.5 create mode 100644 man5/proc_sys_user.5 create mode 100644 man5/proc_sys_vm.5 create mode 100644 man5/proc_sysrq-trigger.5 create mode 100644 man5/proc_sysvipc.5 create mode 100644 man5/proc_thread-self.5 create mode 100644 man5/proc_tid.5 create mode 100644 man5/proc_tid_children.5 create mode 100644 man5/proc_timer_list.5 create mode 100644 man5/proc_timer_stats.5 create mode 100644 man5/proc_tty.5 create mode 100644 man5/proc_uptime.5 create mode 100644 man5/proc_version.5 create mode 100644 man5/proc_vmstat.5 create mode 100644 man5/proc_zoneinfo.5 delete mode 100755 scripts/LinuxManBook/BuildLinuxMan.pl create mode 100644 scripts/LinuxManBook/LMBfront.roff delete mode 100644 scripts/LinuxManBook/LMBfront.t delete mode 100644 scripts/LinuxManBook/an-ext.tmac delete mode 100644 scripts/LinuxManBook/andoc.tmac delete mode 100644 scripts/LinuxManBook/anmark.tmac create mode 100755 scripts/LinuxManBook/build.sh delete mode 100644 scripts/LinuxManBook/en.tmac delete mode 100755 scripts/LinuxManBook/gropdf delete mode 100644 scripts/LinuxManBook/hyphen.en delete mode 100644 scripts/LinuxManBook/hyphenex.en create mode 100755 scripts/LinuxManBook/prepare.pl delete mode 100644 scripts/LinuxManBook/troffrc delete mode 100644 scripts/LinuxManBook/utp.mac create mode 100755 scripts/sortman delete mode 100644 share/lint/groff/man.ignore.grep delete mode 100644 share/lint/mandoc/man.ignore.grep delete mode 100644 share/lint/mandoc/mdoc.ignore.grep create mode 100644 share/mk/build/book.mk delete mode 100644 share/mk/build/catman.mk create mode 100644 share/mk/build/catman/_.mk create mode 100644 share/mk/build/catman/eqn.mk create mode 100644 share/mk/build/catman/grotty.mk create mode 100644 share/mk/build/catman/troff.ignore.grep create mode 100644 share/mk/build/catman/troff.mk create mode 100644 share/mk/build/examples/_.mk create mode 100644 share/mk/build/examples/cc.mk create mode 100644 share/mk/build/examples/ld.mk create mode 100644 share/mk/build/examples/src.mk delete mode 100644 share/mk/build/groff.mk delete mode 100644 share/mk/build/html.mk create mode 100644 share/mk/build/html/_.mk create mode 100644 share/mk/build/html/post-grohtml.mk create mode 100644 share/mk/build/html/troff.mk delete mode 100644 share/mk/build/pdf.mk create mode 100644 share/mk/build/pdf/_.mk create mode 100644 share/mk/build/pdf/eqn.mk create mode 100644 share/mk/build/pdf/gropdf.mk create mode 100644 share/mk/build/pdf/troff.mk delete mode 100644 share/mk/build/pre.mk create mode 100644 share/mk/build/pre/_.mk create mode 100644 share/mk/build/pre/preconv.mk create mode 100644 share/mk/build/pre/tbl.mk delete mode 100644 share/mk/build/ps.mk create mode 100644 share/mk/build/ps/_.mk create mode 100644 share/mk/build/ps/eqn.mk create mode 100644 share/mk/build/ps/grops.mk create mode 100644 share/mk/build/ps/troff.mk delete mode 100644 share/mk/build/src.mk delete mode 100644 share/mk/check/catman.mk create mode 100644 share/mk/check/catman/_.mk create mode 100644 share/mk/check/catman/col.mk create mode 100644 share/mk/check/catman/grep.mk create mode 100644 share/mk/clean.mk delete mode 100644 share/mk/cmd.mk delete mode 100644 share/mk/compress.mk create mode 100644 share/mk/configure/build-depends/bsdextrautils.mk create mode 100644 share/mk/configure/build-depends/bzip2.mk create mode 100644 share/mk/configure/build-depends/cc.mk create mode 100644 share/mk/configure/build-depends/checkpatch.mk create mode 100644 share/mk/configure/build-depends/clang-tidy.mk create mode 100644 share/mk/configure/build-depends/clang.mk create mode 100644 share/mk/configure/build-depends/coreutils.mk create mode 100644 share/mk/configure/build-depends/cpp.mk create mode 100644 share/mk/configure/build-depends/cppcheck.mk create mode 100644 share/mk/configure/build-depends/cpplint.mk create mode 100644 share/mk/configure/build-depends/diffoscope.mk create mode 100644 share/mk/configure/build-depends/findutils.mk create mode 100644 share/mk/configure/build-depends/git.mk create mode 100644 share/mk/configure/build-depends/grep.mk create mode 100644 share/mk/configure/build-depends/groff-base.mk create mode 100644 share/mk/configure/build-depends/groff.mk create mode 100644 share/mk/configure/build-depends/gzip.mk create mode 100644 share/mk/configure/build-depends/iwyu.mk create mode 100644 share/mk/configure/build-depends/ld.mk create mode 100644 share/mk/configure/build-depends/libc-bin.mk create mode 100644 share/mk/configure/build-depends/lzip.mk create mode 100644 share/mk/configure/build-depends/man.mk create mode 100644 share/mk/configure/build-depends/mandoc.mk create mode 100644 share/mk/configure/build-depends/moreutils.mk create mode 100644 share/mk/configure/build-depends/pkgconf.mk create mode 100644 share/mk/configure/build-depends/sed.mk create mode 100644 share/mk/configure/build-depends/tar.mk create mode 100644 share/mk/configure/build-depends/xz-utils.mk create mode 100644 share/mk/configure/directory_variables.mk create mode 100644 share/mk/configure/link_pages.mk create mode 100644 share/mk/configure/src.mk create mode 100644 share/mk/configure/verbose.mk create mode 100644 share/mk/configure/version.mk create mode 100644 share/mk/configure/xfail.mk create mode 100644 share/mk/configure/z.mk delete mode 100644 share/mk/dist.mk create mode 100644 share/mk/dist/_.mk create mode 100644 share/mk/dist/check/_.mk create mode 100644 share/mk/dist/check/diffoscope.mk create mode 100644 share/mk/dist/check/dist.mk create mode 100644 share/mk/dist/check/tar.mk create mode 100644 share/mk/dist/files.mk create mode 100644 share/mk/dist/tar.mk create mode 100644 share/mk/dist/z.mk delete mode 100644 share/mk/lint/c.mk create mode 100644 share/mk/lint/c/_.mk create mode 100644 share/mk/lint/c/checkpatch.mk create mode 100644 share/mk/lint/c/clang-tidy.mk create mode 100644 share/mk/lint/c/cppcheck.mk create mode 100644 share/mk/lint/c/cpplint.mk create mode 100644 share/mk/lint/c/iwyu.mk delete mode 100644 share/mk/lint/man/man.mk create mode 100644 share/mk/lint/man/mandoc.ignore.grep create mode 100644 share/mk/lint/man/mandoc.mk delete mode 100644 share/mk/lint/man/mdoc.mk create mode 100644 share/mk/lint/man/tbl.mk create mode 100644 share/mk/lint/mdoc/_.mk create mode 100644 share/mk/lint/mdoc/mandoc.ignore.grep create mode 100644 share/mk/lint/mdoc/mandoc.mk delete mode 100644 share/mk/verbose.mk delete mode 100644 share/mk/version.mk diff --git a/.checkpatch.conf b/.checkpatch.conf deleted file mode 100644 index b1a4b40..0000000 --- a/.checkpatch.conf +++ /dev/null @@ -1,33 +0,0 @@ ---ignore AVOID_EXTERNS ---ignore BLOCK_COMMENT_STYLE ---ignore BRACES ---ignore CAMELCASE ---ignore CODE_INDENT ---ignore COMPARISON_TO_NULL ---ignore COMPLEX_MACRO ---ignore CONCATENATED_STRING ---ignore FUNCTION_ARGUMENTS ---ignore INITIALISED_STATIC ---ignore LEADING_SPACE ---ignore LINE_SPACING ---ignore LOGICAL_CONTINUATIONS ---ignore MACRO_ARG_REUSE ---ignore MULTIPLE_ASSIGNMENTS ---ignore OPEN_BRACE ---ignore PREFER_FALLTHROUGH ---ignore PREFER_KERNEL_TYPES ---ignore SPACING ---ignore SPDX_LICENSE_TAG ---ignore SPLIT_STRING ---ignore STATIC_CONST_CHAR_ARRAY ---ignore SUSPECT_CODE_INDENT ---ignore TRAILING_STATEMENTS ---ignore UNNECESSARY_PARENTHESES ---ignore VOLATILE - ---no-tree ---quiet ---root=. ---show-types ---strict ---verbose diff --git a/.checkpatch.conf b/.checkpatch.conf new file mode 120000 index 0000000..a614af4 --- /dev/null +++ b/.checkpatch.conf @@ -0,0 +1 @@ +etc/checkpatch/checkpatch.conf \ No newline at end of file diff --git a/.gitignore b/.gitignore index 8786f3c..a2a25ec 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,4 @@ /.tmp/ # checkpatch spurious output. I hope we fix that some day. -/.checkpatch-camelcase.git. +/.checkpatch-camelcase.* diff --git a/CONTRIBUTING b/CONTRIBUTING index b08000b..f6d48e9 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -3,10 +3,9 @@ Name Synopsis Mailing list, patches, lint & check, style guide, bug reports, - and notes + and more. Description - Mailing list The main discussions regarding development of the project, patches, bugs, news, doubts, etc. happen on the mailing list. To send an email to the project, send it to Alejandro and CC the @@ -15,214 +14,24 @@ Description To: Alejandro Colomar Cc: - Please CC any relevant developers and mailing lists that may know - about or be interested in the discussion. If your email - discusses a feature or change, and you know which developers - added the feature or made the change that your email discusses, - please CC them on the email; with luck they may review and - comment on it. If you don't know who the developers are, you may - be able to discover that information from mailing list archives - or from git(1) logs or logs in other version control systems. - Obviously, if you are the developer of the feature being - discussed in a man-pages email, please identify yourself as such. - Relevant mailing lists may include: +Files + CONTRIBUTING.d/mail + Instructions for sending emails to the project - Cc: LKML - Cc: Linux API - Cc: Glibc + CONTRIBUTING.d/patches + Instructions for contributing patches - For other kernel mailing lists and maintainers, check the - file in the Linux kernel repository. + CONTRIBUTING.d/bugs + Instructions for reporting bugs - Please don't send HTML email; it will be discarded by the list. + CONTRIBUTING.d/lint + Instructions for linting manual pages - Archives: - - + CONTRIBUTING.d/external_pages + Pages imported or generated from other projects - Subscription: - Send a message to containing - the following body: - - subscribe linux-man - - Unsubscribing: - - unsubscribe linux-man - - Help: - - help - - Patches - If you know how to fix a problem in a manual page (if not, see - "Reporting bugs" below), then send a patch in an email. - - - Follow the instructions for sending mail to the mailing list - above. - - - The subject of the email should contain "[patch]" in the - subject line. - - The above is the minimum needed so that someone might respond to - your patch. If you did that and someone does not respond within - a few days, then ping the email thread, "replying to all". Make - sure to send it to the maintainers in addition to the mailing - list. - - To make your patch even more useful, please note the following - points: - - - Write a suitable subject line. Make sure to mention the - name(s) of the page(s) being patched. Example: - - [patch] shmop.2: Add "(void *)" cast to RETURN VALUE - - - Sign your patch with "Signed-off-by:". Read about the - "Developer's Certificate of Origin" at - . - When appropriate, other tags documented in that file, such as - "Reported-by:", "Reviewed-by:", "Acked-by:", and - "Suggested-by:" can be added to the patch. The man-pages - project also uses a "Cowritten-by:" tag with the obvious - meaning. Example: - - Signed-off-by: Alejandro Colomar - - - Describe how you obtained the information in your patch. For - example, was it: - - - by reading (or writing) the relevant kernel or (g)libc - source code? Please provide a pointer to the following - code. - - - from a commit message in the kernel or (g)libc source code - repository? Please provide a commit ID. - - - by writing a test program? Send it with the patch, but - please make sure it's as simple as possible, and provide - instructions on how to use it and/or a demo run. - - - from a standards document? Please name the standard, and - quote the relevant text. - - - from other documentation? Please provide a pointer to that - documentation. - - - from a mailing list or online forum? Please provide a URL - if possible. - - - Send patches in diff -u format, inline inside the email - message. If you're worried about your mailer breaking the - patch, the send it both inline and as an attachment. You may - find it useful to employ git-send-email(1) and - git-format-patch(1). - - - Where relevant, include source code comments that cite commit - hashes for relevant kernel or glibc changes: - - .\" commit <40-character-git-hash> - - - For trivial patches, you can use subject tags: - - - ffix: Formatting fix. - - tfix: Typo fix. - - wfix: Minor wording fix. - - srcfix: Change to manual page source that doesn't affect - the output. - - Example: - - [patch] tcp.7: tfix - - - Send logically separate patches. For unrelated pages, or for - logically-separate issues in the same page, send separate - emails. - - - Make patches against the latest version of the manual page. - Use git(1) for getting the latest version. - - Lint & check - If you plan to patch a manual page, consider running the linters - and checks configured in the build system, to make sure your - change doesn't add new warnings. However, you might still get - warnings that are not your fault. To minimize that, do the - following steps: - - (1) First use make(1)'s -t option, so that make(1) knows that it - only needs to lint & check again pages that you will touch. - - $ make -t lint check >/dev/null - - (2) Run make(1) again, asking it to imagine that the page wou'll - modify has been touched, to see which warnings you'll still - see from that page that are not your fault. - - $ # replace 'man2/membarrier.2' by the page you'll modify - $ make -W man2/membarrier.2 -k lint check - - (3) Apply your changes, and then run make(1) again. You can - ignore warnings that you saw in step (2), but if you see any - new ones, please fix them if you know how, or at least note - them in your patch email. - - $ vi man2/membarrier.2 # do your work - $ make -k lint check - - See for a list of dependencies that this feature - requires. If you can't meet them all, don't worry; it will still - run the linters and checks that you have available. - - Style guide - For a description of the preferred layout of manual pages, as - well as some style guide notes, see: - - $ man 7 man-pages - - It will also be interesting to consult groff_man(7) and - groff_man_style(7) for understanding and writing good man(7) - source code. - -Reporting bugs - Report bugs to the mailing list, following the instructions above - for sending mails to the list. If you can write a patch (see - instructions for sending patches above), it's preferred. - - If you're unsure if the bug is in the manual page or in the code - being documented (kernel, glibc, ...), it's best to send the - report to both at the same time, that is, CC all the mailing - lists that may be concerned by the report. - - Some distributions (for example Debian) apply patches to the - upstream manual pages. If you suspect the bug is in one of those - patches, report it to your distribution maintainer. - - Send logically separate reports. For unrelated pages, or for - logically-separate issues in the same page, send separate emails. - - There's also a bugzilla, but we don't use it as much as the - mailing list. - -Notes - External and autogenerated pages - A few pages come from external sources. Fixes to the pages - should really go to the upstream source. - - tzfile(5), tzselect(8), zdump(8), and zic(8) come from the tz - project . - - bpf-helpers(7) is autogenerated from the Linux kernel sources - using scripts. See man-pages commits 53666f6c3 and 19c7f7839 for - details. - -Bugs - Bugzilla: - + CONTRIBUTING.d/style + Preferred layout of manual pages and style guide notes See also - man-pages(7) - - - - diff --git a/CONTRIBUTING.d/bugs b/CONTRIBUTING.d/bugs new file mode 100644 index 0000000..4b8cf74 --- /dev/null +++ b/CONTRIBUTING.d/bugs @@ -0,0 +1,28 @@ +Name + Bugs - instructions for reporting bugs + +Description + Report bugs to the mailing list. If you can write a patch, it's + very welcome. + + If you're unsure if the bug is in the manual page or in the code + being documented (kernel, glibc, ...), it's best to send the + report to both at the same time, that is, CC all the mailing + lists that may be concerned by the report. + + Some distributions (for example Debian) apply patches to the + upstream manual pages. If you suspect the bug is in one of those + patches, report it to your distribution maintainer. + + Send logically separate reports. For unrelated pages, or for + logically-separate issues in the same page, send separate emails. + + There's also a bugzilla, but we don't use it as much as the + mailing list. If you want to track your bug there, feel free to + open a bug report, but expect more attention in the mailing list. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + diff --git a/CONTRIBUTING.d/external_pages b/CONTRIBUTING.d/external_pages new file mode 100644 index 0000000..63b3e16 --- /dev/null +++ b/CONTRIBUTING.d/external_pages @@ -0,0 +1,17 @@ +Name + External pages - pages imported or generated from other projects + +Description + A few pages come from external sources. Fixes to the pages + should really go to the upstream source. + + tzfile(5), tzselect(8), zdump(8), and zic(8) come from the tz + project . + + bpf-helpers(7) is autogenerated from the Linux kernel sources + using scripts. See man-pages commits 53666f6c3 and 19c7f7839 for + details. + +See also + CONTRIBUTING + CONTRIBUTING.d/* diff --git a/CONTRIBUTING.d/lint b/CONTRIBUTING.d/lint new file mode 100644 index 0000000..0a936d9 --- /dev/null +++ b/CONTRIBUTING.d/lint @@ -0,0 +1,40 @@ +Name + Lint - instructions for linting manual pages + +Description + The entire project + To run the linters and checks for the entire project, run + + $ make lint build check; + + This skips tests that are known to fail. To run those too, run + + $ make lint build check SKIP_XFAIL=no; + + A single page + To run those for a single page, you can take advantage of some + make(1) features: + + (1) First use make(1)'s -t option, so that make(1) knows that + it only needs to lint & check again pages that you will + touch. + + $ make -t lint build check; + + (2) Run make(1) again, asking it to imagine that the page + you're interested in has been touched. + + $ # replace 'man2/membarrier.2' by any page. + $ make -W man2/membarrier.2 -k lint build check; + + Dependencies + See for a list of dependencies that this feature + requires. If you can't meet them all, don't worry; it will still + run the linters and checks that you have available. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + INSTALL + + $ make help diff --git a/CONTRIBUTING.d/mail b/CONTRIBUTING.d/mail new file mode 100644 index 0000000..48e5b9a --- /dev/null +++ b/CONTRIBUTING.d/mail @@ -0,0 +1,67 @@ +Name + Mail - instructions for sending email to the project + +Description + The main discussions regarding development of the project, + patches, bugs, news, doubts, etc. happen on the mailing list. + To send an email to the project, send it to Alejandro and CC the + mailing list: + + To: Alejandro Colomar + Cc: + + Please CC any relevant developers and mailing lists that may know + about or be interested in the discussion. If your email + discusses a feature or change, and you know which developers + added the feature or made the change that your email discusses, + please CC them on the email; with luck they may review and + comment on it. If you don't know who the developers are, you may + be able to discover that information from mailing list archives + or from git(1) logs or logs in other version control systems. + Obviously, if you are the developer of the feature being + discussed in a man-pages email, please identify yourself as such. + Relevant mailing lists may include: + + Cc: LKML + Cc: Linux API + Cc: Glibc + + For other kernel mailing lists and maintainers, check the + file in the Linux kernel repository. + + Please don't send HTML email; it will be discarded by the list. + + Archives: + + + + Subscription: + It is not necessary to subscribe to the list to send an + email. For subscribing to the list, or information about + it, go to + . + + Sign your emails with PGP + We encourage that you sign all of your emails sent to the + mailing list, (especially) including the ones containing + patches, with your PGP key. This helps establish trust between + you and other contributors of this project, and prevent others + impersonating you. If you don't have a key, it's not mandatory + to sign your email, but you're encouraged to create and start + using a PGP key. See also: + + + There are many ways you can sign your patches, and it depends on + your preferred tools. You can use neomutt(1) (>= 20240201) as a + driver for git-send-email(1). In <~/.gitconfig>, add the + following section: + + [sendemail] + sendmailcmd = neomutt -C -H - && true + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + + diff --git a/CONTRIBUTING.d/patches b/CONTRIBUTING.d/patches new file mode 100644 index 0000000..96550ce --- /dev/null +++ b/CONTRIBUTING.d/patches @@ -0,0 +1,94 @@ +Name + Patches - instructions for contributing patches + +Description + If you know how to fix a problem in a manual page (if not, see + ), then send a patch in an email. + + - Follow the instructions for sending mail to the mailing list + from . + + - The subject of the email should contain "[patch]" in the + subject line. + + The above is the minimum needed so that someone might respond to + your patch. If you did that and someone does not respond within + a few days, then ping the email thread, "replying to all". Make + sure to send it to the maintainers in addition to the mailing + list. + + To make your patch even more useful, please note the following + points: + + - Write a suitable subject line. Make sure to mention the + name(s) of the page(s) being patched. Example: + + [patch] shmop.2: Add "(void *)" cast to RETURN VALUE + + - Sign your patch with "Signed-off-by:". Read about the + "Developer's Certificate of Origin" at + . + When appropriate, other tags documented in that file, such as + "Reported-by:", "Reviewed-by:", "Acked-by:", and + "Suggested-by:" can be added to the patch. The man-pages + project also uses a "Cowritten-by:" tag with the obvious + meaning. Example: + + Signed-off-by: Alejandro Colomar + + - Describe how you obtained the information in your patch. For + example, was it: + + - by reading (or writing) the relevant kernel or (g)libc + source code? Please provide a pointer to the following + code. + + - from a commit message in the kernel or (g)libc source code + repository? Please provide a commit ID. + + - by writing a test program? Send it with the patch, but + please make sure it's as simple as possible, and provide + instructions on how to use it and/or a demo run. + + - from a standards document? Please name the standard, and + quote the relevant text. + + - from other documentation? Please provide a pointer to that + documentation. + + - from a mailing list or online forum? Please provide a URL + if possible. + + - Send patches in diff -u format in an email patch. You may + find it useful to employ git-send-email(1) and + git-format-patch(1). + + - Where relevant, include source code comments that cite commit + hashes for relevant kernel or glibc changes: + + .\" commit <40-character-git-hash> + + - For trivial patches, you can use subject tags: + + - ffix: Formatting fix. + - tfix: Typo fix. + - wfix: Minor wording fix. + - srcfix: Change to manual page source that doesn't affect + the output. + + Example: + + [patch] tcp.7: tfix + + - Send logically separate patches. For unrelated pages, or for + logically-separate issues in the same page, send separate + emails. + + - Make patches against the latest version of the manual page. + Use git(1) for getting the latest version. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + diff --git a/CONTRIBUTING.d/style b/CONTRIBUTING.d/style new file mode 100644 index 0000000..da34d1b --- /dev/null +++ b/CONTRIBUTING.d/style @@ -0,0 +1,21 @@ +Name + Style - preferred layout of manual pages and style guide notes + +Description + For a description of the preferred layout of manual pages, as + well as some style guide notes, see: + + $ man 7 man-pages + + It will also be interesting to consult groff_man(7) and + groff_man_style(7) for understanding and writing good man(7) + source code. + +See also + CONTRIBUTING + CONTRIBUTING.d/* + + man-pages(7) + groff_man(7) + groff_man_style(7) + groff_char(7) diff --git a/CPPLINT.cfg b/CPPLINT.cfg deleted file mode 100644 index 7bdd508..0000000 --- a/CPPLINT.cfg +++ /dev/null @@ -1,2 +0,0 @@ -filter=-build/include_subdir,-legal/copyright,-readability/alt_tokens,-readability/braces,-readability/casting,-readability/multiline_comment,-runtime/int,-runtime/threadsafe_fn,-whitespace/blank_line,-whitespace/braces - diff --git a/CPPLINT.cfg b/CPPLINT.cfg new file mode 120000 index 0000000..7afed40 --- /dev/null +++ b/CPPLINT.cfg @@ -0,0 +1 @@ +etc/cpplint/cpplint.cfg \ No newline at end of file diff --git a/Changes b/Changes index 1d2c608..c18bbfc 100644 --- a/Changes +++ b/Changes @@ -1,207 +1,40 @@ -==================== Changes in man-pages-6.05 ==================== - -Released: 2023-08-01, Aldaya - - -Contributors ------------- - -The following people contributed patches/fixes, reports, notes, -ideas, and discussions that have been incorporated in changes in -this release: - -"David S. Miller" -"G. Branden Robinson" -A. Wilcox -Adam Dobes -Ahelenia ZiemiaÅ„ska -Alan Cox -Alejandro Colomar -Alexei Starovoitov -Andreas Schwab -Andrew Clayton -Andrew Morton -Avinesh Kumar -Bastien Roucariès -Bjarni Ingi Gislason -Brian Inglis -Bruno Haible -Carsten Grohmann -Colin Watson -Cyril Hrubis -DJ Delorie -Daniel Verkamp -David Howells -Dirk Gouders -Dmitry Goncharov -Eli Zaretskii -Elliott Hughes -Eric Biggers -Eric Blake -Eric Wong -Fangrui Song -Florian Weimer -Gavin Smith -Guillem Jover -Günther Noack -Helge Kreutzmann -Igor Sysoev -Ingo Schwarze -Jakub Jelinek -Jakub Sitnicki -Jakub Wilk -Johannes Weiner -John Gilmore -John Hubbard -John Scott -Jonathan Corbet -Jonathan Wakely -Joseph Myers -Josh Triplett -Kirill A. Shutemov -Larry McVoy -Lennart Jablonka -Linus Heckemann -Lukas Javorsky -Marcos Fouces -Mario Blaettermann -Martin (Joey) Schulze -Masami Hiramatsu -Masatake YAMATO -Matthew House -Matthew Wilcox (Oracle) -Michael Kerrisk -Michael Weiß -Mickaël Salaün -Mike Frysinger -Mike Kravetz -Mingye Wang -Nadav Amit -Nick Desaulniers -Oskari Pirhonen -Paul E. McKenney -Paul Eggert -Paul Floyd -Paul Smith -Philip Guenther -Ralph Corderoy -Reuben Thomas -Rich Felker -Richard Biener -Sam James -Serge Hallyn -Seth David Schoen -Siddhesh Poyarekar -Simon Horman -Stefan Puiu -Steffen Nurpmeso -Szabolcs Nagy -Thomas Weißschuh -Tom Schwindl -Tomáš Golembiovský -Torbjorn SVENSSON -Ulrich Drepper -Vahid Noormofidi -Vlastimil Babka -Wilco Dijkstra -Xi Ruoyao -Yang Xu -Yedidyah Bar David -Zack Weinberg -Zijun Zhao - -Apologies if I missed anyone! +==================== Changes in man-pages-6.7 ===================== + +Released: 2024-03-19, València New and rewritten pages ----------------------- -man2/ - ioctl_pipe.2 - man3/ - regex.3 - -man5/ - erofs.5 + TIMEVAL_TO_TIMESPEC.3 Newly documented interfaces in existing pages --------------------------------------------- -bpf.2 - EAGAIN - -ioctl_userfaultfd.2 - UFFD_FEATURE_EXACT_ADDRESS - -prctl.2 - PR_GET_AUXV - -recv.2 - MSG_CMSG_CLOEXEC - -statx.2 - STAT_ATTR_MOUNT_ROOT - -syscall.2 - ENOSYS - -resolv.conf.5 - no-aaaa - RES_NOAAAA - -tmpfs.5 - CONFIG_TRANSPARENT_HUGEPAGE - -ip.7 - IP_LOCAL_PORT_RANGE - -rtnetlink.7 - IFLA_PERM_ADDRESS +man2/ + process_madvise.2 + process_madvise() glibc wrapper New and changed links --------------------- -man3type/ - regex_t.3type (regex(3)) - regmatch_t.3type (regex(3)) - regoff_t.3type (regex(3)) +man3/ + TIMESPEC_TO_TIMEVAL.3 (TIMEVAL_TO_TIMESPEC(3)) Global changes -------------- -- Types: - - Document functions using off64_t as if they used off_t (except - for lseek64()). - -- Build system: - - Keep file modes in the release tarball. - - Fix symlink installation (`make install LINK_PAGES=symlink`). - - Add support for using bzip2(1), lzip(1), and xz(1) when installing - pages and creating release tarballs. - - Create reproducible release tarballs. - - Move makefiles from lib/ to share/mk/. - - Support mdoc(7) pages. - - Relicense Makefiles as GPL-3.0-or-later. - - Build PostScript and PDF manual pages. - - Add support for running our build system on arbitrary source - trees; this makes it possible to easily run our linters on another - project's manual pages as easily as `make lint MANDIR=~/src/groff` - -- Licenses: - - Relicense ddp.7 from VERBATIM_ONE_PARA to Linux-man-pages-copyleft. - - Relicense dir_colors.5 from LDPv1 to GPL-2.0-or-later. - - Use new SPDX license identifiers: - - Linux-man-pages-1-para (was VERBATIM_ONE_PARA) - - Linux-man-pages-copyleft-2-para (was VERBATIM_TWO_PARA) - - Linux-man-pages-copyleft-var (was VERBATIM_PROF) - -- ffix: - - use `\%` - - un-bracket tbl(1) tables +- Build system + - Reorganize build system + - Clarify dependencies + - Clarify configurable variables + - Add 'distcheck' target + - Ignore known warnings + - Replace uses of man2html(1) by grohtml(1) Changes to individual pages @@ -209,10 +42,4 @@ Changes to individual pages The manual pages (and other files in the repository) have been improved beyond what this changelog covers. To learn more about changes applied -to individual pages, use git(1). - - -==================== Changes in man-pages-6.05.01 ================= - -- Build system: - - Ignore dot-dirs within $MANDIR +to individual pages, or the authors of changes, use git(1). diff --git a/Changes.old b/Changes.old index 3dfc4bc..fa134e5 100644 --- a/Changes.old +++ b/Changes.old @@ -55916,3 +55916,590 @@ Changes to individual pages The manual pages (and other files in the repository) have been improved beyond what this changelog covers. To learn more about changes applied to individual pages, use git(1). + + +==================== Changes in man-pages-6.05 ==================== + +Released: 2023-08-01, Aldaya + + +Contributors +------------ + +The following people contributed patches/fixes, reports, notes, +ideas, and discussions that have been incorporated in changes in +this release: + +"David S. Miller" +"G. Branden Robinson" +A. Wilcox +Adam Dobes +Ahelenia ZiemiaÅ„ska +Alan Cox +Alejandro Colomar +Alexei Starovoitov +Andreas Schwab +Andrew Clayton +Andrew Morton +Avinesh Kumar +Bastien Roucariès +Bjarni Ingi Gislason +Brian Inglis +Bruno Haible +Carsten Grohmann +Colin Watson +Cyril Hrubis +DJ Delorie +Daniel Verkamp +David Howells +Dirk Gouders +Dmitry Goncharov +Eli Zaretskii +Elliott Hughes +Eric Biggers +Eric Blake +Eric Wong +Fangrui Song +Florian Weimer +Gavin Smith +Guillem Jover +Günther Noack +Helge Kreutzmann +Igor Sysoev +Ingo Schwarze +Jakub Jelinek +Jakub Sitnicki +Jakub Wilk +Johannes Weiner +John Gilmore +John Hubbard +John Scott +Jonathan Corbet +Jonathan Wakely +Joseph Myers +Josh Triplett +Kirill A. Shutemov +Larry McVoy +Lennart Jablonka +Linus Heckemann +Lukas Javorsky +Marcos Fouces +Mario Blaettermann +Martin (Joey) Schulze +Masami Hiramatsu +Masatake YAMATO +Matthew House +Matthew Wilcox (Oracle) +Michael Kerrisk +Michael Weiß +Mickaël Salaün +Mike Frysinger +Mike Kravetz +Mingye Wang +Nadav Amit +Nick Desaulniers +Oskari Pirhonen +Paul E. McKenney +Paul Eggert +Paul Floyd +Paul Smith +Philip Guenther +Ralph Corderoy +Reuben Thomas +Rich Felker +Richard Biener +Sam James +Serge Hallyn +Seth David Schoen +Siddhesh Poyarekar +Simon Horman +Stefan Puiu +Steffen Nurpmeso +Szabolcs Nagy +Thomas Weißschuh +Tom Schwindl +Tomáš Golembiovský +Torbjorn SVENSSON +Ulrich Drepper +Vahid Noormofidi +Vlastimil Babka +Wilco Dijkstra +Xi Ruoyao +Yang Xu +Yedidyah Bar David +Zack Weinberg +Zijun Zhao + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +man2/ + ioctl_pipe.2 + +man3/ + regex.3 + +man5/ + erofs.5 + + +Newly documented interfaces in existing pages +--------------------------------------------- + +bpf.2 + EAGAIN + +ioctl_userfaultfd.2 + UFFD_FEATURE_EXACT_ADDRESS + +prctl.2 + PR_GET_AUXV + +recv.2 + MSG_CMSG_CLOEXEC + +statx.2 + STAT_ATTR_MOUNT_ROOT + +syscall.2 + ENOSYS + +resolv.conf.5 + no-aaaa + RES_NOAAAA + +tmpfs.5 + CONFIG_TRANSPARENT_HUGEPAGE + +ip.7 + IP_LOCAL_PORT_RANGE + +rtnetlink.7 + IFLA_PERM_ADDRESS + + +New and changed links +--------------------- + +man3type/ + regex_t.3type (regex(3)) + regmatch_t.3type (regex(3)) + regoff_t.3type (regex(3)) + + +Global changes +-------------- + +- Types: + - Document functions using off64_t as if they used off_t (except + for lseek64()). + +- Build system: + - Keep file modes in the release tarball. + - Fix symlink installation (`make install LINK_PAGES=symlink`). + - Add support for using bzip2(1), lzip(1), and xz(1) when installing + pages and creating release tarballs. + - Create reproducible release tarballs. + - Move makefiles from lib/ to share/mk/. + - Support mdoc(7) pages. + - Relicense Makefiles as GPL-3.0-or-later. + - Build PostScript and PDF manual pages. + - Add support for running our build system on arbitrary source + trees; this makes it possible to easily run our linters on another + project's manual pages as easily as `make lint MANDIR=~/src/groff` + +- Licenses: + - Relicense ddp.7 from VERBATIM_ONE_PARA to Linux-man-pages-copyleft. + - Relicense dir_colors.5 from LDPv1 to GPL-2.0-or-later. + - Use new SPDX license identifiers: + - Linux-man-pages-1-para (was VERBATIM_ONE_PARA) + - Linux-man-pages-copyleft-2-para (was VERBATIM_TWO_PARA) + - Linux-man-pages-copyleft-var (was VERBATIM_PROF) + +- ffix: + - use `\%` + - un-bracket tbl(1) tables + + +Changes to individual pages +--------------------------- + +The manual pages (and other files in the repository) have been improved +beyond what this changelog covers. To learn more about changes applied +to individual pages, use git(1). + + +==================== Changes in man-pages-6.06 ==================== + +Released: 2024-02-12, Aldaya + + +Contributors +------------ + +The following people contributed patches/fixes, reports, notes, +ideas, and discussions that have been incorporated in changes in +this release: + +"G. Branden Robinson" +"G. Branden Robinson" +"Huang, Ying" +"Serge E. Hallyn" +Adhemerval Zanella Netto +Ahelenia ZiemiaÅ„ska +Alejandro Colomar +Alexander Kozhevnikov +Alexey Tikhonov +Amir Goldstein +Andreas Schwab +Andreas Schwab +Andreas Schwab +Andriy Utkin +Arnav Rawat +Arnd Bergmann +Aurelien Jarno +Avinesh Kumar +Axel Rasmussen +Brian Inglis +Bruno Haible +Carlos O'Donell +Catalin Marinas +Christian Brauner +Christopher Lameter +Colin Watson +DJ Delorie +David Mosberger +Deri James +Don Brace +Elliott Hughes +Florent Revest +Florian Lehner +Florian Weimer +G. Branden Robinson +Geoff Keating +Gobinda Das +Greg Kroah-Hartman +Guillem Jover +Guo Ren +Guo Ren +Günther Noack +Hanno Böck +Helge Kreutzmann +Iker Pedrosa +Ingo Schwarze +Ingo Schwarze +Jakub Jelinek +Jakub Wilk +Jan Engelhardt +Jan Kara +John Watts +Jonathan Wakely +Jonny Grant +Kees Cook +Kevin Barnett +Kuniyuki Iwashima +Lee Griffiths +Luis Chamberlain +Maciej Å»enczykowski +Mario Blaettermann +Matthew House +Matthias Gerstner +Max Kellermann +Michael Kerrisk +Miguel de Icaza +Mike McGowen +Mike Rapoport (IBM) +Morten Welinder +Muhammad Usama Anjum +Oskari Pirhonen +Patch by Xavier Leroy . +Paul Eggert +Paul Smith +Peter Xu +Petr Vorel +Philip Blundell +Renzo Davoli +Reported by Ralf Corsepius . +Reported by Sam Roberts . +Richard Henderson +Richard Henderson +Richard Henderson +Rik van Riel +Roland McGrath +Sam James +Sambit Nayak +Samuel Thibault +Sargun Dhillon +Sascha Grunert +Sascha Grunert +Scott Benesh +Scott Teel +Serge Hallyn +Sergei Gromeniuk +Shahab Ouraie +Shani Leviim +Stefan Puiu +Thorsten Kukuk +Tom Schwindl +Tomáš Golembiovský +Ulrich Drepper +Ulrich Drepper +Wolfram Gloger +Wolfram Gloger +Xavier Leroy +Xi Ruoyao +Yafang Shao +Yang Xu +Zack Weinberg +Å tÄ›pán NÄ›mec +ДилÑн Палаузов +наб + +Apologies if I missed anyone! + + +New and rewritten pages +----------------------- + +man2/ + ioctl_pagemap_scan.2 + +man3/ (taken from glibc's linuxthreads) + pthread_cond_init.3 + pthread_condattr_init.3 + pthread_key_create.3 + pthread_mutex_init.3 + pthread_mutexattr_setkind_np.3 + pthread_once.3 + +man5/ + proc.5 (split into many small pages) + proc_apm.5 + proc_buddyinfo.5 + proc_bus.5 + proc_cgroups.5 + proc_cmdline.5 + proc_config.gz.5 + proc_cpuinfo.5 + proc_crypto.5 + proc_devices.5 + proc_diskstats.5 + proc_dma.5 + proc_driver.5 + proc_execdomains.5 + proc_fb.5 + proc_filesystems.5 + proc_fs.5 + proc_ide.5 + proc_interrupts.5 + proc_iomem.5 + proc_ioports.5 + proc_kallsyms.5 + proc_kcore.5 + proc_key-users.5 + proc_keys.5 + proc_kmsg.5 + proc_kpagecgroup.5 + proc_kpagecount.5 + proc_kpageflags.5 + proc_ksyms.5 + proc_loadavg.5 + proc_locks.5 + proc_malloc.5 + proc_meminfo.5 + proc_modules.5 + proc_mtrr.5 + proc_partitions.5 + proc_pci.5 + proc_pid.5 + proc_pid_attr.5 + proc_pid_autogroup.5 + proc_pid_auxv.5 + proc_pid_cgroup.5 + proc_pid_clear_refs.5 + proc_pid_cmdline.5 + proc_pid_comm.5 + proc_pid_coredump_filter.5 + proc_pid_cpuset.5 + proc_pid_cwd.5 + proc_pid_environ.5 + proc_pid_exe.5 + proc_pid_fd.5 + proc_pid_fdinfo.5 + proc_pid_io.5 + proc_pid_limits.5 + proc_pid_map_files.5 + proc_pid_maps.5 + proc_pid_mem.5 + proc_pid_mountinfo.5 + proc_pid_mounts.5 + proc_pid_mountstats.5 + proc_pid_net.5 + proc_pid_ns.5 + proc_pid_numa_maps.5 + proc_pid_oom_score.5 + proc_pid_oom_score_adj.5 + proc_pid_pagemap.5 + proc_pid_personality.5 + proc_pid_projid_map.5 + proc_pid_root.5 + proc_pid_seccomp.5 + proc_pid_setgroups.5 + proc_pid_smaps.5 + proc_pid_stack.5 + proc_pid_stat.5 + proc_pid_statm.5 + proc_pid_status.5 + proc_pid_syscall.5 + proc_pid_task.5 + proc_pid_timers.5 + proc_pid_timerslack_ns.5 + proc_pid_uid_map.5 + proc_pid_wchan.5 + proc_profile.5 + proc_scsi.5 + proc_slabinfo.5 + proc_stat.5 + proc_swaps.5 + proc_sys.5 + proc_sys_abi.5 + proc_sys_debug.5 + proc_sys_dev.5 + proc_sys_fs.5 + proc_sys_kernel.5 + proc_sys_net.5 + proc_sys_proc.5 + proc_sys_sunrpc.5 + proc_sys_user.5 + proc_sys_vm.5 + proc_sysrq-trigger.5 + proc_sysvipc.5 + proc_tid_children.5 + proc_timer_list.5 + proc_timer_stats.5 + proc_tty.5 + proc_uptime.5 + proc_version.5 + proc_vmstat.5 + proc_zoneinfo.5 + + +Newly documented interfaces in existing pages +--------------------------------------------- + +man2/ + access.2 + AT_EMPTY_PATH + + execve.2 + E2BIG + + ioctl_userfaultfd.2 + UFFDIO_API handshake + UFFDIO_POISON + UFFD_FEATURE_WP_ASYNC + + mbind.2 + MPOL_F_NUMA_BALANCING + + prctl.2 + PR_SET_MDWE + PR_GET_MDWE + + set_thread_area.2 + C-SKY + + utimensat.2 + AT_EMPTY_PATH + +man3/ + stdio.3 + fmemopen(3) + fopencookie(3) + open_memstream(3) + open_wmemstream(3) + +man4/ + smartpqi.4 + ctrl_ready_timeout + enable_stream_detection + ssd_smart_path_enabled + enable_r5_writes + enable_r6_writes + lunid + unique_id + path_info + raid_bypass_cnt + sas_ncq_prio_enable + +man5/ + proc_pid_status.5 (previously, proc.5) + Seccomp_filters + + tmpfs.5 + size/blocks=0 + nr_inodes=0 + +man8/ + ld.so.8 + --list-diagnostics + --glibc-hwcaps-mask + --glibc-hwcaps-prepend + + +New and changed links +--------------------- + +man5/ + proc_mounts.5 (proc_pid_mounts(5)) + proc_net.5 (proc_pid_net(5)) + proc_pid_gid_map.5 (proc_pid_uid_map(5)) + proc_pid_oom_adj.5 (proc_pid_oom_score_adj(5)) + proc_self.5 (proc_pid(5)) + proc_thread-self.5 (proc_pid_task(5)) + proc_tid.5 (proc_pid_task(5)) + + +Removed links +------------- + +man3/ + stpecpy.3 + stpecpyx.3 + ustpcpy.3 + ustr2stp.3 + zustr2stp.3 + zustr2ustp.3 + + +Global changes +-------------- + +- Build system + - Update PDF book for groff-1.23.0. + - Add targets to [un]install intro(*) pages separately. + - Support manual pages in other projects, so that our build system + can be used to for example lint them. + - Reject non-GNU make(1). + - Add target to build the PDF book. + +- man*/ + - Add some consistency in the use of man(7). + - Split proc(5) into many small pages. + - Import pages from old linuxthreads (glibc), with their git + history (from both glibc and Debian). + - Rewrite a large part of the documentation for string-copying + functions. + - Say ISO/IEC instead of ISO where appropriate, and be consistent in + the formatting of names of ISO or ISO/IEC standards. + + +Changes to individual pages +--------------------------- + +The manual pages (and other files in the repository) have been improved +beyond what this changelog covers. To learn more about changes applied +to individual pages, use git(1). diff --git a/GNUmakefile b/GNUmakefile new file mode 100644 index 0000000..7baa19b --- /dev/null +++ b/GNUmakefile @@ -0,0 +1,66 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +BASH := bash +SHELL := /usr/bin/env +.SHELLFLAGS := -S '$(BASH) -Eeuo pipefail -c' + + +MAKEFLAGS += --no-builtin-rules +MAKEFLAGS += --no-builtin-variables +MAKEFLAGS += --warn-undefined-variables + + +srcdir := . +DATAROOTDIR := $(srcdir)/share +MAKEFILEDIR := $(DATAROOTDIR)/mk + + +INFO_ := + + +.PHONY: all +all: build; + + +.SECONDEXPANSION: + + +MK_ := $(wildcard $(addprefix $(MAKEFILEDIR)/, *.mk */*.mk */*/*.mk)) +MK := $(srcdir)/GNUmakefile $(MK_) +include $(MK_) +$(MK):: ; + + +.PHONY: nothing +nothing:; + + +.PHONY: help +help: + $(info $(INFO_)To see a list of .PHONY targets, run:) + $(info $(INFO_) $$ make nothing -p \) + $(info $(INFO_) | grep '^\.PHONY:' \) + $(info $(INFO_) | tr ' ' '\n' \) + $(info $(INFO_) | grep -v '^\.PHONY:' \) + $(info $(INFO_) | sort;) + $(info ) + $(info $(INFO_)To see a list of available variables, run:) + $(info $(INFO_) $$ find GNUmakefile share/mk/configure -type f \) + $(info $(INFO_) | sort \) + $(info $(INFO_) | xargs grep '^[^[:space:]].*=' \) + $(info $(INFO_) | sed 's/=.*/=/';) + $(info ) + $(info ) + $(info $(INFO_)To see a list of dependencies, run:) + $(info $(INFO_) $$ find share/mk/configure/build-depends -type f \) + $(info $(INFO_) | sed 's,share/mk/configure/build-depends/,,' \) + $(info $(INFO_) | sed 's,\.mk,,' \) + $(info $(INFO_) | sort;) + $(info ) + + +.DELETE_ON_ERROR: +.SILENT: +FORCE: diff --git a/INSTALL b/INSTALL index d12fd7a..0fdc36f 100644 --- a/INSTALL +++ b/INSTALL @@ -2,7 +2,7 @@ Name Install - instructions for installing the pages into the system Synopsis - sudo make [-j] install [V=1] [prefix=ARG] [DESTDIR=ARG] [...] + sudo make [-j] install [prefix=ARG] [DESTDIR=ARG] [...] Description (a) Use a package manager @@ -46,17 +46,13 @@ Description are specially designed for this project. To see all of the available variables, use: - $ make help-variables + $ make help The most common ones that you may use are: - DESTDIR - prefix - Use V=1 for a more verbose output from the makefiles: - - $ sudo make install V=1 - Uninstall You can uninstall the pages with the following command (but see the "Caveats" section below): @@ -70,60 +66,13 @@ Description $ make help Dependencies - - Build-depends: - - Generic: - - echo(1) - - expr(1) - - find(1) - - grep(1) - - locale(1) - - make(1) - GNU Make is required. - - sed(1) - - sort(1) - - xargs(1) - - - For installing: - - gzip(1) - - install(1) - - ln(1) - - sponge(1) - - test(1) - - - For uninstalling / cleaning: - - rm(1) - - rmdir(1) - - - For linting/building/checking man(7) source: - - eqn(1) - - grotty(1) - - head(1) - - mkdir(1) - - tail(1) - - tbl(1) - - troff(1) >= 1.23.0 - GNU troff is required. - - - For linting/building C source: - - cc(1) - GCC or Clang - - clang-tidy(1) - - cpplint(1) - - iwyu(1) - - mandoc(1) - - mkdir(1) - - pkg-config(1) - - tac(1) - - libbsd-dev - - And one that isn't packaged, but can be extracted from the - Linux kernel source tree in : - - - checkpatch(1) - - - For building HTML pages: - - man2html(1) - - - Depends: - - man(1) - - groff(1) | mandoc(1) + To see the build-dependencies of the project, that is, the + dependencies of the build system, see `make help`. + + To read the manual pages, you'll need: + + - man(1) + - groff(1) | mandoc(1) Lint & check You can lint and check both the manual pages, and the example C @@ -131,7 +80,7 @@ Description targets that can be used. Files - Makefile, share/mk/install-man.mk, share/mk/install.mk + GNUmakefile, share/mk/install-man.mk, share/mk/install.mk Main makefiles for installing (however, others may also be used by inclusion). diff --git a/LICENSES/BSD-2-Clause.txt b/LICENSES/BSD-2-Clause.txt index 5f662b3..eb3c575 100644 --- a/LICENSES/BSD-2-Clause.txt +++ b/LICENSES/BSD-2-Clause.txt @@ -1,4 +1,4 @@ -Copyright (c) +Copyright (c) Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/LICENSES/BSD-3-Clause.txt b/LICENSES/BSD-3-Clause.txt index ea890af..086d399 100644 --- a/LICENSES/BSD-3-Clause.txt +++ b/LICENSES/BSD-3-Clause.txt @@ -1,4 +1,4 @@ -Copyright (c) . +Copyright (c) . Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/LICENSES/LGPL-3.0-linking-exception.txt b/LICENSES/LGPL-3.0-linking-exception.txt new file mode 100644 index 0000000..186456f --- /dev/null +++ b/LICENSES/LGPL-3.0-linking-exception.txt @@ -0,0 +1,16 @@ +As a special exception to the GNU Lesser General Public License version 3 +("LGPL3"), the copyright holders of this Library give you permission to +convey to a third party a Combined Work that links statically or dynamically +to this Library without providing any Minimal Corresponding Source or +Minimal Application Code as set out in 4d or providing the installation +information set out in section 4e, provided that you comply with the other +provisions of LGPL3 and provided that you meet, for the Application the +terms and conditions of the license(s) which apply to the Application. + +Except as stated in this special exception, the provisions of LGPL3 will +continue to comply in full to this Library. If you modify this Library, you +may apply this exception to your version of this Library, but you are not +obliged to do so. If you do not wish to do so, delete this exception +statement from your version. This exception does not (and cannot) modify any +license terms which apply to the Application, with which you must still +comply. diff --git a/LICENSES/LGPL-3.0-or-later.txt b/LICENSES/LGPL-3.0-or-later.txt new file mode 100644 index 0000000..513d1c0 --- /dev/null +++ b/LICENSES/LGPL-3.0-or-later.txt @@ -0,0 +1,304 @@ +GNU LESSER GENERAL PUBLIC LICENSE +Version 3, 29 June 2007 + +Copyright (C) 2007 Free Software Foundation, Inc. + +Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. + +This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. + +0. Additional Definitions. + +As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. + +"The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. + +An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. + +A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version". + +The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. + +The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. + +1. Exception to Section 3 of the GNU GPL. +You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. + +2. Conveying Modified Versions. +If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: + + a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or + + b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. + +3. Object Code Incorporating Material from Library Header Files. +The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: + + a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. + + b) Accompany the object code with a copy of the GNU GPL and this license document. + +4. Combined Works. +You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: + + a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. + + b) Accompany the Combined Work with a copy of the GNU GPL and this license document. + + c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. + + d) Do one of the following: + + 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. + + 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. + + e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) + +5. Combined Libraries. +You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: + + a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. + + b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. + +6. Revised Versions of the GNU Lesser General Public License. +The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. + +If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall +apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library. + +GNU GENERAL PUBLIC LICENSE +Version 3, 29 June 2007 + +Copyright © 2007 Free Software Foundation, Inc. + +Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. + +Preamble + +The GNU General Public License is a free, copyleft license for software and other kinds of works. + +The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. + +For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. + +Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. + +Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. + +Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and modification follow. + +TERMS AND CONDITIONS + +0. Definitions. + +“This License†refers to version 3 of the GNU General Public License. + +“Copyright†also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. + +“The Program†refers to any copyrightable work licensed under this License. Each licensee is addressed as “youâ€. “Licensees†and “recipients†may be individuals or organizations. + +To “modify†a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version†of the earlier work or a work “based on†the earlier work. + +A “covered work†means either the unmodified Program or a work based on the Program. + +To “propagate†a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. + +To “convey†a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. + +An interactive user interface displays “Appropriate Legal Notices†to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. + +1. Source Code. +The “source code†for a work means the preferred form of the work for making modifications to it. “Object code†means any non-source form of a work. + +A “Standard Interface†means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. + +The “System Libraries†of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Componentâ€, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. + +The “Corresponding Source†for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same work. + +2. Basic Permissions. +All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. + +3. Protecting Users' Legal Rights From Anti-Circumvention Law. +No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. + +When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. + +4. Conveying Verbatim Copies. +You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. + +5. Conveying Modified Source Versions. +You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all noticesâ€. + + c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. + +A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate†if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. + +6. Conveying Non-Source Forms. +You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: + + a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. + + d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. + +A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. + +A “User Product†is either (1) a “consumer productâ€, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used†refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. + +“Installation Information†for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. + +If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). + +The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. + +Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. + +7. Additional Terms. +“Additional permissions†are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or authors of the material; or + + e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. + +All other non-permissive additional terms are considered “further restrictions†within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. + +8. Termination. +You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). + +However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. + +Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. + +Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. + +9. Acceptance Not Required for Having Copies. +You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. + +10. Automatic Licensing of Downstream Recipients. +Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. + +An “entity transaction†is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. + +11. Patents. +A “contributor†is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor versionâ€. + +A contributor's “essential patent claims†are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control†includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. + +In the following three paragraphs, a “patent license†is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant†such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. + +If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying†means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. + +A patent license is “discriminatory†if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. + +12. No Surrender of Others' Freedom. +If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. + +13. Use with the GNU Affero General Public License. +Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. + +14. Revised Versions of this License. +The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version†applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. + +If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. + +Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. + +15. Disclaimer of Warranty. +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS†WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +16. Limitation of Liability. +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +17. Interpretation of Sections 15 and 16. +If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS + +How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. + +To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright†line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an “about boxâ€. + +You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer†for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see . + +The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read . diff --git a/LICENSES/Linux-man-pages-copyleft-var.txt b/LICENSES/Linux-man-pages-copyleft-var.txt index 1742303..79e8369 100644 --- a/LICENSES/Linux-man-pages-copyleft-var.txt +++ b/LICENSES/Linux-man-pages-copyleft-var.txt @@ -1,16 +1,16 @@ -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice are preserved on all copies. -Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided -that the entire resulting derived work is distributed under the +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided +that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. -Since the Linux kernel and libraries are constantly changing, this -manual page may be incorrect or out-of-date. The author(s) assume -no responsibility for errors or omissions, or for damages resulting +Since the Linux kernel and libraries are constantly changing, this +manual page may be incorrect or out-of-date. The author(s) assume +no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. -Formatted or processed versions of this manual, if unaccompanied by +Formatted or processed versions of this manual, if unaccompanied by the source, must acknowledge the copyright and authors of this work. diff --git a/Makefile b/Makefile deleted file mode 100644 index 56f288c..0000000 --- a/Makefile +++ /dev/null @@ -1,234 +0,0 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## -# Conventions: -# -# - Follow "Makefile Conventions" from the "GNU Coding Standards" closely. -# However, when something could be improved, don't follow those. -# - Uppercase variables, when referring files, refer to files in this repo. -# - Lowercase variables, when referring files, refer to system files. -# - Lowercase variables starting with '_' refer to absolute paths, -# including $(DESTDIR). -# - Uppercase variables starting with '_' refer to temporary files produced -# in $builddir. -# - Variables ending with '_' refer to a subdir of their parent dir, which -# is in a variable of the same name but without the '_'. The subdir is -# named after this project: <*/man>. -# - Variables ending in '_rm' refer to files that can be removed (exist). -# - Targets of the form '%-rm' remove their corresponding file '%'. -# -######################################################################## - - -ifndef MAKEFILE_INCLUDED -MAKEFILE_INCLUDED := 1 - - -SHELL := /usr/bin/env bash -Eeuo pipefail - - -MAKEFLAGS += --no-builtin-rules -MAKEFLAGS += --no-builtin-variables -MAKEFLAGS += --warn-undefined-variables - - -srcdir := . -DATAROOTDIR := $(srcdir)/share -MAKEFILEDIR := $(DATAROOTDIR)/mk - - -.PHONY: all -all: build; - -.PHONY: help -help: - $(info all Alias for "build") - $(info ) - $(info clean Remove $$(builddir)) - $(info ) - $(info build Wrapper for build-* targets) - $(info ) - $(info build-pre Preprocess man pages; alias for "build-pre-tbl") - $(info build-pre-preconv Preprocess man pages with preconv(1)) - $(info build-pre-tbl Preprocess man pages with tbl(1)) - $(info ) - $(info build-catman Build cat pages; alias for "build-catman-grotty") - $(info build-catman-eqn eqn(1) step of "build-catman") - $(info build-catman-troff Wrapper for build-catman-troff-* targets) - $(info build-catman-troff-man troff(1) step of "build-catman" for man(7) pages) - $(info build-catman-troff-mdoc troff(1) step of "build-catman" for mdoc(7) pages) - $(info build-catman-grotty grotty(1) step of "build-catman") - $(info ) - $(info build-html Build HTML manual pages) - $(info html Alias for "build-html") - $(info ) - $(info build-pdf Build PDF manual pages; alias for "build-pdf-grops") - $(info build-pdf-eqn eqn(1) step of "build-pdf") - $(info build-pdf-troff Wrapper for build-pdf-troff-* targets) - $(info build-pdf-troff-man troff(1) step of "build-pdf" for man(7) pages) - $(info build-pdf-troff-mdoc troff(1) step of "build-pdf" for mdoc(7) pages) - $(info build-pdf-gropdf gropdf(1) step of "build-pdf") - $(info ) - $(info build-ps Build PostScript manual pages; alias for "build-ps-grops") - $(info build-ps-eqn eqn(1) step of "build-ps") - $(info build-ps-troff Wrapper for build-ps-troff-* targets) - $(info build-ps-troff-man troff(1) step of "build-ps" for man(7) pages) - $(info build-ps-troff-mdoc troff(1) step of "build-ps" for mdoc(7) pages) - $(info build-ps-grops grops(1) step of "build-ps") - $(info ) - $(info build-src Alias for "build-src-ld") - $(info build-src-c Extract C programs from EXAMPLES) - $(info build-src-cc Compile C programs from EXAMPLES) - $(info build-src-ld Link C programs from EXAMPLES) - $(info ) - $(info lint Wrapper for "lint-c lint-man lint-mdoc") - $(info lint-c Wrapper for lint-c-* targets) - $(info lint-c-checkpatch Lint C programs from EXAMPLES with checkpatch(1)) - $(info lint-c-clang-tidy Lint C programs from EXAMPLES with clang-tidy(1)) - $(info lint-c-cppcheck Lint C programs from EXAMPLES with cppcheck(1)) - $(info lint-c-cpplint Lint C programs from EXAMPLES with cpplint(1)) - $(info lint-c-iwyu Lint C programs from EXAMPLES with iwyu(1)) - $(info lint-man Wrapper for lint-man-* targets) - $(info lint-man-mandoc Lint man(7) pages with mandoc(1)) - $(info lint-man-tbl Lint man(7) pages about '\" t' comment for tbl(1)) - $(info lint-mdoc Wrapper for lint-mdoc-* targets) - $(info lint-mdoc-mandoc Lint mdoc(7) pages with mandoc(1)) - $(info ) - $(info check Alias for "check-catman") - $(info check-catman Check cat pages; alias for "check-catman-grep") - $(info check-catman-col Filter cat pages with col(1)) - $(info check-catman-grep Check cat pages with grep(1)) - $(info ) - $(info [un]install Alias for "[un]install-man") - $(info [un]install-man Wrapper for [un]install-man* targets) - $(info [un]install-man1 [Un]install man pages in section 1) - $(info [un]install-man2 [Un]install man pages in section 2) - $(info [un]install-man2type [Un]install man pages in section 2type) - $(info [un]install-man3 [Un]install man pages in section 3) - $(info [un]install-man3const [Un]install man pages in section 3const) - $(info [un]install-man3head [Un]install man pages in section 3head) - $(info [un]install-man3type [Un]install man pages in section 3type) - $(info [un]install-man4 [Un]install man pages in section 4) - $(info [un]install-man5 [Un]install man pages in section 5) - $(info [un]install-man6 [Un]install man pages in section 6) - $(info [un]install-man7 [Un]install man pages in section 7) - $(info [un]install-man8 [Un]install man pages in section 8) - $(info ) - $(info [un]install-html [Un]install HTML manual pages) - $(info ) - $(info dist Wrapper for dist-* targets) - $(info dist-tar Create a tarball of the repository) - $(info dist-bz2 Create a compressed tarball (.tar.bz2)) - $(info dist-gz Create a compressed tarball (.tar.gz)) - $(info dist-lz Create a compressed tarball (.tar.lz)) - $(info dist-xz Create a compressed tarball (.tar.xz)) - $(info ) - $(info help Print this help) - $(info help-variables Print all variables available, and their default values) - $(info ) - - -.SECONDEXPANSION: - - -MK := \ - $(srcdir)/Makefile \ - $(wildcard $(addprefix $(MAKEFILEDIR)/, *.mk */*.mk */*/*.mk)) -include $(MK) -$(MK):: ; - - -.PHONY: help-variables -help-variables: - $(info V Define to non-empty string for verbose output) - $(info ) - $(info LINK_PAGES How to install link pages. [".so", "symlink"]) - $(info Z Install pages compressed. ["", ".bz2", ".gz", ".lz", ".xz"]) - $(info ) - $(info DISTNAME $$(git describe)) - $(info DISTVERSION /$$DISTNAME/s/man-pages-//) - $(info ) - $(info # Directory variables:) - $(info ) - $(info builddir .tmp) - $(info DESTDIR ) - $(info prefix /usr/local) - $(info mandir $$(datarootdir)/man) - $(info docdir $$(datarootdir)/doc) - $(info ) - $(info man1dir $$(mandir)/man1) - $(info man2dir $$(mandir)/man2) - $(info man2typedir $$(mandir)/man2type) - $(info man3dir $$(mandir)/man3) - $(info man3constdir $$(mandir)/man3const) - $(info man3headdir $$(mandir)/man3head) - $(info man3typedir $$(mandir)/man3type) - $(info man4dir $$(mandir)/man4) - $(info man5dir $$(mandir)/man5) - $(info man6dir $$(mandir)/man6) - $(info man7dir $$(mandir)/man7) - $(info man8dir $$(mandir)/man8) - $(info ) - $(info htmldir $$(docdir)) - $(info htmlext .html) - $(info ) - $(info # Command variables (and flags):) - $(info ) - $(info - MANWIDTH) - $(info - NROFF_OUT_DEVICE) - $(info PRECONV {EXTRA_,}PRECONVFLAGS) - $(info TBL) - $(info EQN {EXTRA_,}EQNFLAGS) - $(info TROFF {EXTRA_,}TROFFFLAGS{,_MAN,_MDOC} {EXTRA_,}NROFFFLAGS) - $(info GROPDF {EXTRA_,}GROPDFFLAGS) - $(info GROPS {EXTRA_,}GROPSFLAGS) - $(info GROTTY {EXTRA_,}GROTTYFLAGS) - $(info COL {EXTRA_,}COLFLAGS) - $(info ) - $(info MANDOC {EXTRA_,}MANDOCFLAGS) - $(info MAN2HTML {EXTRA_,}MAN2HTMLFLAGS) - $(info ) - $(info BZIP2 {EXTRA_,}BZIP2FLAGS) - $(info CP) - $(info ECHO) - $(info EXPR) - $(info FIND) - $(info GIT) - $(info GZIP {EXTRA_,}GZIPFLAGS) - $(info HEAD) - $(info LN) - $(info LOCALE) - $(info LZIP {EXTRA_,}LZIPFLAGS) - $(info PKGCONF) - $(info SED) - $(info SORT) - $(info SPONGE) - $(info TAC) - $(info TAIL) - $(info TAR) - $(info TEST) - $(info XARGS) - $(info XZ {EXTRA_,}XZFLAGS) - $(info ) - $(info INSTALL) - $(info INSTALL_DATA) - $(info MKDIR) - $(info RM) - $(info ) - $(info - {EXTRA_,}CPPFLAGS) - $(info CC {EXTRA_,}CFLAGS) - $(info LD {EXTRA_,}LDFLAGS {EXTRA_,}LDLIBS) - $(info ) - $(info CHECKPATCH {EXTRA_,}CHECKPATCHFLAGS) - $(info CLANG-TIDY {EXTRA_,}CLANG-TIDYFLAGS) - $(info CPPCHECK {EXTRA_,}CPPCHECKFLAGS) - $(info CPPLINT {EXTRA_,}CPPLINTFLAGS) - $(info IWYU {EXTRA_,}IWYUFLAGS) - $(info ) - - -.DELETE_ON_ERROR: - - -endif #include guard diff --git a/README b/README index 9925ac1..ad65c8d 100644 --- a/README +++ b/README @@ -17,6 +17,7 @@ Description Files CONTRIBUTING + CONTRIBUTING.d/* Instructions for reporting bugs and contributing. INSTALL @@ -35,16 +36,13 @@ Files Change log. Includes most relevant changes. However, it's not as complete as the git(1) log. - Makefile, share/mk/* + GNUmakefile, share/mk/* Build system. For help, consult the file, and run 'make help'. lsm Linux software map. See also . - .mailmap - See gitmailmap(5). - LICENSES/*.txt Licenses in use by the project. @@ -62,20 +60,20 @@ Files Default directory for files created by the build system. Versions - Tarballs - + Distribution + + Git - - - A secondary git(1) repository can be found at: - - + Online man-pages PDF - + + + HTML + History Tarballs @@ -83,7 +81,7 @@ History Maintainers - Alejandro Colomar + Alejandro Colomar 2020 - present (5.09 - HEAD) Michael Kerrisk 2004 - 2021 (2.00 - 5.13) @@ -107,7 +105,7 @@ See also man-pages(7) Website - . + . Downstream packages Arch man-pages diff --git a/RELEASE b/RELEASE index aff3287..90a4612 100644 --- a/RELEASE +++ b/RELEASE @@ -12,23 +12,8 @@ Description release, you only need step (4) "Tarball". Dependencies - The following list of dependencies states what the build system - (the makefiles) need to perform the relevant (dist) targets: - - - echo(1) - - expr(1) - - find(1) - - git(1) - - grep(1) - - gzip(1) - - install(1) - - locale(1) - - make(1) - GNU Make is required. - - sed(1) - - sort(1) - - tar(1) - GNU tar is required. - - xargs(1) - - xz(1) + To see the build-dependencies of the project, that is, the + dependencies of the build system, see `make help`. Apart from that, the following commands are also needed for other tasks shown below: @@ -188,7 +173,7 @@ Files Changes, Changes.old Change log. Includes most relevant changes. - Makefile, share/mk/dist.mk, share/mk/version.mk + GNUmakefile, share/mk/dist.mk, share/mk/version.mk Main makefiles used for releasing (however, others may also be used by inclusion). diff --git a/etc/checkpatch/checkpatch.conf b/etc/checkpatch/checkpatch.conf new file mode 100644 index 0000000..3bf7c0a --- /dev/null +++ b/etc/checkpatch/checkpatch.conf @@ -0,0 +1,36 @@ +--ignore AVOID_EXTERNS +--ignore BLOCK_COMMENT_STYLE +--ignore BRACES +--ignore CAMELCASE +--ignore CODE_INDENT +--ignore COMPARISON_TO_NULL +--ignore COMPLEX_MACRO +--ignore CONCATENATED_STRING +--ignore EMBEDDED_FUNCTION_NAME +--ignore FUNCTION_ARGUMENTS +--ignore INDENTED_LABEL +--ignore INITIALISED_STATIC +--ignore LEADING_SPACE +--ignore LINE_SPACING +--ignore LOGICAL_CONTINUATIONS +--ignore MACRO_ARG_REUSE +--ignore MULTIPLE_ASSIGNMENTS +--ignore OPEN_BRACE +--ignore PARENTHESIS_ALIGNMENT +--ignore PREFER_FALLTHROUGH +--ignore PREFER_KERNEL_TYPES +--ignore SPACING +--ignore SPDX_LICENSE_TAG +--ignore SPLIT_STRING +--ignore STATIC_CONST_CHAR_ARRAY +--ignore SUSPECT_CODE_INDENT +--ignore TRAILING_STATEMENTS +--ignore UNNECESSARY_PARENTHESES +--ignore VOLATILE + +--no-tree +--quiet +--root=. +--show-types +--strict +--verbose diff --git a/etc/checkpatch/config b/etc/checkpatch/config deleted file mode 100644 index b1a4b40..0000000 --- a/etc/checkpatch/config +++ /dev/null @@ -1,33 +0,0 @@ ---ignore AVOID_EXTERNS ---ignore BLOCK_COMMENT_STYLE ---ignore BRACES ---ignore CAMELCASE ---ignore CODE_INDENT ---ignore COMPARISON_TO_NULL ---ignore COMPLEX_MACRO ---ignore CONCATENATED_STRING ---ignore FUNCTION_ARGUMENTS ---ignore INITIALISED_STATIC ---ignore LEADING_SPACE ---ignore LINE_SPACING ---ignore LOGICAL_CONTINUATIONS ---ignore MACRO_ARG_REUSE ---ignore MULTIPLE_ASSIGNMENTS ---ignore OPEN_BRACE ---ignore PREFER_FALLTHROUGH ---ignore PREFER_KERNEL_TYPES ---ignore SPACING ---ignore SPDX_LICENSE_TAG ---ignore SPLIT_STRING ---ignore STATIC_CONST_CHAR_ARRAY ---ignore SUSPECT_CODE_INDENT ---ignore TRAILING_STATEMENTS ---ignore UNNECESSARY_PARENTHESES ---ignore VOLATILE - ---no-tree ---quiet ---root=. ---show-types ---strict ---verbose diff --git a/etc/clang-tidy/config.yaml b/etc/clang-tidy/config.yaml index c9bcbae..d910b14 100644 --- a/etc/clang-tidy/config.yaml +++ b/etc/clang-tidy/config.yaml @@ -11,33 +11,46 @@ Checks: > -android-cloexec-pipe, -bugprone-easily-swappable-parameters, -bugprone-implicit-widening-of-multiplication-result, + -bugprone-macro-parentheses, -bugprone-reserved-identifier, + -cert-dcl16-c, -cert-dcl37-c, -cert-dcl51-cpp, -cert-env33-c, -cert-err33-c, -cert-err34-c, -cert-msc30-c, + -cert-msc32-c, -cert-msc50-cpp, + -cert-msc51-cpp, + -clang-analyzer-optin.portability.UnixAPI, -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling, + -clang-analyzer-security.insecureAPI.strcpy, + -clang-analyzer-unix.Malloc, + -clang-diagnostic-c2x-extensions, -concurrency-mt-unsafe, -cppcoreguidelines-avoid-non-const-global-variables, -cppcoreguidelines-init-variables, -google-readability-braces-around-statements, -hicpp-braces-around-statements, -hicpp-no-assembler, + -hicpp-uppercase-literal-suffix, -llvmlibc-restrict-system-libc-headers, -misc-no-recursion, + -modernize-macro-to-enum, -readability-braces-around-statements, -readability-function-cognitive-complexity, -readability-identifier-length, -readability-isolate-declaration, + -readability-uppercase-literal-suffix, WarningsAsErrors: > *, -altera-struct-pack-align, -bugprone-narrowing-conversions, + -clang-diagnostic-declaration-after-statement, -clang-diagnostic-format, + -clang-diagnostic-format-invalid-specifier, -clang-diagnostic-sign-compare, -clang-diagnostic-uninitialized, -clang-diagnostic-unused-parameter, diff --git a/etc/cppcheck/cppcheck.suppress b/etc/cppcheck/cppcheck.suppress index cd9806b..c8a7f91 100644 --- a/etc/cppcheck/cppcheck.suppress +++ b/etc/cppcheck/cppcheck.suppress @@ -1,4 +1,8 @@ +checkersReport ConfigurationNotChecked +constParameter +constParameterCallback +knownConditionTrueFalse missingIncludeSystem redundantContinue unassignedVariable diff --git a/etc/cpplint/CPPLINT.cfg b/etc/cpplint/CPPLINT.cfg deleted file mode 100644 index 7bdd508..0000000 --- a/etc/cpplint/CPPLINT.cfg +++ /dev/null @@ -1,2 +0,0 @@ -filter=-build/include_subdir,-legal/copyright,-readability/alt_tokens,-readability/braces,-readability/casting,-readability/multiline_comment,-runtime/int,-runtime/threadsafe_fn,-whitespace/blank_line,-whitespace/braces - diff --git a/etc/cpplint/cpplint.cfg b/etc/cpplint/cpplint.cfg new file mode 100644 index 0000000..b0b018d --- /dev/null +++ b/etc/cpplint/cpplint.cfg @@ -0,0 +1,2 @@ +filter=-build/include_order,-build/include_subdir,-legal/copyright,-readability/alt_tokens,-readability/braces,-readability/casting,-readability/multiline_comment,-runtime/int,-runtime/printf,-runtime/threadsafe_fn,-whitespace/blank_line,-whitespace/braces,-whitespace/parens + diff --git a/lsm b/lsm index 29c2611..f05812c 100644 --- a/lsm +++ b/lsm @@ -1,7 +1,7 @@ Begin4 Title: Linux man-pages -Version: 6.05 -Entered-date: 2023-08-01 +Version: 6.06 +Entered-date: 2024-02-12 Description: Manual pages for GNU/Linux. This package contains manual pages for sections 2, 3, 4, 5, and 7, and subsections of those. Only a few pages are provided in @@ -9,7 +9,7 @@ Description: Manual pages for GNU/Linux. This package contains Keywords: man pages Maintained-by: Alejandro Colomar Primary-site: http://www.kernel.org/pub/linux/docs/man-pages - 3.0M man-pages-6.05.tar.gz + 3.0M man-pages-6.06.tar.gz Copying-policy: several; the pages are all freely distributable as long as nroff source is provided End diff --git a/man1/getent.1 b/man1/getent.1 index 1168fc5..d1cd5a9 100644 --- a/man1/getent.1 +++ b/man1/getent.1 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH getent 1 2023-01-07 "Linux man-pages 6.05.01" +.TH getent 1 2023-11-01 "Linux man-pages 6.7" .SH NAME getent \- get entries from Name Service Switch libraries .SH SYNOPSIS @@ -25,12 +25,11 @@ Otherwise, if no .I key is provided, all entries will be displayed (unless the database does not support enumeration). -.PP +.P The .I database may be any of those supported by the GNU C Library, listed below: -.RS 3 -.TP 10 +.TP .B ahosts When no .I key @@ -41,7 +40,7 @@ and .BR endhostent (3) to enumerate the hosts database. This is identical to using -.BR hosts . +.BR hosts (5). When one or more .I key arguments are provided, pass each @@ -324,41 +323,48 @@ arguments are provided, pass each in succession to .BR getspnam (3) and display the result. -.RE .SH OPTIONS .TP -.BR \-s\ \fIservice\fP ", " \-\-service\ \fIservice\fP +.BI \-\-service\~ service +.TQ +.BI \-s\~ service .\" commit 9d0881aa76b399e6a025c5cf44bebe2ae0efa8af (glibc) Override all databases with the specified service. (Since glibc 2.2.5.) .TP -.BR \-s\ \fIdatabase\fP:\fIservice\fP ", "\ -\-\-service\ \fIdatabase\fP:\fIservice\fP +.BI \-\-service\~ database : service +.TQ +.BI \-s\~ database : service .\" commit b4f6f4be85d32b9c03361c38376e36f08100e3e8 (glibc) Override only specified databases with the specified service. The option may be used multiple times, but only the last service for each database will be used. (Since glibc 2.4.) .TP -.BR \-i ", " \-\-no\-idn +.B \-\-no\-idn +.TQ +.B \-i .\" commit a160f8d808cf8020b13bd0ef4a9eaf3c11f964ad (glibc) Disables IDN encoding in lookups for .BR ahosts / getaddrinfo (3) (Since glibc-2.13.) .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Print a usage summary and exit. .TP -.B "\-\-usage" +.B \-\-usage Print a short usage summary and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Print the version number, license, and disclaimer of warranty for .BR getent . .SH EXIT STATUS One of the following exit values can be returned by .BR getent : -.RS 3 .TP .B 0 Command completed successfully. @@ -377,6 +383,5 @@ could not be found in the .B 3 Enumeration not supported on this .IR database . -.RE .SH SEE ALSO .BR nsswitch.conf (5) diff --git a/man1/iconv.1 b/man1/iconv.1 index 39fb6ba..d1e10f8 100644 --- a/man1/iconv.1 +++ b/man1/iconv.1 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH iconv 1 2023-03-30 "Linux man-pages 6.05.01" +.TH iconv 1 2024-01-28 "Linux man-pages 6.7" .SH NAME iconv \- convert text from one character encoding to another .SH SYNOPSIS @@ -22,7 +22,7 @@ reads from standard input. If no output file is given, .B iconv writes to standard output. -.PP +.P If no .I from-encoding is given, the default is derived @@ -34,12 +34,16 @@ from the current locale's character encoding. .SH OPTIONS .TP -.BI \-f " from-encoding" "\fR, \fP\-\-from\-code=" from-encoding +.BI \-\-from\-code= from-encoding +.TQ +.BI \-f\~ from-encoding Use .I from-encoding for input characters. .TP -.BI \-t " to-encoding" "\fR, \fP\-\-to\-code=" to-encoding +.BI \-\-to\-code= to-encoding +.TQ +.BI \-t\~ to-encoding Use .I to-encoding for output characters. @@ -62,32 +66,42 @@ looking characters. Characters that are outside of the target character set and cannot be transliterated are replaced with a question mark (?) in the output. .TP -.BR \-l ", " \-\-list +.B \-\-list +.TQ +.B \-l List all known character set encodings. .TP -.B "\-c" +.B \-c Silently discard characters that cannot be converted instead of terminating when encountering such characters. .TP -.BI \-o " outputfile" "\fR, \fP\-\-output=" outputfile +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile Use .I outputfile for output. .TP -.BR \-s ", " \-\-silent +.B \-\-silent +.TQ +.B \-s This option is ignored; it is provided only for compatibility. .TP -.B "\-\-verbose" +.B \-\-verbose Print progress information on standard error when processing multiple files. .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Print a usage summary and exit. .TP -.B "\-\-usage" +.B \-\-usage Print a short usage summary and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Print the version number, license, and disclaimer of warranty for .BR iconv . .SH EXIT STATUS @@ -155,7 +169,7 @@ Usual system default gconv module configuration file. .TP .I /usr/lib/gconv/gconv\-modules.cache Usual system gconv module configuration cache. -.PP +.P Depending on the architecture, the above files may instead be located at directories with the path prefix .IR /usr/lib64 . @@ -164,17 +178,17 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001. .SH EXAMPLES -Convert text from the ISO 8859-15 character encoding to UTF-8: -.PP +Convert text from the ISO/IEC\~8859-15 character encoding to UTF-8: +.P .in +4n .EX $ \fBiconv \-f ISO\-8859\-15 \-t UTF\-8 < input.txt > output.txt\fP .EE .in -.PP +.P The next example converts from UTF-8 to ASCII, transliterating when possible: -.PP +.P .in +4n .EX $ \fBecho abc ß α € àḃç | iconv \-f UTF\-8 \-t ASCII//TRANSLIT\fP diff --git a/man1/intro.1 b/man1/intro.1 index 06905e1..bf8a1fe 100644 --- a/man1/intro.1 +++ b/man1/intro.1 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH intro 1 2023-05-03 "Linux man-pages 6.05.01" +.TH intro 1 2023-10-31 "Linux man-pages 6.7" .SH NAME intro \- introduction to user commands .SH DESCRIPTION @@ -13,7 +13,7 @@ web browsers, file and image viewers and editors, and so on. Linux is a flavor of UNIX, and as a first approximation all user commands under UNIX work precisely the same under Linux (and FreeBSD and lots of other UNIX-like systems). -.PP +.P Under Linux, there are GUIs (graphical user interfaces), where you can point and click and drag, and hopefully get work done without first reading lots of documentation. @@ -52,9 +52,9 @@ See also .BR dash (1), .BR ksh (1), .BR zsh (1). -.PP +.P A session might go like: -.PP +.P .in +4n .EX .RB "knuth login: " aeb @@ -98,9 +98,9 @@ maja 0501\-1136285 $ .EE .in -.PP +.P Here typing Control-D ended the session. -.PP +.P The .B $ here was the command prompt\[em]it is the shell's way of indicating @@ -110,13 +110,13 @@ in lots of ways, and one might include stuff like username, machine name, current directory, time, and so on. An assignment PS1="What next, master? " would change the prompt as indicated. -.PP +.P We see that there are commands .I date (that gives date and time), and .I cal (that gives a calendar). -.PP +.P The command .I ls lists the contents of the current directory\[em]it tells you what @@ -132,7 +132,7 @@ Owner and permissions can be changed by the commands .I chown and .IR chmod . -.PP +.P The command .I cat will show the contents of a file. @@ -142,26 +142,26 @@ parameters are concatenated and sent to "standard output" .BR stdout (3)), here the terminal screen.) -.PP +.P The command .I cp (from "copy") will copy a file. -.PP +.P The command .I mv (from "move"), on the other hand, only renames it. -.PP +.P The command .I diff lists the differences between two files. Here there was no output because there were no differences. -.PP +.P The command .I rm (from "remove") deletes the file, and be careful! it is gone. No wastepaper basket or anything. Deleted means lost. -.PP +.P The command .I grep (from "g/re/p") finds occurrences of a string in one or more files. @@ -185,15 +185,15 @@ to .I tel when the current directory is .IR /home/aeb . -.PP +.P The command .I pwd prints the current directory. -.PP +.P The command .I cd changes the current directory. -.PP +.P Try alternatively .I cd and @@ -205,11 +205,11 @@ usage: "cd", "cd .", "cd ..", "cd /", and "cd \[ti]". The command .I mkdir makes a new directory. -.PP +.P The command .I rmdir removes a directory if it is empty, and complains otherwise. -.PP +.P The command .I find (with a rather baroque syntax) will find files with given name @@ -266,7 +266,7 @@ sends the text through some usually .IR less . Hit the space bar to get the next page, hit q to quit. -.PP +.P In documentation it is customary to refer to man pages by giving the name and section number, as in .BR man (1). @@ -274,12 +274,12 @@ Man pages are terse, and allow you to find quickly some forgotten detail. For newcomers an introductory text with more examples and explanations is useful. -.PP +.P A lot of GNU/FSF software is provided with info files. Type "info info" for an introduction on the use of the program .IR info . -.PP +.P Special topics are often treated in HOWTOs. Look in .I /usr/share/doc/howto/en diff --git a/man1/ldd.1 b/man1/ldd.1 index 1c894de..7375d99 100644 --- a/man1/ldd.1 +++ b/man1/ldd.1 @@ -8,7 +8,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ldd 1 2023-02-05 "Linux man-pages 6.05.01" +.TH ldd 1 2023-10-31 "Linux man-pages 6.7" .SH NAME ldd \- print shared object dependencies .SH SYNOPSIS @@ -21,7 +21,7 @@ prints the shared objects (shared libraries) required by each program or shared object specified on the command line. An example of its use and output is the following: -.PP +.P .in +4n .EX $ \fBldd /bin/ls\fP @@ -36,7 +36,7 @@ $ \fBldd /bin/ls\fP libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f87e45fa000) .EE .in -.PP +.P In the usual case, .B ldd invokes the standard dynamic linker (see @@ -89,7 +89,7 @@ the upstream .B ldd implementation did this for example, although most distributions provided a modified version that did not.) -.PP +.P Thus, you should .I never employ @@ -97,13 +97,13 @@ employ on an untrusted executable, since this may result in the execution of arbitrary code. A safer alternative when dealing with untrusted executables is: -.PP +.P .in +4n .EX $ \fBobjdump \-p /path/to/program | grep NEEDED\fP .EE .in -.PP +.P Note, however, that this alternative shows only the direct dependencies of the executable, while .B ldd @@ -114,18 +114,26 @@ shows the entire dependency tree of the executable. Print the version number of .BR ldd . .TP -.BR \-v ", " \-\-verbose +.B \-\-verbose +.TQ +.B \-v Print all information, including, for example, symbol versioning information. .TP -.BR \-u ", " \-\-unused +.B \-\-unused +.TQ +.B \-u Print unused direct dependencies. (Since glibc 2.3.4.) .TP -.BR \-d ", " \-\-data\-relocs +.B \-\-data\-relocs +.TQ +.B \-d Perform relocations and report any missing objects (ELF only). .TP -.BR \-r ", " \-\-function\-relocs +.B \-\-function\-relocs +.TQ +.B \-r Perform relocations for both data objects and functions, and report any missing objects or functions (ELF only). .TP @@ -142,7 +150,7 @@ Usage information. .\" .B \-V .\" and only has the equivalent .\" .BR \-\-version . -.\" .LP +.\" .P .\" The libc5 version of this program will use the name of a library given .\" on the command line as-is when it contains a \[aq]/\[aq]; otherwise it .\" searches for the library in the standard locations. @@ -151,7 +159,7 @@ Usage information. .SH BUGS .B ldd does not work on a.out shared libraries. -.PP +.P .B ldd does not work with some extremely old a.out programs which were built before diff --git a/man1/locale.1 b/man1/locale.1 index 31ca0ea..2e71e68 100644 --- a/man1/locale.1 +++ b/man1/locale.1 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH locale 1 2023-05-03 "Linux man-pages 6.05.01" +.TH locale 1 2023-10-31 "Linux man-pages 6.7" .SH NAME locale \- get locale-specific information .SH SYNOPSIS @@ -17,7 +17,7 @@ The .B locale command displays information about the current locale, or all locales, on standard output. -.PP +.P When invoked without arguments, .B locale displays the current locale settings for each locale category (see @@ -27,7 +27,7 @@ based on the settings of the environment variables that control the locale .BR locale (7)). Values for variables set in the environment are printed without double quotes, implied values are printed with double quotes. -.PP +.P If either the .B \-a or the @@ -35,7 +35,9 @@ or the option (or one of their long-format equivalents) is specified, the behavior is as follows: .TP -.BR \-a ", " \-\-all\-locales +.B \-\-all\-locales +.TQ +.B \-a Display a list of all available locales. The .B \-v @@ -43,11 +45,13 @@ option causes the .B LC_IDENTIFICATION metadata about each locale to be included in the output. .TP -.BR \-m ", " \-\-charmaps +.B \-\-charmaps +.TQ +.B \-m Display the available charmaps (character set description files). To display the current character set for the locale, use \fBlocale \-c charmap\fR. -.PP +.P The .B locale command can also be provided with one or more arguments, @@ -67,10 +71,12 @@ For a locale keyword, the value of that keyword to be displayed. .IP \[bu] For a locale category, the values of all keywords in that category are displayed. -.PP +.P When arguments are supplied, the following options are meaningful: .TP -.BR \-c ", " \-\-category\-name +.B \-\-category\-name +.TQ +.B \-c For a category name argument, write the name of the locale category on a separate line preceding the list of keyword values for that category. @@ -84,7 +90,9 @@ It can be combined with the .B \-k option. .TP -.BR \-k ", " \-\-keyword\-name +.B \-\-keyword\-name +.TQ +.B \-k For each keyword whose value is being displayed, include also the name of that keyword, so that the output has the format: @@ -94,22 +102,28 @@ so that the output has the format: .IR keyword =\[dq] value \[dq] .EE .in -.PP +.P The .B locale command also knows about the following options: .TP -.BR \-v ", " \-\-verbose +.B \-\-verbose +.TQ +.B \-v Display additional information for some command-line option and argument combinations. .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Display a summary of command-line options and arguments and exit. .TP .B \-\-usage Display a short usage message and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Display the program version and exit. .SH FILES .TP @@ -139,24 +153,24 @@ LC_TELEPHONE="en_US.UTF\-8" LC_MEASUREMENT="en_US.UTF\-8" LC_IDENTIFICATION="en_US.UTF\-8" LC_ALL= -.PP +.P $ \fBlocale date_fmt\fP %a %b %e %H:%M:%S %Z %Y -.PP +.P $ \fBlocale \-k date_fmt\fP date_fmt="%a %b %e %H:%M:%S %Z %Y" -.PP +.P $ \fBlocale \-ck date_fmt\fP LC_TIME date_fmt="%a %b %e %H:%M:%S %Z %Y" -.PP +.P $ \fBlocale LC_TELEPHONE\fP +%c (%a) %l (%a) %l 11 1 UTF\-8 -.PP +.P $ \fBlocale \-k LC_TELEPHONE\fP tel_int_fmt="+%c (%a) %l" tel_dom_fmt="(%a) %l" @@ -164,7 +178,7 @@ int_select="11" int_prefix="1" telephone\-codeset="UTF\-8" .EE -.PP +.P The following example compiles a custom locale from the .I ./wrk directory with the @@ -179,7 +193,7 @@ and .B LANG in the shell profile file so that the custom locale will be used in the subsequent user sessions: -.PP +.P .EX $ \fBmkdir \-p $HOME/.locale\fP $ \fBI18NPATH=./wrk/ localedef \-f UTF\-8 \-i fi_SE $HOME/.locale/fi_SE.UTF\-8\fP diff --git a/man1/localedef.1 b/man1/localedef.1 index 13dd2f0..8326b92 100644 --- a/man1/localedef.1 +++ b/man1/localedef.1 @@ -12,7 +12,7 @@ .\" Lars Wirzenius to document new functionality (as of GNU .\" C library 2.3.5). .\" -.TH localedef 1 2023-03-12 "Linux man-pages 6.05.01" +.TH localedef 1 2023-10-31 "Linux man-pages 6.7" .SH NAME localedef \- compile locale definition files .SH SYNOPSIS @@ -58,7 +58,7 @@ locale functions in the C library etc.), and places the output in .IR outputpath . -.PP +.P The .I outputpath argument is interpreted as follows: @@ -92,12 +92,12 @@ system-provided locales; it is used by all localized programs when the environment variable .B LOCPATH is not set. -.PP +.P In any case, .B localedef aborts if the directory in which it tries to write locale files has not already been created. -.PP +.P If no .I charmapfile is given, @@ -206,11 +206,15 @@ Use to look up aliases for locale names. There is no default aliases file. .TP -.BR \-c ", " \-\-force +.B \-\-force +.TQ +.B \-c Write the output files even if warnings were generated about the input file. .TP -.BR \-v ", " \-\-verbose +.B \-\-verbose +.TQ +.B \-v Generate extra warnings about errors that are normally ignored. .TP .B \-\-big\-endian @@ -274,15 +278,19 @@ Supported warnings are and .IR intcurrsym . .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Print a usage summary and exit. Also prints the default paths used by .BR localedef . .TP -.B "\-\-usage" +.B \-\-usage Print a short usage summary and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Print the version number, license, and disclaimer of warranty for @@ -378,13 +386,13 @@ POSIX.1-2008. Compile the locale files for Finnish in the UTF\-8 character set and add it to the default locale archive with the name .BR fi_FI.UTF\-8 : -.PP +.P .in +4n .EX localedef \-f UTF\-8 \-i fi_FI fi_FI.UTF\-8 .EE .in -.PP +.P The next example does the same thing, but generates files into the .I fi_FI.UTF\-8 @@ -393,7 +401,7 @@ variable .B LOCPATH is set to the current directory (note that the last argument must contain a slash): -.PP +.P .in +4n .EX localedef \-f UTF\-8 \-i fi_FI ./fi_FI.UTF\-8 diff --git a/man1/memusage.1 b/man1/memusage.1 index 03a5094..fa64544 100644 --- a/man1/memusage.1 +++ b/man1/memusage.1 @@ -2,7 +2,7 @@ .\" and Copyright (C) 2014, Michael Kerrisk .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH memusage 1 2023-05-03 "Linux man-pages 6.05.01" +.TH memusage 1 2023-10-31 "Linux man-pages 6.7" .SH NAME memusage \- profile memory usage of a program .SH SYNOPSIS @@ -33,7 +33,7 @@ optionally, calls to and .BR munmap (2) can also be intercepted. -.PP +.P .B memusage can output the collected data in textual form, or it can use .BR memusagestat (1) @@ -86,7 +86,7 @@ After each function call, the actual stack pointer address is read and the difference from the base stack pointer computed. The maximum of these differences is then the stack peak. .RE -.PP +.P Immediately following this summary line, a table shows the number calls, total memory allocated or deallocated, and number of failed calls for each intercepted function. @@ -102,7 +102,7 @@ For .BR realloc (3), the additional field "free" shows reallocations that caused a block to be freed (i.e., the reallocated size was 0). -.PP +.P The "realloc/total memory" of the table output by .B memusage does not reflect cases where @@ -193,7 +193,7 @@ reallocating the memory in smaller blocks that return to zero. After compiling the program and running the following commands, a graph of the memory usage of the program can be found in the file .IR memusage.png : -.PP +.P .in +4n .EX $ \fBmemusage \-\-data=memusage.dat ./a.out\fP diff --git a/man1/memusagestat.1 b/man1/memusagestat.1 index afce052..d1a76fb 100644 --- a/man1/memusagestat.1 +++ b/man1/memusagestat.1 @@ -1,7 +1,7 @@ .\" Copyright (c) 2013, Peter Schiffer .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH memusagestat 1 2022-10-30 "Linux man-pages 6.05.01" +.TH memusagestat 1 2023-10-31 "Linux man-pages 6.7" .SH NAME memusagestat \- generate graphic from memory profiling data .SH SYNOPSIS @@ -19,7 +19,7 @@ that file is generated via the .IR \-\-data ) option of .BR memusage (1). -.PP +.P The red line in the graph shows the heap usage (allocated memory) and the green line shows the stack usage. The x-scale is either the number of memory-handling function calls or diff --git a/man1/mtrace.1 b/man1/mtrace.1 index 56498d7..3ade2ff 100644 --- a/man1/mtrace.1 +++ b/man1/mtrace.1 @@ -1,7 +1,7 @@ .\" Copyright (c) 2013, Peter Schiffer (pschiffe@redhat.com) .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH mtrace 1 2022-10-30 "Linux man-pages 6.05.01" +.TH mtrace 1 2023-10-31 "Linux man-pages 6.7" .SH NAME mtrace \- interpret the malloc trace log .SH SYNOPSIS @@ -24,7 +24,7 @@ for problem locations (assuming that .I binary was compiled with debugging information). -.PP +.P For more information about the .BR mtrace (3) function and diff --git a/man1/pldd.1 b/man1/pldd.1 index f6859bc..db74dc9 100644 --- a/man1/pldd.1 +++ b/man1/pldd.1 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pldd 1 2023-03-30 "Linux man-pages 6.05.01" +.TH pldd 1 2023-10-31 "Linux man-pages 6.7" .SH NAME pldd \- display dynamic shared objects linked into a process .SH SYNOPSIS @@ -19,13 +19,17 @@ The list includes the libraries that have been dynamically loaded using .BR dlopen (3). .SH OPTIONS .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Display a help message and exit. .TP .B \-\-usage Display a short usage message and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Display program version information and exit. .SH EXIT STATUS On success, @@ -48,16 +52,16 @@ None. glibc 2.15. .SH NOTES The command -.PP +.P .in +4n .EX lsof \-p PID .EE .in -.PP +.P also shows output that includes the dynamic shared objects that are linked into a process. -.PP +.P The .BR gdb (1) .I "info shared" @@ -67,7 +71,7 @@ so that one can obtain similar output to using a command such as the following (to monitor the process with the specified .IR pid ): -.PP +.P .in +4n .EX $ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP diff --git a/man1/sprof.1 b/man1/sprof.1 index 186dad4..6d9796b 100644 --- a/man1/sprof.1 +++ b/man1/sprof.1 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sprof 1 2023-05-03 "Linux man-pages 6.05.01" +.TH sprof 1 2023-10-31 "Linux man-pages 6.7" .SH NAME sprof \- read and display shared object profiling data .SH SYNOPSIS @@ -27,30 +27,40 @@ in the current directory. The following command-line options specify the profile output to be produced: .TP -.BR \-c ", " \-\-call\-pairs +.B \-\-call\-pairs +.TQ +.B \-c Print a list of pairs of call paths for the interfaces exported by the shared object, along with the number of times each path is used. .TP -.BR \-p ", " \-\-flat\-profile +.B \-\-flat\-profile +.TQ +.B \-p Generate a flat profile of all of the functions in the monitored object, with counts and ticks. .TP -.BR \-q ", " \-\-graph +.B \-\-graph +.TQ +.B \-q Generate a call graph. -.PP +.P If none of the above options is specified, then the default behavior is to display a flat profile and a call graph. -.PP +.P The following additional command-line options are available: .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Display a summary of command-line options and arguments and exit. .TP .B \-\-usage Display a short usage message and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Display the program version and exit. .SH STANDARDS GNU. @@ -60,7 +70,7 @@ The following example demonstrates the use of The example consists of a main program that calls two functions in a shared object. First, the code of the main program: -.PP +.P .in +4n .EX $ \fBcat prog.c\fP @@ -78,14 +88,14 @@ main(int argc, char *argv[]) } .EE .in -.PP +.P The functions .IR x1 () and .IR x2 () are defined in the following source file that is used to construct the shared object: -.PP +.P .in +4n .EX $ \fBcat libdemo.c\fP @@ -119,32 +129,32 @@ x2(void) } .EE .in -.PP +.P Now we construct the shared object with the real name .IR libdemo.so.1.0.1 , and the soname .IR libdemo.so.1 : -.PP +.P .in +4n .EX $ \fBcc \-g \-fPIC \-shared \-Wl,\-soname,libdemo.so.1 \e\fP \fB\-o libdemo.so.1.0.1 libdemo.c\fP .EE .in -.PP +.P Then we construct symbolic links for the library soname and the library linker name: -.PP +.P .in +4n .EX $ \fBln \-sf libdemo.so.1.0.1 libdemo.so.1\fP $ \fBln \-sf libdemo.so.1 libdemo.so\fP .EE .in -.PP +.P Next, we compile the main program, linking it against the shared object, and then list the dynamic dependencies of the program: -.PP +.P .in +4n .EX $ \fBcc \-g \-o prog prog.c \-L. \-ldemo\fP @@ -155,46 +165,46 @@ $ \fBldd prog\fP /lib64/ld\-linux\-x86\-64.so.2 (0x00007fd4dc51f000) .EE .in -.PP +.P In order to get profiling information for the shared object, we define the environment variable .B LD_PROFILE with the soname of the library: -.PP +.P .in +4n .EX $ \fBexport LD_PROFILE=libdemo.so.1\fP .EE .in -.PP +.P We then define the environment variable .B LD_PROFILE_OUTPUT with the pathname of the directory where profile output should be written, and create that directory if it does not exist already: -.PP +.P .in +4n .EX $ \fBexport LD_PROFILE_OUTPUT=$(pwd)/prof_data\fP $ \fBmkdir \-p $LD_PROFILE_OUTPUT\fP .EE .in -.PP +.P .B LD_PROFILE causes profiling output to be .I appended to the output file if it already exists, so we ensure that there is no preexisting profiling data: -.PP +.P .in +4n .EX $ \fBrm \-f $LD_PROFILE_OUTPUT/$LD_PROFILE.profile\fP .EE .in -.PP +.P We then run the program to produce the profiling output, which is written to a file in the directory specified in .BR LD_PROFILE_OUTPUT : -.PP +.P .in +4n .EX $ \fBLD_LIBRARY_PATH=. ./prog\fP @@ -202,11 +212,11 @@ $ \fBls prof_data\fP libdemo.so.1.profile .EE .in -.PP +.P We then use the .B sprof \-p option to generate a flat profile with counts and ticks: -.PP +.P .in +4n .EX $ \fBsprof \-p libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP @@ -221,11 +231,11 @@ Each sample counts as 0.01 seconds. 0.00 0.10 0.00 1 0.00 x2 .EE .in -.PP +.P The .B sprof \-q option generates a call graph: -.PP +.P .in +4n .EX $ \fBsprof \-q libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP @@ -248,15 +258,15 @@ index % time self children called name \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- .EE .in -.PP +.P Above and below, the "" strings represent identifiers that are outside of the profiled object (in this example, these are instances of .IR main() ). -.PP +.P The .B sprof \-c option generates a list of call pairs and the number of their occurrences: -.PP +.P .in +4n .EX $ \fBsprof \-c libdemo.so.1 $LD_PROFILE_OUTPUT/libdemo.so.1.profile\fP diff --git a/man1/time.1 b/man1/time.1 index df09106..6e4ea37 100644 --- a/man1/time.1 +++ b/man1/time.1 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH time 1 2023-07-30 "Linux man-pages 6.05.01" +.TH time 1 2023-10-31 "Linux man-pages 6.7" .SH NAME time \- time a simple command or give resource usage .SH SYNOPSIS @@ -40,7 +40,7 @@ values in a .I "struct tms" as returned by .BR times (2)). -.PP +.P Note: some shells (e.g., .BR bash (1)) have a built-in @@ -98,20 +98,20 @@ using the option or the .B TIME environment variable. -.PP +.P The default format string is: -.PP +.P .in +4n .EX %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps .EE .in -.PP +.P When the .I \-p option is given, the (portable) output format is used: -.PP +.P .in +4n .EX real %e @@ -133,7 +133,7 @@ The conversions follow. All of those used by .BR tcsh (1) are supported. -.PP +.P .B "Time" .TP .B %E @@ -152,7 +152,7 @@ Total number of CPU-seconds that the process spent in user mode. .TP .B %P Percentage of the CPU that this job got, computed as (%U + %S) / %E. -.PP +.P .B "Memory" .TP .B %M @@ -205,7 +205,7 @@ Number of times the process was context-switched involuntarily .B %w Number of waits: times that the program was context-switched voluntarily, for instance while waiting for an I/O operation to complete. -.PP +.P .B "I/O" .TP .B %I @@ -272,10 +272,10 @@ Not all resources are measured by all versions of UNIX, so some of the values might be reported as zero. The present selection was mostly inspired by the data provided by 4.2 or 4.3BSD. -.PP +.P GNU time version 1.7 is not yet localized. Thus, it does not implement the POSIX requirements. -.PP +.P The environment variable .B TIME was badly chosen. @@ -287,14 +287,14 @@ to use environment variables with the name of a utility to override the utility to be used. Uses like MORE or TIME for options to programs (instead of program pathnames) tend to lead to difficulties. -.PP +.P It seems unfortunate that .I \-o overwrites instead of appends. (That is, the .I \-a option should be the default.) -.PP +.P Mail suggestions and bug reports for GNU .B time to @@ -302,13 +302,13 @@ to Please include the version of .BR time , which you can get by running -.PP +.P .in +4n .EX time \-\-version .EE .in -.PP +.P and the operating system and C compiler you used. .\" .SH AUTHORS diff --git a/man2/_exit.2 b/man2/_exit.2 index 22cccd9..ea3ca63 100644 --- a/man2/_exit.2 +++ b/man2/_exit.2 @@ -6,7 +6,7 @@ .\" Modified Wed Jul 21 23:02:38 1993 by Rik Faith .\" Modified 2001-11-17, aeb .\" -.TH _exit 2 2023-03-30 "Linux man-pages 6.05.01" +.TH _exit 2 2023-10-31 "Linux man-pages 6.7" .SH NAME _exit, _Exit \- terminate the calling process .SH LIBRARY @@ -15,19 +15,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[noreturn]] void _exit(int " status ); -.PP +.P .B #include -.PP +.P .BI "[[noreturn]] void _Exit(int " status ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR _Exit (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -45,14 +45,14 @@ operation). The process's parent is sent a .B SIGCHLD signal. -.PP +.P The value .I "status & 0xFF" is returned to the parent process as the process's exit status, and can be collected by the parent using one of the .BR wait (2) family of calls. -.PP +.P The function .BR _Exit () is equivalent to @@ -68,14 +68,14 @@ POSIX.1-2008. C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P .BR _Exit () was introduced by C99. .SH NOTES For a discussion on the effects of an exit, the transmission of exit status, zombie processes, signals sent, and so on, see .BR exit (3). -.PP +.P The function .BR _exit () is like @@ -108,7 +108,7 @@ which is to terminate a process, and these are the semantics specified by POSIX.1 and implemented by the C library wrapper function. On modern systems, this means termination of all threads in the process. -.PP +.P By contrast with the C library wrapper function, the raw Linux .BR _exit () system call terminates only the calling thread, and actions such as @@ -117,7 +117,7 @@ reparenting child processes or sending to the parent process are performed only if this is the last thread in the thread group. .\" _exit() is used by pthread_exit() to terminate the calling thread -.PP +.P Up to glibc 2.3, the .BR _exit () wrapper function invoked the kernel system call of the same name. diff --git a/man2/_syscall.2 b/man2/_syscall.2 index ef6542f..84612a1 100644 --- a/man2/_syscall.2 +++ b/man2/_syscall.2 @@ -16,15 +16,15 @@ .\" 2007-10-23 mtk: created as a new page, by taking the content .\" specific to the _syscall() macros from intro(2). .\" -.TH _syscall 2 2023-05-03 "Linux man-pages 6.05.01" +.TH _syscall 2 2024-02-26 "Linux man-pages 6.7" .SH NAME _syscall \- invoking a system call without library support (OBSOLETE) .SH SYNOPSIS .nf .B #include -.PP +.P A _syscall macro -.PP +.P desired system call .fi .SH DESCRIPTION @@ -33,13 +33,13 @@ You need to know how many arguments, their types, and the function return type. There are seven macros that make the actual call into the system easier. They have the form: -.PP +.P .in +4n .EX .RI _syscall X ( type , name , type1 , arg1 , type2 , arg2 ,...) .EE .in -.PP +.P where .IP .I X @@ -57,7 +57,7 @@ is the Nth argument's type .IP .I argN is the name of the Nth argument -.PP +.P These macros create a function called .I name with the arguments you @@ -85,7 +85,7 @@ The _syscall() macros produce a prototype. You may have to create one, especially for C++ users. -.PP +.P System calls are not required to return only positive or negative error codes. You need to read the source to be sure how it will return errors. @@ -106,7 +106,7 @@ when is negative. For the error codes, see .BR errno (3). -.PP +.P When defining a system call, the argument types .I must be @@ -123,7 +123,7 @@ passed by-value or by-pointer (for aggregates like structs). .\" Otherwise, the use of a _syscall macro is required. .\" .SH EXAMPLES -.\" [[deprecated]] SRC BEGIN (_syscall.c) +.\" SRC BEGIN (_syscall.c) .EX #include #include diff --git a/man2/accept.2 b/man2/accept.2 index 340fdb8..bc73416 100644 --- a/man2/accept.2 +++ b/man2/accept.2 @@ -10,7 +10,7 @@ .\" Modified 2004-06-17 by Michael Kerrisk .\" 2008-12-04, mtk, Add documentation of accept4() .\" -.TH accept 2 2023-04-05 "Linux man-pages 6.05.01" +.TH accept 2 2023-10-31 "Linux man-pages 6.7" .SH NAME accept, accept4 \- accept a connection on a socket .SH LIBRARY @@ -19,13 +19,13 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int accept(int " sockfd ", struct sockaddr *_Nullable restrict " addr , .BI " socklen_t *_Nullable restrict " addrlen ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int accept4(int " sockfd ", struct sockaddr *_Nullable restrict " addr , .BI " socklen_t *_Nullable restrict " addrlen ", int " flags ); .fi @@ -44,7 +44,7 @@ The newly created socket is not in the listening state. The original socket .I sockfd is unaffected by this call. -.PP +.P The argument .I sockfd is a socket that has been created with @@ -53,7 +53,7 @@ bound to a local address with .BR bind (2), and is listening for connections after a .BR listen (2). -.PP +.P The argument .I addr is a pointer to a @@ -71,7 +71,7 @@ When is NULL, nothing is filled in; in this case, .I addrlen is not used, and should also be NULL. -.PP +.P The .I addrlen argument is a value-result argument: @@ -79,12 +79,12 @@ the caller must initialize it to contain the size (in bytes) of the structure pointed to by .IR addr ; on return it will contain the actual size of the peer address. -.PP +.P The returned address is truncated if the buffer provided is too small; in this case, .I addrlen will return a value greater than was supplied to the call. -.PP +.P If no pending connections are present on the queue, and the socket is not marked as nonblocking, @@ -97,7 +97,7 @@ fails with the error .B EAGAIN or .BR EWOULDBLOCK . -.PP +.P In order to be notified of incoming connections on a socket, you can use .BR select (2), .BR poll (2), @@ -112,7 +112,7 @@ Alternatively, you can set the socket to deliver when activity occurs on a socket; see .BR socket (7) for details. -.PP +.P If .I flags is 0, then @@ -222,7 +222,9 @@ The per-process limit on the number of open file descriptors has been reached. .B ENFILE The system-wide limit on the total number of open files has been reached. .TP -.BR ENOBUFS ", " ENOMEM +.B ENOBUFS +.TQ +.B ENOMEM Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory. @@ -241,7 +243,7 @@ Firewall rules forbid connection. .TP .B EPROTO Protocol error. -.PP +.P In addition, network errors for the new socket and as defined for the protocol may be returned. Various Linux kernels can @@ -313,7 +315,7 @@ needs to have the .B O_NONBLOCK flag set (see .BR socket (7)). -.PP +.P For certain protocols which require an explicit confirmation, such as DECnet, .BR accept () diff --git a/man2/access.2 b/man2/access.2 index 3f492d2..7e60a33 100644 --- a/man2/access.2 +++ b/man2/access.2 @@ -20,7 +20,7 @@ .\" Modified 2004-06-23 by Michael Kerrisk .\" 2007-06-10, mtk, various parts rewritten, and added BUGS section. .\" -.TH access 2 2023-03-30 "Linux man-pages 6.05.01" +.TH access 2 2024-01-01 "Linux man-pages 6.7" .SH NAME access, faccessat, faccessat2 \- check user's permissions for a file .SH LIBRARY @@ -29,30 +29,30 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int access(const char *" pathname ", int " mode ); -.PP +.P .BR "#include " " /* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int faccessat(int " dirfd ", const char *" pathname ", int " \ mode ", int " flags ); /* But see C library/kernel differences, below */ -.PP +.P .BR "#include " " /* Definition of " AT_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .B int syscall(SYS_faccessat2, .BI " int " dirfd ", const char *" pathname ", int " mode \ ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR faccessat (): .nf Since glibc 2.10: @@ -67,7 +67,7 @@ checks whether the calling process can access the file If .I pathname is a symbolic link, it is dereferenced. -.PP +.P The .I mode specifies the accessibility check(s) to be performed, @@ -81,7 +81,7 @@ tests for the existence of the file. .BR R_OK ", " W_OK ", and " X_OK test whether the file exists and grants read, write, and execute permissions, respectively. -.PP +.P The check is done using the calling process's .I real UID and GID, rather than the effective IDs as is done when @@ -92,7 +92,7 @@ Similarly, for the root user, the check uses the set of permitted capabilities rather than the set of effective capabilities; and for non-root users, the check uses an empty set of capabilities. -.PP +.P This allows set-user-ID programs and capability-endowed programs to easily determine the invoking user's authority. In other words, @@ -105,7 +105,7 @@ read/write/execute this file?", which gives set-user-ID programs the possibility to prevent malicious users from causing them to read files which users shouldn't be able to read. -.PP +.P If the calling process is privileged (i.e., its real UID is zero), then an .B X_OK @@ -116,7 +116,7 @@ is enabled for any of the file owner, group, or other. operates in exactly the same way as .BR access (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -126,7 +126,7 @@ referred to by the file descriptor the calling process, as is done by .BR access () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -138,13 +138,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR access ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags is constructed by ORing together zero or more of the following values: .TP @@ -155,12 +155,33 @@ By default, uses the real IDs (like .BR access ()). .TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP .B AT_SYMLINK_NOFOLLOW If .I pathname is a symbolic link, do not dereference it: instead return information about the link itself. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -346,20 +367,20 @@ interval between checking and opening the file to manipulate it. a safer alternative would be to temporarily switch the process's effective user ID to the real ID and then call .BR open (2).) -.PP +.P .BR access () always dereferences symbolic links. If you need to check the permissions on a symbolic link, use .BR faccessat () with the flag .BR AT_SYMLINK_NOFOLLOW . -.PP +.P These calls return an error if any of the access types in .I mode is denied, even if some of the other access types in .I mode are permitted. -.PP +.P A file is accessible only if the permissions on each of the directories in the path prefix of .I pathname @@ -367,7 +388,7 @@ grant search (i.e., execute) access. If any directory is inaccessible, then the .BR access () call fails, regardless of the permissions on the file itself. -.PP +.P Only access bits are checked, not the file type or contents. Therefore, if a directory is found to be writable, it probably means that files can be created in the directory, @@ -375,7 +396,7 @@ and not that the directory can be written as a file. Similarly, a DOS file may be reported as executable, but the .BR execve (2) call will still fail. -.PP +.P These calls may not work correctly on NFSv2 filesystems with UID mapping enabled, because UID mapping is done on the server and hidden from the client, @@ -401,7 +422,7 @@ Starting with glibc 2.33, the wrapper function avoids this bug by making use of the .BR faccessat2 () system call where it is provided by the underlying kernel. -.PP +.P In Linux 2.4 (and earlier) there is some strangeness in the handling of .B X_OK tests for superuser. @@ -424,7 +445,7 @@ returns 0 for such files. .\" This behavior appears to have been an implementation accident. Early Linux 2.6 (up to and including Linux 2.6.3) also behaved in the same way as Linux 2.4. -.PP +.P Before Linux 2.6.20, these calls ignored the effect of the .B MS_NOEXEC diff --git a/man2/acct.2 b/man2/acct.2 index de03a0e..d3ce589 100644 --- a/man2/acct.2 +++ b/man2/acct.2 @@ -9,7 +9,7 @@ .\" Modified 1998-11-04 by Tigran Aivazian .\" Modified 2004-05-27, 2004-06-17, 2004-06-23 by Michael Kerrisk .\" -.TH acct 2 2023-03-30 "Linux man-pages 6.05.01" +.TH acct 2 2023-10-31 "Linux man-pages 6.7" .SH NAME acct \- switch process accounting on or off .SH LIBRARY @@ -18,15 +18,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int acct(const char *_Nullable " filename ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR acct (): .nf Since glibc 2.21: @@ -129,7 +129,7 @@ SVr4, 4.3BSD. .SH NOTES No accounting is produced for programs running when a system crash occurs. In particular, nonterminating processes are never accounted for. -.PP +.P The structure of the records written to the accounting file is described in .BR acct (5). .SH SEE ALSO diff --git a/man2/add_key.2 b/man2/add_key.2 index 570db11..6e81ec9 100644 --- a/man2/add_key.2 +++ b/man2/add_key.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH add_key 2 2023-05-03 "Linux man-pages 6.05.01" +.TH add_key 2 2024-02-25 "Linux man-pages 6.7" .SH NAME add_key \- add a key to the kernel's key management facility .SH LIBRARY @@ -13,12 +13,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "key_serial_t add_key(const char *" type ", const char *" description , .BI " const void " payload [. plen "], size_t " plen , .BI " key_serial_t " keyring ");" .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see NOTES. .SH DESCRIPTION @@ -34,10 +34,10 @@ of length attaches it to the nominated .IR keyring , and returns the key's serial number. -.PP +.P The key may be rejected if the provided data is in the wrong format or it is invalid in some other way. -.PP +.P If the destination .I keyring already contains a key that matches the specified @@ -55,7 +55,7 @@ and it will displace the link to the extant key from the keyring. .\" is consequently unlinked, then keys that it was anchoring .\" will have their reference count decreased by one (and may .\" consequently be garbage collected). Is this all correct? -.PP +.P The destination .I keyring serial number may be that of a valid keyring for which the caller has @@ -96,7 +96,7 @@ argument to .BR add_key () are the following: .TP -.I """keyring""" +.I \[dq]keyring\[dq] Keyrings are special key types that may contain links to sequences of other keys of any type. If this interface is used to create a keyring, then @@ -105,21 +105,21 @@ should be NULL and .I plen should be zero. .TP -.I """user""" +.I \[dq]user\[dq] This is a general purpose key type whose payload may be read and updated by user-space applications. The key is kept entirely within kernel memory. The payload for keys of this type is a blob of arbitrary data of up to 32,767 bytes. .TP -.IR """logon""" " (since Linux 3.3)" +.IR \[dq]logon\[dq] " (since Linux 3.3)" .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b This key type is essentially the same as -.IR """user""" , +.IR \[dq]user\[dq] , but it does not permit the key to read. This is suitable for storing payloads that you do not want to be readable from user space. -.PP +.P This key type vets the .I description to ensure that it is qualified by a "service" prefix, @@ -127,15 +127,15 @@ by checking to ensure that the .I description contains a ':' that is preceded by other characters. .TP -.IR """big_key""" " (since Linux 3.13)" +.IR \[dq]big_key\[dq] " (since Linux 3.13)" .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 This key type is similar to -.IR """user""" , +.IR \[dq]user\[dq] , but may hold a payload of up to 1\ MiB. If the key payload is large enough, then it may be stored encrypted in tmpfs (which can be swapped out) rather than kernel memory. -.PP +.P For further details on these key types, see .BR keyrings (7). .SH RETURN VALUE @@ -175,11 +175,11 @@ The payload data was invalid. .B EINVAL .I type was -.I """logon""" +.I \[dq]logon\[dq] and the .I description was not qualified with a prefix string of the form -.IR """service:""" . +.IR \[dq]service:\[dq] . .TP .B EKEYEXPIRED The keyring has expired. @@ -202,7 +202,7 @@ Key types that begin with a period are reserved to the implementation. .B EPERM .I type was -.I """keyring""" +.I \[dq]keyring\[dq] and the .I description started with a period (\[aq].\[aq]). @@ -227,7 +227,7 @@ The program below creates a key with the type, description, and payload specified in its command-line arguments, and links that key into the session keyring. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX $ \fB./a.out user mykey "Some payload"\fP @@ -285,7 +285,7 @@ main(int argc, char *argv[]) .BR thread\-keyring (7), .BR user\-keyring (7), .BR user\-session\-keyring (7) -.PP +.P The kernel source files .I Documentation/security/keys/core.rst and diff --git a/man2/adjtimex.2 b/man2/adjtimex.2 index c850a3d..e5264df 100644 --- a/man2/adjtimex.2 +++ b/man2/adjtimex.2 @@ -8,7 +8,7 @@ .\" Modified 1997-07-30 by Paul Slootman .\" Modified 2004-05-27 by Michael Kerrisk .\" -.TH adjtimex 2 2023-07-20 "Linux man-pages 6.05.01" +.TH adjtimex 2 2023-10-31 "Linux man-pages 6.7" .SH NAME adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock .SH LIBRARY @@ -17,11 +17,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int adjtimex(struct timex *" "buf" ); -.PP +.P .BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); -.PP +.P .BI "int ntp_adjtime(struct timex *" buf ); .fi .SH DESCRIPTION @@ -34,7 +34,7 @@ It takes a pointer to a structure, updates kernel parameters from (selected) field values, and returns the same structure updated with the current kernel values. This structure is declared as follows: -.PP +.P .in +4n .EX struct timex { @@ -81,7 +81,7 @@ struct timex { }; .EE .in -.PP +.P The .I modes field determines which parameters, if any, to set. @@ -204,7 +204,7 @@ and the difference between TAI and UTC, see .B ADJ_TICK Set tick value from .IR buf.tick . -.PP +.P Alternatively, .I modes can be specified as either of the following (multibit mask) values, @@ -236,13 +236,13 @@ This feature was added in Linux 2.6.24, but did not work correctly .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1 until Linux 2.6.28. -.PP +.P Ordinary users are restricted to a value of either 0 or .B ADJ_OFFSET_SS_READ for .IR modes . Only the superuser may set any parameters. -.PP +.P The .I buf.status field is a bit mask that is used to set and/or retrieve status @@ -346,7 +346,7 @@ Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop). .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db .\" Author: Roman Zippel Clock source (0 = A, 1 = B); currently unused. -.PP +.P Attempts to set read-only .I status bits are silently ignored. @@ -452,13 +452,13 @@ The symbolic name is a synonym for .BR TIME_ERROR , provided for backward compatibility. -.PP +.P Note that starting with Linux 3.4, .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous .\" operation, so we can no longer rely on the return code. the call operates asynchronously and the return value usually will not reflect a state change caused by the call itself. -.PP +.P On failure, these calls return \-1 and set .I errno to indicate the error. @@ -548,14 +548,13 @@ T{ .BR \%ntp_adjtime () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR adjtimex () .TQ .BR clock_adjtime () Linux. -.PP +.P The preferred API for the NTP daemon is .BR ntp_adjtime (). .SH NOTES @@ -571,7 +570,7 @@ actually means 2\[ha]-16 ppm, and 2\[ha]16=65536 is 1 ppm. This is the case for both input values (in the case of .IR freq ) and output values. -.PP +.P The leap-second processing triggered by .B STA_INS and @@ -589,7 +588,7 @@ for the leap second to be inserted or deleted. .BR time (7), .BR adjtimex (8), .BR hwclock (8) -.PP +.P .ad l .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm NTP "Kernel Application Program Interface" diff --git a/man2/alarm.2 b/man2/alarm.2 index cae0890..18a93ad 100644 --- a/man2/alarm.2 +++ b/man2/alarm.2 @@ -7,7 +7,7 @@ .\" Modified Sun Jul 21 21:25:26 1996 by Andries Brouwer .\" Modified Wed Nov 6 03:46:05 1996 by Eric S. Raymond .\" -.TH alarm 2 2023-03-30 "Linux man-pages 6.05.01" +.TH alarm 2 2023-10-31 "Linux man-pages 6.7" .SH NAME alarm \- set an alarm clock for delivery of a signal .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "unsigned int alarm(unsigned int " seconds ); .fi .SH DESCRIPTION @@ -26,11 +26,11 @@ arranges for a signal to be delivered to the calling process in .I seconds seconds. -.PP +.P If .I seconds is zero, any pending alarm is canceled. -.PP +.P In any event any previously set .BR alarm () is canceled. @@ -49,14 +49,14 @@ and .BR setitimer (2) share the same timer; calls to one will interfere with use of the other. -.PP +.P Alarms created by .BR alarm () are preserved across .BR execve (2) and are not inherited by children created via .BR fork (2). -.PP +.P .BR sleep (3) may be implemented using .BR SIGALRM ; @@ -65,7 +65,7 @@ mixing calls to and .BR sleep (3) is a bad idea. -.PP +.P Scheduling delays can, as ever, cause the execution of the process to be delayed by an arbitrary amount of time. .SH SEE ALSO diff --git a/man2/alloc_hugepages.2 b/man2/alloc_hugepages.2 index 33671da..0aba97e 100644 --- a/man2/alloc_hugepages.2 +++ b/man2/alloc_hugepages.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH alloc_hugepages 2 2023-03-30 "Linux man-pages 6.05.01" +.TH alloc_hugepages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME alloc_hugepages, free_hugepages \- allocate or free huge pages .SH SYNOPSIS @@ -15,7 +15,7 @@ size_t " len , .BI "int syscall(SYS_free_hugepages, void *" addr ); .\" asmlinkage int sys_free_hugepages(unsigned long addr); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -31,7 +31,7 @@ They existed only on i386 and ia64 (when built with In Linux 2.4.20, the syscall numbers exist, but the calls fail with the error .BR ENOSYS . -.PP +.P On i386 the memory management hardware knows about ordinary pages (4\ KiB) and huge pages (2 or 4\ MiB). Similarly ia64 knows about huge pages of @@ -39,7 +39,7 @@ several sizes. These system calls serve to map huge pages into the process's memory or to free them again. Huge pages are locked into memory, and are not swapped. -.PP +.P The .I key argument is an identifier. @@ -48,7 +48,7 @@ not inherited by children. When positive the pages are shared with other applications using the same .IR key , and inherited by child processes. -.PP +.P The .I addr argument of @@ -63,12 +63,12 @@ argument of .BR alloc_hugepages () is a hint, that the kernel may or may not follow. Addresses must be properly aligned. -.PP +.P The .I len argument is the length of the required segment. It must be a multiple of the huge page size. -.PP +.P The .I prot argument specifies the memory protection of the segment. @@ -76,7 +76,7 @@ It is one of .BR PROT_READ , .BR PROT_WRITE , .BR PROT_EXEC . -.PP +.P The .I flag argument is ignored, unless @@ -124,11 +124,11 @@ Memory backed by huge pages (if the CPU supports them) is obtained by using .BR mmap (2) to map files in this virtual filesystem. -.PP +.P The maximal number of huge pages can be specified using the .B hugepages= boot parameter. -.\".PP +.\".P .\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") .\" and CONFIG_HUGETLBFS (under "Filesystems"). .\" mount \-t hugetlbfs hugetlbfs /huge diff --git a/man2/arch_prctl.2 b/man2/arch_prctl.2 index 04a3633..6981ec3 100644 --- a/man2/arch_prctl.2 +++ b/man2/arch_prctl.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH arch_prctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH arch_prctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME arch_prctl \- set architecture-specific thread state .SH LIBRARY @@ -13,11 +13,11 @@ Standard C library .BR "#include " " /* Definition of " ARCH_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP -.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long " addr ); -.BI "int syscall(SYS_arch_prctl, int " code ", unsigned long *" addr ); +.P +.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long " addr ); +.BI "int syscall(SYS_arch_prctl, int " op ", unsigned long *" addr ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR arch_prctl (), @@ -26,8 +26,8 @@ necessitating the use of .SH DESCRIPTION .BR arch_prctl () sets architecture-specific process or thread state. -.I code -selects a subfunction +.I op +selects an operation and passes argument .I addr to it; @@ -37,7 +37,7 @@ is interpreted as either an for the "set" operations, or as an .IR "unsigned long\ *" , for the "get" operations. -.PP +.P Subfunctions for both x86 and x86-64 are: .TP .BR ARCH_SET_CPUID " (since Linux 4.12)" @@ -120,8 +120,8 @@ is set to indicate the error. points to an unmapped address or is outside the process address space. .TP .B EINVAL -.I code -is not a valid subcommand. +.I op +is not a valid operation. .TP .B ENODEV .B ARCH_SET_CPUID @@ -137,12 +137,12 @@ Linux/x86-64. .SH NOTES .BR arch_prctl () is supported only on Linux/x86-64 for 64-bit programs currently. -.PP +.P The 64-bit base changes when a new 32-bit segment selector is loaded. -.PP +.P .B ARCH_SET_GS is disabled in some kernels. -.PP +.P Context switches for 64-bit segment bases are rather expensive. As an optimization, if a 32-bit TLS base address is used, .BR arch_prctl () @@ -154,14 +154,14 @@ Memory in the first 2\ GB of address space can be allocated by using with the .B MAP_32BIT flag. -.PP +.P Because of the aforementioned optimization, using .BR arch_prctl () and .BR set_thread_area (2) in the same thread is dangerous, as they may overwrite each other's TLS entries. -.PP +.P .I FS may be already used by the threading library. Programs that use @@ -172,5 +172,5 @@ directly are very likely to crash. .BR modify_ldt (2), .BR prctl (2), .BR set_thread_area (2) -.PP +.P AMD X86-64 Programmer's manual diff --git a/man2/bdflush.2 b/man2/bdflush.2 index d97949e..0f1ccca 100644 --- a/man2/bdflush.2 +++ b/man2/bdflush.2 @@ -5,13 +5,13 @@ .\" Modified 1997-01-31 by Eric S. Raymond .\" Modified 2004-06-17 by Michael Kerrisk .\" -.TH bdflush 2 2023-03-30 "Linux man-pages 6.05.01" +.TH bdflush 2 2023-10-31 "Linux man-pages 6.7" .SH NAME bdflush \- start, flush, or tune buffer-dirty-flush daemon .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int bdflush(int " func ", long *" address ); .BI "[[deprecated]] int bdflush(int " func ", long " data ); .fi @@ -26,25 +26,25 @@ Nowadays, the task performed by is handled by the kernel .I pdflush thread. -.PP +.P .BR bdflush () starts, flushes, or tunes the buffer-dirty-flush daemon. Only a privileged process (one with the .B CAP_SYS_ADMIN capability) may call .BR bdflush (). -.PP +.P If .I func is negative or 0, and no daemon has been started, then .BR bdflush () enters the daemon code and never returns. -.PP +.P If .I func is 1, some dirty buffers are written to disk. -.PP +.P If .I func is 2 or more and is even (low bit is 0), then @@ -53,7 +53,7 @@ is the address of a long word, and the tuning parameter numbered .RI "(" "func" "\-2)/2" is returned to the caller in that address. -.PP +.P If .I func is 3 or more and is odd (low bit is 1), then @@ -62,7 +62,7 @@ is a long word, and the kernel sets tuning parameter numbered .RI "(" "func" "\-3)/2" to that value. -.PP +.P The set of parameters, their values, and their valid ranges are defined in the Linux kernel source file .IR fs/buffer.c . diff --git a/man2/bind.2 b/man2/bind.2 index 6288c41..0fc3308 100644 --- a/man2/bind.2 +++ b/man2/bind.2 @@ -18,7 +18,7 @@ .\" $Id: bind.2,v 1.3 1999/04/23 19:56:07 freitag Exp $ .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH bind 2 2023-05-03 "Linux man-pages 6.05.01" +.TH bind 2 2023-10-31 "Linux man-pages 6.7" .SH NAME bind \- bind a name to a socket .SH LIBRARY @@ -27,7 +27,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int bind(int " sockfd ", const struct sockaddr *" addr , .BI " socklen_t " addrlen ); .fi @@ -44,14 +44,14 @@ to the socket referred to by the file descriptor specifies the size, in bytes, of the address structure pointed to by .IR addr . Traditionally, this operation is called \[lq]assigning a name to a socket\[rq]. -.PP +.P It is normally necessary to assign a local address using .BR bind () before a .B SOCK_STREAM socket may receive connections (see .BR accept (2)). -.PP +.P The rules used in name binding vary between address families. Consult the manual entries in Section 7 for detailed information. For @@ -82,14 +82,14 @@ and for .BR AF_NETLINK , see .BR netlink (7). -.PP +.P The actual structure passed for the .I addr argument will depend on the address family. The .I sockaddr structure is defined as something like: -.PP +.P .in +4n .EX struct sockaddr { @@ -98,7 +98,7 @@ struct sockaddr { } .EE .in -.PP +.P The only purpose of this structure is to cast the structure pointer passed in .I addr @@ -147,7 +147,7 @@ is not a valid address for this socket's domain. The file descriptor .I sockfd does not refer to a socket. -.PP +.P The following errors are specific to UNIX domain .RB ( AF_UNIX ) sockets: @@ -206,14 +206,14 @@ An example of the use of .BR bind () with Internet domain sockets can be found in .BR getaddrinfo (3). -.PP +.P The following example shows how to bind a stream socket in the UNIX .RB ( AF_UNIX ) domain, and accept connections: .\" listen.7 refers to this example. .\" accept.7 refers to this example. .\" unix.7 refers to this example. -.PP +.P .\" SRC BEGIN (bind.c) .EX #include diff --git a/man2/bpf.2 b/man2/bpf.2 index 4df108d..2822076 100644 --- a/man2/bpf.2 +++ b/man2/bpf.2 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH bpf 2 2023-07-28 "Linux man-pages 6.05.01" +.TH bpf 2 2024-03-18 "Linux man-pages 6.7" .SH NAME bpf \- perform a command on an extended BPF map or program .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int bpf(int " cmd ", union bpf_attr *" attr ", unsigned int " size ); .fi .SH DESCRIPTION @@ -22,7 +22,7 @@ the original ("classic") BPF (cBPF) used to filter network packets. For both cBPF and eBPF programs, the kernel statically analyzes the programs before loading them, in order to ensure that they cannot harm the running system. -.PP +.P eBPF extends cBPF in multiple ways, including the ability to call a fixed set of in-kernel helper functions .\" See 'enum bpf_func_id' in include/uapi/linux/bpf.h @@ -36,13 +36,13 @@ eBPF maps are a generic data structure for storage of different data types. Data types are generally treated as binary blobs, so a user just specifies the size of the key and the size of the value at map-creation time. In other words, a key/value for a given map can have an arbitrary structure. -.PP +.P A user process can create multiple maps (with key/value-pairs being opaque bytes of data) and access them via file descriptors. Different eBPF programs can access the same maps in parallel. It's up to the user process and eBPF program to decide what they store inside maps. -.PP +.P There's one special map type, called a program array. This type of map stores file descriptors referring to other eBPF programs. When a lookup in the map is performed, the program flow is @@ -60,7 +60,7 @@ If a map lookup fails, the current program continues its execution. See .B BPF_MAP_TYPE_PROG_ARRAY below for further details. -.PP +.P Generally, eBPF programs are loaded by the user process and automatically unloaded when the process exits. In some cases, for example, @@ -74,7 +74,7 @@ Thus, whether a specific program continues to live inside the kernel depends on how it is further attached to a given kernel subsystem after it was loaded via .BR bpf (). -.PP +.P Each eBPF program is a set of instructions that is safe to run until its completion. An in-kernel verifier statically determines that the eBPF program @@ -82,7 +82,7 @@ terminates and is safe to execute. During verification, the kernel increments reference counts for each of the maps that the eBPF program uses, so that the attached maps can't be removed until the program is unloaded. -.PP +.P eBPF programs can be attached to different events. These events can be the arrival of network packets, tracing events, classification events by network queueing disciplines @@ -93,10 +93,10 @@ A new event triggers execution of the eBPF program, which may store information about the event in eBPF maps. Beyond storing data, eBPF programs may call a fixed set of in-kernel helper functions. -.PP +.P The same eBPF program can be attached to multiple events and different eBPF programs can access the same map: -.PP +.P .in +4n .EX tracing tracing tracing packet packet packet @@ -128,7 +128,7 @@ The .I size argument is the size of the union pointed to by .IR attr . -.PP +.P The value provided in .I cmd is one of the following: @@ -164,7 +164,7 @@ The union consists of various anonymous structures that are used by different .BR bpf () commands: -.PP +.P .in +4n .EX union bpf_attr { @@ -209,7 +209,7 @@ union bpf_attr { Maps are a generic data structure for storage of different types of data. They allow sharing of data between eBPF kernel programs, and also between kernel and user-space applications. -.PP +.P Each map type has the following attributes: .IP \[bu] 3 type @@ -219,7 +219,7 @@ maximum number of elements key size in bytes .IP \[bu] value size in bytes -.PP +.P The following wrapper functions demonstrate how various .BR bpf () commands can be used to access the maps. @@ -710,7 +710,7 @@ The command is used to load an eBPF program into the kernel. The return value for this command is a new file descriptor associated with this eBPF program. -.PP +.P .in +4n .EX char bpf_log_buf[LOG_BUF_SIZE]; @@ -734,7 +734,7 @@ bpf_prog_load(enum bpf_prog_type type, } .EE .in -.PP +.P .I prog_type is one of the available program types: .IP @@ -769,9 +769,9 @@ enum bpf_prog_type { }; .EE .in -.PP +.P For further details of eBPF program types, see below. -.PP +.P The remaining fields of .I bpf_attr are set as follows: @@ -814,16 +814,16 @@ verbosity level of the verifier. A value of zero means that the verifier will not provide a log; in this case, .I log_buf -must be a NULL pointer, and +must be a null pointer, and .I log_size must be zero. -.PP +.P Applying .BR close (2) to the file descriptor returned by .B BPF_PROG_LOAD will unload the eBPF program (but see NOTES). -.PP +.P Maps are accessible from eBPF programs and are used to exchange data between eBPF programs and between eBPF programs and user-space programs. For example, @@ -849,17 +849,17 @@ format of .\" Somewhere in this page we need a general introduction to the .\" bpf_context. For example, how does a BPF program access the .\" context? -.PP +.P For example, a tracing program does not have the exact same subset of helper functions as a socket filter program (though they may have some helpers in common). Similarly, the input (context) for a tracing program is a set of register values, while for a socket filter it is a network packet. -.PP +.P The set of functions available to eBPF programs of a given type may increase in the future. -.PP +.P The following program types are supported: .TP .BR BPF_PROG_TYPE_SOCKET_FILTER " (since Linux 3.19)" @@ -918,7 +918,7 @@ argument is a pointer to a .SS Events Once a program is loaded, it can be attached to an event. Various kernel subsystems have different ways to do so. -.PP +.P Since Linux 3.19, .\" commit 89aa075832b0da4402acebd698d0411dcc82d03e the following call will attach the program @@ -927,14 +927,14 @@ to the socket .IR sockfd , which was created by an earlier call to .BR socket (2): -.PP +.P .in +4n .EX setsockopt(sockfd, SOL_SOCKET, SO_ATTACH_BPF, &prog_fd, sizeof(prog_fd)); .EE .in -.PP +.P Since Linux 4.1, .\" commit 2541517c32be2531e0da59dfd7efc1ce844644f5 the following call may be used to attach @@ -944,7 +944,7 @@ to a perf event file descriptor, .IR event_fd , that was created by a previous call to .BR perf_event_open (2): -.PP +.P .in +4n .EX ioctl(event_fd, PERF_EVENT_IOC_SET_BPF, prog_fd); @@ -963,7 +963,7 @@ The new file descriptor associated with the eBPF program. .TP All other commands Zero. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -1091,10 +1091,10 @@ tail_call .IP \[bu] ktime_get_ns .PD -.PP +.P Unprivileged access may be blocked by writing the value 1 to the file .IR /proc/sys/kernel/unprivileged_bpf_disabled . -.PP +.P eBPF objects (maps and programs) can be shared between processes. For example, after .BR fork (2), @@ -1107,7 +1107,7 @@ in the usual way, using and similar calls. An eBPF object is deallocated only after all file descriptors referring to the object have been closed. -.PP +.P eBPF programs can be written in a restricted C that is compiled (using the .B clang compiler) into eBPF bytecode. @@ -1119,7 +1119,7 @@ Some examples can be found in the files in the kernel source tree. .\" There are also examples for the tc classifier, in the iproute2 .\" project, in examples/bpf -.PP +.P The kernel contains a just-in-time (JIT) compiler that translates eBPF bytecode into native machine code for better performance. Before Linux 4.15, @@ -1140,10 +1140,10 @@ The generated opcodes are dumped in hexadecimal into the kernel log. These opcodes can then be disassembled using the program .I tools/net/bpf_jit_disasm.c provided in the kernel source tree. -.PP +.P Since Linux 4.15, .\" commit 290af86629b25ffd1ed6232c4e9107da031705cb -the kernel may configured with the +the kernel may be configured with the .B CONFIG_BPF_JIT_ALWAYS_ON option. In this case, the JIT compiler is always enabled, and the @@ -1151,7 +1151,7 @@ In this case, the JIT compiler is always enabled, and the is initialized to 1 and is immutable. (This kernel configuration option was provided as a mitigation for one of the Spectre attacks against the BPF interpreter.) -.PP +.P The JIT compiler for eBPF is currently .\" Last reviewed in Linux 4.18-rc by grepping for BPF_ALU64 in arch/ .\" and by checking the documentation for bpf_jit_enable in @@ -1192,7 +1192,7 @@ riscv (since Linux 5.1). .\" commit 2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2 .PD .SH EXAMPLES -.\" [[FIXME]] SRC BEGIN (bpf.c) +.\" SRC BEGIN (bpf.c) .EX /* bpf+sockets example: * 1. create array map of 256 elements @@ -1258,7 +1258,7 @@ main(int argc, char *argv[]) } .EE .\" SRC END -.PP +.P Some complete working code can be found in the .I samples/bpf directory in the kernel source tree. @@ -1268,6 +1268,6 @@ directory in the kernel source tree. .BR socket (7), .BR tc (8), .BR tc\-bpf (8) -.PP +.P Both classic and extended BPF are explained in the kernel source file .IR Documentation/networking/filter.txt . diff --git a/man2/brk.2 b/man2/brk.2 index 2cc61a9..0248459 100644 --- a/man2/brk.2 +++ b/man2/brk.2 @@ -7,7 +7,7 @@ .\" Modified Wed Jul 21 19:52:58 1993 by Rik Faith .\" Modified Sun Aug 21 17:40:38 1994 by Rik Faith .\" -.TH brk 2 2023-03-30 "Linux man-pages 6.05.01" +.TH brk 2 2023-10-31 "Linux man-pages 6.7" .SH NAME brk, sbrk \- change data segment size .SH LIBRARY @@ -16,16 +16,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int brk(void *" addr ); .BI "void *sbrk(intptr_t " increment ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR brk (), .BR sbrk (): .nf @@ -57,14 +57,14 @@ uninitialized data segment). Increasing the program break has the effect of allocating memory to the process; decreasing the break deallocates memory. -.PP +.P .BR brk () sets the end of the data segment to the value specified by .IR addr , when that value is reasonable, the system has enough memory, and the process does not exceed its maximum data size (see .BR setrlimit (2)). -.PP +.P .BR sbrk () increments the program's data space by .I increment @@ -82,7 +82,7 @@ On error, \-1 is returned, and .I errno is set to .BR ENOMEM . -.PP +.P On success, .BR sbrk () returns the previous program break. @@ -113,7 +113,7 @@ the .BR malloc (3) memory allocation package is the portable and comfortable way of allocating memory. -.PP +.P Various systems use various types for the argument of .BR sbrk (). Common are \fIint\fP, \fIssize_t\fP, \fIptrdiff_t\fP, \fIintptr_t\fP. @@ -139,7 +139,7 @@ The glibc wrapper function does some work (i.e., checks whether the new break is less than .IR addr ) to provide the 0 and \-1 return values described above. -.PP +.P On Linux, .BR sbrk () is implemented as a library function that uses the diff --git a/man2/cacheflush.2 b/man2/cacheflush.2 index 733462e..b2a5f26 100644 --- a/man2/cacheflush.2 +++ b/man2/cacheflush.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cacheflush 2 2023-03-30 "Linux man-pages 6.05.01" +.TH cacheflush 2 2023-10-31 "Linux man-pages 6.7" .SH NAME cacheflush \- flush contents of instruction and/or data cache .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int cacheflush(void " addr [. nbytes "], int "nbytes ", int "cache ); .fi -.PP +.P .IR Note : On some architectures, there is no glibc wrapper for this system call; see NOTES. @@ -73,7 +73,7 @@ glibc provides a wrapper for this system call, with the prototype shown in SYNOPSIS, for the following architectures: ARC, CSKY, MIPS, and NIOS2. -.PP +.P On some other architectures, Linux provides this system call, with different arguments: .TP @@ -92,7 +92,7 @@ NDS32: .nf .BI "int cacheflush(unsigned int " start ", unsigned int " end ", int " cache ); .fi -.PP +.P On the above architectures, glibc does not provide a wrapper for this system call; call it using .BR syscall (2). @@ -102,17 +102,17 @@ you probably want to use the GCC built-in function .BR __builtin___clear_cache (), which provides a portable interface across platforms supported by GCC and compatible compilers: -.PP +.P .in +4n .EX .BI "void __builtin___clear_cache(void *" begin ", void *" end ); .EE .in -.PP +.P On platforms that don't require instruction cache flushes, .BR __builtin___clear_cache () has no effect. -.PP +.P .IR Note : On some GCC-compatible compilers, the prototype for this built-in function uses @@ -133,7 +133,7 @@ and .I nbytes arguments, making this function fairly expensive. Therefore, the whole cache is always flushed. -.PP +.P This function always behaves as if .B BCACHE has been passed for the diff --git a/man2/capget.2 b/man2/capget.2 index 9c4ba7d..db9ad25 100644 --- a/man2/capget.2 +++ b/man2/capget.2 @@ -11,7 +11,7 @@ .\" 64-bit capability sets in Linux 2.6.2[45]. .\" Modified 2009-01-26, andi kleen .\" -.TH capget 2 2023-05-03 "Linux man-pages 6.05.01" +.TH capget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME capget, capset \- set/get capabilities of thread(s) .SH LIBRARY @@ -23,13 +23,13 @@ Standard C library .BR " _LINUX_CAPABILITY_*" " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_capget, cap_user_header_t " hdrp , .BI " cap_user_data_t " datap ); .BI "int syscall(SYS_capset, cap_user_header_t " hdrp , .BI " const cap_user_data_t " datap ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -43,7 +43,7 @@ these system calls (in particular the format of the .I cap_user_*_t types) is subject to extension with each kernel revision, but old programs will keep working. -.PP +.P The portable interfaces are .BR cap_set_proc (3) and @@ -53,7 +53,7 @@ if possible, you should use those interfaces in applications; see NOTES. .SS Current details Now that you have been warned, some current kernel details. The structures are defined as follows. -.PP +.P .in +4n .EX #define _LINUX_CAPABILITY_VERSION_1 0x19980330 @@ -82,7 +82,7 @@ typedef struct __user_cap_data_struct { } *cap_user_data_t; .EE .in -.PP +.P The .IR effective , .IR permitted , @@ -99,7 +99,7 @@ To define the structures for passing to the system call, you have to use the and .I struct __user_cap_data_struct names because the typedefs are only pointers. -.PP +.P Kernels prior to Linux 2.6.25 prefer 32-bit capabilities with version .BR _LINUX_CAPABILITY_VERSION_1 . @@ -108,26 +108,26 @@ Linux 2.6.25 added 64-bit capability sets, with version There was, however, an API glitch, and Linux 2.6.26 added .B _LINUX_CAPABILITY_VERSION_3 to fix the problem. -.PP +.P Note that 64-bit capabilities use .I datap[0] and .IR datap[1] , whereas 32-bit capabilities use only .IR datap[0] . -.PP +.P On kernels that support file capabilities (VFS capabilities support), these system calls behave slightly differently. This support was added as an option in Linux 2.6.24, and became fixed (nonoptional) in Linux 2.6.33. -.PP +.P For .BR capget () calls, one can probe the capabilities of any process by specifying its process ID with the .I hdrp\->pid field value. -.PP +.P For details on the data, see .BR capabilities (7). .\" @@ -179,7 +179,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P The calls fail with the error .BR EINVAL , and set the diff --git a/man2/chdir.2 b/man2/chdir.2 index 5aca7bf..33e7473 100644 --- a/man2/chdir.2 +++ b/man2/chdir.2 @@ -10,7 +10,7 @@ .\" Modified 1997-08-21 by Joseph S. Myers .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH chdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH chdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chdir, fchdir \- change working directory .SH LIBRARY @@ -19,16 +19,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int chdir(const char *" path ); .BI "int fchdir(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fchdir (): .nf _XOPEN_SOURCE >= 500 @@ -41,7 +41,7 @@ Feature Test Macro Requirements for glibc (see changes the current working directory of the calling process to the directory specified in .IR path . -.PP +.P .BR fchdir () is identical to .BR chdir (); @@ -92,7 +92,7 @@ Insufficient kernel memory was available. A component of .I path is not a directory. -.PP +.P The general errors for .BR fchdir () are listed below: @@ -115,7 +115,7 @@ POSIX.1-2001, SVr4, 4.4BSD. .SH NOTES The current working directory is the starting point for interpreting relative pathnames (those not starting with \[aq]/\[aq]). -.PP +.P A child process created via .BR fork (2) inherits its parent's current working directory. diff --git a/man2/chmod.2 b/man2/chmod.2 index b1c130e..d7b9694 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -9,7 +9,7 @@ .\" : NFS details .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH chmod 2 2023-03-30 "Linux man-pages 6.05.01" +.TH chmod 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chmod, fchmod, fchmodat \- change permissions of a file .SH LIBRARY @@ -18,22 +18,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int chmod(const char *" pathname ", mode_t " mode ); .BI "int fchmod(int " fd ", mode_t " mode ); -.PP +.P .BR "#include " " /* Definition of AT_* constants */" .B #include -.PP +.P .BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \ mode ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR fchmod (): Since glibc 2.24: @@ -50,7 +50,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE >= 500 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) .fi -.PP +.P .BR fchmodat (): .nf Since glibc 2.10: @@ -76,7 +76,7 @@ which is dereferenced if it is a symbolic link. .BR fchmod () changes the mode of the file referred to by the open file descriptor .IR fd . -.PP +.P The new file mode is specified in .IR mode , which is a bit mask created by ORing together zero or @@ -127,12 +127,12 @@ write by others .TP .BR S_IXOTH " (00001)" execute/search by others -.PP +.P The effective UID of the calling process must match the owner of the file, or the process must be privileged (Linux: it must have the .B CAP_FOWNER capability). -.PP +.P If the calling process is not privileged (Linux: does not have the .B CAP_FSETID capability), and the group of the file does not match @@ -141,7 +141,7 @@ supplementary group IDs, the .B S_ISGID bit will be turned off, but this will not cause an error to be returned. -.PP +.P As a security measure, depending on the filesystem, the set-user-ID and set-group-ID execution bits may be turned off if a file is written. @@ -153,7 +153,7 @@ which may have a special meaning. For the sticky bit, and for set-user-ID and set-group-ID bits on directories, see .BR inode (7). -.PP +.P On NFS filesystems, restricting the permissions will immediately influence already open files, because the access control is done on the server, but open files are maintained by the client. @@ -167,7 +167,7 @@ The system call operates in exactly the same way as .BR chmod (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -177,7 +177,7 @@ referred to by the file descriptor the calling process, as is done by .BR chmod () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -189,13 +189,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR chmod ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags can either be 0, or include the following flag: .TP @@ -205,7 +205,7 @@ If is a symbolic link, do not dereference it: instead operate on the link itself. This flag is not currently implemented. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -218,7 +218,7 @@ is set to indicate the error. .SH ERRORS Depending on the filesystem, errors other than those listed below can be returned. -.PP +.P The more general errors for .BR chmod () are listed below: diff --git a/man2/chown.2 b/man2/chown.2 index ff7c6dd..f71030d 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -15,7 +15,7 @@ .\" (bsdgroups versus sysvgroups, and the effect of the parent .\" directory's set-group-ID mode bit). .\" -.TH chown 2 2023-05-03 "Linux man-pages 6.05.01" +.TH chown 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chown, fchown, lchown, fchownat \- change ownership of a file .SH LIBRARY @@ -24,23 +24,23 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group ); .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); .BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group ); -.PP +.P .BR "#include " "/* Definition of AT_* constants */" .B #include -.PP +.P .BI "int fchownat(int " dirfd ", const char *" pathname , .BI " uid_t " owner ", gid_t " group ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fchown (), .BR lchown (): .nf @@ -49,7 +49,7 @@ Feature Test Macro Requirements for glibc (see .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR fchownat (): .nf Since glibc 2.10: @@ -79,7 +79,7 @@ changes the ownership of the file referred to by the open file descriptor is like .BR chown (), but does not dereference symbolic links. -.PP +.P Only a privileged process (Linux: one with the .B CAP_CHOWN capability) may change the owner of a file. @@ -88,13 +88,13 @@ to any group of which that owner is a member. A privileged process (Linux: with .BR CAP_CHOWN ) may change the group arbitrarily. -.PP +.P If the .I owner or .I group is specified as \-1, then that ID is not changed. -.PP +.P When the owner or group of an executable file is changed by an unprivileged user, the .B S_ISUID @@ -115,7 +115,7 @@ bit is not set) the .B S_ISGID bit indicates mandatory locking, and is not cleared by a .BR chown (). -.PP +.P When the owner or group of an executable file is changed (by any user), all capability sets for the file are cleared. .\" @@ -125,7 +125,7 @@ The system call operates in exactly the same way as .BR chown (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -135,7 +135,7 @@ referred to by the file descriptor the calling process, as is done by .BR chown () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -147,13 +147,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR chown ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P The .I flags argument is a bit mask created by ORing together @@ -192,7 +192,7 @@ instead operate on the link itself, like .BR fchownat () dereferences symbolic links, like .BR chown ().) -.PP +.P See .BR openat (2) for an explanation of the need for @@ -205,7 +205,7 @@ is set to indicate the error. .SH ERRORS Depending on the filesystem, errors other than those listed below can be returned. -.PP +.P The more general errors for .BR chown () are listed below. @@ -341,7 +341,7 @@ If the filesystem is mounted with and the set-group-ID bit is enabled on the parent directory, then the group of a new file is made the same as that of the parent directory. -.PP +.P As at Linux 4.12, the .B \-o\ grpid @@ -398,7 +398,7 @@ The glibc and .BR lchown () wrapper functions transparently deal with the variations across kernel versions. -.PP +.P Before Linux 2.1.81 (except 2.1.46), .BR chown () did not follow symbolic links. diff --git a/man2/chroot.2 b/man2/chroot.2 index d872b8a..bdba54f 100644 --- a/man2/chroot.2 +++ b/man2/chroot.2 @@ -10,7 +10,7 @@ .\" Modified 1997-08-21 by Joseph S. Myers .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH chroot 2 2023-04-03 "Linux man-pages 6.05.01" +.TH chroot 2 2023-10-31 "Linux man-pages 6.7" .SH NAME chroot \- change root directory .SH LIBRARY @@ -19,15 +19,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int chroot(const char *" path ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR chroot (): .nf Since glibc 2.2.2: @@ -43,12 +43,12 @@ changes the root directory of the calling process to that specified in .IR path . This directory will be used for pathnames beginning with \fI/\fP. The root directory is inherited by all children of the calling process. -.PP +.P Only a privileged process (Linux: one with the .B CAP_SYS_CHROOT capability in its user namespace) may call .BR chroot (). -.PP +.P This call changes an ingredient in the pathname resolution process and does nothing else. In particular, it is not intended to be used @@ -65,7 +65,7 @@ The easiest way to do that is to .BR chdir (2) to the to-be-moved directory, wait for it to be moved out, then open a path like ../../../etc/passwd. -.PP +.P .\" This is how the "slightly trickier variation" works: .\" https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-014-2015.txt#L142 A slightly @@ -76,19 +76,19 @@ If a daemon allows a "chroot directory" to be specified, that usually means that if you want to prevent remote users from accessing files outside the chroot directory, you must ensure that folders are never moved out of it. -.PP +.P This call does not change the current working directory, so that after the call \[aq]\fI.\fP\[aq] can be outside the tree rooted at \[aq]\fI/\fP\[aq]. In particular, the superuser can escape from a "chroot jail" by doing: -.PP +.P .in +4n .EX mkdir foo; chroot foo; cd .. .EE .in -.PP +.P This call does not close open file descriptors, and such file descriptors may allow access to files outside the chroot tree. .SH RETURN VALUE @@ -148,13 +148,13 @@ A child process created via inherits its parent's root directory. The root directory is left unchanged by .BR execve (2). -.PP +.P The magic symbolic link, .IR /proc/ pid /root , can be used to discover a process's root directory; see .BR proc (5) for details. -.PP +.P FreeBSD has a stronger .BR jail () system call. diff --git a/man2/clock_getres.2 b/man2/clock_getres.2 index 170215d..ec1e327 100644 --- a/man2/clock_getres.2 +++ b/man2/clock_getres.2 @@ -9,32 +9,32 @@ .\" 2003-08-24 aeb, large parts rewritten .\" 2004-08-06 Christoph Lameter , SMP note .\" -.TH clock_getres 2 2023-07-20 "Linux man-pages 6.05.01" +.TH clock_getres 2 2024-03-05 "Linux man-pages 6.7" .SH NAME clock_getres, clock_gettime, clock_settime \- clock and time functions .SH LIBRARY Standard C library .RI ( libc ", " \-lc ), since glibc 2.17 -.PP +.P Before glibc 2.17, Real-time library .RI ( librt ", " \-lrt ) .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int clock_getres(clockid_t " clockid ", struct timespec *_Nullable " res ); -.PP +.P .BI "int clock_gettime(clockid_t " clockid ", struct timespec *" tp ); .BI "int clock_settime(clockid_t " clockid ", const struct timespec *" tp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR clock_getres (), .BR clock_gettime (), .BR clock_settime (): @@ -60,14 +60,14 @@ is not a multiple of .IR res , then it is truncated to a multiple of .IR res . -.PP +.P The functions .BR clock_gettime () and .BR clock_settime () retrieve and set the time of the specified clock .IR clockid . -.PP +.P The .I res and @@ -75,24 +75,24 @@ and arguments are .BR timespec (3) structures. -.PP +.P The .I clockid argument is the identifier of the particular clock on which to act. A clock may be system-wide and hence visible for all processes, or per-process if it measures time only within a single process. -.PP +.P All implementations support the system-wide real-time clock, which is identified by .BR CLOCK_REALTIME . Its time represents seconds and nanoseconds since the Epoch. When its time is changed, timers for a relative interval are unaffected, but timers for an absolute point in time are affected. -.PP +.P More clocks may be implemented. The interpretation of the corresponding time values and the effect on timers is unspecified. -.PP +.P Sufficiently recent versions of glibc and the Linux kernel support the following clocks: .TP @@ -101,9 +101,17 @@ A settable system-wide clock that measures real (i.e., wall-clock) time. Setting this clock requires appropriate privileges. This clock is affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the clock), -and by the incremental adjustments performed by -.BR adjtime (3) -and NTP. +and by frequency adjustments performed by NTP and similar applications via +.BR adjtime (3), +.BR adjtimex (2), +.BR clock_adjtime (2), +and +.BR ntp_adjtime (3). +This clock normally counts the number of seconds since +1970-01-01 00:00:00 Coordinated Universal Time (UTC) +except that it ignores leap seconds; +near a leap second it is typically adjusted by NTP +to stay roughly in sync with UTC. .TP .BR CLOCK_REALTIME_ALARM " (since Linux 3.0; Linux-specific)" Like @@ -126,9 +134,9 @@ and probably also architecture support for this flag in the .BR CLOCK_TAI " (since Linux 3.10; Linux-specific)" .\" commit 1ff3c9677bff7e468e0c487d0ffefe4e901d33f4 A nonsettable system-wide clock derived from wall-clock time -but ignoring leap seconds. +but counting leap seconds. This clock does -not experience discontinuities and backwards jumps caused by NTP +not experience discontinuities or frequency adjustments caused by inserting leap seconds as .B CLOCK_REALTIME does. @@ -146,9 +154,7 @@ The .B CLOCK_MONOTONIC clock is not affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the clock), -but is affected by the incremental adjustments performed by -.BR adjtime (3) -and NTP. +but is affected by frequency adjustments. This clock does not count time that the system is suspended. All .B CLOCK_MONOTONIC @@ -170,9 +176,7 @@ and probably also architecture support for this flag in the Similar to .BR CLOCK_MONOTONIC , but provides access to a raw hardware-based time -that is not subject to NTP adjustments or -the incremental adjustments performed by -.BR adjtime (3). +that is not subject to frequency adjustments. This clock does not count time that the system is suspended. .TP .BR CLOCK_BOOTTIME " (since Linux 2.6.39; Linux-specific)" @@ -203,7 +207,7 @@ On Linux, this clock is not settable. .BR CLOCK_THREAD_CPUTIME_ID " (since Linux 2.6.12)" This is a clock that measures CPU time consumed by this thread. On Linux, this clock is not settable. -.PP +.P Linux also implements dynamic clock instances as described below. .SS Dynamic clocks In addition to the hard-coded System-V style clock IDs described above, @@ -211,7 +215,7 @@ Linux also supports POSIX clock operations on certain character devices. Such devices are called "dynamic" clocks, and are supported since Linux 2.6.39. -.PP +.P Using the appropriate macros, open file descriptors may be converted into clock IDs and passed to .BR clock_gettime (), @@ -220,7 +224,7 @@ and .BR clock_adjtime (2). The following example shows how to convert a file descriptor into a dynamic clock ID. -.PP +.P .in +4n .EX #define CLOCKFD 3 @@ -304,6 +308,17 @@ has disappeared after its character device was opened. The operation is not supported by the dynamic POSIX clock device specified. .TP +.B EOVERFLOW +The timestamp would not fit in +.I time_t +range. +This can happen if an executable with 32-bit +.I time_t +is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later. +However, when the system time is out of +.I time_t +range in other situations, the behavior is undefined. +.TP .B EPERM .BR clock_settime () does not have permission to set the clock indicated. @@ -323,11 +338,10 @@ T{ .BR clock_settime () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS POSIX.1 specifies the following: .RS -.PP +.P Setting the value of the .B CLOCK_REALTIME clock via @@ -339,7 +353,7 @@ function; nor on the expiration of relative timers based upon this clock. Consequently, these time services shall expire when the requested relative interval elapses, independently of the new or old value of the clock. .RE -.PP +.P According to POSIX.1-2001, a process with "appropriate privileges" may set the .B CLOCK_PROCESS_CPUTIME_ID and @@ -359,10 +373,12 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SUSv2. Linux 2.6. -.PP +.P On POSIX systems on which these functions are available, the symbol .B _POSIX_TIMERS is defined in \fI\fP to a value greater than 0. +POSIX.1-2008 makes these functions mandatory. +.P The symbols .BR _POSIX_MONOTONIC_CLOCK , .BR _POSIX_CPUTIME , @@ -374,7 +390,6 @@ indicate that are available. (See also .BR sysconf (3).) -POSIX.1-2008 makes these APIs mandatory. .\" .SS Historical note for SMP systems Before Linux added kernel support for @@ -388,7 +403,7 @@ These registers may differ between CPUs and as a consequence these clocks may return .B bogus results if a process is migrated to another CPU. -.PP +.P If the CPUs in an SMP system have different clock sources, then there is no way to maintain a correlation between the timer registers since each CPU will run at a slightly different frequency. @@ -399,7 +414,7 @@ will return to signify this condition. The two clocks will then be useful only if it can be ensured that a process stays on a certain CPU. -.PP +.P The processors in an SMP system do not start all at exactly the same time and therefore the timer registers are typically running at an offset. Some architectures include code that attempts to limit these offsets on bootup. @@ -408,7 +423,7 @@ glibc contains no provisions to deal with these offsets (unlike the Linux Kernel). Typically these offsets are small and therefore the effects may be negligible in most cases. -.PP +.P Since glibc 2.4, the wrapper functions for the system calls described in this page avoid the abovementioned problems by employing the kernel implementation of @@ -424,7 +439,7 @@ and .BR clock_getres () with various clocks. This is an example of what we might see when running the program: -.PP +.P .in +4n .EX $ \fB./clock_times x\fP diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2 index d1e53a6..12948c7 100644 --- a/man2/clock_nanosleep.2 +++ b/man2/clock_nanosleep.2 @@ -3,31 +3,31 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH clock_nanosleep 2 2023-03-30 "Linux man-pages 6.05.01" +.TH clock_nanosleep 2 2024-03-05 "Linux man-pages 6.7" .SH NAME clock_nanosleep \- high-resolution sleep with specifiable clock .SH LIBRARY Standard C library .RI ( libc ", " \-lc ), since glibc 2.17 -.PP +.P Before glibc 2.17, Real-time library .RI ( librt ", " \-lrt ) .SH SYNOPSIS .B #include .nf -.PP +.P .BI "int clock_nanosleep(clockid_t " clockid ", int " flags , -.BI " const struct timespec *" request , +.BI " const struct timespec *" t , .BI " struct timespec *_Nullable " remain ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR clock_nanosleep (): .nf _POSIX_C_SOURCE >= 200112L @@ -42,11 +42,11 @@ It differs in allowing the caller to select the clock against which the sleep interval is to be measured, and in allowing the sleep interval to be specified as either an absolute or a relative value. -.PP +.P The time values passed to and returned by this call are specified using .BR timespec (3) structures. -.PP +.P The .I clockid argument specifies the clock against which the sleep interval @@ -59,7 +59,7 @@ This argument can have one of the following values: A settable system-wide real-time clock. .TP .BR CLOCK_TAI " (since Linux 3.10)" -A system-wide clock derived from wall-clock time but ignoring leap seconds. +A system-wide clock derived from wall-clock time but counting leap seconds. .TP .B CLOCK_MONOTONIC A nonsettable, monotonically increasing clock that measures time @@ -77,7 +77,7 @@ A settable per-process clock that measures CPU time consumed by all threads in the process. .\" There is some trickery between glibc and the kernel .\" to deal with the CLOCK_PROCESS_CPUTIME_ID case. -.PP +.P See .BR clock_getres (2) for further details on these clocks. @@ -90,38 +90,38 @@ can also be passed in .\" Sleeping against CLOCK_REALTIME_ALARM and CLOCK_BOOTTIME_ALARM .\" is also possible (tested), with CAP_WAKE_ALARM, but I'm not .\" sure if this is useful or needs to be documented. -.PP +.P If .I flags is 0, then the value specified in -.I request +.I t is interpreted as an interval relative to the current value of the clock specified by .IR clockid . -.PP +.P If .I flags is .BR TIMER_ABSTIME , then -.I request +.I t is interpreted as an absolute time as measured by the clock, .IR clockid . If -.I request +.I t is less than or equal to the current value of the clock, then .BR clock_nanosleep () returns immediately without suspending the calling thread. -.PP +.P .BR clock_nanosleep () suspends the execution of the calling thread until either at least the time specified by -.I request +.I t has elapsed, or a signal is delivered that causes a signal handler to be called or that terminates the process. -.PP +.P If the call is interrupted by a signal handler, .BR clock_nanosleep () fails with the error @@ -146,7 +146,7 @@ then it returns one of the positive error number listed in ERRORS. .SH ERRORS .TP .B EFAULT -.I request +.I t or .I remain specified an invalid address. @@ -180,13 +180,13 @@ Linux 2.6, glibc 2.1. .SH NOTES If the interval specified in -.I request +.I t is not an exact multiple of the granularity underlying clock (see .BR time (7)), then the interval will be rounded up to the next multiple. Furthermore, after the sleep completes, there may still be a delay before the CPU becomes free to once again execute the calling thread. -.PP +.P Using an absolute timer is useful for preventing timer drift problems of the type described in .BR nanosleep (2). @@ -201,14 +201,14 @@ and then call with the .B TIMER_ABSTIME flag. -.PP +.P .BR clock_nanosleep () is never restarted after being interrupted by a signal handler, regardless of the use of the .BR sigaction (2) .B SA_RESTART flag. -.PP +.P The .I remain argument is unused, and unnecessary, when @@ -216,13 +216,13 @@ argument is unused, and unnecessary, when is .BR TIMER_ABSTIME . (An absolute sleep can be restarted using the same -.I request +.I t argument.) -.PP +.P POSIX.1 specifies that .BR clock_nanosleep () has no effect on signals dispositions or the signal mask. -.PP +.P POSIX.1 specifies that after changing the value of the .B CLOCK_REALTIME clock via @@ -234,7 +234,7 @@ will wake up; if the new clock value falls past the end of the sleep interval, then the .BR clock_nanosleep () call will return immediately. -.PP +.P POSIX.1 specifies that changing the value of the .B CLOCK_REALTIME diff --git a/man2/clone.2 b/man2/clone.2 index 38d2b90..69e4547 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -38,7 +38,7 @@ .\" 2008-11-19, mtk, document CLONE_NEWIPC .\" 2008-11-19, Jens Axboe, mtk, document CLONE_IO .\" -.TH clone 2 2023-05-03 "Linux man-pages 6.05.01" +.TH clone 2 2024-02-18 "Linux man-pages 6.7" .SH NAME clone, __clone2, clone3 \- create a child process .SH LIBRARY @@ -47,27 +47,27 @@ Standard C library .SH SYNOPSIS .nf /* Prototype for the glibc wrapper function */ -.PP +.P .B #define _GNU_SOURCE .B #include -.PP +.P .BI "int clone(int (*" "fn" ")(void *_Nullable), void *" stack \ ", int " flags , .BI " void *_Nullable " "arg" ", ..." \ " \fR/*\fP" " pid_t *_Nullable " parent_tid , .BI " void *_Nullable " tls , .BI " pid_t *_Nullable " child_tid " \fR*/\fP );" -.PP +.P /* For the prototype of the raw clone() system call, see NOTES */ -.PP +.P .BR "#include " " /* Definition of " "struct clone_args" " */" .BR "#include " " /* Definition of " CLONE_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_clone3, struct clone_args *" cl_args ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR clone3 (), @@ -77,7 +77,7 @@ necessitating the use of These system calls create a new ("child") process, in a manner similar to .BR fork (2). -.PP +.P By contrast with .BR fork (2), these system calls provide more precise control over what pieces of execution @@ -88,7 +88,7 @@ the table of file descriptors, and the table of signal handlers. These system calls also allow the new child process to be placed in separate .BR namespaces (7). -.PP +.P Note that in this manual page, "calling process" normally corresponds to "parent process". But see the descriptions of @@ -96,7 +96,7 @@ But see the descriptions of and .B CLONE_THREAD below. -.PP +.P This page describes the following interfaces: .IP \[bu] 3 The glibc @@ -109,9 +109,9 @@ are described toward the end of this page. The newer .BR clone3 () system call. -.PP +.P In the remainder of this page, the terminology "the clone call" is used -when noting details that apply to all of these interfaces, +when noting details that apply to all of these interfaces. .\" .SS The clone() wrapper function When the child process is created with the @@ -129,7 +129,7 @@ The .I arg argument is passed as the argument of the function .IR fn . -.PP +.P When the .IR fn ( arg ) function returns, the child process terminates. @@ -139,7 +139,7 @@ is the exit status for the child process. The child process may also terminate explicitly by calling .BR exit (2) or after receiving a fatal signal. -.PP +.P The .I stack argument specifies the location of the stack used by the child process. @@ -159,7 +159,7 @@ Note that .BR clone () does not provide a means whereby the caller can inform the kernel of the size of the stack area. -.PP +.P The remaining arguments to .BR clone () are discussed below. @@ -174,20 +174,20 @@ It also provides a number of API improvements, including: space for additional flags bits; cleaner separation in the use of various arguments; and the ability to specify the size of the child's stack area. -.PP +.P As with .BR fork (2), .BR clone3 () returns in both the parent and the child. It returns 0 in the child process and returns the PID of the child in the parent. -.PP +.P The .I cl_args argument of .BR clone3 () is a structure of the following form: -.PP +.P .in +4n .EX struct clone_args { @@ -212,7 +212,7 @@ struct clone_args { }; .EE .in -.PP +.P The .I size argument that is supplied to @@ -223,7 +223,7 @@ should be initialized to the size of this structure. argument permits future extensions to the .I clone_args structure.) -.PP +.P The stack for the child process is specified via .IR cl_args.stack , which points to the lowest byte of the stack area, @@ -237,7 +237,7 @@ and specified. Otherwise, these two fields can be specified as NULL and 0, which causes the child to use the same stack area as the parent (in the child's own virtual address space). -.PP +.P The remaining fields in the .I cl_args argument are discussed below. @@ -253,7 +253,7 @@ structure shown above. This structure allows for a superset of the information passed via the .BR clone () arguments. -.PP +.P The following table shows the equivalence between the arguments of .BR clone () and the fields in the @@ -322,7 +322,7 @@ then the first element in the array has to be the desired PID and .I set_tid_size needs to be 1. -.PP +.P If the PID of the newly created process should have a certain value in multiple PID namespaces, then the .I set_tid @@ -335,7 +335,7 @@ The number of PID namespaces in which a PID should be set is defined by .I set_tid_size which cannot be larger than the number of currently nested PID namespaces. -.PP +.P To create a process with the following PIDs in a PID namespace hierarchy: .RS 4 .TS @@ -347,9 +347,9 @@ PID NS level Requested PID Notes 2 7 Innermost PID namespace .TE .RE -.PP +.P Set the array to: -.PP +.P .in +4n .EX set_tid[0] = 7; @@ -358,10 +358,10 @@ set_tid[2] = 31496; set_tid_size = 3; .EE .in -.PP +.P If only the PIDs in the two innermost PID namespaces need to be specified, set the array to: -.PP +.P .in +4n .EX set_tid[0] = 7; @@ -369,10 +369,10 @@ set_tid[1] = 42; set_tid_size = 2; .EE .in -.PP +.P The PID in the PID namespaces outside the two innermost PID namespaces is selected the same way as any other PID is selected. -.PP +.P The .I set_tid feature requires @@ -383,7 +383,7 @@ or .\" commit 1caef81da05a84a40dbf02110e967ce6d1135ff6 .B CAP_CHECKPOINT_RESTORE in all owning user namespaces of the target PID namespaces. -.PP +.P Callers may only choose a PID greater than 1 in a given PID namespace if an .B init @@ -410,7 +410,7 @@ field passed to referred to as the .I flags mask in the remainder of this page. -.PP +.P The .I flags mask is specified as a bitwise OR of zero or more of @@ -456,6 +456,8 @@ By default, signal dispositions in the child thread are the same as in the parent. If this flag is specified, then all signals that are handled in the parent +(and not set to +.BR SIG_IGN ) are reset to their default dispositions .RB ( SIG_DFL ) in the child. @@ -736,9 +738,7 @@ Only a privileged process can employ .BR CLONE_NEWPID . This flag can't be specified in conjunction with -.B CLONE_THREAD -or -.BR CLONE_PARENT . +.BR CLONE_THREAD . .TP .B CLONE_NEWUSER (This flag first became meaningful for @@ -1317,10 +1317,7 @@ were specified in the mask. .TP .B EINVAL -One (or both) of .B CLONE_NEWPID -or -.B CLONE_NEWUSER and one (or both) of .B CLONE_THREAD or @@ -1329,6 +1326,14 @@ were specified in the .I flags mask. .TP +.B EINVAL +.B CLONE_NEWUSER +and +.B CLONE_THREAD +were specified in the +.I flags +mask. +.TP .BR EINVAL " (since Linux 2.6.32)" .\" commit 123be07b0b399670a7cc3d82fef0cb4f93ef885c .B CLONE_PARENT @@ -1444,7 +1449,7 @@ or was specified in the .I flags mask, but a signal was specified in -.I exit_signal. +.IR exit_signal . .TP .BR EINVAL " (AArch64 only, Linux 4.6 and earlier)" .I stack @@ -1568,7 +1573,7 @@ So, in cases where is used to recursively create children, do not use the buffer employed for the parent's stack as the stack of the child. -.PP +.P On i386, .BR clone () should not be called through vsyscall, but directly through @@ -1587,7 +1592,7 @@ and arguments of the .BR clone () wrapper function are omitted. -.PP +.P In contrast to the glibc wrapper, the raw .BR clone () system call accepts NULL as a @@ -1609,14 +1614,14 @@ the parent's memory because of the use of the .B CLONE_VM flag, then no copy-on-write duplication occurs and chaos is likely to result.) -.PP +.P The order of the arguments also differs in the raw system call, and there are variations in the arguments across architectures, as detailed in the following paragraphs. -.PP +.P The raw system call interface on x86-64 and some other architectures (including sh, tile, and alpha) is: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1624,13 +1629,13 @@ The raw system call interface on x86-64 and some other architectures .BI " unsigned long " tls ); .EE .in -.PP +.P On x86-32, and several other common architectures (including score, ARM, ARM 64, PA-RISC, arc, Power PC, xtensa, and MIPS), .\" CONFIG_CLONE_BACKWARDS the order of the last two arguments is reversed: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1638,11 +1643,11 @@ the order of the last two arguments is reversed: .BI " int *" child_tid ); .EE .in -.PP +.P On the cris and s390 architectures, .\" CONFIG_CLONE_BACKWARDS2 the order of the first two arguments is reversed: -.PP +.P .in +4n .EX .BI "long clone(void *" stack ", unsigned long " flags , @@ -1650,11 +1655,11 @@ the order of the first two arguments is reversed: .BI " unsigned long " tls ); .EE .in -.PP +.P On the microblaze architecture, .\" CONFIG_CLONE_BACKWARDS3 an additional argument is supplied: -.PP +.P .in +4n .EX .BI "long clone(unsigned long " flags ", void *" stack , @@ -1673,7 +1678,7 @@ blackfin, m68k, and sparc are different from the descriptions above. For details, see the kernel (and glibc) source. .SS ia64 On ia64, a different interface is used: -.PP +.P .in +4n .EX .BI "int __clone2(int (*" "fn" ")(void *)," @@ -1683,13 +1688,13 @@ On ia64, a different interface is used: .BI " pid_t *" child_tid " */ );" .EE .in -.PP +.P The prototype shown above is for the glibc wrapper function; for the system call itself, the prototype can be described as follows (it is identical to the .BR clone () prototype on microblaze): -.PP +.P .in +4n .EX .BI "long clone2(unsigned long " flags ", void *" stack_base , @@ -1698,7 +1703,7 @@ prototype on microblaze): .BI " unsigned long " tls ); .EE .in -.PP +.P .BR __clone2 () operates in the same way as .BR clone (), @@ -1731,7 +1736,7 @@ However, from Linux 2.4.7 to Linux 2.4.18 the flag implied the .B CLONE_PARENT flag (as in Linux 2.6.0 and later). -.PP +.P In Linux 2.4 and earlier, .BR clone () does not take arguments @@ -1740,16 +1745,16 @@ does not take arguments and .IR child_tid . .SH NOTES -One use of these systems calls +One use of these system calls is to implement threads: multiple flows of control in a program that run concurrently in a shared address space. -.PP +.P The .BR kcmp (2) system call can be used to test whether two processes share various resources such as a file descriptor table, System V semaphore undo operations, or a virtual address space. -.PP +.P Handlers registered using .BR pthread_atfork (3) are not executed during a clone call. @@ -1784,7 +1789,7 @@ The stale-cache problem also does not occur if the argument includes .BR CLONE_VM .) To get the truth, it was sometimes necessary to use code such as the following: -.PP +.P .in +4n .EX #include @@ -1797,7 +1802,7 @@ mypid = syscall(SYS_getpid); .\" See also the following bug reports .\" https://bugzilla.redhat.com/show_bug.cgi?id=417521 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6910 -.PP +.P Because of the stale-cache problem, as well as other problems noted in .BR getpid (2), the PID caching feature was removed in glibc 2.25. @@ -1811,7 +1816,7 @@ making it possible to see that the hostname differs in the UTS namespaces of the parent and child. For an example of the use of this program, see .BR setns (2). -.PP +.P Within the sample program, we allocate the memory that is to be used for the child's stack using .BR mmap (2) diff --git a/man2/close.2 b/man2/close.2 index 239979b..c653acb 100644 --- a/man2/close.2 +++ b/man2/close.2 @@ -13,7 +13,7 @@ .\" Modified 2000-07-22 by Nicolás Lichtmaier .\" added note about close(2) not guaranteeing that data is safe on close. .\" -.TH close 2 2023-03-30 "Linux man-pages 6.05.01" +.TH close 2 2023-10-31 "Linux man-pages 6.7" .SH NAME close \- close a file descriptor .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int close(int " fd ); .fi .SH DESCRIPTION @@ -32,9 +32,15 @@ may be reused. Any record locks (see .BR fcntl (2)) held on the file it was associated with, -and owned by the process, are removed (regardless of the file -descriptor that was used to obtain the lock). -.PP +and owned by the process, +are removed regardless of the file descriptor that was used to obtain the lock. +This has some unfortunate consequences +and one should be extra careful when using advisory record locking. +See +.BR fcntl (2) +for discussion of the risks and consequences +as well as for the (probably preferred) open file description locks. +.P If .I fd is the last file descriptor referring to the underlying @@ -68,7 +74,9 @@ call was interrupted by a signal; see .B EIO An I/O error occurred. .TP -.BR ENOSPC ", " EDQUOT +.B ENOSPC +.TQ +.B EDQUOT On NFS, these errors are not normally reported against the first write which exceeds the available storage space, but instead against a subsequent @@ -76,7 +84,7 @@ subsequent .BR fsync (2), or .BR close (). -.PP +.P See NOTES for a discussion of why .BR close () should not be retried after an error. @@ -93,7 +101,7 @@ If you need to be sure that the data is physically stored on the underlying disk, use .BR fsync (2). (It will depend on the disk hardware at this point.) -.PP +.P The close-on-exec file descriptor flag can be used to ensure that a file descriptor is automatically closed upon a successful .BR execve (2); @@ -116,7 +124,7 @@ that may cause unintended side effects. .\" call has restarted after ERESTARTSYS, the original system call will .\" later restart with the reused file descriptor. This is most likely a .\" serious programming error. -.PP +.P Furthermore, consider the following scenario where two threads are performing operations on the same file descriptor: .IP (1) 5 @@ -128,11 +136,11 @@ to a pipe that is already full, or trying to from a stream socket which currently has no available data. .IP (2) Another thread closes the file descriptor. -.PP +.P The behavior in this situation varies across systems. On some systems, when the file descriptor is closed, the blocking system call returns immediately with an error. -.PP +.P On Linux (and possibly some other systems), the behavior is different: the blocking I/O system call holds a reference to the underlying open file description, and this reference keeps the description open @@ -158,13 +166,13 @@ Failing to check the return value when closing a file may lead to .I silent loss of data. This can especially be observed with NFS and with disk quota. -.PP +.P Note, however, that a failure return should be used only for diagnostic purposes (i.e., a warning to the application that there may still be I/O pending or there may have been failed I/O) or remedial purposes (e.g., writing the file once more or creating a backup). -.PP +.P Retrying the .BR close () after a failure return is the wrong thing to do, @@ -185,7 +193,7 @@ the steps that may return an error, .\" filp_close() such as flushing data to the filesystem or device, occur only later in the close operation. -.PP +.P Many other implementations similarly always close the file descriptor .\" FreeBSD documents this explicitly. From the look of the source code .\" SVR4, ancient SunOS, later Solaris, and AIX all do this. @@ -198,19 +206,19 @@ POSIX.1 is currently silent on this point, but there are plans to mandate this behavior in the next major release .\" Issue 8 of the standard. -.PP +.P A careful programmer who wants to know about I/O errors may precede .BR close () with a call to .BR fsync (2). -.PP +.P The .B EINTR error is a somewhat special case. Regarding the .B EINTR error, POSIX.1-2008 says: -.PP +.P .RS If .BR close () @@ -222,7 +230,7 @@ and the state of .I fildes is unspecified. .RE -.PP +.P This permits the behavior that occurs on Linux and many other implementations, where, as with other errors that may be reported by diff --git a/man2/close_range.2 b/man2/close_range.2 index c1aa3db..d9582b0 100644 --- a/man2/close_range.2 +++ b/man2/close_range.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH close_range 2 2023-05-03 "Linux man-pages 6.05.01" +.TH close_range 2 2024-02-25 "Linux man-pages 6.7" .SH NAME close_range \- close all file descriptors in a given range .SH LIBRARY @@ -11,10 +11,14 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.B #include -.PP -.BI "int close_range(unsigned int " first ", unsigned int " last , -.BI " unsigned int " flags ); +.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B #include +.P +.BR "#include " " /* Definition of " CLOSE_RANGE_* +.BR "" " constants */" +.P +.BI "int close_range(unsigned int " first ", unsigned int " last \ +", int " flags ); .fi .SH DESCRIPTION The @@ -24,9 +28,9 @@ system call closes all open file descriptors from to .I last (included). -.PP +.P Errors closing a given file descriptor are currently ignored. -.PP +.P .I flags is a bit mask containing 0 or more of the following: .TP @@ -53,7 +57,7 @@ is not valid, or .I first is greater than .IR last . -.PP +.P The following can occur with .B CLOSE_RANGE_UNSHARE (when constructing the new descriptor table): @@ -97,7 +101,7 @@ which provides significant performance benefits. .SS Closing file descriptors before exec .\" 60997c3d45d9a67daf01c56d805ae4fec37e0bd8 File descriptors can be closed safely using -.PP +.P .in +4n .EX /* we don't want anything past stderr here */ @@ -105,17 +109,17 @@ close_range(3, \[ti]0U, CLOSE_RANGE_UNSHARE); execve(....); .EE .in -.PP +.P .B CLOSE_RANGE_UNSHARE is conceptually equivalent to -.PP +.P .in +4n .EX unshare(CLONE_FILES); close_range(first, last, 0); .EE .in -.PP +.P but can be more efficient: if the unshared range extends past the current maximum number of file descriptors allocated @@ -168,7 +172,7 @@ uses to close all file descriptors greater than or equal to 3, and then once more displays the process's list of open files. The following example demonstrates the use of the program: -.PP +.P .in +4n .EX $ \fBtouch /tmp/a /tmp/b /tmp/c\fP @@ -190,7 +194,7 @@ $ \fB./a.out /tmp/a /tmp/b /tmp/c\fP /proc/self/fd/3 ==> /proc/9005/fd .EE .in -.PP +.P Note that the lines showing the pathname .I /proc/9005/fd result from the calls to @@ -205,7 +209,6 @@ result from the calls to #include #include #include -#include #include \& /* Show the contents of the symbolic links in /proc/self/fd */ @@ -259,7 +262,7 @@ main(int argc, char *argv[]) \& printf("========= About to call close_range() =======\en"); \& - if (syscall(SYS_close_range, 3, \[ti]0U, 0) == \-1) { + if (close_range(3, \[ti]0U, 0) == \-1) { perror("close_range"); exit(EXIT_FAILURE); } diff --git a/man2/connect.2 b/man2/connect.2 index abd9e87..ad8888a 100644 --- a/man2/connect.2 +++ b/man2/connect.2 @@ -16,7 +16,7 @@ .\" Modified 1998, 1999 by Andi Kleen .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH connect 2 2023-03-30 "Linux man-pages 6.05.01" +.TH connect 2 2023-11-01 "Linux man-pages 6.7" .SH NAME connect \- initiate a connection on a socket .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int connect(int " sockfd ", const struct sockaddr *" addr , .BI " socklen_t " addrlen ); .fi @@ -47,7 +47,7 @@ is determined by the address space of the socket see .BR socket (2) for further details. -.PP +.P If the socket .I sockfd is of type @@ -63,18 +63,18 @@ or this call attempts to make a connection to the socket that is bound to the address specified by .IR addr . -.PP +.P Some protocol sockets (e.g., UNIX domain stream sockets) may successfully .BR connect () only once. -.PP +.P Some protocol sockets (e.g., datagram sockets in the UNIX and Internet domains) may use .BR connect () multiple times to change their association. -.PP +.P Some protocol sockets (e.g., TCP sockets as well as datagram sockets in the UNIX and Internet domains) @@ -104,7 +104,9 @@ in the path prefix. (See also .BR path_resolution (7).) .TP -.BR EACCES ", " EPERM +.B EACCES +.TQ +.B EPERM The user tried to connect to a broadcast address without having the socket broadcast flag enabled or the connection request failed because of a local firewall rule. @@ -216,7 +218,7 @@ be very long when syncookies are enabled on the server. POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.4BSD, -.RB (connect () +.RB ( connect () first appeared in 4.2BSD). .\" SVr4 documents the additional .\" general error codes diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 index 8bea2e8..aee9801 100644 --- a/man2/copy_file_range.2 +++ b/man2/copy_file_range.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH copy_file_range 2 2023-07-15 "Linux man-pages 6.05.01" +.TH copy_file_range 2 2023-10-31 "Linux man-pages 6.7" .SH NAME copy_file_range \- Copy a range of data from one file to another .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .B #define _GNU_SOURCE .B #define _FILE_OFFSET_BITS 64 .B #include -.PP +.P .BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in , .BI " int " fd_out ", off_t *_Nullable " off_out , .BI " size_t " len ", unsigned int " flags ); @@ -31,7 +31,7 @@ bytes of data from the source file descriptor to the target file descriptor .IR fd_out , overwriting any data that exists within the requested range of the target file. -.PP +.P The following semantics apply for .IR off_in , and similar statements apply to @@ -57,14 +57,14 @@ The file offset of is not changed, but .I off_in is adjusted appropriately. -.PP +.P .I fd_in and .I fd_out can refer to the same file. If they refer to the same file, then the source and target ranges are not allowed to overlap. -.PP +.P The .I flags argument is provided to allow for future extensions @@ -79,7 +79,7 @@ If the file offset of is at or past the end of file, no bytes are copied, and .BR copy_file_range () returns zero. -.PP +.P On error, .BR copy_file_range () returns \-1 and @@ -189,13 +189,13 @@ or do not support cross-filesystem copy. A major rework of the kernel implementation occurred in Linux 5.3. Areas of the API that weren't clearly defined were clarified and the API bounds are much more strictly checked than on earlier kernels. -.PP +.P Since Linux 5.19, cross-filesystem copies can be achieved when both filesystems are of the same type, and that filesystem implements support for it. See BUGS for behavior prior to Linux 5.19. -.PP +.P Applications should target the behaviour and requirements of Linux 5.19, that was also backported to earlier stable kernels. .SH STANDARDS @@ -219,13 +219,13 @@ in a loop, and using the and .B SEEK_HOLE operations to find the locations of data segments. -.PP +.P .BR copy_file_range () gives filesystems an opportunity to implement "copy acceleration" techniques, such as the use of reflinks (i.e., two or more inodes that share pointers to the same copy-on-write disk blocks) or server-side-copy (in the case of NFS). -.PP +.P .B _FILE_OFFSET_BITS should be defined to be 64 in code that uses non-null .I off_in diff --git a/man2/create_module.2 b/man2/create_module.2 index d159cb1..153acc2 100644 --- a/man2/create_module.2 +++ b/man2/create_module.2 @@ -5,19 +5,19 @@ .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" -.TH create_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH create_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME create_module \- create a loadable module entry .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] caddr_t create_module(const char *" name ", size_t " size ); .fi .SH DESCRIPTION .IR Note : This system call is present only before Linux 2.6. -.PP +.P .BR create_module () attempts to create a loadable module entry and reserve the kernel memory that will be needed to hold the module. @@ -58,7 +58,7 @@ Linux. .SH HISTORY Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.PP +.P This obsolete system call is not supported by glibc. No declaration is provided in glibc headers, but, through a quirk of history, glibc versions before glibc 2.23 did export an ABI for this system call. diff --git a/man2/delete_module.2 b/man2/delete_module.2 index a909729..bbee49b 100644 --- a/man2/delete_module.2 +++ b/man2/delete_module.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH delete_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH delete_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME delete_module \- unload a kernel module .SH LIBRARY @@ -13,10 +13,10 @@ Standard C library .BR "#include " " /* Definition of " O_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_delete_module, const char *" name ", unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR delete_module (), @@ -36,7 +36,7 @@ The argument is used to modify the behavior of the system call, as described below. This system call requires privilege. -.PP +.P Module removal is attempted according to the following rules: .IP (1) 5 If there are other loaded modules that depend on @@ -88,7 +88,7 @@ until the reference count is zero, at which point the call unblocks. The module is unloaded in the usual way. .RE .RE -.PP +.P The .B O_TRUNC flag has one further effect on the rules described above. @@ -100,7 +100,7 @@ function, then an attempt to remove the module fails. However, if .B O_TRUNC was specified, this requirement is bypassed. -.PP +.P Using the .B O_TRUNC flag is dangerous! @@ -174,13 +174,13 @@ alternatively, you can invoke the system call using .BR syscall (2). .SS Linux 2.4 and earlier In Linux 2.4 and earlier, the system call took only one argument: -.PP +.P .BI " int delete_module(const char *" name ); -.PP +.P If .I name is NULL, all unused modules marked auto-clean are removed. -.PP +.P Some further details of differences in the behavior of .BR delete_module () in Linux 2.4 and earlier are diff --git a/man2/dup.2 b/man2/dup.2 index b7187ed..e03ca26 100644 --- a/man2/dup.2 +++ b/man2/dup.2 @@ -14,7 +14,7 @@ .\" details for dup2(). .\" 2008-10-09, mtk: add description of dup3() .\" -.TH dup 2 2023-05-03 "Linux man-pages 6.05.01" +.TH dup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME dup, dup2, dup3 \- duplicate a file descriptor .SH LIBRARY @@ -23,14 +23,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int dup(int " oldfd ); .BI "int dup2(int " oldfd ", int " newfd ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .BR "#include " " /* Definition of " O_* " constants */" .B #include -.PP +.P .BI "int dup3(int " oldfd ", int " newfd ", int " flags ); .fi .SH DESCRIPTION @@ -43,7 +43,7 @@ open file description as the descriptor .BR open (2).) The new file descriptor number is guaranteed to be the lowest-numbered file descriptor that was unused in the calling process. -.PP +.P After a successful return, the old and new file descriptors may be used interchangeably. Since the two file descriptors refer to the same open file description, @@ -52,7 +52,7 @@ for example, if the file offset is modified by using .BR lseek (2) on one of the file descriptors, the offset is also changed for the other file descriptor. -.PP +.P The two file descriptors do not share file descriptor flags (the close-on-exec flag). The close-on-exec flag @@ -74,14 +74,14 @@ the file descriptor .I newfd is adjusted so that it now refers to the same open file description as .IR oldfd . -.PP +.P If the file descriptor .I newfd was previously open, it is closed before being reused; the close is performed silently (i.e., any errors during the close are not reported by .BR dup2 ()). -.PP +.P The steps of closing and reusing the file descriptor .I newfd are performed @@ -97,7 +97,7 @@ might be reused between the two steps. Such reuse could happen because the main program is interrupted by a signal handler that allocates a file descriptor, or because a parallel thread allocates a file descriptor. -.PP +.P Note the following points: .IP \[bu] 3 If @@ -233,7 +233,7 @@ also sometimes returns .B EINVAL like .BR F_DUPFD . -.PP +.P If .I newfd was open, any errors that would have been reported at @@ -249,7 +249,7 @@ before calling .BR dup2 (), because of the race condition described above. Instead, code something like the following could be used: -.PP +.P .in +4n .EX /* Obtain a duplicate of \[aq]newfd\[aq] that can subsequently diff --git a/man2/epoll_create.2 b/man2/epoll_create.2 index 8d2c0be..c6369f4 100644 --- a/man2/epoll_create.2 +++ b/man2/epoll_create.2 @@ -8,7 +8,7 @@ .\" Modified 2005-04-04 by Marko Kohtala .\" 2008-10-10, mtk: add description of epoll_create1() .\" -.TH epoll_create 2 2023-07-16 "Linux man-pages 6.05.01" +.TH epoll_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll_create, epoll_create1 \- open an epoll file descriptor .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int epoll_create(int " size ); .BI "int epoll_create1(int " flags ); .fi @@ -29,7 +29,7 @@ instance. Since Linux 2.6.8, the .I size argument is ignored, but must be greater than zero; see HISTORY. -.PP +.P .BR epoll_create () returns a file descriptor referring to the new epoll instance. This file descriptor is used for all the subsequent calls to the @@ -103,7 +103,7 @@ glibc 2.3.2. .BR epoll_create1 () Linux 2.6.27, glibc 2.9. -.PP +.P In the initial .BR epoll_create () implementation, the @@ -126,7 +126,7 @@ must still be greater than zero, in order to ensure backward compatibility when new .B epoll applications are run on older kernels. -.PP +.P Prior to Linux 2.6.29, .\" commit 9df04e1f25effde823a600e755b51475d438f56b a diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 index e8ee1e6..73a0446 100644 --- a/man2/epoll_ctl.2 +++ b/man2/epoll_ctl.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH epoll_ctl 2 2023-04-03 "Linux man-pages 6.05.01" +.TH epoll_ctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll_ctl \- control interface for an epoll file descriptor .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int epoll_ctl(int " epfd ", int " op ", int " fd , .BI " struct epoll_event *_Nullable " event ); .fi @@ -28,7 +28,7 @@ It requests that the operation .I op be performed for the target file descriptor, .IR fd . -.PP +.P Valid values for the .I op argument are: @@ -58,7 +58,7 @@ from the interest list. The .I event argument is ignored and can be NULL (but see BUGS below). -.PP +.P The .I event argument describes the object linked to the file descriptor @@ -67,7 +67,7 @@ The .I struct epoll_event is described in .BR epoll_event (3type). -.PP +.P The .I data member of the @@ -75,7 +75,7 @@ member of the structure specifies data that the kernel should save and then return (via .BR epoll_wait (2)) when this file descriptor becomes ready. -.PP +.P The .I events member of the @@ -133,7 +133,7 @@ Note that when reading from a channel such as a pipe or a stream socket, this event merely indicates that the peer closed its end of the channel. Subsequent reads from the channel will return 0 (end of file) only after all outstanding data in the channel has been consumed. -.PP +.P And the available input flags are: .TP .B EPOLLET @@ -395,7 +395,7 @@ when using Applications that need to be portable to kernels before Linux 2.6.9 should specify a non-null pointer in .IR event . -.PP +.P If .B EPOLLWAKEUP is specified in diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2 index 5efaada..72d6fab 100644 --- a/man2/epoll_wait.2 +++ b/man2/epoll_wait.2 @@ -6,7 +6,7 @@ .\" .\" 2007-04-30: mtk, Added description of epoll_pwait() .\" -.TH epoll_wait 2 2023-05-03 "Linux man-pages 6.05.01" +.TH epoll_wait 2 2024-03-03 "Linux man-pages 6.7" .SH NAME epoll_wait, epoll_pwait, epoll_pwait2 \- wait for an I/O event on an epoll file descriptor @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int epoll_wait(int " epfd ", struct epoll_event *" events , .BI " int " maxevents ", int " timeout ); .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events , @@ -46,7 +46,7 @@ are returned by The .I maxevents argument must be greater than zero. -.PP +.P The .I timeout argument specifies the number of milliseconds that @@ -55,7 +55,7 @@ will block. Time is measured against the .B CLOCK_MONOTONIC clock. -.PP +.P A call to .BR epoll_wait () will block until either: @@ -65,7 +65,7 @@ a file descriptor delivers an event; the call is interrupted by a signal handler; or .IP \[bu] the timeout expires. -.PP +.P Note that the .I timeout interval will be rounded up to the system clock granularity, @@ -77,15 +77,15 @@ of \-1 causes .BR epoll_wait () to block indefinitely, while specifying a .I timeout -equal to zero cause +equal to zero causes .BR epoll_wait () to return immediately, even if no events are available. -.PP +.P The .I struct epoll_event is described in .BR epoll_event (3type). -.PP +.P The .I data field of each returned @@ -95,7 +95,7 @@ in the most recent call to .BR epoll_ctl (2) .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD ) for the corresponding open file descriptor. -.PP +.P The .I events field is a bit mask that indicates the events that have occurred for the @@ -118,21 +118,21 @@ like .BR epoll_pwait () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P The following .BR epoll_pwait () call: -.PP +.P .in +4n .EX ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); .EE .in -.PP +.P is equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -142,7 +142,7 @@ ready = epoll_wait(epfd, &events, maxevents, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The .I sigmask argument may be specified as NULL, in which case @@ -173,8 +173,8 @@ can block indefinitely. .SH RETURN VALUE On success, .BR epoll_wait () -returns the number of file descriptors ready for the requested I/O, or zero -if no file descriptor became ready during the requested +returns the number of file descriptors ready for the requested I/O operation, +or zero if no file descriptor became ready during the requested .I timeout milliseconds. On failure, @@ -233,7 +233,7 @@ If the new file descriptor becomes ready, it will cause the .BR epoll_wait () call to unblock. -.PP +.P If more than .I maxevents file descriptors are ready when @@ -245,7 +245,7 @@ This behavior helps avoid starvation scenarios, where a process fails to notice that additional file descriptors are ready because it focuses on a set of file descriptors that are already known to be ready. -.PP +.P Note that it is possible to call .BR epoll_wait () on an diff --git a/man2/eventfd.2 b/man2/eventfd.2 index 7be6a3a..2de063e 100644 --- a/man2/eventfd.2 +++ b/man2/eventfd.2 @@ -6,7 +6,7 @@ .\" .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC .\" -.TH eventfd 2 2023-07-20 "Linux man-pages 6.05.01" +.TH eventfd 2 2023-10-31 "Linux man-pages 6.7" .SH NAME eventfd \- create a file descriptor for event notification .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int eventfd(unsigned int " initval ", int " flags ); .fi .SH DESCRIPTION @@ -28,12 +28,12 @@ The object contains an unsigned 64-bit integer counter that is maintained by the kernel. This counter is initialized with the value specified in the argument .IR initval . -.PP +.P As its return value, .BR eventfd () returns a new file descriptor that can be used to refer to the eventfd object. -.PP +.P The following values may be bitwise ORed in .I flags to change the behavior of @@ -62,11 +62,11 @@ to achieve the same result. .BR EFD_SEMAPHORE " (since Linux 2.6.30)" Provide semaphore-like semantics for reads from the new file descriptor. See below. -.PP +.P Up to Linux 2.6.26, the .I flags argument is unused, and must be specified as zero. -.PP +.P The following operations can be performed on the file descriptor returned by .BR eventfd (): .TP @@ -142,7 +142,11 @@ fails with the error if the size of the supplied buffer is less than 8 bytes, or if an attempt is made to write the value 0xffffffffffffffff. .TP -.BR poll "(2), " select "(2) (and similar)" +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) The returned file descriptor supports .BR poll (2) (and analogously @@ -203,7 +207,7 @@ and When the file descriptor is no longer required it should be closed. When all file descriptors associated with the same eventfd object have been closed, the resources for object are freed by the kernel. -.PP +.P A copy of the file descriptor created by .BR eventfd () is inherited by the child produced by @@ -260,7 +264,6 @@ T{ .BR eventfd () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel differences There are two underlying Linux system calls: @@ -280,7 +283,7 @@ where it is available. The GNU C library defines an additional type, and two functions that attempt to abstract some of the details of reading and writing on an eventfd file descriptor: -.PP +.P .in +4n .EX typedef uint64_t eventfd_t; @@ -289,7 +292,7 @@ int eventfd_read(int fd, eventfd_t *value); int eventfd_write(int fd, eventfd_t value); .EE .in -.PP +.P The functions perform the read and write operations on an eventfd file descriptor, returning 0 if the correct number of bytes was transferred, @@ -318,13 +321,13 @@ The kernel overhead of an eventfd file descriptor is much lower than that of a pipe, and only one file descriptor is required (versus the two required for a pipe). -.PP +.P When used in the kernel, an eventfd file descriptor can provide a bridge from kernel to user space, allowing, for example, functionalities like KAIO (kernel AIO) .\" or eventually syslets/threadlets to signal to a file descriptor that some operation is complete. -.PP +.P A key point about an eventfd file descriptor is that it can be monitored just like any other file descriptor using .BR select (2), @@ -341,7 +344,7 @@ interface, these mechanisms could not be multiplexed via .BR poll (2), or .BR epoll (7).) -.PP +.P The current value of an eventfd counter can be viewed via the entry for the corresponding file descriptor in the process's .IR /proc/ pid /fdinfo @@ -357,9 +360,9 @@ the child writes each of the integers supplied in the program's command-line arguments to the eventfd file descriptor. When the parent has finished sleeping, it reads from the eventfd file descriptor. -.PP +.P The following shell session shows a sample run of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out 1 2 4 7 14" diff --git a/man2/execve.2 b/man2/execve.2 index ae1863c..23404b5 100644 --- a/man2/execve.2 +++ b/man2/execve.2 @@ -14,7 +14,7 @@ .\" 2007-09-14 Ollie Wild , mtk .\" Add text describing limits on command-line arguments + environment .\" -.TH execve 2 2023-05-03 "Linux man-pages 6.05.01" +.TH execve 2 2023-11-01 "Linux man-pages 6.7" .SH NAME execve \- execute program .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int execve(const char *" pathname ", char *const _Nullable " argv [], .BI " char *const _Nullable " envp []); .fi @@ -33,18 +33,18 @@ executes the program referred to by \fIpathname\fP. This causes the program that is currently being run by the calling process to be replaced with a new program, with newly initialized stack, heap, and (initialized and uninitialized) data segments. -.PP +.P \fIpathname\fP must be either a binary executable, or a script starting with a line of the form: -.PP +.P .in +4n .EX \fB#!\fP\fIinterpreter \fP[optional-arg] .EE .in -.PP +.P For details of the latter case, see "Interpreter scripts" below. -.PP +.P .I argv is an array of pointers to strings passed to the new program as its command-line arguments. @@ -53,19 +53,19 @@ By convention, the first of these strings (i.e., should contain the filename associated with the file being executed. The .I argv -array must be terminated by a NULL pointer. +array must be terminated by a null pointer. (Thus, in the new program, .I argv[argc] -will be NULL.) -.PP +will be a null pointer.) +.P .I envp is an array of pointers to strings, conventionally of the form .BR key=value , which are passed as the environment of the new program. The .I envp -array must be terminated by a NULL pointer. -.PP +array must be terminated by a null pointer. +.P This manual page describes the Linux system call in detail; for an overview of the nomenclature and the many, often preferable, standardised variants of this function provided by libc, @@ -73,31 +73,31 @@ including ones that search the .B PATH environment variable, see .BR exec (3). -.PP +.P The argument vector and environment can be accessed by the new program's main function, when it is defined as: -.PP +.P .in +4n .EX int main(int argc, char *argv[], char *envp[]) .EE .in -.PP +.P Note, however, that the use of a third argument to the main function is not specified in POSIX.1; according to POSIX.1, the environment should be accessed via the external variable .BR environ (7). -.PP +.P .BR execve () does not return on success, and the text, initialized data, uninitialized data (bss), and stack of the calling process are overwritten according to the contents of the newly loaded program. -.PP +.P If the current program is being ptraced, a \fBSIGTRAP\fP signal is sent to it after a successful .BR execve (). -.PP +.P If the set-user-ID bit is set on the program file referred to by \fIpathname\fP, then the effective user ID of the calling process is changed @@ -105,7 +105,7 @@ to that of the owner of the program file. Similarly, if the set-group-ID bit is set on the program file, then the effective group ID of the calling process is set to the group of the program file. -.PP +.P The aforementioned transformations of the effective IDs are .I not performed (i.e., the set-user-ID and set-group-ID bits are ignored) @@ -125,20 +125,20 @@ flag for or .IP \[bu] the calling process is being ptraced. -.PP +.P The capabilities of the program file (see .BR capabilities (7)) are also ignored if any of the above are true. -.PP +.P The effective user ID of the process is copied to the saved set-user-ID; similarly, the effective group ID is copied to the saved set-group-ID. This copying takes place after any effective ID changes that occur because of the set-user-ID and set-group-ID mode bits. -.PP +.P The process's real UID and real GID, as well as its supplementary group IDs, are unchanged by a call to .BR execve (). -.PP +.P If the executable is an a.out dynamically linked binary executable containing shared-library stubs, the Linux dynamic linker @@ -146,7 +146,7 @@ shared-library stubs, the Linux dynamic linker is called at the start of execution to bring needed shared objects into memory and link the executable with them. -.PP +.P If the executable is a dynamically linked ELF executable, the interpreter named in the PT_INTERP segment is used to load the needed shared objects. @@ -198,7 +198,7 @@ Exit handlers are not preserved .IP \[bu] The floating-point environment is reset to the default (see .BR fenv (3)). -.PP +.P The process attributes in the preceding list are all specified in POSIX.1. The following Linux-specific process attributes are also @@ -257,7 +257,7 @@ The file descriptor table is unshared, undoing the effect of the .B CLONE_FILES flag of .BR clone (2). -.PP +.P Note the following further points: .IP \[bu] 3 All threads other than the calling thread are destroyed during an @@ -313,17 +313,17 @@ closed across an .SS Interpreter scripts An interpreter script is a text file that has execute permission enabled and whose first line is of the form: -.PP +.P .in +4n .EX \fB#!\fP\fIinterpreter \fP[optional-arg] .EE .in -.PP +.P The .I interpreter must be a valid pathname for an executable file. -.PP +.P If the .I pathname argument of @@ -331,13 +331,13 @@ argument of specifies an interpreter script, then .I interpreter will be invoked with the following arguments: -.PP +.P .in +4n .EX \fIinterpreter\fP [optional-arg] \fIpathname\fP arg... .EE .in -.PP +.P where .I pathname is the pathname of the file specified as the first argument of @@ -358,12 +358,12 @@ call. .\" See the P - preserve-argv[0] option. .\" Documentation/admin-guide/binfmt-misc.rst .\" https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html -.PP +.P For portable use, .I optional-arg should either be absent, or be specified as a single word (i.e., it should not contain white space); see NOTES below. -.PP +.P Since Linux 2.6.28, .\" commit bf2a9a39639b8b51377905397a5005f444e9a892 the kernel permits the interpreter of a script to itself be a script. @@ -383,14 +383,14 @@ constant (either defined in .I or available at run time using the call .IR "sysconf(_SC_ARG_MAX)" ). -.PP +.P Before Linux 2.6.23, the memory used to store the environment and argument strings was limited to 32 pages (defined by the kernel constant .BR MAX_ARG_PAGES ). On architectures with a 4-kB page size, this yields a maximum size of 128\ kB. -.PP +.P On Linux 2.6.23 and later, most architectures support a size limit derived from the soft .B RLIMIT_STACK @@ -443,7 +443,12 @@ The total number of bytes in the environment .RI ( envp ) and argument list .RI ( argv ) -is too large. +is too large, +an argument or environment string is too long, +or the full +.I pathname +of the executable is too long. +The terminating null byte is counted as part of the string length. .TP .B EACCES Search permission is denied on a component of the path prefix of @@ -555,7 +560,7 @@ The specified executable was open for writing by one or more processes. .SH VERSIONS POSIX does not document the #! behavior, but it exists (with some variations) on other UNIX systems. -.PP +.P On Linux, .I argv and @@ -577,7 +582,7 @@ case the same as Linux. .\" Bug filed 30 Apr 2007: http://bugzilla.kernel.org/show_bug.cgi?id=8408 .\" Bug rejected (because fix would constitute an ABI change). .\" -.PP +.P POSIX.1 says that values returned by .BR sysconf (3) should be invariant over the lifetime of a process. @@ -597,7 +602,7 @@ Before Linux 5.1, the limit is 127 characters. Since Linux 5.1, .\" commit 6eb3c3d0a52dca337e327ae8868ca1f44a712e02 the limit is 255 characters. -.PP +.P The semantics of the .I optional-arg argument of an interpreter script vary across implementations. @@ -616,7 +621,7 @@ an interpreter script can have multiple arguments, and white spaces in .I optional-arg are used to delimit the arguments. -.PP +.P Linux (like most other modern UNIX systems) ignores the set-user-ID and set-group-ID bits on scripts. .SH STANDARDS @@ -627,7 +632,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .\" conditions EAGAIN, EINTR, ELIBACC, ENOLINK, EMULTIHOP; POSIX does not .\" document ETXTBSY, EPERM, EFAULT, ELOOP, EIO, ENFILE, EMFILE, EINVAL, .\" EISDIR or ELIBBAD error conditions. -.PP +.P With UNIX\ V6, the argument list of an .BR exec () call was ended by 0, @@ -654,10 +659,10 @@ All that .BR execve () does is arrange for an existing process (the calling process) to execute a new program. -.PP +.P Set-user-ID and set-group-ID processes can not be .BR ptrace (2)d. -.PP +.P The result of mounting a filesystem .I nosuid varies across Linux kernel versions: @@ -668,7 +673,7 @@ give the user powers they did not have already (and return some will just ignore the set-user-ID and set-group-ID bits and .BR exec () successfully. -.PP +.P In most cases where .BR execve () fails, control returns to the original executable image, @@ -691,7 +696,7 @@ A more detailed explanation of the error that can occur (since Linux 3.1) when calling .BR execve () is as follows. -.PP +.P The .B EAGAIN error can occur when a @@ -713,7 +718,7 @@ call to fail. .\" commit 909cc4ae86f3380152a18e2a3c44523893ee11c4 the resource limit was not imposed on processes that changed their user IDs.) -.PP +.P Since Linux 3.1, the scenario just described no longer causes the .BR set*uid () call to fail, @@ -744,7 +749,7 @@ common privileged daemon workflow\[em]namely, .BR set*uid () + .BR execve (). -.PP +.P If the resource limit was not still exceeded at the time of the .BR execve () call @@ -772,7 +777,7 @@ by this process succeeds. .SH EXAMPLES The following program is designed to be execed by the second program below. It just echoes its command-line arguments, one per line. -.PP +.P .in +4n .\" SRC BEGIN (myecho.c) .EX @@ -792,10 +797,10 @@ main(int argc, char *argv[]) .EE .\" SRC END .in -.PP +.P This program can be used to exec the program named in its command-line argument: -.PP +.P .in +4n .\" SRC BEGIN (execve.c) .EX @@ -825,9 +830,9 @@ main(int argc, char *argv[]) .EE .\" SRC END .in -.PP +.P We can use the second program to exec the first as follows: -.PP +.P .in +4n .EX .RB "$" " cc myecho.c \-o myecho" @@ -838,13 +843,13 @@ argv[1]: hello argv[2]: world .EE .in -.PP +.P We can also use these programs to demonstrate the use of a script interpreter. To do this we create a script whose "interpreter" is our .I myecho program: -.PP +.P .in +4n .EX .RB "$" " cat > script" @@ -853,9 +858,9 @@ program: .RB "$" " chmod +x script" .EE .in -.PP +.P We can then use our program to exec the script: -.PP +.P .in +4n .EX .RB "$" " ./execve ./script" diff --git a/man2/execveat.2 b/man2/execveat.2 index 22c468a..3a612ae 100644 --- a/man2/execveat.2 +++ b/man2/execveat.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH execveat 2 2023-03-30 "Linux man-pages 6.05.01" +.TH execveat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME execveat \- execute program relative to a directory file descriptor .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#include " " /* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int execveat(int " dirfd ", const char *" pathname , .BI " char *const _Nullable " argv [], .BI " char *const _Nullable " envp [], @@ -30,7 +30,7 @@ and It operates in exactly the same way as .BR execve (2), except for the differences described in this manual page. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -40,7 +40,7 @@ referred to by the file descriptor the calling process, as is done by .BR execve (2) for a relative pathname). -.PP +.P If .I pathname is relative and @@ -52,13 +52,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR execve (2)). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P If .I pathname is an empty string and the @@ -68,7 +68,7 @@ flag is specified, then the file descriptor specifies the file to be executed (i.e., .I dirfd refers to an executable file, rather than a directory). -.PP +.P The .I flags argument is a bit mask that can include zero or more of the following flags: @@ -160,7 +160,7 @@ system call is also needed to allow to be implemented on systems that do not have the .I /proc filesystem mounted. -.PP +.P When asked to execute a script file, the .I argv[0] that is passed to the script interpreter is a string of the form @@ -183,7 +183,7 @@ in this case, .I P is the value given in .IR pathname . -.PP +.P For the same reasons described in .BR fexecve (3), the natural idiom when using @@ -196,13 +196,13 @@ The .B ENOENT error described above means that it is not possible to set the close-on-exec flag on the file descriptor given to a call of the form: -.PP +.P .in +4n .EX execveat(fd, "", argv, envp, AT_EMPTY_PATH); .EE .in -.PP +.P However, the inability to set the close-on-exec flag means that a file descriptor referring to the script leaks through to the script itself. As well as wasting a file descriptor, diff --git a/man2/exit_group.2 b/man2/exit_group.2 index 3515406..af66e6a 100644 --- a/man2/exit_group.2 +++ b/man2/exit_group.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH exit_group 2 2023-03-30 "Linux man-pages 6.05.01" +.TH exit_group 2 2023-10-31 "Linux man-pages 6.7" .SH NAME exit_group \- exit all threads in a process .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "[[noreturn]] void syscall(SYS_exit_group, int " status ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR exit_group (), diff --git a/man2/fallocate.2 b/man2/fallocate.2 index e462658..bedc533 100644 --- a/man2/fallocate.2 +++ b/man2/fallocate.2 @@ -6,7 +6,7 @@ .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE .\" 2011-09-19: Substantial restructuring of the page .\" -.TH fallocate 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fallocate 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fallocate \- manipulate file space .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int fallocate(int " fd ", int " mode ", off_t " offset \ ", off_t " len ");" .fi @@ -25,7 +25,7 @@ This is a nonportable, Linux-specific system call. For the portable, POSIX.1-specified method of ensuring that space is allocated for a file, see .BR posix_fallocate (3). -.PP +.P .BR fallocate () allows the caller to directly manipulate the allocated disk space for the file referred to by @@ -35,7 +35,7 @@ for the byte range starting at and continuing for .I len bytes. -.PP +.P The .I mode argument determines the operation to be performed on the given range. @@ -63,13 +63,13 @@ This default behavior closely resembles the behavior of the .BR posix_fallocate (3) library function, and is intended as a method of optimally implementing that function. -.PP +.P After a successful call, subsequent writes into the range specified by .I offset and .I len are guaranteed not to fail because of lack of disk space. -.PP +.P If the .B FALLOC_FL_KEEP_SIZE flag is specified in @@ -80,7 +80,7 @@ but the file size will not be changed even if is greater than the file size. Preallocating zeroed blocks beyond the end of the file in this manner is useful for optimizing append workloads. -.PP +.P If the .B FALLOC_FL_UNSHARE_RANGE flag is specified in @@ -90,7 +90,7 @@ that a subsequent write will not fail due to lack of space. Typically, this will be done by performing a copy-on-write operation on all shared data in the file. This flag may not be supported by all filesystems. -.PP +.P Because allocation is done in block size chunks, .BR fallocate () may allocate a larger range of disk space than was specified. @@ -109,7 +109,7 @@ Within the specified range, partial filesystem blocks are zeroed, and whole filesystem blocks are removed from the file. After a successful call, subsequent reads from this range will return zeros. -.PP +.P The .B FALLOC_FL_PUNCH_HOLE flag must be ORed with @@ -120,7 +120,7 @@ in other words, even when punching off the end of the file, the file size (as reported by .BR stat (2)) does not change. -.PP +.P Not all filesystems support .BR FALLOC_FL_PUNCH_HOLE ; if a filesystem doesn't support the operation, an error is returned. @@ -160,7 +160,7 @@ will be appended at the location and the file will be .I len bytes smaller. -.PP +.P A filesystem may place limitations on the granularity of the operation, in order to ensure efficient implementation. Typically, @@ -174,7 +174,7 @@ If a filesystem has such a requirement, fails with the error .B EINVAL if this requirement is violated. -.PP +.P If the region specified by .I offset plus @@ -183,12 +183,12 @@ reaches or passes the end of file, an error is returned; instead, use .BR ftruncate (2) to truncate a file. -.PP +.P No other flags may be specified in .I mode in conjunction with .BR FALLOC_FL_COLLAPSE_RANGE . -.PP +.P As at Linux 3.15, .B FALLOC_FL_COLLAPSE_RANGE is supported by @@ -212,13 +212,13 @@ Within the specified range, blocks are preallocated for the regions that span the holes in the file. After a successful call, subsequent reads from this range will return zeros. -.PP +.P Zeroing is done within the filesystem preferably by converting the range into unwritten extents. This approach means that the specified range will not be physically zeroed out on the device (except for partial blocks at the either end of the range), and I/O is (otherwise) required only to update metadata. -.PP +.P If the .B FALLOC_FL_KEEP_SIZE flag is additionally specified in @@ -230,7 +230,7 @@ is greater than the file size. This behavior is the same as when preallocating space with .B FALLOC_FL_KEEP_SIZE specified. -.PP +.P Not all filesystems support .BR FALLOC_FL_ZERO_RANGE ; if a filesystem doesn't support the operation, an error is returned. @@ -270,7 +270,7 @@ bytes. Inserting a hole inside a file increases the file size by .I len bytes. -.PP +.P This mode has the same limitations as .B FALLOC_FL_COLLAPSE_RANGE regarding the granularity of the operation. @@ -284,12 +284,12 @@ is equal to or greater than the end of file, an error is returned. For such operations (i.e., inserting a hole at the end of file), .BR ftruncate (2) should be used. -.PP +.P No other flags may be specified in .I mode in conjunction with .BR FALLOC_FL_INSERT_RANGE . -.PP +.P .B FALLOC_FL_INSERT_RANGE requires filesystem support. Filesystems that support this operation include diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index f48e43a..8a9667b 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2013, Heinrich Schuchardt .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify_init 2 2023-07-08 "Linux man-pages 6.05.01" +.TH fanotify_init 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fanotify_init \- create and initialize fanotify group .SH LIBRARY @@ -11,17 +11,17 @@ Standard C library .nf .BR "#include " " /* Definition of " O_* " constants */" .B #include -.PP +.P .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); .fi .SH DESCRIPTION For an overview of the fanotify API, see .BR fanotify (7). -.PP +.P .BR fanotify_init () initializes a new fanotify group and returns a file descriptor for the event queue associated with the group. -.PP +.P The file descriptor is used in calls to .BR fanotify_mark (2) to specify the files, directories, mounts, or filesystems for which fanotify @@ -32,25 +32,25 @@ Other events can be used to determine whether another application is permitted to access a file or directory. Permission to access filesystem objects is granted by writing to the file descriptor. -.PP +.P Multiple programs may be using the fanotify interface at the same time to monitor the same files. -.PP +.P The number of fanotify groups per user is limited. See .BR fanotify (7) for details about this limit. -.PP +.P The .I flags argument contains a multi-bit field defining the notification class of the listening application and further single bit fields specifying the behavior of the file descriptor. -.PP +.P If multiple listeners for permission events exist, the notification class is used to establish the sequence in which the listeners receive the events. -.PP +.P Only one of the following notification classes may be specified in .IR flags : .TP @@ -82,7 +82,7 @@ It does not need to be specified. This value only allows the receipt of events notifying that a file has been accessed. Permission decisions before the file is accessed are not possible. -.PP +.P Listeners with different notification classes will receive events in the order .BR FAN_CLASS_PRE_CONTENT , @@ -90,7 +90,7 @@ order .BR FAN_CLASS_NOTIF . The order of notification for listeners in the same notification class is undefined. -.PP +.P The following bits can additionally be set in .IR flags : .TP @@ -364,7 +364,7 @@ so this restriction may eventually be lifted. For more details on information records, see .BR fanotify (7). -.PP +.P The .I event_f_flags argument @@ -386,7 +386,7 @@ This value allows only write access. .TP .B O_RDWR This value allows read and write access. -.PP +.P Additional bits can be set in .IR event_f_flags . The most useful values are: @@ -406,7 +406,7 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P The following are also allowable: .BR O_APPEND , .BR O_DSYNC , @@ -525,7 +525,7 @@ The .B O_CLOEXEC is ignored when passed in .IR event_f_flags . -.PP +.P The following bug was present before Linux 3.14: .IP \[bu] 3 .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index d1f7eec..c942b0b 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2013, Heinrich Schuchardt .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify_mark 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fanotify_mark 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem object @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , .BI " uint64_t " mask ", int " dirfd , .BI " const char *_Nullable " pathname ); @@ -19,17 +19,17 @@ Standard C library .SH DESCRIPTION For an overview of the fanotify API, see .BR fanotify (7). -.PP +.P .BR fanotify_mark () adds, removes, or modifies an fanotify mark on a filesystem object. The caller must have read permission on the filesystem object that is to be marked. -.PP +.P The .I fanotify_fd argument is a file descriptor returned by .BR fanotify_init (2). -.PP +.P .I flags is a bit mask describing the modification to perform. It must include exactly one of the following values: @@ -74,11 +74,11 @@ can be used in conjunction with .BR FAN_MARK_FLUSH . .I mask is ignored. -.PP +.P If none of the values above is specified, or more than one is specified, the call fails with the error .BR EINVAL . -.PP +.P In addition, zero or more of the following values may be ORed into .IR flags : @@ -311,7 +311,7 @@ and if it is not, the listener sets a mark with an ignore mask on the directory. Evictable inode marks allow using this method for a large number of directories without the concern of pinning all inodes and exhausting the system's memory. -.PP +.P .I mask defines which events shall be listened for (or which shall be ignored). It is a bit mask composed of the following values: @@ -486,7 +486,7 @@ and are not generated for children of marked directories. To monitor complete directory trees it is necessary to mark the relevant mount or filesystem. -.PP +.P The following composed values are defined: .TP .B FAN_CLOSE @@ -496,7 +496,7 @@ A file is closed .B FAN_MOVE A file or directory has been moved .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ). -.PP +.P The filesystem object to be marked is determined by the file descriptor .I dirfd and the pathname specified in @@ -743,10 +743,17 @@ do not specify a directory. .B EOPNOTSUPP The object indicated by .I pathname -is associated with a filesystem that does not support the encoding of file -handles. +is associated with a filesystem +that does not support the encoding of file handles. This error can be returned only with an fanotify group that identifies filesystem objects by file handles. +Calling +.BR name_to_handle_at (2) +with the flag +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +can be used as a test +to check if a filesystem supports reporting events with file handles. .TP .B EPERM The operation is not permitted because the caller lacks a required capability. @@ -784,28 +791,28 @@ or .BR uselib (2). Events of these types will not be raised in the situation where an interpreter is passed (or reads) a file for interpretation. -.PP +.P Additionally, if a mark has also been placed on the Linux dynamic linker, a user should also expect to receive an event for it when an ELF object has been successfully opened using .BR execve (2) or .BR execveat (2). -.PP +.P For example, if the following ELF binary were to be invoked and a .B FAN_OPEN_EXEC mark has been placed on /: -.PP +.P .in +4n .EX $ /bin/echo foo .EE .in -.PP +.P The listening application in this case would receive .B FAN_OPEN_EXEC events for both the ELF binary and interpreter, respectively: -.PP +.P .in +4n .EX /bin/echo diff --git a/man2/fcntl.2 b/man2/fcntl.2 index 9362044..01d18aa 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -44,7 +44,7 @@ .\" 2017-06-26, Jens Axboe .\" Document F_{GET,SET}_RW_HINT and F_{GET,SET}_FILE_RW_HINT .\" -.TH fcntl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fcntl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME fcntl \- manipulate file descriptor .SH LIBRARY @@ -53,22 +53,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int fcntl(int " fd ", int " cmd ", ... /* " arg " */ );" +.P +.BI "int fcntl(int " fd ", int " op ", ... /* " arg " */ );" .fi .SH DESCRIPTION .BR fcntl () performs one of the operations described below on the open file descriptor .IR fd . The operation is determined by -.IR cmd . -.PP +.IR op . +.P .BR fcntl () can take an optional third argument. Whether or not this argument is required is determined by -.IR cmd . +.IR op . The required argument type is indicated in parentheses after each -.I cmd +.I op name (in most cases, the required type is .IR int , and we identify the argument using the name @@ -76,14 +76,14 @@ and we identify the argument using the name or .I void is specified if the argument is not required. -.PP +.P Certain of the operations below are supported only since a particular Linux kernel version. The preferred method of checking whether the host kernel supports a particular operation is to invoke .BR fcntl () with the desired -.I cmd +.I op value and then test whether the call failed with .BR EINVAL , indicating that the kernel does not recognize this value. @@ -121,7 +121,7 @@ see the description of in .BR open (2). .SS File descriptor flags -The following commands manipulate the flags associated with +The following operations manipulate the flags associated with a file descriptor. Currently, only one such flag is defined: .BR FD_CLOEXEC , @@ -147,7 +147,7 @@ is ignored. .BR F_SETFD " (\fIint\fP)" Set the file descriptor flags to the value specified by .IR arg . -.PP +.P In multithreaded programs, using .BR fcntl () .B F_SETFD @@ -177,7 +177,7 @@ Duplicated file descriptors .BR fork (2), etc.) refer to the same open file description, and thus share the same file status flags. -.PP +.P The file status flags and their semantics are described in .BR open (2). .TP @@ -198,7 +198,7 @@ and file creation flags in .I arg are ignored. -On Linux, this command can change only the +On Linux, this operation can change only the .BR O_APPEND , .BR O_ASYNC , .BR O_DIRECT , @@ -216,7 +216,7 @@ Linux implements traditional ("process-associated") UNIX record locks, as standardized by POSIX. For a Linux-specific alternative with better semantics, see the discussion of open file description locks below. -.PP +.P .BR F_SETLK , .BR F_SETLKW , and @@ -227,7 +227,7 @@ The third argument, .IR lock , is a pointer to a structure that has at least the following fields (in unspecified order). -.PP +.P .in +4n .EX struct flock { @@ -244,13 +244,13 @@ struct flock { }; .EE .in -.PP +.P The .IR l_whence ", " l_start ", and " l_len fields of this structure specify the range of bytes we wish to lock. Bytes past the end of the file may be locked, but not bytes before the start of the file. -.PP +.P .I l_start is the starting offset for the lock, and is interpreted relative to either: @@ -270,7 +270,7 @@ In the final two cases, .I l_start can be a negative number provided the offset does not lie before the start of the file. -.PP +.P .I l_len specifies the number of bytes to be locked. If @@ -285,7 +285,7 @@ has the special meaning: lock all bytes starting at the location specified by .IR l_whence " and " l_start through to the end of file, no matter how large the file grows. -.PP +.P POSIX.1-2001 allows (but does not require) an implementation to support a negative .I l_len @@ -298,7 +298,7 @@ covers bytes up to and including .IR l_start \-1. This is supported since Linux 2.4.21 and Linux 2.5.49. -.PP +.P The .I l_type field can be used to place a read @@ -387,7 +387,7 @@ If the conflicting lock is an open file description lock, then is set to \-1. Note that the returned information may already be out of date by the time the caller inspects it. -.PP +.P In order to place a read lock, .I fd must be open for reading. @@ -395,7 +395,7 @@ In order to place a write lock, .I fd must be open for writing. To place both types of lock, open a file read-write. -.PP +.P When placing locks with .BR F_SETLKW , the kernel detects @@ -418,16 +418,16 @@ attempting regain the locks that it requires. Circular deadlocks involving more than two processes are also detected. Note, however, that there are limitations to the kernel's deadlock-detection algorithm; see BUGS. -.PP +.P As well as being removed by an explicit .BR F_UNLCK , record locks are automatically released when the process terminates. -.PP +.P Record locks are not inherited by a child created via .BR fork (2), but are preserved across an .BR execve (2). -.PP +.P Because of the buffering performed by the .BR stdio (3) library, the use of record locking with routines in that package @@ -436,7 +436,7 @@ should be avoided; use and .BR write (2) instead. -.PP +.P The record locks described above are associated with the process (unlike the open file description locks described below). This has some unfortunate consequences: @@ -461,7 +461,7 @@ The threads in a process share locks. In other words, a multithreaded program can't use record locking to ensure that threads don't simultaneously access the same region of a file. -.PP +.P Open file description locks solve both of these problems. .SS Open file description locks (non-POSIX) Open file description locks are advisory byte-range locks whose operation is @@ -474,7 +474,7 @@ and available since Linux 3.15. to include this lock type in the next revision of POSIX.1.) For an explanation of open file descriptions, see .BR open (2). -.PP +.P The principal difference between the two lock types is that whereas traditional record locks are associated with a process, @@ -492,13 +492,13 @@ with and are only automatically released on the last close of the open file description, instead of being released on any close of the file. -.PP +.P Conflicting lock combinations (i.e., a read lock and a write lock or two write locks) where one lock is an open file description lock and the other is a traditional record lock conflict even when they are acquired by the same process on the same file descriptor. -.PP +.P Open file description locks placed via the same open file description (i.e., via the same file descriptor, or via a duplicate of the file descriptor created by @@ -511,7 +511,7 @@ if a new lock is placed on an already locked region, then the existing lock is converted to the new lock type. (Such conversions may result in splitting, shrinking, or coalescing with an existing lock as discussed above.) -.PP +.P On the other hand, open file description locks may conflict with each other when they are acquired via different open file descriptions. Thus, the threads in a multithreaded program can use @@ -519,7 +519,7 @@ open file description locks to synchronize access to a file region by having each thread perform its own .BR open (2) on the file and applying locks via the resulting file descriptor. -.PP +.P As with traditional advisory locks, the third argument to .BR fcntl (), .IR lock , @@ -529,9 +529,9 @@ structure. By contrast with traditional record locks, the .I l_pid field of that structure must be set to zero -when using the commands described below. -.PP -The commands for working with open file description locks are analogous +when using the operations described below. +.P +The operations for working with open file description locks are analogous to those used with traditional locks: .TP .BR F_OFD_SETLK " (\fIstruct flock *\fP)" @@ -587,7 +587,7 @@ then details about one of these locks are returned via .IR lock , as described above for .BR F_GETLK . -.PP +.P In the current implementation, .\" commit 57b65325fe34ec4c917bc4e555144b4a94d9e1f7 no deadlock detection is performed for open file description locks. @@ -604,12 +604,12 @@ since Linux 4.5, mandatory locking has been made an optional feature, governed by a configuration option .RB ( CONFIG_MANDATORY_FILE_LOCKING ). This feature is no longer supported at all in Linux 5.15 and above. -.PP +.P By default, both traditional (process-associated) and open file description record locks are advisory. Advisory locks are not enforced and are useful only between cooperating processes. -.PP +.P Both lock types can also be mandatory. Mandatory locks are enforced for all processes. If a process tries to perform an incompatible access (e.g., @@ -629,7 +629,7 @@ If the .B O_NONBLOCK flag is enabled, then the system call fails with the error .BR EAGAIN . -.PP +.P To make use of mandatory locks, mandatory locking must be enabled both on the filesystem that contains the file to be locked, and on the file itself. @@ -646,7 +646,7 @@ permission bit (see .BR chmod (1) and .BR chmod (2)). -.PP +.P Mandatory locking is not specified by POSIX. Some other systems also support mandatory locking, although the details of how to enable it vary across systems. @@ -658,7 +658,7 @@ This may happen due to administrative action on the server, or due to a network partition (i.e., loss of network connectivity with the server) which lasts long enough for the server to assume that the client is no longer functioning. -.PP +.P When the filesystem determines that a lock has been lost, future .BR read (2) or @@ -670,7 +670,7 @@ descriptor is closed. Since Linux 3.12, .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d this happens at least for NFSv4 (including all minor versions). -.PP +.P Some versions of UNIX send a signal .RB ( SIGLOST ) in this circumstance. @@ -722,7 +722,7 @@ one must also enable generation of signals on the file descriptor. This is done by using the .BR fcntl () .B F_SETFL -command to set the +operation to set the .B O_ASYNC file status flag on the file descriptor. Subsequently, a @@ -732,7 +732,7 @@ on the file descriptor. The .BR fcntl () .B F_SETSIG -command can be used to obtain delivery of a signal other than +operation can be used to obtain delivery of a signal other than .BR SIGIO . .IP Sending a signal to the owner process (group) specified by @@ -1002,14 +1002,14 @@ delivering and this signal is delivered to the entire process rather than to a specific thread. .\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05 -.PP +.P Using these mechanisms, a program can implement fully asynchronous I/O without using .BR select (2) or .BR poll (2) most of the time. -.PP +.P The use of .B O_ASYNC is specific to BSD and Linux. @@ -1074,7 +1074,7 @@ other open file descriptors for the file. .B F_UNLCK Remove our lease from the file. .RE -.PP +.P Leases are associated with an open file description (see .BR open (2)). This means that duplicate file descriptors (created by, for example, @@ -1087,7 +1087,7 @@ Furthermore, the lease is released by either an explicit .B F_UNLCK operation on any of these duplicate file descriptors, or when all such file descriptors have been closed. -.PP +.P Leases may be taken out only on regular files. An unprivileged process may take out a lease only on a file whose UID (owner) matches the filesystem UID of the process. @@ -1103,7 +1103,7 @@ by returning either indicating, respectively, a read lease , a write lease, or no lease. .I arg is ignored. -.PP +.P When a process (the "lease breaker") performs an .BR open (2) or @@ -1120,7 +1120,7 @@ accessed by another process (e.g., flushing cached buffers) and then either remove or downgrade its lease. A lease is removed by performing an .B F_SETLEASE -command specifying +operation specifying .I arg as .BR F_UNLCK . @@ -1130,16 +1130,16 @@ then it is sufficient for the lease holder to downgrade the lease to a read lease. This is done by performing an .B F_SETLEASE -command specifying +operation specifying .I arg as .BR F_RDLCK . -.PP +.P If the lease holder fails to downgrade or remove the lease within the number of seconds specified in .IR /proc/sys/fs/lease\-break\-time , then the kernel forcibly removes or downgrades the lease holder's lease. -.PP +.P Once a lease break has been initiated, .B F_GETLEASE returns the target lease type (either @@ -1149,11 +1149,11 @@ or depending on what would be compatible with the lease breaker) until the lease holder voluntarily downgrades or removes the lease or the kernel forcibly does so after the lease break timer expires. -.PP +.P Once the lease has been voluntarily or forcibly removed or downgraded, and assuming the lease breaker has not unblocked its system call, the kernel permits the lease breaker's system call to proceed. -.PP +.P If the lease breaker's blocked .BR open (2) or @@ -1174,16 +1174,16 @@ flag when calling then the call immediately fails with the error .BR EWOULDBLOCK , but the other steps still occur as described above. -.PP +.P The default signal used to notify the lease holder is .BR SIGIO , but this can be changed using the .B F_SETSIG -command to +operation to .BR fcntl (). If a .B F_SETSIG -command is performed (even one specifying +operation is performed (even one specifying .BR SIGIO ), and the signal handler is established using @@ -1206,7 +1206,7 @@ The events to be notified are specified in .IR arg , which is a bit mask specified by ORing together zero or more of the following bits: -.PP +.P .RS .PD 0 .TP @@ -1289,7 +1289,7 @@ The default signal is .BR SIGIO , but this can be changed using the .B F_SETSIG -command to +operation to .BR fcntl (). (Note that .B SIGIO @@ -1377,7 +1377,7 @@ file and filesystem. For an overview of file sealing, a discussion of its purpose, and some code examples, see .BR memfd_create (2). -.PP +.P Currently, file seals can be applied only to a file descriptor returned by .BR memfd_create (2) @@ -1388,7 +1388,7 @@ On other filesystems, all .BR fcntl () operations that operate on seals will return .BR EINVAL . -.PP +.P Seals are a property of an inode. Thus, all open file descriptors referring to the same inode share the same set of seals. @@ -1421,7 +1421,7 @@ If the file does not support sealing, \-1 is returned and .I errno is set to .BR EINVAL . -.PP +.P The following seals are available: .TP .B F_SEAL_SEAL @@ -1534,7 +1534,7 @@ for an explanation of open file descriptions.) In this context, the term "write lifetime" means the expected time the data will live on media, before being overwritten or erased. -.PP +.P An application may use the different hint values specified below to separate writes into different write classes, so that multiple users or applications running on a single storage back-end @@ -1542,7 +1542,7 @@ can aggregate their I/O patterns in a consistent manner. However, there are no functional semantics implied by these flags, and different I/O classes can use the write lifetime hints in arbitrary ways, so long as the hints are used consistently. -.PP +.P The following operations can be applied to the file descriptor, .IR fd : .TP @@ -1567,10 +1567,10 @@ the open file description referred to by Sets the read/write hint value associated with the open file description referred to by .IR fd . -.PP +.P If an open file description has not been assigned a read/write hint, then it shall use the value assigned to the inode, if any. -.PP +.P The following read/write hints are valid since Linux 4.13: .TP @@ -1602,7 +1602,7 @@ Data written to this inode or via this open file description is expected to have a lifetime longer than data written with .BR RWH_WRITE_LIFE_LONG . -.PP +.P All the write-specific hints are relative to each other, and no individual absolute meaning should be attributed to them. .SH RETURN VALUE @@ -1629,7 +1629,9 @@ for traditional .B SIGIO behavior. .TP -.BR F_GETPIPE_SZ ", " F_SETPIPE_SZ +.B F_GETPIPE_SZ +.TQ +.B F_SETPIPE_SZ The pipe capacity. .TP .B F_GET_SEALS @@ -1637,9 +1639,9 @@ A bit mask identifying the seals that have been set for the inode referred to by .IR fd . .TP -All other commands +All other operations Zero. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -1657,7 +1659,7 @@ another process. is not an open file descriptor .TP .B EBADF -.I cmd +.I op is .B F_SETLK or @@ -1666,7 +1668,7 @@ and the file descriptor open mode doesn't match with the type of lock requested. .TP .B EBUSY -.I cmd +.I op is .B F_SETPIPE_SZ and the new pipe capacity specified in @@ -1675,7 +1677,7 @@ is smaller than the amount of buffer space currently used to store data in the pipe. .TP .B EBUSY -.I cmd +.I op is .BR F_ADD_SEALS , .I arg @@ -1687,14 +1689,14 @@ and there exists a writable, shared mapping on the file referred to by .B EDEADLK It was detected that the specified .B F_SETLKW -command would cause a deadlock. +operation would cause a deadlock. .TP .B EFAULT .I lock is outside your accessible address space. .TP .B EINTR -.I cmd +.I op is .B F_SETLKW or @@ -1703,7 +1705,7 @@ and the operation was interrupted by a signal; see .BR signal (7). .TP .B EINTR -.I cmd +.I op is .BR F_GETLK , .BR F_SETLK , @@ -1717,11 +1719,11 @@ NFS), but can sometimes happen locally. .TP .B EINVAL The value specified in -.I cmd +.I op is not recognized by this kernel. .TP .B EINVAL -.I cmd +.I op is .B F_ADD_SEALS and @@ -1729,7 +1731,7 @@ and includes an unrecognized sealing bit. .TP .B EINVAL -.I cmd +.I op is .B F_ADD_SEALS or @@ -1739,7 +1741,7 @@ and the filesystem containing the inode referred to by does not support sealing. .TP .B EINVAL -.I cmd +.I op is .B F_DUPFD and @@ -1751,7 +1753,7 @@ in .BR getrlimit (2)). .TP .B EINVAL -.I cmd +.I op is .B F_SETSIG and @@ -1759,7 +1761,7 @@ and is not an allowable signal number. .TP .B EINVAL -.I cmd +.I op is .BR F_OFD_SETLK , .BR F_OFD_SETLKW , @@ -1770,7 +1772,7 @@ and was not specified as zero. .TP .B EMFILE -.I cmd +.I op is .B F_DUPFD and the per-process limit on the number of open file descriptors @@ -1783,13 +1785,13 @@ protocol failed (e.g., locking over NFS). .B ENOTDIR .B F_NOTIFY was specified in -.IR cmd , +.IR op , but .I fd does not refer to a directory. .TP .B EPERM -.I cmd +.I op is .B F_SETPIPE_SZ and the soft or hard user pipe limit has been reached; see @@ -1801,7 +1803,7 @@ Attempted to clear the flag on a file that has the append-only attribute set. .TP .B EPERM -.I cmd +.I op was .BR F_ADD_SEALS , but @@ -1811,7 +1813,7 @@ or the current set of seals on the file already includes .BR F_SEAL_SEAL . .SH STANDARDS POSIX.1-2008. -.PP +.P .BR F_GETOWN_EX , .BR F_SETOWN_EX , .BR F_SETPIPE_SZ , @@ -1826,9 +1828,9 @@ are Linux-specific. (Define the .B _GNU_SOURCE macro to obtain these definitions.) -.\" .PP +.\" .P .\" SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. -.PP +.P .BR F_OFD_SETLK , .BR F_OFD_SETLKW , and @@ -1837,7 +1839,7 @@ are Linux-specific (and one must define .B _GNU_SOURCE to obtain their definitions), but work is being done to have them included in the next version of POSIX.1. -.PP +.P .B F_ADD_SEALS and .B F_GET_SEALS @@ -1845,7 +1847,7 @@ are Linux-specific. .\" FIXME . Once glibc adds support, add a note about FTM requirements .SH HISTORY SVr4, 4.3BSD, POSIX.1-2001. -.PP +.P Only the operations .BR F_DUPFD , .BR F_GETFD , @@ -1857,7 +1859,7 @@ Only the operations and .B F_SETLKW are specified in POSIX.1-2001. -.PP +.P .B F_GETOWN and .B F_SETOWN @@ -1869,7 +1871,7 @@ are specified in POSIX.1-2001. with the value 500 or greater, or .B _POSIX_C_SOURCE with the value 200809L or greater.) -.PP +.P .B F_DUPFD_CLOEXEC is specified in POSIX.1-2008. (To get this definition, define @@ -1895,7 +1897,7 @@ Consequently, an system call was added in Linux 2.4. The newer system call employs a different structure for file locking, .IR flock64 , -and corresponding commands, +and corresponding operations, .BR F_GETLK64 , .BR F_SETLK64 , and @@ -1911,7 +1913,7 @@ placed by .BR flock (2) and .BR fcntl (). -.PP +.P Several systems have more fields in .I "struct flock" such as, for example, @@ -1926,7 +1928,7 @@ alone is not going to be very useful if the process holding the lock may live on a different machine; on Linux, while present on some architectures (such as MIPS32), this field is not used. -.PP +.P The original Linux .BR fcntl () system call was not designed to handle large file offsets @@ -1938,7 +1940,7 @@ Consequently, an system call was added in Linux 2.4. The newer system call employs a different structure for file locking, .IR flock64 , -and corresponding commands, +and corresponding operations, .BR F_GETLK64 , .BR F_SETLK64 , and @@ -1975,7 +1977,7 @@ The default value for this file is 90.) This scenario potentially risks data corruption, since another process might acquire a lock in the intervening period and perform file I/O. -.PP +.P Since Linux 3.12, .\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d if an NFSv4 client loses contact with the server, @@ -2096,7 +2098,7 @@ It is therefore inadvisable to rely on mandatory locking. .BR capabilities (7), .BR feature_test_macros (7), .BR lslocks (8) -.PP +.P .IR locks.txt , .IR mandatory\-locking.txt , and diff --git a/man2/flock.2 b/man2/flock.2 index 5f2917f..c2c93ca 100644 --- a/man2/flock.2 +++ b/man2/flock.2 @@ -12,7 +12,7 @@ .\" FIXME Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE .\" which only have effect for SAMBA. .\" -.TH flock 2 2023-03-30 "Linux man-pages 6.05.01" +.TH flock 2 2024-03-03 "Linux man-pages 6.7" .SH NAME flock \- apply or remove an advisory lock on an open file .SH LIBRARY @@ -21,14 +21,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int flock(int " fd ", int " operation ); +.P +.BI "int flock(int " fd ", int " op ); .fi .SH DESCRIPTION Apply or remove an advisory lock on the open file specified by .IR fd . The argument -.I operation +.I op is one of the following: .RS 4 .TP 9 @@ -45,7 +45,7 @@ file at a given time. .B LOCK_UN Remove an existing lock held by this process. .RE -.PP +.P A call to .BR flock () may block if an incompatible lock is held by another process. @@ -53,9 +53,9 @@ To make a nonblocking request, include .B LOCK_NB (by ORing) with any of the above operations. -.PP +.P A single file may not simultaneously have both shared and exclusive locks. -.PP +.P Locks created by .BR flock () are associated with an open file description (see @@ -70,7 +70,7 @@ Furthermore, the lock is released either by an explicit .B LOCK_UN operation on any of these duplicate file descriptors, or when all such file descriptors have been closed. -.PP +.P If a process uses .BR open (2) (or similar) to obtain more than one file descriptor for the same file, @@ -79,19 +79,19 @@ these file descriptors are treated independently by An attempt to lock the file using one of these file descriptors may be denied by a lock that the calling process has already placed via another file descriptor. -.PP +.P A process may hold only one type of lock (shared or exclusive) on a file. Subsequent .BR flock () calls on an already locked file will convert an existing lock to the new lock mode. -.PP +.P Locks created by .BR flock () are preserved across an .BR execve (2). -.PP +.P A shared or exclusive lock can be placed on a file regardless of the mode in which the file was opened. .SH RETURN VALUE @@ -111,7 +111,7 @@ delivery of a signal caught by a handler; see .BR signal (7). .TP .B EINVAL -.I operation +.I op is invalid. .TP .B ENOLCK @@ -149,7 +149,7 @@ Up to Linux 5.4, .BR flock () is not propagated over SMB. A file with such locks will not appear locked for remote clients. -.PP +.P Since Linux 5.5, .BR flock () locks are emulated with SMB byte-range locks on the entire file. @@ -164,7 +164,7 @@ any IO on a locked file will always fail with when done from a separate file descriptor. This difference originates from the design of locks in the SMB protocol, which provides mandatory locking semantics. -.PP +.P Remote and mandatory locking semantics may vary with SMB protocol, mount options and server type. See @@ -191,7 +191,7 @@ Instead, one could use byte-range locking, which does work over NFS, given a sufficiently recent version of Linux and a server which supports locking. -.PP +.P Since Linux 2.6.12, NFS clients support .BR flock () locks by emulating them as @@ -206,7 +206,7 @@ locks interact with one another over NFS. It also means that in order to place an exclusive lock, the file must be opened for writing. -.PP +.P Since Linux 2.6.37, .\" commit 5eebde23223aeb0ad2d9e3be6590ff8bbfab0fc2 the kernel supports a compatibility mode that allows @@ -224,7 +224,7 @@ places advisory locks only; given suitable permissions on a file, a process is free to ignore the use of .BR flock () and perform I/O on the file. -.PP +.P .BR flock () and .BR fcntl (2) @@ -237,7 +237,7 @@ using the semantics of .BR flock () will be different from those described in this manual page. -.PP +.P Converting a lock (shared to exclusive, or vice versa) is not guaranteed to be atomic: the existing lock is first removed, and then a new lock is established. @@ -260,7 +260,7 @@ and occurs on many other implementations.) .BR open (2), .BR lockf (3), .BR lslocks (8) -.PP +.P .I Documentation/filesystems/locks.txt in the Linux kernel source tree .RI ( Documentation/locks.txt diff --git a/man2/fork.2 b/man2/fork.2 index 607a86b..abfbbed 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -16,7 +16,7 @@ .\" Greatly expanded, to describe all attributes that differ .\" parent and child. .\" -.TH fork 2 2023-05-03 "Linux man-pages 6.05.01" +.TH fork 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fork \- create a child process .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B pid_t fork(void); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ process. The calling process is referred to as the .I parent process. -.PP +.P The child process and the parent process run in separate memory spaces. At the time of .BR fork () @@ -47,7 +47,7 @@ Memory writes, file mappings and unmappings .RB ( munmap (2)) performed by one of the processes do not affect the other. -.PP +.P The child process is an exact duplicate of the parent process except for the following points: .IP \[bu] 3 @@ -93,7 +93,7 @@ from its parent .BR aio_write (3)), nor does it inherit any asynchronous I/O contexts from its parent (see .BR io_setup (2)). -.PP +.P The process attributes in the preceding list are all specified in POSIX.1. The parent and child also differ with respect to the following @@ -144,7 +144,7 @@ The port access permission bits set by are not inherited by the child; the child must turn on any bits that it requires using .BR ioperm (2). -.PP +.P Note the following further points: .IP \[bu] 3 The child process is created with a single thread\[em]the @@ -300,7 +300,7 @@ See and .BR wait (2) for more examples. -.PP +.P .\" SRC BEGIN (fork.c) .EX #include diff --git a/man2/fsync.2 b/man2/fsync.2 index 623e7ca..8566ef7 100644 --- a/man2/fsync.2 +++ b/man2/fsync.2 @@ -15,7 +15,7 @@ .\" 2006-04-28, mtk, substantial rewrite of various parts. .\" 2012-02-27 Various changes by Christoph Hellwig .\" -.TH fsync 2 2023-03-30 "Linux man-pages 6.05.01" +.TH fsync 2 2023-10-31 "Linux man-pages 6.7" .SH NAME fsync, fdatasync \- synchronize a file's in-core state with storage device .SH LIBRARY @@ -24,17 +24,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fsync(int " fd ); -.PP +.P .BI "int fdatasync(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR fsync (): glibc 2.16 and later: @@ -43,7 +43,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE || /* Since glibc 2.8: */ _POSIX_C_SOURCE >= 200112L .fi -.PP +.P .BR fdatasync (): .nf _POSIX_C_SOURCE >= 199309L || _XOPEN_SOURCE >= 500 @@ -59,12 +59,12 @@ changed information can be retrieved even if the system crashes or is rebooted. This includes writing through or flushing a disk cache if present. The call blocks until the device reports that the transfer has completed. -.PP +.P As well as flushing the file data, .BR fsync () also flushes the metadata information associated with the file (see .BR inode (7)). -.PP +.P Calling .BR fsync () does not necessarily ensure @@ -72,7 +72,7 @@ that the entry in the directory containing the file has also reached disk. For that an explicit .BR fsync () on a file descriptor for the directory is also needed. -.PP +.P .BR fdatasync () is similar to .BR fsync (), @@ -93,7 +93,7 @@ On the other hand, a change to the file size as made by say .BR ftruncate (2)), would require a metadata flush. -.PP +.P The aim of .BR fdatasync () is to reduce disk activity for applications that do not @@ -130,12 +130,16 @@ all file descriptors that were open on the file when the error was recorded. .B ENOSPC Disk space was exhausted while synchronizing. .TP -.BR EROFS ", " EINVAL +.B EROFS +.TQ +.B EINVAL .I fd is bound to a special file (e.g., a pipe, FIFO, or socket) which does not support synchronization. .TP -.BR ENOSPC ", " EDQUOT +.B ENOSPC +.TQ +.B EDQUOT .I fd is bound to a file on NFS or another filesystem which does not allocate space at the time of a @@ -155,23 +159,17 @@ to a value greater than 0. .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L. .\" -1: unavailable, 0: ask using sysconf(). .\" glibc defines them to 1. -.PP -On some UNIX systems (but not Linux), -.I fd -must be a -.I writable -file descriptor. .SH STANDARDS POSIX.1-2008. .SH HISTORY -POSIX.1-2001, 4.3BSD. -.PP +POSIX.1-2001, 4.2BSD. +.P In Linux 2.2 and earlier, .BR fdatasync () is equivalent to .BR fsync (), and so has no performance advantage. -.PP +.P The .BR fsync () implementations in older kernels and lesser used filesystems @@ -181,6 +179,13 @@ In these cases disk caches need to be disabled using or .BR sdparm (8) to guarantee safe operation. +.P +Under AT&T UNIX System V Release 4 +.I fd +needs to be opened for writing. +This is by itself incompatible with the original BSD interface +and forbidden by POSIX, +but nevertheless survives in HP-UX and AIX. .SH SEE ALSO .BR sync (1), .BR bdflush (2), diff --git a/man2/futex.2 b/man2/futex.2 index 43b1075..2ff300b 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -19,7 +19,7 @@ .\" FIXME Do we need to add some text regarding Torvald Riegel's 2015-01-24 mail .\" http://thread.gmane.org/gmane.linux.kernel/1703405/focus=1873242 .\" -.TH futex 2 2023-05-03 "Linux man-pages 6.05.01" +.TH futex 2 2023-10-31 "Linux man-pages 6.7" .SH NAME futex \- fast user-space locking .SH LIBRARY @@ -27,18 +27,18 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include " " /* Definition of " FUTEX_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \ ", uint32_t " val , .BI " const struct timespec *" timeout , \ " \fR /* or: \fBuint32_t \fIval2\fP */" .BI " uint32_t *" uaddr2 ", uint32_t " val3 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR futex (), @@ -61,7 +61,7 @@ Other .BR futex () operations can be used to wake any processes or threads waiting for a particular condition. -.PP +.P A futex is a 32-bit value\[em]referred to below as a .IR "futex word" \[em]whose address is supplied to the @@ -80,7 +80,7 @@ virtual addresses in different processes, but these addresses all refer to the same location in physical memory.) In a multithreaded program, it is sufficient to place the futex word in a global variable shared by all threads. -.PP +.P When executing a futex operation that requests to block a thread, the kernel will block only if the futex word has the value that the calling thread supplied (as one of the arguments of the @@ -113,7 +113,7 @@ blocking via a futex is an atomic compare-and-block operation. .\" the reference in the following sentence .\" See NOTES for a detailed specification of .\" the synchronization semantics. -.PP +.P One use of futexes is for implementing locks. The state of the lock (i.e., acquired or not acquired) can be represented as an atomically accessed flag in shared memory. @@ -140,10 +140,10 @@ operation that wakes threads blocked on the lock flag used as a futex word See .BR futex (7) for more detail on how to use futexes. -.PP +.P Besides the basic wait and wake-up futex functionality, there are further futex operations aimed at supporting more complex use cases. -.PP +.P Note that no explicit initialization or destruction is necessary to use futexes; the kernel maintains a futex @@ -164,7 +164,7 @@ argument; .I val is a value whose meaning and purpose depends on .IR futex_op . -.PP +.P The remaining arguments .RI ( timeout , .IR uaddr2 , @@ -172,7 +172,7 @@ and .IR val3 ) are required only for certain of the futex operations described below. Where one of these arguments is not required, it is ignored. -.PP +.P For several blocking operations, the .I timeout argument is a pointer to a @@ -190,12 +190,12 @@ then to and in the remainder of this page, this argument is referred to as .I val2 when interpreted in this fashion. -.PP +.P Where it is required, the .I uaddr2 argument is a pointer to a second futex word that is employed by the operation. -.PP +.P The interpretation of the final integer argument, .IR val3 , depends on the operation. @@ -264,7 +264,7 @@ If this option is not set, the kernel measures the against the .B CLOCK_MONOTONIC clock. -.PP +.P The operation specified in .I futex_op is one of the following: @@ -835,7 +835,7 @@ while tasks at an intermediate priority continuously preempt the low-priority task from the CPU. Consequently, the low-priority task makes no progress toward releasing the lock, and the high-priority task remains blocked. -.PP +.P Priority inheritance is a mechanism for dealing with the priority-inversion problem. With this mechanism, when a high-priority task becomes blocked @@ -852,7 +852,7 @@ held by another intermediate-priority task then both of those tasks (or more generally, all of the tasks in a lock chain) have their priorities raised to be the same as the high-priority task. -.PP +.P From a user-space perspective, what makes a futex PI-aware is a policy agreement (described below) between user space and the kernel about the value of the futex word, @@ -868,7 +868,7 @@ for the implementation of very specific IPC mechanisms.) .\" talk about a PI aware pthread_mutex, than a PI aware futex, since .\" there is a lot of policy and scaffolding that has to be built up .\" around it to use it properly (this is what a PI pthread_mutex is). -.PP +.P .\" mtk: The following text is drawn from the Hart/Guniguntala paper .\" (listed in SEE ALSO), but I have reworded some pieces .\" significantly. @@ -899,7 +899,7 @@ FUTEX_WAITERS | TID (Note that is invalid for a PI futex word to have no owner and .B FUTEX_WAITERS set.) -.PP +.P With this policy in place, a user-space application can acquire an unacquired lock or release a lock using atomic instructions executed in user mode @@ -910,7 +910,7 @@ Acquiring a lock simply consists of using compare-and-swap to atomically set the futex word's value to the caller's TID if its previous value was 0. Releasing a lock requires using compare-and-swap to set the futex word's value to 0 if the previous value was the expected TID. -.PP +.P If a futex is already acquired (i.e., has a nonzero value), waiters must employ the .B FUTEX_LOCK_PI @@ -923,7 +923,7 @@ bit is set in the futex value; in this case, the lock owner must employ the .B FUTEX_UNLOCK_PI operation to release the lock. -.PP +.P In the cases where callers are forced into the kernel (i.e., required to perform a .BR futex () @@ -933,7 +933,7 @@ a kernel locking mechanism which implements the required priority-inheritance semantics. After the RT-mutex is acquired, the futex value is updated accordingly, before the calling thread returns to user space. -.PP +.P It is important to note .\" tglx (July 2015): .\" If there are multiple waiters on a pi futex then a wake pi operation @@ -950,7 +950,7 @@ up in an invalid state, such as having an owner but the value being 0, or having waiters but not having the .B FUTEX_WAITERS bit set.) -.PP +.P If a futex has an associated RT-mutex in the kernel (i.e., there are blocked waiters) and the owner of the futex/RT-mutex dies unexpectedly, @@ -969,7 +969,7 @@ the dead owner. .\" mechanism. In that case the futex value will be set to .\" FUTEX_OWNER_DIED. The robust futex mechanism is also available for non .\" PI futexes. -.PP +.P PI futexes are operated on by specifying one of the values listed below in .IR futex_op . Note that the PI futex operations must be used as paired operations @@ -1000,7 +1000,7 @@ Additionally, (or the error .B EINVAL results). -.PP +.P The PI futex operations are as follows: .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -1362,7 +1362,7 @@ was invoked via all operations return \-1 and set .I errno to indicate the error. -.PP +.P The return value on success depends on the operation, as described in the following list: .TP @@ -1742,7 +1742,7 @@ and the timeout expired before the operation completed. Linux. .SH HISTORY Linux 2.6.0. -.PP +.P Initial futex support was merged in Linux 2.5.7 but with different semantics from what was described above. A four-argument system call with the semantics @@ -1760,7 +1760,7 @@ The two processes each write messages to the terminal and employ a synchronization protocol that ensures that they alternate in writing messages. Upon running this program we see output such as the following: -.PP +.P .in +4n .EX $ \fB./futex_demo\fP @@ -1931,7 +1931,7 @@ main(int argc, char *argv[]) .BR pthread_mutexattr_getprotocol (3), .BR futex (7), .BR sched (7) -.PP +.P The following kernel source files: .IP \[bu] 3 .I Documentation/pi\-futex.txt @@ -1943,28 +1943,28 @@ The following kernel source files: .I Documentation/locking/rt\-mutex\-design.txt .IP \[bu] .I Documentation/robust\-futex\-ABI.txt -.PP +.P Franke, H., Russell, R., and Kirwood, M., 2002. \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP (from proceedings of the Ottawa Linux Symposium 2002), .br .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf .UE -.PP +.P Hart, D., 2009. \fIA futex overview and update\fP, .UR http://lwn.net/Articles/360699/ .UE -.PP +.P Hart, D.\& and Guniguntala, D., 2009. \fIRequeue-PI: Making glibc Condvars PI-Aware\fP (from proceedings of the 2009 Real-Time Linux Workshop), .UR http://lwn.net/images/conf/rtlws11/papers/proc/p10.pdf .UE -.PP +.P Drepper, U., 2011. \fIFutexes Are Tricky\fP, .UR http://www.akkadia.org/drepper/futex.pdf .UE -.PP +.P Futex example library, futex\-*.tar.bz2 at .br .UR https://mirrors.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/ diff --git a/man2/futimesat.2 b/man2/futimesat.2 index 4a120cd..b2a18ab 100644 --- a/man2/futimesat.2 +++ b/man2/futimesat.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH futimesat 2 2023-03-30 "Linux man-pages 6.05.01" +.TH futimesat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME futimesat \- change timestamps of a file relative to a \ directory file descriptor @@ -13,16 +13,16 @@ Standard C library .nf .BR "#include " " /* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "[[deprecated]] int futimesat(int " dirfd ", const char *" pathname , .BI " const struct timeval " times [2]); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR futimesat (): .nf _GNU_SOURCE @@ -32,13 +32,13 @@ This system call is obsolete. Use .BR utimensat (2) instead. -.PP +.P The .BR futimesat () system call operates in exactly the same way as .BR utimes (2), except for the differences described in this manual page. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -48,7 +48,7 @@ referred to by the file descriptor the calling process, as is done by .BR utimes (2) for a relative pathname). -.PP +.P If .I pathname is relative and @@ -60,7 +60,7 @@ then is interpreted relative to the current working directory of the calling process (like .BR utimes (2)). -.PP +.P If .I pathname is absolute, then @@ -113,11 +113,11 @@ None. .SH HISTORY Linux 2.6.16, glibc 2.4. -.PP +.P It was implemented from a specification that was proposed for POSIX.1, but that specification was replaced by the one for .BR utimensat (2). -.PP +.P A similar system call exists on Solaris. .SH NOTES .SH SEE ALSO diff --git a/man2/get_kernel_syms.2 b/man2/get_kernel_syms.2 index 307d9ca..a1029b1 100644 --- a/man2/get_kernel_syms.2 +++ b/man2/get_kernel_syms.2 @@ -5,26 +5,26 @@ .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" -.TH get_kernel_syms 2 2023-03-30 "Linux man-pages 6.05.01" +.TH get_kernel_syms 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_kernel_syms \- retrieve exported kernel and module symbols .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int get_kernel_syms(struct kernel_sym *" table ); .fi .SH DESCRIPTION .BR Note : This system call is present only before Linux 2.6. -.PP +.P If .I table is NULL, .BR get_kernel_syms () returns the number of symbols available for query. Otherwise, it fills in a table of structures: -.PP +.P .in +4n .EX struct kernel_sym { @@ -33,13 +33,13 @@ struct kernel_sym { }; .EE .in -.PP +.P The symbols are interspersed with magic symbols of the form .BI # module-name with the kernel having an empty name. The value associated with a symbol of this form is the address at which the module is loaded. -.PP +.P The symbols exported from each module follow their magic module tag and the modules are returned in the reverse of the order in which they were loaded. @@ -60,7 +60,7 @@ Linux. .SH HISTORY Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.PP +.P This obsolete system call is not supported by glibc. No declaration is provided in glibc headers, but, through a quirk of history, glibc versions before glibc 2.23 did export an ABI for this system call. @@ -73,9 +73,9 @@ There is no way to indicate the size of the buffer allocated for .IR table . If symbols have been added to the kernel since the program queried for the symbol table size, memory will be corrupted. -.PP +.P The length of exported symbol names is limited to 59 characters. -.PP +.P Because of these limitations, this system call is deprecated in favor of .BR query_module (2) diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2 index 45b8f2f..3846bcc 100644 --- a/man2/get_mempolicy.2 +++ b/man2/get_mempolicy.2 @@ -7,7 +7,7 @@ .\" 2007-08-27, Lee Schermerhorn .\" more precise specification of behavior. .\" -.TH get_mempolicy 2 2023-07-16 "Linux man-pages 6.05.01" +.TH get_mempolicy 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_mempolicy \- retrieve NUMA memory policy for a thread .SH LIBRARY @@ -16,7 +16,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .B "#include " .nf -.PP +.P .BI "long get_mempolicy(int *" mode , .BI " unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)" .B " / ULONG_WIDTH]," @@ -28,12 +28,12 @@ NUMA (Non-Uniform Memory Access) policy library retrieves the NUMA policy of the calling thread or of a memory address, depending on the setting of .IR flags . -.PP +.P A NUMA machine has different memory controllers with different distances to specific CPUs. The memory policy defines from which node memory is allocated for the thread. -.PP +.P If .I flags is specified as 0, @@ -55,7 +55,7 @@ When is 0, .I addr must be specified as NULL. -.PP +.P If .I flags specifies @@ -77,7 +77,7 @@ with either .B MPOL_F_ADDR or .BR MPOL_F_NODE . -.PP +.P If .I flags specifies @@ -91,7 +91,7 @@ or one of the helper functions described in .BR numa (3) has been used to establish a policy for the memory range containing .IR addr . -.PP +.P If the .I mode argument is not NULL, then @@ -112,7 +112,7 @@ The value specified by .I maxnode is always rounded to a multiple of .IR "sizeof(unsigned\ long)*8" . -.PP +.P If .I flags specifies both @@ -129,7 +129,7 @@ If no page has yet been allocated for the specified address, will allocate a page as if the thread had performed a read (load) access to that address, and return the ID of the node where that page was allocated. -.PP +.P If .I flags specifies @@ -154,9 +154,9 @@ call with the flag for read accesses, and in memory ranges mapped with the .B MAP_SHARED flag for all accesses. -.PP +.P Other flag values are reserved. -.PP +.P For an overview of the possible policies see .BR set_mempolicy (2). .SH RETURN VALUE diff --git a/man2/get_robust_list.2 b/man2/get_robust_list.2 index 7ca4817..bd8682a 100644 --- a/man2/get_robust_list.2 +++ b/man2/get_robust_list.2 @@ -7,7 +7,7 @@ .\" FIXME Something could be added to this page (or exit(2)) .\" about exit_robust_list processing .\" -.TH get_robust_list 2 2022-10-30 "Linux man-pages 6.05.01" +.TH get_robust_list 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_robust_list, set_robust_list \- get/set list of robust futexes .SH LIBRARY @@ -19,13 +19,13 @@ Standard C library " /* Definition of " "struct robust_list_head" " */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_get_robust_list, int " pid , .BI " struct robust_list_head **" head_ptr ", size_t *" len_ptr ); .B long syscall(SYS_set_robust_list, .BI " struct robust_list_head *" head ", size_t " len ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -38,7 +38,7 @@ A thread can inform the kernel of the location of its robust futex list using .BR set_robust_list (). The address of a thread's robust futex list can be obtained using .BR get_robust_list (). -.PP +.P The purpose of the robust futex list is to ensure that if a thread accidentally fails to unlock a futex before terminating or calling .BR execve (2), @@ -50,7 +50,7 @@ bit is set in the futex word, and the kernel performs a .BR futex (2) .B FUTEX_WAKE operation on one of the threads waiting on the futex. -.PP +.P The .BR get_robust_list () system call returns the head of the robust futex list of the thread @@ -66,14 +66,14 @@ The size of the object pointed to by .I **head_ptr is stored in .IR len_ptr . -.PP +.P Permission to employ .BR get_robust_list () is governed by a ptrace access mode .B PTRACE_MODE_READ_REALCREDS check; see .BR ptrace (2). -.PP +.P The .BR set_robust_list () system call requests the kernel to record the head of the list of @@ -101,7 +101,7 @@ system call can fail with the following error: .I len does not equal .IR "sizeof(struct\ robust_list_head)" . -.PP +.P The .BR get_robust_list () system call can fail with the following errors: @@ -126,11 +126,11 @@ could be found. These system calls were added in Linux 2.6.17. .SH NOTES These system calls are not needed by normal applications. -.PP +.P A thread can have only one robust futex list; therefore applications that wish to use this functionality should use the robust mutexes provided by glibc. -.PP +.P In the initial implementation, a thread waiting on a futex was notified that the owner had died only if the owner terminated. @@ -138,7 +138,7 @@ Starting with Linux 2.6.28, .\" commit 8141c7f3e7aee618312fa1c15109e1219de784a7 notification was extended to include the case where the owner performs an .BR execve (2). -.PP +.P The thread IDs mentioned in the main text are .I kernel thread IDs of the kind returned by @@ -148,7 +148,7 @@ and .SH SEE ALSO .BR futex (2), .BR pthread_mutexattr_setrobust (3) -.PP +.P .I Documentation/robust\-futexes.txt and .I Documentation/robust\-futex\-ABI.txt diff --git a/man2/getcpu.2 b/man2/getcpu.2 index f90401f..4525470 100644 --- a/man2/getcpu.2 +++ b/man2/getcpu.2 @@ -4,7 +4,7 @@ .\" .\" 2008, mtk, various edits .\" -.TH getcpu 2 2023-07-15 "Linux man-pages 6.05.01" +.TH getcpu 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getcpu \- determine CPU and NUMA node on which the calling thread is running .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int getcpu(unsigned int *_Nullable " cpu ", \ unsigned int *_Nullable " node ); .fi @@ -35,7 +35,7 @@ When either or .I node is NULL nothing is written to the respective pointer. -.PP +.P The information placed in .I cpu is guaranteed to be current only at the time of the call: @@ -67,21 +67,21 @@ glibc 2.29. .\" .SS C library/kernel differences The kernel system call has a third argument: -.PP +.P .in +4n .nf .BI "int getcpu(unsigned int *" cpu ", unsigned int *" node , .BI " struct getcpu_cache *" tcache ); .fi .in -.PP +.P The .I tcache argument is unused since Linux 2.6.24, and (when invoking the system call directly) should be specified as NULL, unless portability to Linux 2.6.23 or earlier is required. -.PP +.P .\" commit 4307d1e5ada595c87f9a4d16db16ba5edb70dcb1 .\" Author: Ingo Molnar .\" Date: Wed Nov 7 18:37:48 2007 +0100 diff --git a/man2/getdents.2 b/man2/getdents.2 index 604a6ef..728d4d7 100644 --- a/man2/getdents.2 +++ b/man2/getdents.2 @@ -8,7 +8,7 @@ .\" Derived from 'readdir.2'. .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond .\" -.TH getdents 2 2023-05-03 "Linux man-pages 6.05.01" +.TH getdents 2 2024-02-25 "Linux man-pages 6.7" .SH NAME getdents, getdents64 \- get directory entries .SH LIBRARY @@ -18,23 +18,23 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_getdents, unsigned int " fd \ ", struct linux_dirent *" dirp , .BI " unsigned int " count ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "ssize_t getdents64(int " fd ", void " dirp [. count "], size_t " count ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR getdents (), necessitating the use of .BR syscall (2). -.PP +.P .IR Note : There is no definition of .I struct linux_dirent @@ -58,16 +58,16 @@ into the buffer pointed to by The argument .I count specifies the size of that buffer. -.PP +.P The .I linux_dirent structure is declared as follows: -.PP +.P .in +4n .EX struct linux_dirent { unsigned long d_ino; /* Inode number */ - unsigned long d_off; /* Offset to next \fIlinux_dirent\fP */ + unsigned long d_off; /* Not an offset; see below */ unsigned short d_reclen; /* Length of this \fIlinux_dirent\fP */ char d_name[]; /* Filename (null\-terminated) */ /* length is actually (d_reclen \- 2 \- @@ -80,18 +80,22 @@ struct linux_dirent { } .EE .in -.PP +.P .I d_ino is an inode number. .I d_off -is the distance from the start of the directory to the start of the next -.IR linux_dirent . +is a filesystem-specific value with no specific meaning to user space, +though on older filesystems it used to be +the distance from the start of the directory to the start of the next +.IR linux_dirent ; +see +.BR readdir (3) . .I d_reclen is the size of this entire .IR linux_dirent . .I d_name is a null-terminated filename. -.PP +.P .I d_type is a byte at the end of the structure that indicates the file type. It contains one of the following values (defined in @@ -120,7 +124,7 @@ This is a UNIX domain socket. .TP .B DT_UNKNOWN The file type is unknown. -.PP +.P The .I d_type field is implemented since Linux 2.6.4. @@ -130,7 +134,7 @@ structure. Thus, on kernels up to and including Linux 2.6.3, attempting to access this field always provides the value 0 .RB ( DT_UNKNOWN ). -.PP +.P Currently, .\" kernel 2.6.27 .\" The same sentence is in readdir.2 @@ -155,19 +159,19 @@ In addition, supports an explicit .I d_type field. -.PP +.P The .BR getdents64 () system call is like .BR getdents (), except that its second argument is a pointer to a buffer containing structures of the following type: -.PP +.P .in +4n .EX struct linux_dirent64 { ino64_t d_ino; /* 64\-bit inode number */ - off64_t d_off; /* 64\-bit offset to next structure */ + off64_t d_off; /* Not an offset; see getdents() */ unsigned short d_reclen; /* Size of this dirent */ unsigned char d_type; /* File type */ char d_name[]; /* Filename (null\-terminated) */ @@ -217,11 +221,11 @@ In that case you will need to define the or .I linux_dirent64 structure yourself. -.PP +.P Probably, you want to use .BR readdir (3) instead of these system calls. -.PP +.P These calls supersede .BR readdir (2). .SH EXAMPLES @@ -231,7 +235,7 @@ The program below demonstrates the use of .BR getdents (). The following output shows an example of what we see when running this program on an ext2 directory: -.PP +.P .in +4n .EX .RB "$" " ./a.out /testfs/" diff --git a/man2/getdomainname.2 b/man2/getdomainname.2 index b65cbfb..9c3b6e5 100644 --- a/man2/getdomainname.2 +++ b/man2/getdomainname.2 @@ -6,7 +6,7 @@ .\" Modified 2004-06-17 by Michael Kerrisk .\" Modified 2008-11-27 by mtk .\" -.TH getdomainname 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getdomainname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getdomainname, setdomainname \- get/set NIS domain name .SH LIBRARY @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getdomainname(char *" name ", size_t " len ); .BI "int setdomainname(const char *" name ", size_t " len ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getdomainname (), .BR setdomainname (): .nf @@ -41,7 +41,7 @@ These functions are used to access or to change the NIS domain name of the host system. More precisely, they operate on the NIS domain name associated with the calling process's UTS namespace. -.PP +.P .BR setdomainname () sets the domain name to the value given in the character array .IR name . @@ -52,7 +52,7 @@ argument specifies the number of bytes in (Thus, .I name does not require a terminating null byte.) -.PP +.P .BR getdomainname () returns the null-terminated domain name in the character array .IR name , @@ -84,7 +84,7 @@ The caller did not have the .B CAP_SYS_ADMIN capability in the user namespace associated with its UTS namespace (see .BR namespaces (7)). -.PP +.P .BR getdomainname () can fail with the following errors: .TP diff --git a/man2/getgid.2 b/man2/getgid.2 index a1f64e0..74394a1 100644 --- a/man2/getgid.2 +++ b/man2/getgid.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getgid, getegid \- get group identity .SH LIBRARY @@ -11,14 +11,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B gid_t getgid(void); .B gid_t getegid(void); .fi .SH DESCRIPTION .BR getgid () returns the real group ID of the calling process. -.PP +.P .BR getegid () returns the effective group ID of the calling process. .SH ERRORS @@ -47,7 +47,7 @@ for details regarding register mapping. POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P The original Linux .BR getgid () and diff --git a/man2/getgroups.2 b/man2/getgroups.2 index eb282b9..d00dc9e 100644 --- a/man2/getgroups.2 +++ b/man2/getgroups.2 @@ -9,7 +9,7 @@ .\" 2008-05-03, mtk, expanded and rewrote parts of DESCRIPTION and RETURN .\" VALUE, made style of page more consistent with man-pages style. .\" -.TH getgroups 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getgroups 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getgroups, setgroups \- get/set list of supplementary group IDs .SH LIBRARY @@ -18,19 +18,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getgroups(int " size ", gid_t " list []); -.PP +.P .B #include -.PP +.P .BI "int setgroups(size_t " size ", const gid_t *_Nullable " list ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setgroups (): .nf Since glibc 2.19: @@ -50,13 +50,13 @@ buffer pointed to by If the calling process is a member of more than .I size supplementary groups, then an error results. -.PP +.P It is unspecified whether the effective group ID of the calling process is included in the returned list. (Thus, an application should also call .BR getegid (2) and add or remove the resulting value.) -.PP +.P If .I size is zero, @@ -67,7 +67,7 @@ This allows the caller to determine the size of a dynamically allocated .I list to be used in a further call to .BR getgroups (). -.PP +.P .BR setgroups () sets the supplementary group IDs for the calling process. Appropriate privileges are required (see the description of the @@ -79,7 +79,7 @@ argument specifies the number of supplementary group IDs in the buffer pointed to by .IR list . A process can drop all of its supplementary groups with the call: -.PP +.P .in +4n .EX setgroups(0, NULL); @@ -92,7 +92,7 @@ returns the number of supplementary group IDs. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR setgroups () returns 0. @@ -104,14 +104,14 @@ is set to indicate the error. .B EFAULT .I list has an invalid address. -.PP +.P .BR getgroups () can additionally fail with the following error: .TP .B EINVAL .I size is less than the number of supplementary group IDs, but is not zero. -.PP +.P .BR setgroups () can additionally fail with the following errors: .TP @@ -170,7 +170,7 @@ SVr4, 4.3BSD. Since .BR setgroups () requires privilege, it is not covered by POSIX.1. -.PP +.P The original Linux .BR getgroups () system call supported only 16-bit group IDs. @@ -192,17 +192,17 @@ is defined in The set of supplementary group IDs is inherited from the parent process, and preserved across an .BR execve (2). -.PP +.P The maximum number of supplementary group IDs can be found at run time using .BR sysconf (3): -.PP +.P .in +4n .EX long ngroups_max; ngroups_max = sysconf(_SC_NGROUPS_MAX); .EE .in -.PP +.P The maximum return value of .BR getgroups () cannot be larger than one more than this value. diff --git a/man2/gethostname.2 b/man2/gethostname.2 index 26b8df3..0e3ed70 100644 --- a/man2/gethostname.2 +++ b/man2/gethostname.2 @@ -9,7 +9,7 @@ .\" Modified 2004-06-17 by mtk .\" Modified 2008-11-27 by mtk .\" -.TH gethostname 2 2023-03-30 "Linux man-pages 6.05.01" +.TH gethostname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME gethostname, sethostname \- get/set hostname .SH LIBRARY @@ -18,16 +18,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int gethostname(char *" name ", size_t " len ); .BI "int sethostname(const char *" name ", size_t " len ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gethostname (): .nf _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see .\" The above is something of a simplification .\" also before glibc 2.3 there was a bit churn .fi -.PP +.P .BR sethostname (): .nf Since glibc 2.21: @@ -50,7 +50,7 @@ Feature Test Macro Requirements for glibc (see These system calls are used to access or to change the system hostname. More precisely, they operate on the hostname associated with the calling process's UTS namespace. -.PP +.P .BR sethostname () sets the hostname to the value given in the character array .IR name . @@ -61,7 +61,7 @@ argument specifies the number of bytes in (Thus, .I name does not require a terminating null byte.) -.PP +.P .BR gethostname () returns the null-terminated hostname in the character array .IR name , @@ -155,7 +155,7 @@ POSIX.1-2001 and POSIX.1-2008 specify .BR gethostname () but not .BR sethostname (). -.PP +.P Versions of glibc before glibc 2.2 .\" At least glibc 2.0 and glibc 2.1, older versions not checked handle the case where the length of the diff --git a/man2/getitimer.2 b/man2/getitimer.2 index 422a04e..6674117 100644 --- a/man2/getitimer.2 +++ b/man2/getitimer.2 @@ -10,7 +10,7 @@ .\" 2005-04-06 mtk, Matthias Lang .\" Noted MAX_SEC_IN_JIFFIES ceiling .\" -.TH getitimer 2 2023-05-03 "Linux man-pages 6.05.01" +.TH getitimer 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getitimer, setitimer \- get or set value of an interval timer .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getitimer(int " which ", struct itimerval *" curr_value ); .BI "int setitimer(int " which ", const struct itimerval *restrict " new_value , .BI " struct itimerval *_Nullable restrict " old_value ); @@ -31,7 +31,7 @@ and (optionally) at regular intervals after that. When a timer expires, a signal is generated for the calling process, and the timer is reset to the specified interval (if the interval is nonzero). -.PP +.P Three types of timers\[em]specified via the .I which argument\[em]are provided, @@ -63,11 +63,11 @@ In conjunction with .BR ITIMER_VIRTUAL , this timer can be used to profile user and system CPU time consumed by the process. -.PP +.P A process has only one of each of the three types of timers. -.PP +.P Timer values are defined by the following structures: -.PP +.P .in +4n .EX struct itimerval { @@ -89,7 +89,7 @@ places the current value of the timer specified by .I which in the buffer pointed to by .IR curr_value . -.PP +.P The .I it_value substructure is populated with the amount of time remaining until @@ -100,7 +100,7 @@ when the timer expires. If both fields of .I it_value are zero, then this timer is currently disarmed (inactive). -.PP +.P The .I it_interval substructure is populated with the timer interval. @@ -120,7 +120,7 @@ is non-NULL, the buffer it points to is used to return the previous value of the timer (i.e., the same information that is returned by .BR getitimer ()). -.PP +.P If either field in .I new_value.it_value is nonzero, @@ -128,7 +128,7 @@ then the timer is armed to initially expire at the specified time. If both fields in .I new_value.it_value are zero, then the timer is disarmed. -.PP +.P The .I new_value.it_interval field specifies the new interval for the timer; @@ -161,22 +161,22 @@ fields in the structure pointed to by contains a value outside the range [0, 999999]. .SH VERSIONS The standards are silent on the meaning of the call: -.PP +.P .in +4n .EX setitimer(which, NULL, &old_value); .EE .in -.PP +.P Many systems (Solaris, the BSDs, and perhaps others) treat this as equivalent to: -.PP +.P .in +4n .EX getitimer(which, &old_value); .EE .in -.PP +.P In Linux, this is treated as being equivalent to a call in which the .I new_value fields are zero; that is, the timer is disabled. @@ -203,13 +203,13 @@ on the system timer resolution and on the system load; see If the timer expires while the process is active (always true for .BR ITIMER_VIRTUAL ), the signal will be delivered immediately when generated. -.PP +.P A child created via .BR fork (2) does not inherit its parent's interval timers. Interval timers are preserved across an .BR execve (2). -.PP +.P POSIX.1 leaves the interaction between .BR setitimer () @@ -228,7 +228,7 @@ Under very heavy loading, an timer may expire before the signal from a previous expiration has been delivered. The second signal in such an event will be lost. -.PP +.P Before Linux 2.6.16, timer values are represented in jiffies. If a request is made set a timer with a value whose jiffies representation exceeds @@ -243,14 +243,14 @@ approximately 99.42 days. Since Linux 2.6.16, the kernel uses a different internal representation for times, and this ceiling is removed. -.PP +.P On certain systems (including i386), Linux kernels before Linux 2.6.12 have a bug which will produce premature timer expirations of up to one jiffy under some circumstances. This bug is fixed in Linux 2.6.12. .\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x. .\" http://lkml.org/lkml/2005/7/1/165 -.PP +.P POSIX.1-2001 says that .BR setitimer () should fail if a diff --git a/man2/getpagesize.2 b/man2/getpagesize.2 index 6f3b54b..25fcbcd 100644 --- a/man2/getpagesize.2 +++ b/man2/getpagesize.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getpagesize 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getpagesize 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpagesize \- get memory page size .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int getpagesize(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpagesize (): .nf Since glibc 2.20: @@ -52,19 +52,19 @@ Portable applications should employ .I sysconf(_SC_PAGESIZE) instead of .BR getpagesize (): -.PP +.P .in +4n .EX #include long sz = sysconf(_SC_PAGESIZE); .EE .in -.PP +.P (Most systems allow the synonym .B _SC_PAGE_SIZE for .BR _SC_PAGESIZE .) -.PP +.P Whether .BR getpagesize () is present as a Linux system call depends on the architecture. diff --git a/man2/getpeername.2 b/man2/getpeername.2 index d150617..b738e9e 100644 --- a/man2/getpeername.2 +++ b/man2/getpeername.2 @@ -11,7 +11,7 @@ .\" Modified 17 Jul 2002, Michael Kerrisk .\" Added 'socket' to NAME, so that "man -k socket" will show this page. .\" -.TH getpeername 2 2023-04-03 "Linux man-pages 6.05.01" +.TH getpeername 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpeername \- get name of connected peer socket .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getpeername(int " sockfd ", struct sockaddr *restrict " addr , .BI " socklen_t *restrict " addrlen ); .fi @@ -37,7 +37,7 @@ by .IR addr . On return it contains the actual size of the name returned (in bytes). The name is truncated if the buffer provided is too small. -.PP +.P The returned address is truncated if the buffer provided is too small; in this case, .I addrlen diff --git a/man2/getpid.2 b/man2/getpid.2 index 3b78823..5166035 100644 --- a/man2/getpid.2 +++ b/man2/getpid.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getpid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getpid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpid, getppid \- get process identification .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B pid_t getpid(void); .B pid_t getppid(void); .fi @@ -20,7 +20,7 @@ Standard C library returns the process ID (PID) of the calling process. (This is often used by routines that generate unique temporary filenames.) -.PP +.P .BR getppid () returns the process ID of the parent of the calling process. This will be either the ID of the process that created this process using @@ -109,7 +109,7 @@ via the glibc wrapper function. .BR clone (2).) Furthermore, the complexity of the caching code had been the source of a few bugs within glibc over the years. -.PP +.P Because of the aforementioned problems, since glibc 2.25, the PID cache is removed: .\" commit c579f48edba88380635ab98cb612030e3ed8691e @@ -124,7 +124,7 @@ If the caller's parent is in a different PID namespace (see .BR pid_namespaces (7)), .BR getppid () returns 0. -.PP +.P From a kernel perspective, the PID (which is shared by all of the threads in a multithreaded process) is sometimes also known as the thread group ID (TGID). diff --git a/man2/getpriority.2 b/man2/getpriority.2 index 723d3d4..e4aa4f0 100644 --- a/man2/getpriority.2 +++ b/man2/getpriority.2 @@ -14,7 +14,7 @@ .\" Clarified meaning of 0 value for 'who' argument .\" Modified 2004-05-27 by Michael Kerrisk .\" -.TH getpriority 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getpriority 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getpriority, setpriority \- get/set program scheduling priority .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getpriority(int " which ", id_t " who ); .BI "int setpriority(int " which ", id_t " who ", int " prio ); .fi @@ -41,7 +41,7 @@ call. The process attribute dealt with by these system calls is the same attribute (also known as the "nice" value) that is dealt with by .BR nice (2). -.PP +.P The value .I which is one of @@ -64,7 +64,7 @@ A zero value for .I who denotes (respectively) the calling process, the process group of the calling process, or the real user ID of the calling process. -.PP +.P The .I prio argument is a value in the range \-20 to 19 (but see NOTES below), @@ -73,7 +73,7 @@ Attempts to set a priority outside this range are silently clamped to the range. The default priority is 0; lower values give a process a higher scheduling priority. -.PP +.P The .BR getpriority () call returns the highest priority (lowest numerical value) @@ -82,7 +82,7 @@ The .BR setpriority () call sets the priorities of all of the specified processes to the specified value. -.PP +.P Traditionally, only a privileged process could lower the nice value (i.e., set a higher priority). However, since Linux 2.6.12, an unprivileged process can decrease @@ -98,7 +98,7 @@ returns the calling thread's nice value, which may be a negative number. On error, it returns \-1 and sets .I errno to indicate the error. -.PP +.P Since a successful call to .BR getpriority () can legitimately return the value \-1, it is necessary @@ -109,7 +109,7 @@ call, then check .I errno afterward to determine if \-1 is an error or a legitimate value. -.PP +.P .BR setpriority () returns 0 on success. On failure, it returns \-1 and sets @@ -154,19 +154,19 @@ SVr4, 4.4BSD (these interfaces first appeared in 4.2BSD). .SH NOTES For further details on the nice value, see .BR sched (7). -.PP +.P .IR Note : the addition of the "autogroup" feature in Linux 2.6.38 means that the nice value no longer has its traditional effect in many circumstances. For details, see .BR sched (7). -.PP +.P A child created by .BR fork (2) inherits its parent's nice value. The nice value is preserved across .BR execve (2). -.PP +.P The details on the condition for .B EPERM depend on the system. @@ -204,6 +204,6 @@ which may be made standards conformant in the future. .BR fork (2), .BR capabilities (7), .BR sched (7) -.PP +.P .I Documentation/scheduler/sched\-nice\-design.txt in the Linux kernel source tree (since Linux 2.6.23) diff --git a/man2/getrandom.2 b/man2/getrandom.2 index 565763b..e4c63a8 100644 --- a/man2/getrandom.2 +++ b/man2/getrandom.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getrandom 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getrandom 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getrandom \- obtain a series of random bytes .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t getrandom(void " buf [. buflen "], size_t " buflen ", \ unsigned int " flags ); .fi @@ -27,7 +27,7 @@ with up to random bytes. These bytes can be used to seed user-space random number generators or for cryptographic purposes. -.PP +.P By default, .BR getrandom () draws entropy from the @@ -38,7 +38,7 @@ device). This behavior can be changed via the .I flags argument. -.PP +.P If the .I urandom source has been initialized, @@ -48,7 +48,7 @@ No such guarantees apply for larger buffer sizes. For example, if the call is interrupted by a signal handler, it may return a partially filled buffer, or fail with the error .BR EINTR . -.PP +.P If the .I urandom source has not yet been initialized, then @@ -57,7 +57,7 @@ will block, unless .B GRND_NONBLOCK is specified in .IR flags . -.PP +.P The .I flags argument is a bit mask that can contain zero or more of the following values @@ -119,7 +119,7 @@ was specified in and insufficient entropy was present in the .I random source or the system call was interrupted by a signal. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -164,7 +164,7 @@ glibc 2.25. For an overview and comparison of the various interfaces that can be used to obtain randomness, see .BR random (7). -.PP +.P Unlike .I /dev/random and @@ -222,7 +222,7 @@ will block until some random bytes become available (unless the .B GRND_NONBLOCK flag was specified). -.PP +.P The behavior when a call to .BR getrandom () that is blocked while reading from the @@ -247,26 +247,26 @@ then will not fail with .BR EINTR . Instead, it will return all of the bytes that have been requested. -.PP +.P When reading from the .I random source, blocking requests of any size can be interrupted by a signal handler (the call fails with the error .BR EINTR ). -.PP +.P Using .BR getrandom () to read small buffers (<=\ 256 bytes) from the .I urandom source is the preferred mode of usage. -.PP +.P The special treatment of small values of .I buflen was designed for compatibility with OpenBSD's .BR getentropy (3), which is nowadays supported by glibc. -.PP +.P The user of .BR getrandom () .I must diff --git a/man2/getresuid.2 b/man2/getresuid.2 index d5cadd7..9b4a1ff 100644 --- a/man2/getresuid.2 +++ b/man2/getresuid.2 @@ -5,7 +5,7 @@ .\" .\" Modified, 2003-05-26, Michael Kerrisk, .\" -.TH getresuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getresuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getresuid, getresgid \- get real, effective, and saved user/group IDs .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int getresuid(uid_t *" ruid ", uid_t *" euid ", uid_t *" suid ); .BI "int getresgid(gid_t *" rgid ", gid_t *" egid ", gid_t *" sgid ); .fi @@ -46,7 +46,7 @@ These calls also appear on HP-UX and some of the BSDs. .SH HISTORY Linux 2.1.44, glibc 2.3.2. -.PP +.P The original Linux .BR getresuid () and diff --git a/man2/getrlimit.2 b/man2/getrlimit.2 index afc2c22..ece8e97 100644 --- a/man2/getrlimit.2 +++ b/man2/getrlimit.2 @@ -42,7 +42,7 @@ .\" 2008-05-07, mtk / Peter Zijlstra, Added description of RLIMIT_RTTIME .\" 2010-11-06, mtk: Added documentation of prlimit() .\" -.TH getrlimit 2 2023-07-20 "Linux man-pages 6.05.01" +.TH getrlimit 2 2024-02-25 "Linux man-pages 6.7" .SH NAME getrlimit, setrlimit, prlimit \- get/set resource limits .SH LIBRARY @@ -51,20 +51,20 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getrlimit(int " resource ", struct rlimit *" rlim ); .BI "int setrlimit(int " resource ", const struct rlimit *" rlim ); -.PP +.P .BI "int prlimit(pid_t " pid ", int " resource , .BI " const struct rlimit *_Nullable " new_limit , .BI " struct rlimit *_Nullable " old_limit ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR prlimit (): .nf _GNU_SOURCE @@ -78,7 +78,7 @@ system calls get and set resource limits. Each resource has an associated soft and hard limit, as defined by the .I rlimit structure: -.PP +.P .in +4n .EX struct rlimit { @@ -87,7 +87,7 @@ struct rlimit { }; .EE .in -.PP +.P The soft limit is the value that the kernel enforces for the corresponding resource. The hard limit acts as a ceiling for the soft limit: @@ -97,14 +97,14 @@ A privileged process (under Linux: one with the .B CAP_SYS_RESOURCE capability in the initial user namespace) may make arbitrary changes to either limit value. -.PP +.P The value .B RLIM_INFINITY denotes no limit on a resource (both in the structure returned by .BR getrlimit () and in the structure passed to .BR setrlimit ()). -.PP +.P The .I resource argument must be one of: @@ -450,14 +450,14 @@ system call combines and extends the functionality of and .BR getrlimit (). It can be used to both set and get the resource limits of an arbitrary process. -.PP +.P The .I resource argument has the same meaning as for .BR setrlimit () and .BR getrlimit (). -.PP +.P If the .I new_limit argument is not NULL, then the @@ -475,7 +475,7 @@ in the .I rlimit structure pointed to by .IR old_limit . -.PP +.P The .I pid argument specifies the ID of the process on which the call is to operate. @@ -556,7 +556,6 @@ T{ .BR prlimit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR getrlimit () @@ -566,7 +565,7 @@ POSIX.1-2008. .TP .BR prlimit () Linux. -.PP +.P .B RLIMIT_MEMLOCK and .B RLIMIT_NPROC @@ -598,15 +597,15 @@ A child process created via inherits its parent's resource limits. Resource limits are preserved across .BR execve (2). -.PP +.P Resource limits are per-process attributes that are shared by all of the threads in a process. -.PP +.P Lowering the soft limit for a resource below the process's current consumption of that resource will succeed (but will prevent the process from further increasing its consumption of the resource). -.PP +.P One can set the resource limits of the shell using the built-in .I ulimit command @@ -615,12 +614,12 @@ in .BR csh (1)). The shell's resource limits are inherited by the processes that it creates to execute commands. -.PP +.P Since Linux 2.6.24, the resource limits of any process can be inspected via .IR /proc/ pid /limits ; see .BR proc (5). -.PP +.P Ancient systems provided a .BR vlimit () function with a similar purpose to @@ -638,7 +637,7 @@ wrapper functions no longer invoke the corresponding system calls, but instead employ .BR prlimit (), for the reasons described in BUGS. -.PP +.P The name of the glibc wrapper function is .BR prlimit (); the underlying system call is @@ -652,7 +651,7 @@ signals delivered when a process encountered the soft and hard .B RLIMIT_CPU limits were delivered one (CPU) second later than they should have been. This was fixed in Linux 2.6.8. -.PP +.P In Linux 2.6.x kernels before Linux 2.6.17, a .B RLIMIT_CPU limit of 0 is wrongly treated as "no limit" (like @@ -660,12 +659,12 @@ limit of 0 is wrongly treated as "no limit" (like Since Linux 2.6.17, setting a limit of 0 does have an effect, but is actually treated as a limit of 1 second. .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=114008066530167&w=2 -.PP +.P A kernel bug means that .\" See https://lwn.net/Articles/145008/ .B RLIMIT_RTPRIO does not work in Linux 2.6.12; the problem is fixed in Linux 2.6.13. -.PP +.P In Linux 2.6.12, there was an off-by-one mismatch between the priority ranges returned by .BR getpriority (2) @@ -676,7 +675,7 @@ was calculated as .IR "19\ \-\ rlim_cur" . This was fixed in Linux 2.6.13. .\" see http://marc.theaimsgroup.com/?l=linux-kernel&m=112256338703880&w=2 -.PP +.P Since Linux 2.6.12, .\" The relevant patch, sent to LKML, seems to be .\" http://thread.gmane.org/gmane.linux.kernel/273462 @@ -703,7 +702,7 @@ portable applications should avoid relying on this Linux-specific behavior. The Linux-specific .B RLIMIT_RTTIME limit exhibits the same behavior when the soft limit is encountered. -.PP +.P Kernels before Linux 2.4.22 did not diagnose the error .B EINVAL for @@ -713,12 +712,12 @@ when was greater than .IR rlim\->rlim_max . .\" d3561f78fd379a7110e46c87964ba7aa4120235c -.PP +.P Linux doesn't return an error when an attempt to set .B RLIMIT_CPU has failed, for compatibility reasons. .\" -.SS Representation of """large""" resource limit values on 32-bit platforms +.SS Representation of \[dq]large\[dq] resource limit values on 32-bit platforms The glibc .BR getrlimit () and @@ -753,7 +752,7 @@ represent file offsets\[em]that is, as wide as a 64-bit .B off_t (assuming a program compiled with .IR _FILE_OFFSET_BITS=64 ). -.PP +.P To work around this kernel limitation, if a program tried to set a resource limit to a value larger than can be represented in a 32-bit @@ -763,7 +762,7 @@ then the glibc wrapper function silently converted the limit value to .BR RLIM_INFINITY . In other words, the requested resource limit setting was silently ignored. -.PP +.P Since glibc 2.13, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12201 glibc works around the limitations of the @@ -779,7 +778,7 @@ as wrapper functions that call .SH EXAMPLES The program below demonstrates the use of .BR prlimit (). -.PP +.P .\" SRC BEGIN (getrlimit.c) .EX #define _GNU_SOURCE diff --git a/man2/getrusage.2 b/man2/getrusage.2 index 8966295..97c144f 100644 --- a/man2/getrusage.2 +++ b/man2/getrusage.2 @@ -17,7 +17,7 @@ .\" document ru_maxrss .\" 2010-05-24, mtk, enhanced description of various fields .\" -.TH getrusage 2 2023-07-20 "Linux man-pages 6.05.01" +.TH getrusage 2 2024-03-14 "Linux man-pages 6.7" .SH NAME getrusage \- get resource usage .SH LIBRARY @@ -26,7 +26,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getrusage(int " who ", struct rusage *" usage ); .fi .SH DESCRIPTION @@ -55,11 +55,11 @@ feature test macro must be defined (before including header file) in order to obtain the definition of this constant from .IR . -.PP +.P The resource usages are returned in the structure pointed to by .IR usage , which has the following form: -.PP +.P .in +4n .EX struct rusage { @@ -82,7 +82,7 @@ struct rusage { }; .EE .in -.PP +.P Not all fields are completed; unmaintained fields are set to zero by the kernel. (The unmaintained fields are provided for compatibility with other systems, @@ -195,22 +195,21 @@ T{ .BR getrusage () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. -.PP +.P POSIX.1 specifies .BR getrusage (), but specifies only the fields .I ru_utime and .IR ru_stime . -.PP +.P .B RUSAGE_THREAD is Linux-specific. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P Before Linux 2.6.9, if the disposition of .B SIGCHLD is set to @@ -222,10 +221,10 @@ although POSIX.1-2001 explicitly prohibits this. This nonconformance is rectified in Linux 2.6.9 and later. .\" See the description of getrusage() in XSH. .\" A similar statement was also in SUSv2. -.PP +.P The structure definition shown at the start of this page was taken from 4.3BSD Reno. -.PP +.P Ancient systems provided a .BR vtimes () function with a similar purpose to @@ -240,15 +239,12 @@ implementation.) .SH NOTES Resource usage metrics are preserved across an .BR execve (2). -.PP -See also the description of -.IR /proc/ pid /stat -in -.BR proc (5). .SH SEE ALSO .BR clock_gettime (2), .BR getrlimit (2), .BR times (2), .BR wait (2), .BR wait4 (2), -.BR clock (3) +.BR clock (3), +.BR proc_pid_stat (5), +.BR proc_pid_io (5) diff --git a/man2/getsid.2 b/man2/getsid.2 index 842c980..25f0b2d 100644 --- a/man2/getsid.2 +++ b/man2/getsid.2 @@ -5,7 +5,7 @@ .\" .\" Modified Thu Oct 31 14:18:40 1996 by Eric S. Raymond .\" Modified 2001-12-17, aeb -.TH getsid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getsid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getsid \- get session ID .SH LIBRARY @@ -14,15 +14,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "pid_t getsid(pid_t" " pid" ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getsid (): .nf _XOPEN_SOURCE >= 500 diff --git a/man2/getsockname.2 b/man2/getsockname.2 index e2cc11e..6d4a9f6 100644 --- a/man2/getsockname.2 +++ b/man2/getsockname.2 @@ -9,7 +9,7 @@ .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond .\" Modified Sun Mar 28 21:26:46 1999 by Andries Brouwer .\" -.TH getsockname 2 2023-04-03 "Linux man-pages 6.05.01" +.TH getsockname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getsockname \- get socket name .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getsockname(int " sockfd ", struct sockaddr *restrict " addr , .BI " socklen_t *restrict " addrlen ); .fi @@ -34,7 +34,7 @@ argument should be initialized to indicate the amount of space (in bytes) pointed to by .IR addr . On return it contains the actual size of the socket address. -.PP +.P The returned address is truncated if the buffer provided is too small; in this case, .I addrlen diff --git a/man2/getsockopt.2 b/man2/getsockopt.2 index f80900a..baf3395 100644 --- a/man2/getsockopt.2 +++ b/man2/getsockopt.2 @@ -13,7 +13,7 @@ .\" Modified 1999 by Andi Kleen . .\" Removed most stuff because it is in socket.7 now. .\" -.TH getsockopt 2 2023-04-03 "Linux man-pages 6.05.01" +.TH getsockopt 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getsockopt, setsockopt \- get and set options on sockets .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getsockopt(int " sockfd ", int " level ", int " optname , .BI " void " optval "[restrict *." optlen ], .BI " socklen_t *restrict " optlen ); @@ -39,7 +39,7 @@ manipulate options for the socket referred to by the file descriptor Options may exist at multiple protocol levels; they are always present at the uppermost socket level. -.PP +.P When manipulating socket options, the level at which the option resides and the name of the option must be specified. To manipulate options at the sockets API level, @@ -58,7 +58,7 @@ should be set to the protocol number of .BR TCP ; see .BR getprotoent (3). -.PP +.P The arguments .I optval and @@ -80,7 +80,7 @@ the value returned. If no option value is to be supplied or returned, .I optval may be NULL. -.PP +.P .I Optname and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. @@ -90,7 +90,7 @@ contains definitions for socket level options, described below. Options at other protocol levels vary in format and name; consult the appropriate entries in section 4 of the manual. -.PP +.P Most socket-level options utilize an .I int argument for @@ -99,7 +99,7 @@ For .BR setsockopt (), the argument should be nonzero to enable a boolean option, or zero if the option is to be disabled. -.PP +.P For a description of the available socket options see .BR socket (7) and the appropriate protocol man pages. @@ -108,7 +108,7 @@ On success, zero is returned for the standard options. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P Netfilter allows the programmer to define custom socket options with associated handlers; for such options, the return value on success is the value returned by the handler. diff --git a/man2/gettid.2 b/man2/gettid.2 index d4ca4d0..297a902 100644 --- a/man2/gettid.2 +++ b/man2/gettid.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH gettid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH gettid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME gettid \- get thread identification .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .B #define _GNU_SOURCE .B #include -.PP +.P .B pid_t gettid(void); .fi .SH DESCRIPTION @@ -41,7 +41,7 @@ glibc 2.30. The thread ID returned by this call is not the same thing as a POSIX thread ID (i.e., the opaque value returned by .BR pthread_self (3)). -.PP +.P In a new thread group created by a .BR clone (2) call that does not specify the diff --git a/man2/gettimeofday.2 b/man2/gettimeofday.2 index 8381cc0..cd8bc84 100644 --- a/man2/gettimeofday.2 +++ b/man2/gettimeofday.2 @@ -17,7 +17,7 @@ .\" Modified, 2004-05-27 by Michael Kerrisk .\" Added notes on capability requirement. .\" -.TH gettimeofday 2 2023-07-28 "Linux man-pages 6.05.01" +.TH gettimeofday 2 2023-10-31 "Linux man-pages 6.7" .SH NAME gettimeofday, settimeofday \- get / set time .SH LIBRARY @@ -26,18 +26,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int gettimeofday(struct timeval *restrict " tv , .BI " struct timezone *_Nullable restrict " tz ); .BI "int settimeofday(const struct timeval *" tv , .BI " const struct timezone *_Nullable " tz ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR settimeofday (): .nf Since glibc 2.19: @@ -51,14 +51,14 @@ The functions and .BR settimeofday () can get and set the time as well as a timezone. -.PP +.P The .I tv argument is a .I struct timeval (as specified in .IR ): -.PP +.P .in +4n .EX struct timeval { @@ -67,15 +67,15 @@ struct timeval { }; .EE .in -.PP +.P and gives the number of seconds and microseconds since the Epoch (see .BR time (2)). -.PP +.P The .I tz argument is a .IR "struct timezone" : -.PP +.P .in +4n .EX struct timezone { @@ -84,7 +84,7 @@ struct timezone { }; .EE .in -.PP +.P If either .I tv or @@ -96,17 +96,17 @@ is NULL, the corresponding structure is not set or returned. .I tv is NULL.) .\" The following is covered under EPERM below: -.\" .PP +.\" .P .\" Only the superuser may use .\" .BR settimeofday (). -.PP +.P The use of the .I timezone structure is obsolete; the .I tz argument should normally be specified as NULL. (See NOTES below.) -.PP +.P Under Linux, there are some peculiar "warp clock" semantics associated with the .BR settimeofday () @@ -175,11 +175,11 @@ On some architectures, an implementation of .BR gettimeofday () is provided in the .BR vdso (7). -.PP +.P The kernel accepts NULL for both .I tv and -.IR tz. +.IR tz . The timezone argument is ignored by glibc and musl, and not passed to/from the kernel. Android's bionic passes the timezone argument to/from the kernel, @@ -204,7 +204,7 @@ POSIX.1-2008 marks as obsolete, recommending the use of .BR clock_gettime (2) instead. -.PP +.P Traditionally, the fields of .I struct timeval were of type @@ -235,7 +235,7 @@ or .\" Each and every occurrence of this field in the kernel source .\" (other than the declaration) is a bug. Thus, the following is purely of historical interest. -.PP +.P On old systems, the field .I tz_dsttime contains a symbolic constant (values are given below) @@ -245,7 +245,7 @@ is in force. it does not indicate that DST is in force, it just selects an algorithm.) The daylight saving time algorithms defined are as follows: -.PP +.P .in +4n .EX \fBDST_NONE\fP /* not on DST */ @@ -261,7 +261,7 @@ The daylight saving time algorithms defined are as follows: \fBDST_AUSTALT\fP /* Australian style with shift in 1986 */ .EE .in -.PP +.P Of course it turned out that the period in which Daylight Saving Time is in force cannot be given by a simple algorithm, one per country; indeed, @@ -277,7 +277,7 @@ affected by discontinuous jumps in the system time (e.g., if the system administrator manually changes the system time). If you need a monotonically increasing clock, see .BR clock_gettime (2). -.PP +.P Macros for operating on .I timeval structures are described in diff --git a/man2/getuid.2 b/man2/getuid.2 index 1b94158..978b8ec 100644 --- a/man2/getuid.2 +++ b/man2/getuid.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Historical remark, aeb, 2004-06-05 -.TH getuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getuid, geteuid \- get user identity .SH LIBRARY @@ -12,14 +12,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B uid_t getuid(void); .B uid_t geteuid(void); .fi .SH DESCRIPTION .BR getuid () returns the real user ID of the calling process. -.PP +.P .BR geteuid () returns the effective user ID of the calling process. .SH ERRORS @@ -32,7 +32,7 @@ and never modify POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P In UNIX\ V6 the .BR getuid () call returned @@ -41,7 +41,7 @@ UNIX\ V7 introduced separate calls .BR getuid () and .BR geteuid (). -.PP +.P The original Linux .BR getuid () and @@ -57,7 +57,7 @@ The glibc and .BR geteuid () wrapper functions transparently deal with the variations across kernel versions. -.PP +.P On Alpha, instead of a pair of .BR getuid () and diff --git a/man2/getunwind.2 b/man2/getunwind.2 index eaf7117..1a904b7 100644 --- a/man2/getunwind.2 +++ b/man2/getunwind.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getunwind 2 2023-03-30 "Linux man-pages 6.05.01" +.TH getunwind 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getunwind \- copy the unwind data to caller's buffer .SH LIBRARY @@ -15,13 +15,13 @@ Standard C library .B #include .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "[[deprecated]] long syscall(SYS_getunwind, void " buf [. buf_size ], .BI " size_t " buf_size ); .fi .SH DESCRIPTION .I Note: this system call is obsolete. -.PP +.P The IA-64-specific .BR getunwind () @@ -31,7 +31,7 @@ unwind data into the buffer pointed to by and returns the size of the unwind data; this data describes the gate page (kernel code that is mapped into user space). -.PP +.P The size of the buffer .I buf is specified in @@ -43,11 +43,11 @@ is greater than or equal to the size of the unwind data and is not NULL; otherwise, no data is copied, and the call succeeds, returning the size that would be needed to store the unwind data. -.PP +.P The first part of the unwind data contains an unwind table. The rest contains the associated unwind information, in no particular order. The unwind table contains entries of the following form: -.PP +.P .in +4n .EX u64 start; (64\-bit address of start of function) @@ -55,7 +55,7 @@ u64 end; (64\-bit address of end of function) u64 info; (BUF\-relative offset to unwind info) .EE .in -.PP +.P An entry whose .I start value is zero indicates the end of the table. @@ -79,7 +79,7 @@ if the unwind info can't be stored in the space specified by Linux on IA-64. .SH HISTORY Linux 2.4. -.PP +.P This system call has been deprecated. The modern way to obtain the kernel's unwind data is via the .BR vdso (7). diff --git a/man2/getxattr.2 b/man2/getxattr.2 index 21df6ca..6d7a0ee 100644 --- a/man2/getxattr.2 +++ b/man2/getxattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH getxattr 2 2023-07-28 "Linux man-pages 6.05.01" +.TH getxattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t getxattr(const char *" path ", const char *" name , .BI " void " value [. size "], size_t " size ); .BI "ssize_t lgetxattr(const char *" path ", const char *" name , @@ -30,7 +30,7 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR getxattr () retrieves the value of the extended attribute identified by .I name @@ -43,13 +43,13 @@ The attribute value is placed in the buffer pointed to by specifies the size of that buffer. The return value of the call is the number of bytes placed in .IR value . -.PP +.P .BR lgetxattr () is identical to .BR getxattr (), except in the case of a symbolic link, where the link itself is interrogated, not the file that it refers to. -.PP +.P .BR fgetxattr () is identical to .BR getxattr (), @@ -59,7 +59,7 @@ only the open file referred to by .BR open (2)) is interrogated in place of .IR path . -.PP +.P An extended attribute .I name is a null-terminated string. @@ -68,7 +68,7 @@ namespaces associated with an individual inode. The value of an extended attribute is a chunk of arbitrary textual or binary data that was assigned using .BR setxattr (2). -.PP +.P If .I size is specified as zero, these calls return the current size of the @@ -113,7 +113,7 @@ The of the .I value buffer is too small to hold the result. -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. diff --git a/man2/idle.2 b/man2/idle.2 index 197f366..c32b3d7 100644 --- a/man2/idle.2 +++ b/man2/idle.2 @@ -9,13 +9,13 @@ .\" N.B. calling "idle" from user process used to hang process! .\" Modified Thu Oct 31 14:41:15 1996 by Eric S. Raymond .\" " -.TH idle 2 2023-03-30 "Linux man-pages 6.05.01" +.TH idle 2 2023-10-31 "Linux man-pages 6.7" .SH NAME idle \- make process 0 idle .SH SYNOPSIS .nf .B #include -.PP +.P .B [[deprecated]] int idle(void); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ It marks the process's pages as swappable, lowers its priority, and enters the main scheduling loop. .BR idle () never returns. -.PP +.P Only process 0 may call .BR idle (). Any user process, even a process with superuser permission, diff --git a/man2/init_module.2 b/man2/init_module.2 index a5fed4d..5cc61d0 100644 --- a/man2/init_module.2 +++ b/man2/init_module.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH init_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH init_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME init_module, finit_module \- load a kernel module .SH LIBRARY @@ -15,14 +15,14 @@ Standard C library .BR "#include " " /* Definition of " MODULE_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_init_module, void " module_image [. len "], \ unsigned long " len , .BI " const char *" param_values ); .BI "int syscall(SYS_finit_module, int " fd , .BI " const char *" param_values ", int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -36,7 +36,7 @@ and then runs the module's .I init function. This system call requires privilege. -.PP +.P The .I module_image argument points to a buffer containing the binary image @@ -44,7 +44,7 @@ to be loaded; .I len specifies the size of that buffer. The module image should be a valid ELF image, built for the running kernel. -.PP +.P The .I param_values argument is a string containing space-delimited specifications of the @@ -55,12 +55,12 @@ and The kernel parses this string and initializes the specified parameters. Each of the parameter specifications has the form: -.PP +.P .RI " " name [\c .BI = value\c .RB [ ,\c .IR value ...]] -.PP +.P The parameter .I name is one of those defined within the module using @@ -93,7 +93,7 @@ The .I param_values argument is as for .BR init_module (). -.PP +.P The .I flags argument modifies the operation of @@ -107,7 +107,7 @@ Ignore symbol version hashes. .TP .B MODULE_INIT_IGNORE_VERMAGIC Ignore kernel version magic. -.PP +.P There are some safety checks built into a module to ensure that it matches the kernel against which it is loaded. .\" http://www.tldp.org/HOWTO/Module-HOWTO/basekerncompat.html @@ -125,7 +125,7 @@ for the function named by the symbol. In this case, the kernel version number within the "vermagic" string is ignored, as the symbol version hashes are assumed to be sufficiently reliable. -.PP +.P Using the .B MODULE_INIT_IGNORE_VERMAGIC flag indicates that the "vermagic" string is to be ignored, and the @@ -177,7 +177,7 @@ or module loading is disabled .I /proc/sys/kernel/modules_disabled in .BR proc (5)). -.PP +.P The following errors may additionally occur for .BR init_module (): .TP @@ -205,7 +205,7 @@ The binary image supplied in .I module_image is not an ELF image, or is an ELF image that is invalid or for a different architecture. -.PP +.P The following errors may additionally occur for .BR finit_module (): .TP @@ -232,7 +232,7 @@ does not refer to an open file. The file referred to by .I fd is opened for read-write. -.PP +.P In addition to the above errors, if the module's .I init function is executed and returns an error, then @@ -250,7 +250,7 @@ Linux. .TP .BR finit_module () Linux 3.8. -.PP +.P The .BR init_module () system call is not supported by glibc. @@ -265,11 +265,11 @@ alternatively, you can invoke the system call using In Linux 2.4 and earlier, the .BR init_module () system call was rather different: -.PP +.P .B " #include " -.PP +.P .BI " int init_module(const char *" name ", struct module *" image ); -.PP +.P (User-space applications can detect which version of .BR init_module () is available by calling @@ -277,7 +277,7 @@ is available by calling the latter call fails with the error .B ENOSYS on Linux 2.6 and later.) -.PP +.P The older version of the system call loads the relocated module image pointed to by .I image @@ -288,11 +288,11 @@ The caller is responsible for providing the relocated image (since Linux 2.6, the .BR init_module () system call does the relocation). -.PP +.P The module image begins with a module structure and is followed by code and data as appropriate. Since Linux 2.2, the module structure is defined as follows: -.PP +.P .in +4n .EX struct module { @@ -317,7 +317,7 @@ struct module { }; .EE .in -.PP +.P All of the pointer fields, with the exception of .I next and @@ -330,7 +330,7 @@ Information about currently loaded modules can be found in .I /proc/modules and in the file trees under the per-module subdirectories under .IR /sys/module . -.PP +.P See the Linux kernel source file .I include/linux/module.h for some useful background information. diff --git a/man2/inotify_add_watch.2 b/man2/inotify_add_watch.2 index 2604115..b86328b 100644 --- a/man2/inotify_add_watch.2 +++ b/man2/inotify_add_watch.2 @@ -6,7 +6,7 @@ .\" 2005-07-19 Robert Love - initial version .\" 2006-02-07 mtk, various changes .\" -.TH inotify_add_watch 2 2023-03-30 "Linux man-pages 6.05.01" +.TH inotify_add_watch 2 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify_add_watch \- add a watch to an initialized inotify instance .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int inotify_add_watch(int " fd ", const char *" pathname ", uint32_t " mask ); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ See .BR inotify (7) for a description of the bits that can be set in .IR mask . -.PP +.P A successful call to .BR inotify_add_watch () returns a unique watch descriptor for this inotify instance, @@ -49,7 +49,7 @@ then the watch descriptor is newly allocated. If the filesystem object was already being watched (perhaps via a different link to the same object), then the descriptor for the existing watch is returned. -.PP +.P The watch descriptor is returned by later .BR read (2)s from the inotify file descriptor. diff --git a/man2/inotify_init.2 b/man2/inotify_init.2 index e6be9c3..16694cf 100644 --- a/man2/inotify_init.2 +++ b/man2/inotify_init.2 @@ -7,7 +7,7 @@ .\" 2006-02-07 mtk, minor changes .\" 2008-10-10 mtk: add description of inotify_init1() .\" -.TH inotify_init 2 2023-03-30 "Linux man-pages 6.05.01" +.TH inotify_init 2 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify_init, inotify_init1 \- initialize an inotify instance .SH LIBRARY @@ -16,18 +16,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "int inotify_init(void);" .BI "int inotify_init1(int " flags ); .fi .SH DESCRIPTION For an overview of the inotify API, see .BR inotify (7). -.PP +.P .BR inotify_init () initializes a new inotify instance and returns a file descriptor associated with a new inotify event queue. -.PP +.P If .I flags is 0, then diff --git a/man2/inotify_rm_watch.2 b/man2/inotify_rm_watch.2 index 8e1b283..9fb5238 100644 --- a/man2/inotify_rm_watch.2 +++ b/man2/inotify_rm_watch.2 @@ -5,7 +5,7 @@ .\" 2005-07-19 Robert Love - initial version .\" 2006-02-07 mtk, minor changes .\" -.TH inotify_rm_watch 2 2023-03-30 "Linux man-pages 6.05.01" +.TH inotify_rm_watch 2 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify_rm_watch \- remove an existing watch from an inotify instance .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int inotify_rm_watch(int " fd ", int " wd ); .\" Before glibc 2.10, the second argument was types as uint32_t. .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040 @@ -25,7 +25,7 @@ removes the watch associated with the watch descriptor .I wd from the inotify instance associated with the file descriptor .IR fd . -.PP +.P Removing a watch causes an .B IN_IGNORED event to be generated for this watch descriptor. diff --git a/man2/intro.2 b/man2/intro.2 index ef3d8cf..74af07c 100644 --- a/man2/intro.2 +++ b/man2/intro.2 @@ -6,7 +6,7 @@ .\" new _syscall(2) page, and substantially enhanced and rewrote .\" the remaining material on this page. .\" -.TH intro 2 2023-02-05 "Linux man-pages 6.05.01" +.TH intro 2 2023-10-31 "Linux man-pages 6.7" .SH NAME intro \- introduction to system calls .SH DESCRIPTION @@ -19,7 +19,7 @@ wrapper functions which perform the steps required the system call. Thus, making a system call looks the same as invoking a normal library function. -.PP +.P In many cases, the C library wrapper function does nothing more than: .IP \[bu] 3 copying arguments and the unique system call number to the @@ -32,7 +32,7 @@ setting .I errno if the system call returns an error number when the kernel returns the CPU to user mode. -.PP +.P However, in a few cases, a wrapper function may do rather more than this, for example, performing some preprocessing of the arguments before trapping to kernel mode, @@ -42,7 +42,7 @@ try to note the details of both the (usually GNU) C library API interface and the raw system call. Most commonly, the main DESCRIPTION will focus on the C library interface, and differences for the system call are covered in the NOTES section. -.PP +.P For a list of the Linux system calls, see .BR syscalls (2). .SH RETURN VALUE @@ -54,12 +54,12 @@ system call returns a negative value, the wrapper copies the absolute value into the .I errno variable, and returns \-1 as the return value of the wrapper. -.PP +.P The value returned by a successful system call depends on the call. Many system calls return 0 on success, but some can return nonzero values from a successful call. The details are described in the individual manual pages. -.PP +.P In some cases, the programmer must define a feature test macro in order to obtain the declaration of a system call from the header file specified diff --git a/man2/io_cancel.2 b/man2/io_cancel.2 index 1b413e2..7cce965 100644 --- a/man2/io_cancel.2 +++ b/man2/io_cancel.2 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_cancel 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_cancel 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_cancel \- cancel an outstanding asynchronous I/O operation .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. @@ -17,7 +17,7 @@ see VERSIONS. .BR "#include " " /* Definition of needed types */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_io_cancel, aio_context_t " ctx_id ", struct iocb *" iocb , .BI " struct io_event *" result ); .fi @@ -30,7 +30,7 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_cancel () system call @@ -71,7 +71,7 @@ You probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_destroy.2 b/man2/io_destroy.2 index 4f513e5..b22be59 100644 --- a/man2/io_destroy.2 +++ b/man2/io_destroy.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_destroy 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_destroy 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_destroy \- destroy an asynchronous I/O context .SH LIBRARY @@ -13,10 +13,10 @@ Standard C library .BR "#include " " /* Definition of " aio_context_t " */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_io_destroy, aio_context_t " ctx_id ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR io_destroy (), @@ -31,7 +31,7 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_destroy () system call @@ -62,7 +62,7 @@ You probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_getevents.2 b/man2/io_getevents.2 index 3cf506c..05332f3 100644 --- a/man2/io_getevents.2 +++ b/man2/io_getevents.2 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_getevents 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_getevents 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_getevents \- read asynchronous I/O events from the completion queue .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. @@ -17,12 +17,12 @@ see VERSIONS. .BR "#include " " /* Definition of " *io_* " types */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_io_getevents, aio_context_t " ctx_id , .BI " long " min_nr ", long " nr ", struct io_event *" events , .BI " struct timespec *" timeout ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR io_getevents (), @@ -37,22 +37,22 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_getevents () system call attempts to read at least \fImin_nr\fP events and up to \fInr\fP events from the completion queue of the AIO context specified by \fIctx_id\fP. -.PP +.P The \fItimeout\fP argument specifies the amount of time to wait for events, and is specified as a relative timeout in a .BR timespec (3) structure. -.PP +.P The specified time will be rounded up to the system clock granularity and is guaranteed not to expire early. -.PP +.P Specifying .I timeout as NULL means block indefinitely until at least @@ -70,7 +70,7 @@ expired. It may also be a nonzero value less than .IR min_nr , if the call was interrupted by a signal handler. -.PP +.P For the failure return, see VERSIONS. .SH ERRORS .TP @@ -95,7 +95,7 @@ You probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_setup.2 b/man2/io_setup.2 index 0745456..8fba0ba 100644 --- a/man2/io_setup.2 +++ b/man2/io_setup.2 @@ -2,23 +2,23 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_setup 2 2023-03-30 "Linux man-pages 6.05.01" +.TH io_setup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_setup \- create an asynchronous I/O context .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. .SH SYNOPSIS .nf .BR "#include " " /* Defines needed types */" -.PP +.P .BI "long io_setup(unsigned int " nr_events ", aio_context_t *" ctx_idp ); .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see VERSIONS. .SH DESCRIPTION @@ -30,7 +30,7 @@ uses a different type for the .I ctx_idp argument. See VERSIONS. -.PP +.P The .BR io_setup () system call @@ -79,7 +79,7 @@ But instead, you probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/io_submit.2 b/man2/io_submit.2 index 51efb6b..215701e 100644 --- a/man2/io_submit.2 +++ b/man2/io_submit.2 @@ -3,24 +3,24 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH io_submit 2 2023-05-03 "Linux man-pages 6.05.01" +.TH io_submit 2 2023-10-31 "Linux man-pages 6.7" .SH NAME io_submit \- submit asynchronous I/O blocks for processing .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Asynchronous I/O library .RI ( libaio ", " \-laio ); see VERSIONS. .SH SYNOPSIS .nf .BR "#include " " /* Defines needed types */" -.PP +.P .BI "int io_submit(aio_context_t " ctx_id ", long " nr \ ", struct iocb **" iocbpp ); .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see VERSIONS. .SH DESCRIPTION @@ -32,7 +32,7 @@ uses a different type for the .I ctx_id argument. See VERSIONS. -.PP +.P The .BR io_submit () system call @@ -42,13 +42,13 @@ The .I iocbpp argument should be an array of \fInr\fP AIO control blocks, which will be submitted to context \fIctx_id\fP. -.PP +.P The .I iocb (I/O control block) structure defined in .I linux/aio_abi.h defines the parameters that control the I/O operation. -.PP +.P .in +4n .EX #include @@ -68,7 +68,7 @@ struct iocb { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I aio_data @@ -254,7 +254,7 @@ But instead, you probably want to use the wrapper function provided by .\" http://git.fedorahosted.org/git/?p=libaio.git .IR libaio . -.PP +.P Note that the .I libaio wrapper function uses a different type diff --git a/man2/ioctl.2 b/man2/ioctl.2 index d6c0701..518712b 100644 --- a/man2/ioctl.2 +++ b/man2/ioctl.2 @@ -10,7 +10,7 @@ .\" Modified 1999-06-25 by Rachael Munns .\" Modified 2000-09-21 by Andries Brouwer .\" -.TH ioctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl \- control device .SH LIBRARY @@ -19,10 +19,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int ioctl(int " fd ", unsigned long " request ", ...);" -.\" POSIX says 'request' is int, but glibc has the above -.\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705 +.P +.BI "int ioctl(int " fd ", unsigned long " op ", ...);" "\f[R] /* glibc, BSD */\f[]" +.BI "int ioctl(int " fd ", int " op ", ...);" "\f[R] /* musl, other UNIX */\f[]" .fi .SH DESCRIPTION The @@ -31,22 +30,22 @@ system call manipulates the underlying device parameters of special files. In particular, many operating characteristics of character special files (e.g., terminals) may be controlled with .BR ioctl () -requests. +operations. The argument .I fd must be an open file descriptor. -.PP -The second argument is a device-dependent request code. +.P +The second argument is a device-dependent operation code. The third argument is an untyped pointer to memory. It's traditionally .BI "char *" argp (from the days before .B "void *" was valid C), and will be so named for this discussion. -.PP +.P An .BR ioctl () -.I request +.I op has encoded in it whether the argument is an .I in parameter or @@ -56,7 +55,7 @@ parameter, and the size of the argument in bytes. Macros and defines used in specifying an .BR ioctl () -.I request +.I op are located in the file .IR . See NOTES. @@ -64,7 +63,7 @@ See NOTES. Usually, on success zero is returned. A few .BR ioctl () -requests use the return value as an output parameter +operations use the return value as an output parameter and return a nonnegative value on success. On error, \-1 is returned, and .I errno @@ -80,7 +79,7 @@ is not a valid file descriptor. references an inaccessible memory area. .TP .B EINVAL -.I request +.I op or .I argp is not valid. @@ -90,7 +89,7 @@ is not valid. is not associated with a character special device. .TP .B ENOTTY -The specified request does not apply to the kind of object that the +The specified operation does not apply to the kind of object that the file descriptor .I fd references. @@ -103,7 +102,52 @@ model). .SH STANDARDS None. .SH HISTORY -Version\~7 AT&T UNIX. +Version\~7 AT&T UNIX has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " fildes ", int " op ", struct sgttyb *" argp ); +.fi +.in +.P +.PD +(where +.B struct sgttyb +has historically been used by +.BR stty (2) +and +.BR gtty (2), +and is polymorphic by operation type (like a +.B void * +would be, if it had been available)). +.P +SysIII documents +.I arg +without a type at all. +.P +4.3BSD has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " d ", unsigned long " op ", char *" argp ); +.fi +.in +.P +.PD +(with +.B char * +similarly in for +.BR "void *" ). +.P +SysVr4 has +.PD 0 +.in +4n +.nf +.BI "int ioctl(int " fildes ", int " op ", ... /* " arg " */);" +.fi +.in +.P +.PD .SH NOTES In order to use this call, one needs an open file descriptor. Often the @@ -115,10 +159,12 @@ flag. .\" .SS ioctl structure .\" added two sections - aeb -Ioctl command values are 32-bit constants. +Ioctl +.I op +values are 32-bit constants. In principle these constants are completely arbitrary, but people have tried to build some structure into them. -.PP +.P The old Linux situation was that of mostly 16-bit constants, where the last byte is a serial number, and the preceding byte(s) give a type indicating the driver. @@ -137,7 +183,7 @@ has value .B CYGETTIMEOUT has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq] indicating the cyclades driver. -.PP +.P Later (0.98p5) some more information was built into the number. One has 2 direction bits (00: none, 01: write, 10: read, 11: read/write) @@ -145,7 +191,7 @@ followed by 14 size bits (giving the size of the argument), followed by an 8-bit type (collecting the ioctls in groups for a common purpose or a common driver), and an 8-bit serial number. -.PP +.P The macros describing this structure live in .I and are @@ -156,12 +202,12 @@ They use .I sizeof(size) so that size is a misnomer here: this third argument is a data type. -.PP +.P Note that the size bits are very unreliable: in lots of cases they are wrong, either because of buggy macros using .IR sizeof(sizeof(struct)) , or because of legacy values. -.PP +.P Thus, it seems that the new structure only gave disadvantages: it does not help in checking, but it causes varying values for the various architectures. diff --git a/man2/ioctl_console.2 b/man2/ioctl_console.2 index 455be75..f06725f 100644 --- a/man2/ioctl_console.2 +++ b/man2/ioctl_console.2 @@ -19,14 +19,14 @@ .\" VT_UNLOCKSWITCH (since Linux 1.3.47, needs CAP_SYS_TTY_CONFIG) .\" VT_GETHIFONTMASK (since Linux 2.6.18) .\" -.TH ioctl_console 2 2023-01-22 "Linux man-pages 6.05.01" +.TH ioctl_console 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_console \- ioctls for console terminal and virtual consoles .SH DESCRIPTION The following Linux-specific .BR ioctl (2) -requests are supported for console terminals and virtual consoles. -Each requires a third argument, assumed here to be +operations are supported for console terminals and virtual consoles. +Each operation requires a third argument, assumed here to be .IR argp . .TP .B KDGETLED @@ -53,7 +53,7 @@ unsigned long integer in However, if a higher order bit is set, the LEDs revert to normal: displaying the state of the keyboard functions of caps lock, num lock, and scroll lock. -.PP +.P Before Linux 1.1.54, the LEDs just reflected the state of the corresponding keyboard flags, and KDGETLED/KDSETLED would also change the keyboard flags. @@ -546,7 +546,7 @@ points to a struct vt_mode { char mode; /* vt mode */ char waitv; /* if set, hang on writes if not active */ - short relsig; /* signal to raise on release req */ + short relsig; /* signal to raise on release op */ short acqsig; /* signal to raise on acquisition */ short frsig; /* unused (set to 0) */ }; @@ -657,7 +657,7 @@ Note that this does not change the videomode. See .BR resizecons (8). (Since Linux 1.3.3.) -.PP +.P The action of the following ioctls depends on the first byte in the struct pointed to by .IR argp , @@ -715,12 +715,20 @@ is 0 for character-by-character selection, or 2 for line-by-line selection. The indicated screen characters are highlighted and saved in a kernel buffer. +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. .TP .BR TIOCLINUX ", " subcode = TIOCL_PASTESEL Paste selection. The characters in the selection buffer are written to .IR fd . +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. .TP .BR TIOCLINUX ", " subcode = TIOCL_UNBLANKSCREEN Unblank the screen. @@ -729,6 +737,10 @@ Unblank the screen. Sets contents of a 256-bit look up table defining characters in a "word", for word-by-word selection. (Since Linux 1.1.32.) +.IP +Since Linux 6.7, using this subcode requires the +.B CAP_SYS_ADMIN +capability. .TP .BR TIOCLINUX ", " subcode = TIOCL_GETSHIFTSTATE .I argp @@ -849,7 +861,7 @@ is invalid. .TP .B ENOTTY The file descriptor is not associated with a character special device, -or the specified request does not apply to it. +or the specified operation does not apply to it. .TP .B EPERM Insufficient permission. @@ -864,16 +876,16 @@ without warning. situation as of kernel version 1.1.94; there are many minor and not-so-minor differences with earlier versions.) -.PP +.P Very often, ioctls are introduced for communication between the kernel and one particular well-known program (fdisk, hdparm, setserial, tunelp, loadkeys, selection, setfont, etc.), and their behavior will be changed when required by this particular program. -.PP +.P Programs using these ioctls will not be portable to other versions of UNIX, will not work on older versions of Linux, and will not work on future versions of Linux. -.PP +.P Use POSIX functions. .SH SEE ALSO .BR dumpkeys (1), @@ -898,6 +910,6 @@ Use POSIX functions. .BR mapscrn (8), .BR resizecons (8), .BR setfont (8) -.PP +.P .IR /usr/include/linux/kd.h , .I /usr/include/linux/vt.h diff --git a/man2/ioctl_fat.2 b/man2/ioctl_fat.2 index 67b5a2c..a690cf1 100644 --- a/man2/ioctl_fat.2 +++ b/man2/ioctl_fat.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2014, Heinrich Schuchardt .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH ioctl_fat 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_fat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_fat \- manipulating the FAT filesystem .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .BR "#include " " /* Definition of [" V ] FAT_* " and" .BR " ATTR_* " constants */" .B #include -.PP +.P .BI "int ioctl(int " fd ", FAT_IOCTL_GET_ATTRIBUTES, uint32_t *" attr ); .BI "int ioctl(int " fd ", FAT_IOCTL_SET_ATTRIBUTES, uint32_t *" attr ); .BI "int ioctl(int " fd ", FAT_IOCTL_GET_VOLUME_ID, uint32_t *" id ); @@ -32,7 +32,7 @@ can be read with .B FAT_IOCTL_GET_ATTRIBUTES and written with .BR FAT_IOCTL_SET_ATTRIBUTES . -.PP +.P The .I fd argument contains a file descriptor for a file or directory. @@ -41,7 +41,7 @@ It is sufficient to create the file descriptor by calling with the .B O_RDONLY flag. -.PP +.P The .I attr argument contains a pointer to a bit mask. @@ -68,7 +68,7 @@ This attribute is read-only. This bit indicates that this file or directory should be archived. It is set when a file is created or modified. It is reset by an archiving system. -.PP +.P The zero value .B ATTR_NONE can be used to indicate that no attribute bit is set. @@ -76,7 +76,7 @@ can be used to indicate that no attribute bit is set. FAT filesystems are identified by a volume ID. The volume ID can be read with .BR FAT_IOCTL_GET_VOLUME_ID . -.PP +.P The .I fd argument can be a file descriptor for any file or directory of the @@ -86,13 +86,13 @@ It is sufficient to create the file descriptor by calling with the .B O_RDONLY flag. -.PP +.P The .I id argument is a pointer to the field that will be filled with the volume ID. Typically the volume ID is displayed to the user as a group of two 16-bit fields: -.PP +.P .in +4n .EX printf("Volume ID %04x\-%04x\en", id >> 16, id & 0xFFFF); @@ -104,12 +104,12 @@ consisting of up to 8 capital letters, optionally followed by a period and up to 3 capital letters for the file extension. If the actual filename does not fit into this scheme, it is stored as a long filename of up to 255 UTF-16 characters. -.PP +.P The short filenames in a directory can be read with .BR VFAT_IOCTL_READDIR_SHORT . .B VFAT_IOCTL_READDIR_BOTH reads both the short and the long filenames. -.PP +.P The .I fd argument must be a file descriptor for a directory. @@ -122,11 +122,11 @@ The file descriptor can be used only once to iterate over the directory entries by calling .BR ioctl (2) repeatedly. -.PP +.P The .I entry argument is a two-element array of the following structures: -.PP +.P .in +4n .EX struct __fat_dirent { @@ -137,10 +137,10 @@ struct __fat_dirent { }; .EE .in -.PP +.P The first entry in the array is for the short filename. The second entry is for the long filename. -.PP +.P The .I d_ino and @@ -154,7 +154,7 @@ The field holds the offset of the file entry in the directory. As these values are not available for short filenames, the user code should simply ignore them. -.PP +.P The field .I d_reclen contains the length of the filename in the field @@ -174,7 +174,7 @@ is a character string of length 0 for the long filename. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P For .B VFAT_IOCTL_READDIR_BOTH and @@ -205,7 +205,7 @@ does not refer to a directory. The file descriptor .I fd does not refer to an object in a FAT filesystem. -.PP +.P For further error values, see .BR ioctl (2). .SH STANDARDS @@ -234,10 +234,10 @@ to manipulate file attributes. The program reads and displays the archive attribute of a file. After inverting the value of the attribute, the program reads and displays the attribute again. -.PP +.P The following was recorded when applying the program for the file .IR /mnt/user/foo : -.PP +.P .in +4n .EX # ./toggle_fat_archive_flag /mnt/user/foo @@ -335,11 +335,11 @@ main(int argc, char *argv[]) The following program demonstrates the use of .BR ioctl (2) to display the volume ID of a FAT filesystem. -.PP +.P The following output was recorded when applying the program for directory .IR /mnt/user : -.PP +.P .in +4n .EX $ ./display_fat_volume_id /mnt/user @@ -400,10 +400,10 @@ main(int argc, char *argv[]) The following program demonstrates the use of .BR ioctl (2) to list a directory. -.PP +.P The following was recorded when applying the program to the directory .IR /mnt/user : -.PP +.P .in +4n .EX $ \fB./fat_dir /mnt/user\fP diff --git a/man2/ioctl_ficlonerange.2 b/man2/ioctl_ficlonerange.2 index 68cfc67..b2c5e6b 100644 --- a/man2/ioctl_ficlonerange.2 +++ b/man2/ioctl_ficlonerange.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2016, Oracle. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_ficlonerange 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl_ficlonerange 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_ficlonerange, ioctl_ficlone \- share some the data of one file with another file @@ -12,7 +12,7 @@ Standard C library .nf .BR "#include " " /* Definition of " FICLONE* " constants */" .B #include -.PP +.P .BI "int ioctl(int " dest_fd ", FICLONERANGE, struct file_clone_range *" arg ); .BI "int ioctl(int " dest_fd ", FICLONE, int " src_fd ); .fi @@ -31,7 +31,7 @@ If a file write should occur to a shared region, the filesystem must ensure that the changes remain private to the file being written. This behavior is commonly referred to as "copy on write". -.PP +.P This ioctl reflinks up to .I src_length bytes from file descriptor @@ -48,7 +48,7 @@ If is zero, the ioctl reflinks to the end of the source file. This information is conveyed in a structure of the following form: -.PP +.P .in +4n .EX struct file_clone_range { @@ -59,10 +59,10 @@ struct file_clone_range { }; .EE .in -.PP +.P Clones are atomic with regards to concurrent writes, so no locks need to be taken to obtain a consistent cloned copy. -.PP +.P The .B FICLONE ioctl clones entire files. @@ -114,7 +114,7 @@ are not on the same mounted filesystem. Linux. .SH HISTORY Linux 4.5. -.PP +.P They were previously known as .B BTRFS_IOC_CLONE and diff --git a/man2/ioctl_fideduperange.2 b/man2/ioctl_fideduperange.2 index 5388c5d..84fd2e8 100644 --- a/man2/ioctl_fideduperange.2 +++ b/man2/ioctl_fideduperange.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2016, Oracle. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_fideduperange 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl_fideduperange 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_fideduperange \- share some the data of one file with another file .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .BR "#include " " /* Definition of " FIDEDUPERANGE " and" .BR " FILE_DEDUPE_* " constants */ .B #include -.PP +.P .BI "int ioctl(int " src_fd ", FIDEDUPERANGE, struct file_dedupe_range *" arg ); .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ If a file write should occur to a shared region, the filesystem must ensure that the changes remain private to the file being written. This behavior is commonly referred to as "copy on write". -.PP +.P This ioctl performs the "compare and share if identical" operation on up to .I src_length bytes from file descriptor @@ -40,7 +40,7 @@ bytes from file descriptor at offset .IR src_offset . This information is conveyed in a structure of the following form: -.PP +.P .in +4n .EX struct file_dedupe_range { @@ -53,20 +53,20 @@ struct file_dedupe_range { }; .EE .in -.PP +.P Deduplication is atomic with regards to concurrent writes, so no locks need to be taken to obtain a consistent deduplicated copy. -.PP +.P The fields .IR reserved1 " and " reserved2 must be zero. -.PP +.P Destinations for the deduplication operation are conveyed in the array at the end of the structure. The number of destinations is given in .IR dest_count , and the destination information is conveyed in the following form: -.PP +.P .in +4n .EX struct file_dedupe_range_info { @@ -78,7 +78,7 @@ struct file_dedupe_range_info { }; .EE .in -.PP +.P Each deduplication operation targets .I src_length bytes in file descriptor @@ -109,14 +109,14 @@ is mapped into and the previous contents in .I dest_fd are freed. -.PP +.P Upon successful completion of this ioctl, the number of bytes successfully deduplicated is returned in .I bytes_deduped and a status code for the deduplication operation is returned in .IR status . If even a single byte in the range does not match, the deduplication -request will be ignored and +operation request will be ignored and .I status set to .BR FILE_DEDUPE_RANGE_DIFFERS . @@ -187,7 +187,7 @@ single call. Linux. .SH HISTORY Linux 4.5. -.PP +.P It was previously known as .B BTRFS_IOC_FILE_EXTENT_SAME and was private to Btrfs. diff --git a/man2/ioctl_fslabel.2 b/man2/ioctl_fslabel.2 index 885a43c..7fcde80 100644 --- a/man2/ioctl_fslabel.2 +++ b/man2/ioctl_fslabel.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2018, Red Hat, Inc. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_fslabel 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioctl_fslabel 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_fslabel \- get or set a filesystem label .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .nf .BR "#include " " /* Definition of " *FSLABEL* " constants */" .B #include -.PP +.P .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]); .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]); .fi @@ -50,7 +50,7 @@ The calling process does not have sufficient permissions to set the label. Linux. .SH HISTORY Linux 4.18. -.PP +.P They were previously known as .B BTRFS_IOC_GET_FSLABEL and diff --git a/man2/ioctl_getfsmap.2 b/man2/ioctl_getfsmap.2 index e80c1d9..97fbc67 100644 --- a/man2/ioctl_getfsmap.2 +++ b/man2/ioctl_getfsmap.2 @@ -1,7 +1,7 @@ .\" Copyright (c) 2017, Oracle. All rights reserved. .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH ioctl_getfsmap 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_getfsmap 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_getfsmap \- retrieve the physical layout of the filesystem .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .BR "#include " "/* Definition of " FS_IOC_GETFSMAP , .BR " FM?_OF_*" ", and " *FMR_OWN_* " constants */" .B #include -.PP +.P .BI "int ioctl(int " fd ", FS_IOC_GETFSMAP, struct fsmap_head * " arg ); .fi .SH DESCRIPTION @@ -21,10 +21,10 @@ This operation retrieves physical extent mappings for a filesystem. This information can be used to discover which files are mapped to a physical block, examine free space, or find known bad blocks, among other things. -.PP +.P The sole argument to this operation should be a pointer to a single .IR "struct fsmap_head" ":" -.PP +.P .in +4n .EX struct fsmap { @@ -50,7 +50,7 @@ struct fsmap_head { }; .EE .in -.PP +.P The two .I fmh_keys array elements specify the lowest and highest reverse-mapping @@ -60,7 +60,7 @@ A reverse mapping key consists of the tuple (device, block, owner, offset). The owner and offset fields are part of the key because some filesystems support sharing physical blocks between multiple files and therefore may return multiple mappings for a given physical block. -.PP +.P Filesystem mappings are copied into the .I fmh_recs array, which immediately follows the header data. @@ -70,7 +70,7 @@ The .I fmh_iflags field is a bit mask passed to the kernel to alter the output. No flags are currently defined, so the caller must set this value to zero. -.PP +.P The .I fmh_oflags field is a bit mask of flags set by the kernel concerning the returned mappings. @@ -81,7 +81,7 @@ is set, then the field represents a .I dev_t structure containing the major and minor numbers of the block device. -.PP +.P The .I fmh_count field contains the number of elements in the array being passed to the @@ -91,13 +91,13 @@ If this value is 0, will be set to the number of records that would have been returned had the array been large enough; no mapping information will be returned. -.PP +.P The .I fmh_entries field contains the number of elements in the .I fmh_recs array that contain useful information. -.PP +.P The .I fmh_reserved fields must be set to zero. @@ -124,8 +124,8 @@ By convention, the field .I fsmap_head.fmh_keys[0] must contain the low key and .I fsmap_head.fmh_keys[1] -must contain the high key for the request. -.PP +must contain the high key for the operation. +.P For convenience, if .I fmr_length is set in the low key, it will be added to @@ -154,11 +154,11 @@ field, this field contains a from which major and minor numbers can be extracted. If the flag is not set, this field contains a value that must be unique for each unique storage device. -.PP +.P The .I fmr_physical field contains the disk address of the extent in bytes. -.PP +.P The .I fmr_owner field contains the owner of the extent. @@ -168,7 +168,7 @@ is set in the .I fmr_flags field, in which case the value is determined by the filesystem. See the section below about owner values for more details. -.PP +.P The .I fmr_offset field contains the logical address in the mapping record in bytes. @@ -176,11 +176,11 @@ This field has no meaning if the .BR FMR_OF_SPECIAL_OWNER " or " FMR_OF_EXTENT_MAP flags are set in .IR fmr_flags "." -.PP +.P The .I fmr_length field contains the length of the extent in bytes. -.PP +.P The .I fmr_flags field is a bit mask of extent state flags. @@ -207,7 +207,7 @@ field contains a special value instead of an inode number. .B FMR_OF_LAST This is the last record in the data set. .RE -.PP +.P The .I fmr_reserved field will be set to zero. @@ -239,7 +239,7 @@ This extent is in use but its owner is not known or not easily retrieved. .B FMR_OWN_METADATA This extent is filesystem metadata. .RE -.PP +.P XFS can return the following special owner values: .RS 0.4i .TP @@ -276,7 +276,7 @@ This extent is being used to stage a copy-on-write. This extent has been marked defective either by the filesystem or the underlying device. .RE -.PP +.P ext4 can return the following special owner values: .RS 0.4i .TP @@ -328,16 +328,16 @@ physical storage address space than the high key, or a nonzero value was passed in one of the fields that must be zero. .TP .B ENOMEM -Insufficient memory to process the request. +Insufficient memory to process the operation. .TP .B EOPNOTSUPP -The filesystem does not support this command. +The filesystem does not support this operation. .TP .B EUCLEAN The filesystem metadata is corrupt and needs repair. .SH STANDARDS Linux. -.PP +.P Not all filesystems support it. .SH HISTORY Linux 4.12. diff --git a/man2/ioctl_iflags.2 b/man2/ioctl_iflags.2 index d2c3300..e6cc7cb 100644 --- a/man2/ioctl_iflags.2 +++ b/man2/ioctl_iflags.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ioctl_iflags 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_iflags 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_iflags \- ioctl() operations for inode flags .SH DESCRIPTION @@ -13,7 +13,7 @@ that modify the semantics of files and directories. These flags can be retrieved and modified using two .BR ioctl (2) operations: -.PP +.P .in +4n .EX int attr; @@ -26,14 +26,14 @@ ioctl(fd, FS_IOC_SETFLAGS, &attr); /* Update flags for inode referred to by \[aq]fd\[aq] */ .EE .in -.PP +.P The .BR lsattr (1) and .BR chattr (1) shell commands provide interfaces to these two operations, allowing a user to view and modify the inode flags associated with a file. -.PP +.P The following flags are supported (shown along with the corresponding letter used to indicate the flag by .BR lsattr (1) @@ -160,7 +160,7 @@ has an effect only for ext2, ext3, and ext4. Allow the file to be undeleted if it is deleted. This feature is not implemented by any filesystem, since it is possible to implement file-recovery mechanisms outside the kernel. -.PP +.P In most cases, when any of the above flags is set on a directory, the flag is inherited by files and subdirectories @@ -180,7 +180,7 @@ the effective user ID of the caller must match the owner of the file, or the caller must have the .B CAP_FOWNER capability. -.PP +.P The type of the argument given to the .B FS_IOC_GETFLAGS and diff --git a/man2/ioctl_ns.2 b/man2/ioctl_ns.2 index a11e54b..a21c14a 100644 --- a/man2/ioctl_ns.2 +++ b/man2/ioctl_ns.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ioctl_ns 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_ns 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_ns \- ioctl() operations for Linux namespaces .SH DESCRIPTION @@ -17,13 +17,13 @@ operations are provided to allow discovery of namespace relationships (see and .BR pid_namespaces (7)). The form of the calls is: -.PP +.P .in +4n .EX -new_fd = ioctl(fd, request); +new_fd = ioctl(fd, op); .EE .in -.PP +.P In each case, .I fd refers to a @@ -49,7 +49,7 @@ For user namespaces, .B NS_GET_PARENT is synonymous with .BR NS_GET_USERNS . -.PP +.P The new file descriptor returned by these operations is opened with the .B O_RDONLY and @@ -57,7 +57,7 @@ and (close-on-exec; see .BR fcntl (2)) flags. -.PP +.P By applying .BR fstat (2) to the returned file descriptor, one obtains a @@ -70,7 +70,7 @@ structure whose This inode number can be matched with the inode number of another .IR /proc/ pid /ns/ { pid , user } file to determine whether that is the owning/parent namespace. -.PP +.P Either of these .BR ioctl (2) operations can fail with the following errors: @@ -84,7 +84,7 @@ user or PID namespace. .TP .B ENOTTY The operation is not supported by this kernel version. -.PP +.P Additionally, the .B NS_GET_PARENT operation can fail with the following error: @@ -92,7 +92,7 @@ operation can fail with the following error: .B EINVAL .I fd refers to a nonhierarchical namespace. -.PP +.P See the EXAMPLES section for an example of the use of these operations. .\" ============================================================ .\" @@ -103,18 +103,18 @@ The operation (available since Linux 4.11) can be used to discover the type of namespace referred to by the file descriptor .IR fd : -.PP +.P .in +4n .EX nstype = ioctl(fd, NS_GET_NSTYPE); .EE .in -.PP +.P .I fd refers to a .IR /proc/ pid /ns/* file. -.PP +.P The return value is one of the .B CLONE_NEW* values that can be specified to @@ -132,23 +132,23 @@ operation (available since Linux 4.11) can be used to discover the owner user ID of a user namespace (i.e., the effective user ID of the process that created the user namespace). The form of the call is: -.PP +.P .in +4n .EX uid_t uid; ioctl(fd, NS_GET_OWNER_UID, &uid); .EE .in -.PP +.P .I fd refers to a .IR /proc/ pid /ns/user file. -.PP +.P The owner user ID is returned in the .I uid_t pointed to by the third argument. -.PP +.P This operation can fail with the following error: .TP .B EINVAL @@ -173,22 +173,22 @@ operations described above to perform simple discovery of namespace relationships. The following shell sessions show various examples of the use of this program. -.PP +.P Trying to get the parent of the initial user namespace fails, since it has no parent: -.PP +.P .in +4n .EX $ \fB./ns_show /proc/self/ns/user p\fP The parent namespace is outside your namespace scope .EE .in -.PP +.P Create a process running .BR sleep (1) that resides in new user and UTS namespaces, and show that the new UTS namespace is associated with the new user namespace: -.PP +.P .in +4n .EX $ \fBunshare \-Uu sleep 1000 &\fP @@ -199,10 +199,10 @@ $ \fBreadlink /proc/23235/ns/user\fP user:[4026532448] .EE .in -.PP +.P Then show that the parent of the new user namespace in the preceding example is the initial user namespace: -.PP +.P .in +4n .EX $ \fBreadlink /proc/self/ns/user\fP @@ -211,13 +211,13 @@ $ \fB./ns_show /proc/23235/ns/user p\fP Device/Inode of parent namespace is: [0,3] / 4026531837 .EE .in -.PP +.P Start a shell in a new user namespace, and show that from within this shell, the parent user namespace can't be discovered. Similarly, the UTS namespace (which is associated with the initial user namespace) can't be discovered. -.PP +.P .in +4n .EX $ \fBPS1="sh2$ " unshare \-U bash\fP diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2 new file mode 100644 index 0000000..fcd9bdc --- /dev/null +++ b/man2/ioctl_pagemap_scan.2 @@ -0,0 +1,206 @@ +.\" This manpage is Copyright (C) 2023 Collabora; +.\" Written by Muhammad Usama Anjum +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH ioctl_pagemap_scan 2 2024-01-28 "Linux man-pages 6.7" +.SH NAME +ioctl_pagemap_scan \- get and/or clear page flags +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " "struct pm_scan_arg" , +.BR " struct page_region" ", and " PAGE_IS_* " constants */" +.B #include +.P +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg ); +.fi +.SH DESCRIPTION +This +.BR ioctl (2) +is used to get and optionally clear some specific flags from page table entries. +The information is returned with +.B PAGE_SIZE +granularity. +.P +To start tracking the written state (flag) of a page or range of memory, +the +.B UFFD_FEATURE_WP_ASYNC +must be enabled by +.B UFFDIO_API +.BR ioctl (2) +on +.B userfaultfd +and memory range must be registered with +.B UFFDIO_REGISTER +.BR ioctl (2) +in +.B UFFDIO_REGISTER_MODE_WP +mode. +.SS Supported page flags +The following page table entry flags are supported: +.TP +.B PAGE_IS_WPALLOWED +The page has asynchronous write-protection enabled. +.TP +.B PAGE_IS_WRITTEN +The page has been written to from the time it was write protected. +.TP +.B PAGE_IS_FILE +The page is file backed. +.TP +.B PAGE_IS_PRESENT +The page is present in the memory. +.TP +.B PAGE_IS_SWAPPED +The page is swapped. +.TP +.B PAGE_IS_PFNZERO +The page has zero PFN. +.TP +.B PAGE_IS_HUGE +The page is THP or Hugetlb backed. +.SS Supported operations +The get operation is always performed +if the output buffer is specified. +The other operations are as following: +.TP +.B PM_SCAN_WP_MATCHING +Write protect the matched pages. +.TP +.B PM_SCAN_CHECK_WPASYNC +Abort the scan +when a page is found +which doesn't have the Userfaultfd Asynchronous Write protection enabled. +.SS The \f[I]struct pm_scan_arg\f[] argument +.EX +struct pm_scan_arg { + __u64 size; + __u64 flags; + __u64 start; + __u64 end; + __u64 walk_end; + __u64 vec; + __u64 vec_len; + __u64 max_pages + __u64 category_inverted; + __u64 category_mask; + __u64 category_anyof_mask + __u64 return_mask; +}; +.EE +.TP +.B size +This field should be set to the size of the structure in bytes, +as in +.IR sizeof(struct\~pm_scan_arg) . +.TP +.B flags +The operations to be performed are specified in it. +.TP +.B start +The starting address of the scan is specified in it. +.TP +.B end +The ending address of the scan is specified in it. +.TP +.B walk_end +The kernel returns the scan's ending address in it. +The +.I walk_end +equal to +.I end +means that scan has completed on the entire range. +.TP +.B vec +The address of +.I page_region +array for output. +.IP +.in +4n +.EX +struct page_region { + __u64 start; + __u64 end; + __u64 categories; +}; +.EE +.in +.TP +.B vec_len +The length of the +.I page_region +struct array. +.TP +.B max_pages +It is the optional limit for the number of output pages required. +.TP +.B category_inverted +.BI PAGE_IS_ * +categories which values match if 0 instead of 1. +.TP +.B category_mask +Skip pages for which any +.BI PAGE_IS_ * +category doesn't match. +.TP +.B category_anyof_mask +Skip pages for which no +.BI PAGE_IS_ * +category matches. +.TP +.B return_mask +.BI PAGE_IS_ * +categories that are to be reported in +.IR page_region . +.SH RETURN VALUE +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +Error codes can be one of, but are not limited to, the following: +.TP +.B EINVAL +Invalid arguments i.e., +invalid +.I size +of the argument, +invalid +.IR flags , +invalid +.IR categories , +the +.I start +address isn't aligned with +.BR PAGE_SIZE , +or +.I vec_len +is specified when +.I vec +is NULL. +.TP +.B EFAULT +Invalid +.I arg +pointer, +invalid +.I vec +pointer, +or invalid address range specified by +.I start +and +.IR end . +.TP +.B ENOMEM +No memory is available. +.TP +.B EINTR +Fetal signal is pending. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 6.7. +.SH SEE ALSO +.BR ioctl (2) diff --git a/man2/ioctl_pipe.2 b/man2/ioctl_pipe.2 index 31e02bb..d08efa1 100644 --- a/man2/ioctl_pipe.2 +++ b/man2/ioctl_pipe.2 @@ -2,14 +2,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH ioctl_pipe 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_pipe 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioctl_pipe \- ioctl() operations for General notification mechanism .SH SYNOPSIS .nf .BR "#include " " /* Definition of " IOC_WATCH_QUEUE_ "* */" .B #include -.PP +.P .BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_SIZE, int " size ); .BI "int ioctl(int " pipefd "[1], IOC_WATCH_QUEUE_SET_FILTER," .BI " struct watch_notification_filter *" filter ); diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 index dfbd9a8..9d247ed 100644 --- a/man2/ioctl_tty.2 +++ b/man2/ioctl_tty.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ioctl_tty 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_tty 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_tty \- ioctls for terminals and serial lines .SH LIBRARY @@ -17,25 +17,25 @@ Standard C library .BR " struct termios2" ", and" .BR " Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL , .BR " TC*" { FLUSH , ON , OFF "} and other constants */" -.PP -.BI "int ioctl(int " fd ", int " cmd ", ...);" +.P +.BI "int ioctl(int " fd ", int " op ", ...);" .fi .SH DESCRIPTION The .BR ioctl (2) -call for terminals and serial ports accepts many possible command arguments. +call for terminals and serial ports accepts many possible operation arguments. Most require a third argument, of varying type, here called .I argp or .IR arg . -.PP +.P Use of .BR ioctl () makes for nonportable programs. Use the POSIX interface described in .BR termios (3) whenever possible. -.PP +.P Please note that .B struct termios from @@ -87,7 +87,7 @@ Equivalent to .IP Allow the output buffer to drain, discard pending input, and set the current serial port settings. -.PP +.P The following four ioctls, added in Linux 2.6.20, .\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6 .\" commit 592ee3a5e5e2a981ef2829a0380093006d045661 @@ -119,7 +119,7 @@ TCSETSW2 \fBconst struct termios2 *\fPargp TCSETSF2 \fBconst struct termios2 *\fPargp .TE .RE -.PP +.P The following four ioctls are just like .BR TCGETS , .BR TCSETS , @@ -182,9 +182,9 @@ Argument: .BI "const struct winsize\~*" argp .IP Set window size. -.PP +.P The struct used by these ioctls is defined as -.PP +.P .in +4n .EX struct winsize { @@ -195,7 +195,7 @@ struct winsize { }; .EE .in -.PP +.P When the window size changes, a .B SIGWINCH signal is sent to the @@ -334,6 +334,15 @@ Argument: .BI "const char\~*" argp .IP Insert the given byte in the input queue. +.IP +Since Linux 6.2, +.\" commit 690c8b804ad2eafbd35da5d3c95ad325ca7d5061 +.\" commit 83efeeeb3d04b22aaed1df99bc70a48fe9d22c4d +this operation may require the +.B CAP_SYS_ADMIN +capability (if the +.I dev.tty.legacy_tiocsti +sysctl variable is set to false). .SS Redirecting console output .TP .B TIOCCONS @@ -594,7 +603,7 @@ and similar library functions that have insecure APIs. .BR ptsname (3) with a pathname where a devpts filesystem has been mounted in a different mount namespace.) -.PP +.P The BSD ioctls .BR TIOCSTOP , .BR TIOCSTART , @@ -627,9 +636,9 @@ Argument: .BI "const int\~*" argp .IP Set the indicated modem bits. -.PP +.P The following bits are used by the above ioctls: -.PP +.P .TS lb l. TIOCM_LE DSR (data set ready/line enable) @@ -695,7 +704,7 @@ Set the CLOCAL flag in the structure when .RI * argp is nonzero, and clear it otherwise. -.PP +.P If the .B CLOCAL flag for a line is off, the hardware carrier detect (DCD) @@ -726,7 +735,7 @@ Get the .I tty_struct corresponding to .IR fd . -This command was removed in Linux 2.5.67. +This operation was removed in Linux 2.5.67. .\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864 .\" Author: Andries E. Brouwer .\" Date: Tue Apr 1 04:42:46 2003 -0800 @@ -738,7 +747,7 @@ This command was removed in Linux 2.5.67. .\" .\" .SS Serial info .\" .BR "#include " -.\" .PP +.\" .P .\" .TP .\" .BI "TIOCGSERIAL struct serial_struct *" argp .\" Get serial info. @@ -755,10 +764,10 @@ to indicate the error. .SH ERRORS .TP .B EINVAL -Invalid command parameter. +Invalid operation parameter. .TP .B ENOIOCTLCMD -Unknown command. +Unknown operation. .TP .B ENOTTY Inappropriate @@ -768,7 +777,7 @@ Inappropriate Insufficient permission. .SH EXAMPLES Check the condition of DTR on the serial port. -.PP +.P .\" SRC BEGIN (tiocmget.c) .EX #include @@ -791,9 +800,9 @@ main(void) } .EE .\" SRC END -.PP +.P Get or set arbitrary baudrate on the serial port. -.PP +.P .\" SRC BEGIN (tcgets.c) .EX /* SPDX-License-Identifier: GPL-2.0-or-later */ diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index 6ab9c11..08e52e6 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ioctl_userfaultfd 2 2023-05-03 "Linux man-pages 6.05.01" +.TH ioctl_userfaultfd 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ioctl_userfaultfd \- create a file descriptor for handling page faults in user space @@ -16,8 +16,8 @@ Standard C library .nf .BR "#include " " /* Definition of " UFFD* " constants */" .B #include -.PP -.BI "int ioctl(int " fd ", int " cmd ", ...);" +.P +.BI "int ioctl(int " fd ", int " op ", ...);" .fi .SH DESCRIPTION Various @@ -25,21 +25,22 @@ Various operations can be performed on a userfaultfd object (created by a call to .BR userfaultfd (2)) using calls of the form: -.PP +.P .in +4n .EX -ioctl(fd, cmd, argp); +ioctl(fd, op, argp); .EE .in +.P In the above, .I fd is a file descriptor referring to a userfaultfd object, -.I cmd -is one of the commands listed below, and +.I op +is one of the operations listed below, and .I argp is a pointer to a data structure that is specific to -.IR cmd . -.PP +.IR op . +.P The various .BR ioctl (2) operations are described below. @@ -62,13 +63,13 @@ events. .SS UFFDIO_API (Since Linux 4.3.) Enable operation of the userfaultfd and perform API handshake. -.PP +.P The .I argp argument is a pointer to a .I uffdio_api structure, defined as: -.PP +.P .in +4n .EX struct uffdio_api { @@ -78,11 +79,10 @@ struct uffdio_api { }; .EE .in -.PP +.P The .I api field denotes the API version requested by the application. -.PP The kernel verifies that it can support the requested API version, and sets the .I features @@ -91,7 +91,26 @@ and fields to bit masks representing all the available features and the generic .BR ioctl (2) operations available. -.PP +.P +Since Linux 4.11, +applications should use the +.I features +field to perform a two-step handshake. +First, +.B UFFDIO_API +is called with the +.I features +field set to zero. +The kernel responds by setting all supported feature bits. +.P +Applications which do not require any specific features +can begin using the userfaultfd immediately. +Applications which do need specific features +should call +.B UFFDIO_API +again with a subset of the reported feature bits set +to enable those features. +.P Before Linux 4.11, the .I features field must be initialized to zero before the call to @@ -100,26 +119,13 @@ and zero (i.e., no feature bits) is placed in the .I features field by the kernel upon return from .BR ioctl (2). -.PP -Starting from Linux 4.11, the -.I features -field can be used to ask whether particular features are supported -and explicitly enable userfaultfd features that are disabled by default. -The kernel always reports all the available features in the -.I features -field. -.PP -To enable userfaultfd features the application should set -a bit corresponding to each feature it wants to enable in the -.I features -field. -If the kernel supports all the requested features it will enable them. -Otherwise it will zero out the returned +.P +If the application sets unsupported feature bits, +the kernel will zero out the returned .I uffdio_api structure and return .BR EINVAL . -.\" FIXME add more details about feature negotiation and enablement -.PP +.P The following feature bits may be set: .TP .BR UFFD_FEATURE_EVENT_FORK " (since Linux 4.11)" @@ -198,6 +204,13 @@ If this feature bit is set, .I uffd_msg.pagefault.feat.ptid will be set to the faulted thread ID for each page-fault message. .TP +.BR UFFD_FEATURE_PAGEFAULT_FLAG_WP " (since Linux 5.10)" +If this feature bit is set, +userfaultfd supports write-protect faults +for anonymous memory. +(Note that shmem / hugetlbfs support +is indicated by a separate feature.) +.TP .BR UFFD_FEATURE_MINOR_HUGETLBFS " (since Linux 5.13)" If this feature bit is set, the kernel supports registering userfaultfd ranges @@ -215,7 +228,28 @@ will be set to the exact page-fault address that was reported by the hardware, and will not mask the offset within the page. Note that old Linux versions might indicate the exact address as well, even though the feature bit is not set. -.PP +.TP +.BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM " (since Linux 5.19)" +If this feature bit is set, +userfaultfd supports write-protect faults +for hugetlbfs and shmem / tmpfs memory. +.TP +.BR UFFD_FEATURE_WP_UNPOPULATED " (since Linux 6.4)" +If this feature bit is set, +the kernel will handle anonymous memory the same way as file memory, +by allowing the user to write-protect unpopulated page table entries. +.TP +.BR UFFD_FEATURE_POISON " (since Linux 6.6)" +If this feature bit is set, +the kernel supports resolving faults with the +.B UFFDIO_POISON +ioctl. +.TP +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)" +If this feature bit is set, +the write protection faults would be asynchronously resolved +by the kernel. +.P The returned .I ioctls field can contain the following bits: @@ -236,13 +270,21 @@ operation is supported. The .B UFFDIO_UNREGISTER operation is supported. -.PP +.P This .BR ioctl (2) operation returns 0 on success. On error, \-1 is returned and .I errno is set to indicate the error. +If an error occurs, +the kernel may zero the provided +.I uffdio_api +structure. +The caller should treat its contents as unspecified, +and reinitialize it before re-attempting another +.B UFFDIO_API +call. Possible errors include: .TP .B EFAULT @@ -251,38 +293,44 @@ refers to an address that is outside the calling process's accessible address space. .TP .B EINVAL -The userfaultfd has already been enabled by a previous -.B UFFDIO_API -operation. -.TP -.B EINVAL The API version requested in the .I api field is not supported by this kernel, or the .I features field passed to the kernel includes feature bits that are not supported by the current kernel version. -.\" FIXME In the above error case, the returned 'uffdio_api' structure is -.\" zeroed out. Why is this done? This should be explained in the manual page. -.\" -.\" Mike Rapoport: -.\" In my understanding the uffdio_api -.\" structure is zeroed to allow the caller -.\" to distinguish the reasons for -EINVAL. -.\" +.TP +.B EINVAL +A previous +.B UFFDIO_API +call already enabled one or more features for this userfaultfd. +Calling +.B UFFDIO_API +twice, +the first time with no features set, +is explicitly allowed +as per the two-step feature detection handshake. +.TP +.B EPERM +The +.B UFFD_FEATURE_EVENT_FORK +feature was enabled, +but the calling process doesn't have the +.B CAP_SYS_PTRACE +capability. .SS UFFDIO_REGISTER (Since Linux 4.3.) Register a memory address range with the userfaultfd object. -The pages in the range must be "compatible". +The pages in the range must be \[lq]compatible\[rq]. Please refer to the list of register modes below for the compatible memory backends for each mode. -.PP +.P The .I argp argument is a pointer to a .I uffdio_register structure, defined as: -.PP +.P .in +4n .EX struct uffdio_range { @@ -297,7 +345,7 @@ struct uffdio_register { }; .EE .in -.PP +.P The .I range field defines a memory range starting at @@ -305,7 +353,7 @@ field defines a memory range starting at and continuing for .I len bytes that should be handled by the userfaultfd. -.PP +.P The .I mode field defines the mode of operation desired for this memory region. @@ -330,7 +378,7 @@ Since Linux 5.13, only hugetlbfs ranges are compatible. Since Linux 5.14, compatibility with shmem ranges was added. -.PP +.P If the operation is successful, the kernel modifies the .I ioctls bit-mask field to indicate which @@ -351,6 +399,7 @@ operation is supported. .B 1 << _UFFDIO_WRITEPROTECT The .B UFFDIO_WRITEPROTECT +operation is supported. .TP .B 1 << _UFFDIO_ZEROPAGE The @@ -361,7 +410,12 @@ operation is supported. The .B UFFDIO_CONTINUE operation is supported. -.PP +.TP +.B 1 << _UFFDIO_POISON +The +.B UFFDIO_POISON +operation is supported. +.P This .BR ioctl (2) operation returns 0 on success. @@ -407,14 +461,15 @@ There as an incompatible mapping in the specified address range. .SS UFFDIO_UNREGISTER (Since Linux 4.3.) Unregister a memory address range from userfaultfd. -The pages in the range must be "compatible" (see the description of -.BR UFFDIO_REGISTER .) -.PP +The pages in the range must be \[lq]compatible\[rq] +(see the description of +.BR UFFDIO_REGISTER .) +.P The address range to unregister is specified in the .I uffdio_range structure pointed to by .IR argp . -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -446,12 +501,15 @@ Atomically copy a continuous memory chunk into the userfault registered range and optionally wake up the blocked thread. The source and destination addresses and the number of bytes to copy are specified by the -.IR src ", " dst ", and " len +.IR src , +.IR dst , +and +.I len fields of the .I uffdio_copy structure pointed to by .IR argp : -.PP +.P .in +4n .EX struct uffdio_copy { @@ -463,7 +521,7 @@ struct uffdio_copy { }; .EE .in -.PP +.P The following value may be bitwise ORed in .I mode to change the behavior of the @@ -482,7 +540,7 @@ This is used only when both and .B UFFDIO_REGISTER_MODE_WP modes are enabled for the registered range. -.PP +.P The .I copy field is used by the kernel to return the number of bytes @@ -503,7 +561,7 @@ field is output-only; it is not read by the .B UFFDIO_COPY operation. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -560,14 +618,14 @@ operation. .SS UFFDIO_ZEROPAGE (Since Linux 4.3.) Zero out a memory range registered with userfaultfd. -.PP +.P The requested range is specified by the .I range field of the .I uffdio_zeropage structure pointed to by .IR argp : -.PP +.P .in +4n .EX struct uffdio_zeropage { @@ -577,7 +635,7 @@ struct uffdio_zeropage { }; .EE .in -.PP +.P The following value may be bitwise ORed in .I mode to change the behavior of the @@ -586,7 +644,7 @@ operation: .TP .B UFFDIO_ZEROPAGE_MODE_DONTWAKE Do not wake up the thread that waits for page-fault resolution. -.PP +.P The .I zeropage field is used by the kernel to return the number of bytes @@ -607,7 +665,7 @@ field is output-only; it is not read by the .B UFFDIO_ZEROPAGE operation. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -648,7 +706,7 @@ operation. (Since Linux 4.3.) Wake up the thread waiting for page-fault resolution on a specified memory address range. -.PP +.P The .B UFFDIO_WAKE operation is used in conjunction with @@ -668,13 +726,13 @@ and .B UFFDIO_ZEROPAGE operations in a batch and then explicitly wake up the faulting thread using .BR UFFDIO_WAKE . -.PP +.P The .I argp argument is a pointer to a .I uffdio_range structure (shown above) that specifies the address range. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -693,17 +751,18 @@ field of the structure was not a multiple of the system page size; or .I len was zero; or the specified range was otherwise invalid. -.SS UFFDIO_WRITEPROTECT (Since Linux 5.7) +.SS UFFDIO_WRITEPROTECT +(Since Linux 5.7.) Write-protect or write-unprotect a userfaultfd-registered memory range registered with mode .BR UFFDIO_REGISTER_MODE_WP . -.PP +.P The .I argp argument is a pointer to a .I uffdio_range structure as shown below: -.PP +.P .in +4n .EX struct uffdio_writeprotect { @@ -712,7 +771,7 @@ struct uffdio_writeprotect { }; .EE .in -.PP +.P There are two mode bits that are supported in this structure: .TP .B UFFDIO_WRITEPROTECT_MODE_WP @@ -729,7 +788,7 @@ page-fault resolution after the operation. This can be specified only if .B UFFDIO_WRITEPROTECT_MODE_WP is not specified. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -767,13 +826,13 @@ Encountered a generic fault during processing. Resolve a minor page fault by installing page table entries for existing pages in the page cache. -.PP +.P The .I argp argument is a pointer to a .I uffdio_continue structure as shown below: -.PP +.P .in +4n .EX struct uffdio_continue { @@ -784,7 +843,7 @@ struct uffdio_continue { }; .EE .in -.PP +.P The following value may be bitwise ORed in .I mode to change the behavior of the @@ -793,7 +852,7 @@ operation: .TP .B UFFDIO_CONTINUE_MODE_DONTWAKE Do not wake up the thread that waits for page-fault resolution. -.PP +.P The .I mapped field is used by the kernel @@ -812,7 +871,7 @@ field is output-only; it is not read by the .B UFFDIO_CONTINUE operation. -.PP +.P This .BR ioctl (2) operation returns 0 on success. @@ -832,6 +891,12 @@ does not equal the value that was specified in the .I range.len field. .TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B EFAULT +No existing page could be found in the page cache for the given range. +.TP .B EINVAL Either .I range.start @@ -846,9 +911,6 @@ An invalid bit was specified in the .I mode field. .TP -.B EEXIST -One or more pages were already mapped in the given range. -.TP .B ENOENT The faulting process has changed its virtual memory layout simultaneously with an outstanding @@ -858,14 +920,118 @@ operation. .B ENOMEM Allocating memory needed to setup the page table mappings failed. .TP -.B EFAULT -No existing page could be found in the page cache for the given range. -.TP .B ESRCH The faulting process has exited at the time of a .B UFFDIO_CONTINUE operation. .\" +.SS UFFDIO_POISON +(Since Linux 6.6.) +Mark an address range as "poisoned". +Future accesses to these addresses will raise a +.B SIGBUS +signal. +Unlike +.B MADV_HWPOISON +this works by installing page table entries, +rather than "really" poisoning the underlying physical pages. +This means it only affects this particular address space. +.P +The +.I argp +argument is a pointer to a +.I uffdio_poison +structure as shown below: +.P +.in +4n +.EX +struct uffdio_poison { + struct uffdio_range range; + /* Range to install poison PTE markers in */ + __u64 mode; /* Flags controlling the behavior of poison */ + __s64 updated; /* Number of bytes poisoned, or negated error */ +}; +.EE +.in +.P +The following value may be bitwise ORed in +.I mode +to change the behavior of the +.B UFFDIO_POISON +operation: +.TP +.B UFFDIO_POISON_MODE_DONTWAKE +Do not wake up the thread that waits for page-fault resolution. +.P +The +.I updated +field is used by the kernel +to return the number of bytes that were actually poisoned, +or an error in the same manner as +.BR UFFDIO_COPY . +If the value returned in the +.I updated +field doesn't match the value that was specified in +.IR range.len , +the operation fails with the error +.BR EAGAIN . +The +.I updated +field is output-only; +it is not read by the +.B UFFDIO_POISON +operation. +.P +This +.BR ioctl (2) +operation returns 0 on success. +In this case, +the entire area was poisoned. +On error, \-1 is returned and +.I errno +is set to indicate the error. +Possible errors include: +.TP +.B EAGAIN +The number of bytes mapped +(i.e., the value returned in the +.I updated +field) +does not equal the value that was specified in the +.I range.len +field. +.TP +.B EINVAL +Either +.I range.start +or +.I range.len +was not a multiple of the system page size; or +.I range.len +was zero; or the range specified was invalid. +.TP +.B EINVAL +An invalid bit was specified in the +.I mode +field. +.TP +.B EEXIST +One or more pages were already mapped in the given range. +.TP +.B ENOENT +The faulting process has changed its virtual memory layout simultaneously with +an outstanding +.B UFFDIO_POISON +operation. +.TP +.B ENOMEM +Allocating memory for page table entries failed. +.TP +.B ESRCH +The faulting process has exited at the time of a +.B UFFDIO_POISON +operation. +.\" .SH RETURN VALUE See descriptions of the individual operations, above. .SH ERRORS @@ -901,6 +1067,6 @@ See .BR ioctl (2), .BR mmap (2), .BR userfaultfd (2) -.PP +.P .I Documentation/admin\-guide/mm/userfaultfd.rst in the Linux kernel source tree diff --git a/man2/ioperm.2 b/man2/ioperm.2 index dcbad6c..dd62ce5 100644 --- a/man2/ioperm.2 +++ b/man2/ioperm.2 @@ -12,7 +12,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH ioperm 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ioperm 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioperm \- set port input/output permissions .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int ioperm(unsigned long " from ", unsigned long " num ", int " turn_on ); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ If .I turn_on is nonzero, the calling thread must be privileged .RB ( CAP_SYS_RAWIO ). -.PP +.P Before Linux 2.6.8, only the first 0x3ff I/O ports could be specified in this manner. For more ports, the @@ -47,7 +47,7 @@ system call had to be used (with a .I level argument of 3). Since Linux 2.6.8, 65,536 I/O ports can be specified. -.PP +.P Permissions are inherited by the child created by .BR fork (2) (but see NOTES). @@ -55,7 +55,7 @@ Permissions are preserved across .BR execve (2); this is useful for giving port access permissions to unprivileged programs. -.PP +.P This call is mostly for the i386 architecture. On many other architectures it does not exist or will always return an error. diff --git a/man2/iopl.2 b/man2/iopl.2 index 239d206..b2211e2 100644 --- a/man2/iopl.2 +++ b/man2/iopl.2 @@ -10,7 +10,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH iopl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH iopl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME iopl \- change I/O privilege level .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int iopl(int " level ); .fi .SH DESCRIPTION @@ -27,10 +27,10 @@ Standard C library changes the I/O privilege level of the calling thread, as specified by the two least significant bits in .IR level . -.PP +.P The I/O privilege level for a normal thread is 0. Permissions are inherited from parents to children. -.PP +.P This call is deprecated, is significantly slower than .BR ioperm (2), and is only provided for older X servers which require @@ -76,7 +76,7 @@ Prior to Linux 5.5 allowed the thread to disable interrupts while running at a higher I/O privilege level. This will probably crash the system, and is not recommended. -.PP +.P Prior to Linux 3.7, on some architectures (such as i386), permissions .I were diff --git a/man2/ioprio_set.2 b/man2/ioprio_set.2 index 7770cbc..629d2df 100644 --- a/man2/ioprio_set.2 +++ b/man2/ioprio_set.2 @@ -7,7 +7,7 @@ .\" with various additions by Michael Kerrisk .\" .\" -.TH ioprio_set 2 2023-04-03 "Linux man-pages 6.05.01" +.TH ioprio_set 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ioprio_get, ioprio_set \- get/set I/O scheduling class and priority .SH LIBRARY @@ -18,11 +18,11 @@ Standard C library .BR "#include " "/* Definition of " IOPRIO_* " constants */" .BR "#include " "/* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_ioprio_get, int " which ", int " who ); .BI "int syscall(SYS_ioprio_set, int " which ", int " who ", int " ioprio ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -34,7 +34,7 @@ and .BR ioprio_set () system calls get and set the I/O scheduling class and priority of one or more threads. -.PP +.P The .I which and @@ -67,7 +67,7 @@ is a user ID identifying all of the processes that have a matching real UID. .\" FIXME . Need to document the behavior when 'who" is specified as 0 .\" See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=652443 -.PP +.P If .I which is specified as @@ -90,7 +90,7 @@ is the lowest) or if it belongs to the same priority class as the other process but has a higher priority level (a lower priority number means a higher priority level). -.PP +.P The .I ioprio argument given to @@ -130,13 +130,13 @@ Given value), this macro returns its priority .RI ( data ) component. -.PP +.P See the NOTES section for more information on scheduling classes and priorities, as well as the meaning of specifying .I ioprio as 0. -.PP +.P I/O priorities are supported for reads and for synchronous .RB ( O_DIRECT , .BR O_SYNC ) @@ -157,7 +157,7 @@ and On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR ioprio_set () returns 0. @@ -211,12 +211,12 @@ is the one that is returned by .BR gettid (2) or .BR clone (2). -.PP +.P These system calls have an effect only when used in conjunction with an I/O scheduler that supports I/O priorities. As at kernel 2.6.17 the only such scheduler is the Completely Fair Queuing (CFQ) I/O scheduler. -.PP +.P If no I/O scheduler has been set for a thread, then by default the I/O priority will follow the CPU nice value .RB ( setpriority (2)). @@ -233,20 +233,20 @@ as 0 can be used to reset to the default I/O scheduling behavior. I/O schedulers are selected on a per-device basis via the special file .IR /sys/block/ device /queue/scheduler . -.PP +.P One can view the current I/O scheduler via the .I /sys filesystem. For example, the following command displays a list of all schedulers currently loaded in the kernel: -.PP +.P .in +4n .EX .RB "$" " cat /sys/block/sda/queue/scheduler" noop anticipatory deadline [cfq] .EE .in -.PP +.P The scheduler surrounded by brackets is the one actually in use for the device .RI ( sda @@ -258,7 +258,7 @@ scheduler for the .I sda device to .IR cfq : -.PP +.P .in +4n .EX .RB "$" " su" @@ -310,7 +310,7 @@ The idle class has no class data. Attention is required when assigning this priority class to a process, since it may become starved if higher priority processes are constantly accessing the disk. -.PP +.P Refer to the kernel source file .I Documentation/block/ioprio.txt for more information on the CFQ I/O Scheduler and an example program. @@ -337,7 +337,7 @@ Up to Linux 2.6.24 also required to set a very low priority .RB ( IOPRIO_CLASS_IDLE ), but since Linux 2.6.25, this is no longer required. -.PP +.P A call to .BR ioprio_set () must follow both rules, or the call will fail with the error @@ -357,6 +357,6 @@ Suitable definitions can be found in .BR open (2), .BR capabilities (7), .BR cgroups (7) -.PP +.P .I Documentation/block/ioprio.txt in the Linux kernel source tree diff --git a/man2/ipc.2 b/man2/ipc.2 index 0b8a911..e1b6c20 100644 --- a/man2/ipc.2 +++ b/man2/ipc.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond -.TH ipc 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ipc 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ipc \- System V IPC system calls .SH LIBRARY @@ -14,13 +14,13 @@ Standard C library .BR "#include " " /* Definition of needed constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_ipc, unsigned int " call ", int " first , .BI " unsigned long " second ", unsigned long " third \ ", void *" ptr , .BI " long " fifth ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR ipc (), @@ -33,7 +33,7 @@ for messages, semaphores, and shared memory. .I call determines which IPC function to invoke; the other arguments are passed through to the appropriate call. -.PP +.P User-space programs should call the appropriate functions by their usual names. Only standard library implementors and kernel hackers need to know about .BR ipc (). diff --git a/man2/kcmp.2 b/man2/kcmp.2 index 98a29f1..cfd65df 100644 --- a/man2/kcmp.2 +++ b/man2/kcmp.2 @@ -5,7 +5,7 @@ .\" .\" Kernel commit d97b46a64674a267bc41c9e16132ee2a98c3347d .\" -.TH kcmp 2 2023-05-03 "Linux man-pages 6.05.01" +.TH kcmp 2 2023-10-31 "Linux man-pages 6.7" .SH NAME kcmp \- compare two processes to determine if they share a kernel resource .SH LIBRARY @@ -16,11 +16,11 @@ Standard C library .BR "#include " " /* Definition of " KCMP_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_kcmp, pid_t " pid1 ", pid_t " pid2 ", int " type , .BI " unsigned long " idx1 ", unsigned long " idx2 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR kcmp (), @@ -35,7 +35,7 @@ and .I pid2 share a kernel resource such as virtual memory, file descriptors, and so on. -.PP +.P Permission to employ .BR kcmp () is governed by ptrace access mode @@ -46,7 +46,7 @@ and .IR pid2 ; see .BR ptrace (2). -.PP +.P The .I type argument specifies which resource is to be compared in the two processes. @@ -161,7 +161,7 @@ The argument .I idx2 is a pointer to a structure where the target file is described. This structure has the form: -.PP +.P .in +4n .EX struct kcmp_epoll_slot { @@ -171,7 +171,7 @@ struct kcmp_epoll_slot { }; .EE .in -.PP +.P Within this structure, .I efd is an epoll file descriptor returned from @@ -183,7 +183,7 @@ is a target file offset counted from zero. Several different targets may be registered with the same file descriptor number and setting a specific offset helps to investigate each of them. -.PP +.P Note the .BR kcmp () is not protected against false positives which may occur if @@ -199,7 +199,7 @@ The return value of a successful call to is simply the result of arithmetic comparison of kernel pointers (when the kernel compares resources, it uses their memory addresses). -.PP +.P The easiest way to explain is to consider an example. Suppose that .I v1 @@ -231,11 +231,11 @@ is not equal to .IR v2 , but ordering information is unavailable. .RE -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .BR kcmp () was designed to return values suitable for sorting. This is particularly handy if one needs to compare @@ -291,7 +291,7 @@ does not exist. Linux. .SH HISTORY Linux 3.5. -.PP +.P Before Linux 5.12, this system call is available only if the kernel is configured with .BR CONFIG_CHECKPOINT_RESTORE , @@ -317,7 +317,7 @@ the same open file description. The program tests different cases for the file descriptor pairs, as described in the program output. An example run of the program is as follows: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man2/kexec_load.2 b/man2/kexec_load.2 index 604fa1c..499f6ca 100644 --- a/man2/kexec_load.2 +++ b/man2/kexec_load.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH kexec_load 2 2023-03-30 "Linux man-pages 6.05.01" +.TH kexec_load 2 2023-10-31 "Linux man-pages 6.7" .SH NAME kexec_load, kexec_file_load \- load a new kernel for later execution .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .BR "#include " " /* Definition of " KEXEC_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_kexec_load, unsigned long " entry , .BI " unsigned long " nr_segments \ ", struct kexec_segment *" segments , @@ -24,7 +24,7 @@ Standard C library .BI " unsigned long " cmdline_len ", const char *" cmdline , .BI " unsigned long " flags ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -34,7 +34,7 @@ The .BR kexec_load () system call loads a new kernel that can be executed later by .BR reboot (2). -.PP +.P The .I flags argument is a bit mask that controls the operation of the call. @@ -66,7 +66,7 @@ This flag is available only if the kernel was configured with and is effective only if .I nr_segments is greater than 0. -.PP +.P The high-order bits (corresponding to the mask 0xffff0000) of .I flags contain the architecture of the to-be-executed kernel. @@ -87,7 +87,7 @@ or one of the following architecture constants and .BR KEXEC_ARCH_MIPS_LE . The architecture must be executable on the CPU of the system. -.PP +.P The .I entry argument is the physical entry address in the kernel image. @@ -102,7 +102,7 @@ The argument is an array of .I kexec_segment structures which define the kernel layout: -.PP +.P .in +4n .EX struct kexec_segment { @@ -113,7 +113,7 @@ struct kexec_segment { }; .EE .in -.PP +.P The kernel image defined by .I segments is copied from the calling process into @@ -154,7 +154,7 @@ If is less than .IR memsz , then the excess bytes in the kernel buffer are zeroed out. -.PP +.P In case of a normal kexec (i.e., the .B KEXEC_ON_CRASH flag is not set), the segment data is loaded in any available memory @@ -163,13 +163,13 @@ and is moved to the final destination at kexec reboot time (e.g., when the command is executed with the .I \-e option). -.PP +.P In case of kexec on panic (i.e., the .B KEXEC_ON_CRASH flag is set), the segment data is loaded to reserved memory at the time of the call, and, after a crash, the kexec mechanism simply passes control to that kernel. -.PP +.P The .BR kexec_load () system call is available only if the kernel was configured with @@ -194,7 +194,7 @@ The .I cmdline_len argument specifies size of the buffer. The last byte in the buffer must be a null byte (\[aq]\e0\[aq]). -.PP +.P The .I flags argument is a bit mask which modifies the behavior of the call. @@ -216,7 +216,7 @@ Specify this flag if no initramfs is being loaded. If this flag is set, the value passed in .I initrd_fd is ignored. -.PP +.P The .BR kexec_file_load () .\" See also http://lwn.net/Articles/603116/ @@ -324,7 +324,7 @@ Linux 3.17. .BR reboot (2), .BR syscall (2), .BR kexec (8) -.PP +.P The kernel source files .I Documentation/kdump/kdump.txt and diff --git a/man2/keyctl.2 b/man2/keyctl.2 index d7bd83d..8f8ec19 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -5,13 +5,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH keyctl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH keyctl 2 2024-02-25 "Linux man-pages 6.7" .SH NAME keyctl \- manipulate the kernel's key management facility .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) -.PP +.P Alternatively, Linux Key Management Utilities .RI ( libkeyutils ", " \-lkeyutils ); see VERSIONS. @@ -20,12 +20,12 @@ see VERSIONS. .BR "#include " " /* Definition of " KEY* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 , .BI " unsigned long " arg3 ", unsigned long " arg4 , .BI " unsigned long " arg5 ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR keyctl (), @@ -34,7 +34,7 @@ necessitating the use of .SH DESCRIPTION .BR keyctl () allows user-space programs to perform key manipulation. -.PP +.P The operation performed by .BR keyctl () is determined by the value of the @@ -46,7 +46,7 @@ library (provided by the .I keyutils package) into individual functions (noted below) to permit the compiler to check types. -.PP +.P The permitted values for .I operation are: @@ -847,7 +847,7 @@ the size of that buffer is specified in (cast to .IR size_t ). .IP -The payload may be a NULL pointer and the buffer size may be 0 +The payload may be a null pointer and the buffer size may be 0 if this is supported by the key type (e.g., it is a keyring). .IP The operation may be fail if the payload data is in the wrong format @@ -1415,7 +1415,7 @@ The .I arg2 argument is a pointer to a set of parameters containing serial numbers for three -.I """user""" +.I \[dq]user\[dq] keys used in the Diffie-Hellman calculation, packaged in a structure of the following form: .IP @@ -1653,7 +1653,7 @@ is 0, the required buffer size. .TP All other operations Zero. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -1897,7 +1897,7 @@ was .B KEYCTL_READ and the key type does not support reading (e.g., the type is -.IR """login""" ). +.IR \[dq]login\[dq] ). .TP .B EOPNOTSUPP .I operation @@ -1968,7 +1968,7 @@ program provided by the package. For informational purposes, the program records various information in a log file. -.PP +.P As described in .BR request_key (2), the @@ -1978,7 +1978,7 @@ describe a key that is to be instantiated. The example program fetches and logs these arguments. The program assumes authority to instantiate the requested key, and then instantiates that key. -.PP +.P The following shell session demonstrates the use of this program. In the session, we compile the program and then use it to temporarily replace the standard @@ -1991,7 +1991,7 @@ While our example program is installed, we use the example program shown in .BR request_key (2) to request a key. -.PP +.P .in +4n .EX $ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP @@ -2002,10 +2002,10 @@ Key ID is 20d035bf $ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP .EE .in -.PP +.P Looking at the log file created by this program, we can see the command-line arguments supplied to our example program: -.PP +.P .in +4n .EX $ \fBcat /tmp/key_instantiate.log\fP @@ -2027,7 +2027,7 @@ Destination keyring: 256e6a6 Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf .EE .in -.PP +.P The last few lines of the above output show that the example program was able to fetch: .IP \[bu] 3 @@ -2048,7 +2048,7 @@ the description of the authorization key, where we can see that the name of the authorization key matches the ID of the key that is to be instantiated .RI ( 20d035bf ). -.PP +.P The example program in .BR request_key (2) specified the destination keyring as @@ -2062,7 +2062,7 @@ we can also see the newly created key with the name .I mykey and ID .IR 20d035bf . -.PP +.P .in +4n .EX $ \fBcat /proc/keys | egrep \[aq]mykey|256e6a6\[aq]\fP @@ -2290,7 +2290,7 @@ main(int argc, char *argv[]) .BR user_namespaces (7), .BR user\-session\-keyring (7), .BR request\-key (8) -.PP +.P The kernel source files under .I Documentation/security/keys/ (or, before Linux 4.13, in the file diff --git a/man2/kill.2 b/man2/kill.2 index d0a2e6f..1260ee0 100644 --- a/man2/kill.2 +++ b/man2/kill.2 @@ -21,7 +21,7 @@ .\" Modified 2004-06-24 by aeb .\" Modified, 2004-11-30, after idea from emmanuel.colbus@ensimag.imag.fr .\" -.TH kill 2 2023-03-30 "Linux man-pages 6.05.01" +.TH kill 2 2023-10-31 "Linux man-pages 6.7" .SH NAME kill \- send signal to a process .SH LIBRARY @@ -30,15 +30,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int kill(pid_t " pid ", int " sig ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR kill (): .nf _POSIX_C_SOURCE @@ -48,25 +48,25 @@ The .BR kill () system call can be used to send any signal to any process group or process. -.PP +.P If \fIpid\fP is positive, then signal \fIsig\fP is sent to the process with the ID specified by \fIpid\fP. -.PP +.P If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the process group of the calling process. -.PP +.P If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process for which the calling process has permission to send signals, except for process 1 (\fIinit\fP), but see below. -.PP +.P If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process in the process group whose ID is \fI\-pid\fP. -.PP +.P If \fIsig\fP is 0, then no signal is sent, but existence and permission checks are still performed; this can be used to check for the existence of a process ID or process group ID that the caller is permitted to signal. -.PP +.P For a process to have permission to send a signal, it must either be privileged (under Linux: have the .B CAP_KILL @@ -125,13 +125,13 @@ process, are those for which has explicitly installed signal handlers. This is done to assure the system is not brought down accidentally. -.PP +.P POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP to all processes that the calling process may send signals to, except possibly for some implementation-defined system processes. Linux allows a process to signal itself, but on Linux the call \fIkill(\-1,sig)\fP does not signal the calling process. -.PP +.P POSIX.1 requires that if a process sends a signal to itself, and the sending thread does not have the signal blocked, and no other thread diff --git a/man2/landlock_add_rule.2 b/man2/landlock_add_rule.2 index 28d5417..2858fa3 100644 --- a/man2/landlock_add_rule.2 +++ b/man2/landlock_add_rule.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH landlock_add_rule 2 2023-07-08 "Linux man-pages 6.05.01" +.TH landlock_add_rule 2 2023-10-31 "Linux man-pages 6.7" .SH NAME landlock_add_rule \- add a new Landlock rule to a ruleset .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#include " " /* Definition of " LANDLOCK_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" -.PP +.P .BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd , .BI " enum landlock_rule_type " rule_type , .BI " const void *" rule_attr ", uint32_t " flags ); @@ -32,11 +32,11 @@ created with See .BR landlock (7) for a global overview. -.PP +.P .I ruleset_fd is a Landlock ruleset file descriptor obtained with .BR landlock_create_ruleset (2). -.PP +.P .I rule_type identifies the structure type pointed to by .IR rule_attr . @@ -72,7 +72,7 @@ is an opened file descriptor, preferably with the flag, which identifies the parent directory of the file hierarchy or just a file. -.PP +.P .I flags must be 0. .SH RETURN VALUE diff --git a/man2/landlock_create_ruleset.2 b/man2/landlock_create_ruleset.2 index faadb57..0c69027 100644 --- a/man2/landlock_create_ruleset.2 +++ b/man2/landlock_create_ruleset.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH landlock_create_ruleset 2 2023-03-30 "Linux man-pages 6.05.01" +.TH landlock_create_ruleset 2 2023-10-31 "Linux man-pages 6.7" .SH NAME landlock_create_ruleset \- create a new Landlock ruleset .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#include " " /* Definition of " LANDLOCK_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" -.PP +.P .B int syscall(SYS_landlock_create_ruleset, .BI " const struct landlock_ruleset_attr *" attr , .BI " size_t " size " , uint32_t " flags ); @@ -31,7 +31,7 @@ and See .BR landlock (7) for a global overview. -.PP +.P .I attr specifies the properties of the new ruleset. It points to the following structure: @@ -53,12 +53,12 @@ in .BR landlock (7)). This enables simply restricting ambient rights (e.g., global filesystem access) and is needed for compatibility reasons. -.PP +.P .I size must be specified as .I sizeof(struct landlock_ruleset_attr) for compatibility reasons. -.PP +.P .I flags must be 0 if .I attr diff --git a/man2/landlock_restrict_self.2 b/man2/landlock_restrict_self.2 index f02c3a1..c82181b 100644 --- a/man2/landlock_restrict_self.2 +++ b/man2/landlock_restrict_self.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH landlock_restrict_self 2 2023-03-30 "Linux man-pages 6.05.01" +.TH landlock_restrict_self 2 2023-10-31 "Linux man-pages 6.7" .SH NAME landlock_restrict_self \- enforce a Landlock ruleset .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#include " " /* Definition of " LANDLOCK_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" -.PP +.P .BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd , .BI " uint32_t " flags ); .SH DESCRIPTION @@ -24,7 +24,7 @@ system call enables enforcing this ruleset on the calling thread. See .BR landlock (7) for a global overview. -.PP +.P A thread can be restricted with multiple rulesets that are then composed together to form the thread's Landlock domain. This can be seen as a stack of rulesets but @@ -43,7 +43,7 @@ composed rulesets limit. Instead, developers are encouraged to build a tailored ruleset thanks to multiple calls to .BR landlock_add_rule (2). -.PP +.P In order to enforce a ruleset, either the caller must have the .B CAP_SYS_ADMIN capability in its user namespace, or the thread must already have the @@ -59,13 +59,13 @@ the thread must make the following call: .EX prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); .EE -.PP +.P .I ruleset_fd is a Landlock ruleset file descriptor obtained with .BR landlock_create_ruleset (2) and fully populated with a set of calls to .BR landlock_add_rule (2). -.PP +.P .I flags must be 0. .SH RETURN VALUE diff --git a/man2/link.2 b/man2/link.2 index 1533409..74437a0 100644 --- a/man2/link.2 +++ b/man2/link.2 @@ -9,7 +9,7 @@ .\" Modified 2004-06-23 by Michael Kerrisk .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2 .\" -.TH link 2 2023-03-30 "Linux man-pages 6.05.01" +.TH link 2 2023-10-31 "Linux man-pages 6.7" .SH NAME link, linkat \- make a new name for a file .SH LIBRARY @@ -18,21 +18,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int link(const char *" oldpath ", const char *" newpath ); -.PP +.P .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int linkat(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR linkat (): .nf Since glibc 2.10: @@ -43,13 +43,13 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION .BR link () creates a new link (also known as a hard link) to an existing file. -.PP +.P If .I newpath exists, it will .I not be overwritten. -.PP +.P This new name may be used exactly as the old one for any operation; both names refer to the same file (and so have the same permissions and ownership) and it is impossible to tell which name was the @@ -60,7 +60,7 @@ The system call operates in exactly the same way as .BR link (), except for the differences described here. -.PP +.P If the pathname given in .I oldpath is relative, then it is interpreted relative to the directory @@ -70,7 +70,7 @@ referred to by the file descriptor the calling process, as is done by .BR link () for a relative pathname). -.PP +.P If .I oldpath is relative and @@ -82,13 +82,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR link ()). -.PP +.P If .I oldpath is absolute, then .I olddirfd is ignored. -.PP +.P The interpretation of .I newpath is as for @@ -96,7 +96,7 @@ is as for except that a relative pathname is interpreted relative to the directory referred to by the file descriptor .IR newdirfd . -.PP +.P The following values can be bitwise ORed in .IR flags : .TP @@ -152,11 +152,11 @@ linkat(AT_FDCWD, "/proc/self/fd/", newdirfd, newname, AT_SYMLINK_FOLLOW); .EE .in -.PP +.P Before Linux 2.6.18, the .I flags argument was unused, and had to be specified as 0. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -260,7 +260,7 @@ are not on the same mounted filesystem. .BR link () does not work across different mounts, even if the same filesystem is mounted on both.) -.PP +.P The following additional errors can occur for .BR linkat (): .TP diff --git a/man2/listen.2 b/man2/listen.2 index 9512366..94f0b2c 100644 --- a/man2/listen.2 +++ b/man2/listen.2 @@ -14,7 +14,7 @@ .\" Modified 11 May 2001 by Sam Varshavchik .\" .\" -.TH listen 2 2023-03-30 "Linux man-pages 6.05.01" +.TH listen 2 2023-10-31 "Linux man-pages 6.7" .SH NAME listen \- listen for connections on a socket .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int listen(int " sockfd ", int " backlog ); .fi .SH DESCRIPTION @@ -33,14 +33,14 @@ marks the socket referred to by as a passive socket, that is, as a socket that will be used to accept incoming connection requests using .BR accept (2). -.PP +.P The .I sockfd argument is a file descriptor that refers to a socket of type .B SOCK_STREAM or .BR SOCK_SEQPACKET . -.PP +.P The .I backlog argument defines the maximum length @@ -114,7 +114,7 @@ connections are specified with Connections are accepted with .BR accept (2). .RE -.PP +.P The behavior of the .I backlog argument on TCP sockets changed with Linux 2.2. @@ -130,7 +130,7 @@ length and this setting is ignored. See .BR tcp (7) for more information. -.PP +.P If the .I backlog argument is greater than the value in diff --git a/man2/listxattr.2 b/man2/listxattr.2 index 58f5ce0..71a8e53 100644 --- a/man2/listxattr.2 +++ b/man2/listxattr.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH listxattr 2 2023-05-03 "Linux man-pages 6.05.01" +.TH listxattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME listxattr, llistxattr, flistxattr \- list extended attribute names .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t listxattr(const char *" path ", char *_Nullable " list \ ", size_t " size ); .BI "ssize_t llistxattr(const char *" path ", char *_Nullable " list \ @@ -30,7 +30,7 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR listxattr () retrieves the list of extended attribute names associated with the given @@ -46,14 +46,14 @@ have access may be omitted from the list. The length of the attribute name .I list is returned. -.PP +.P .BR llistxattr () is identical to .BR listxattr (), except in the case of a symbolic link, where the list of names of extended attributes associated with the link itself is retrieved, not the file that it refers to. -.PP +.P .BR flistxattr () is identical to .BR listxattr (), @@ -63,13 +63,13 @@ only the open file referred to by .BR open (2)) is interrogated in place of .IR path . -.PP +.P A single extended attribute .I name is a null-terminated string. The name includes a namespace prefix; there may be several, disjoint namespaces associated with an individual inode. -.PP +.P If .I size is specified as zero, these calls return the current size of the @@ -88,18 +88,18 @@ The of names is returned as an unordered array of null-terminated character strings (attribute names are separated by null bytes (\[aq]\e0\[aq])), like this: -.PP +.P .in +4n .EX user.name1\e0system.name1\e0user.name2\e0 .EE .in -.PP +.P Filesystems that implement POSIX ACLs using extended attributes might return a .I list like this: -.PP +.P .in +4n .EX system.posix_acl_access\e0system.posix_acl_default\e0 @@ -129,7 +129,7 @@ The of the .I list buffer is too small to hold the result. -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. @@ -160,7 +160,7 @@ and .BR getxattr (2). For the file whose pathname is provided as a command-line argument, it lists all extended file attributes and their values. -.PP +.P To keep the code simple, the program assumes that attribute keys and values are constant during the execution of the program. A production program should expect and handle changes during @@ -177,7 +177,7 @@ with a larger buffer each time it fails with the error Calls to .BR getxattr (2) could be handled similarly. -.PP +.P The following output was recorded by first creating a file, setting some extended file attributes, and then listing the attributes with the example program. diff --git a/man2/llseek.2 b/man2/llseek.2 index 64de504..3ac742f 100644 --- a/man2/llseek.2 +++ b/man2/llseek.2 @@ -6,7 +6,7 @@ .\" .\" Modified Thu Oct 31 15:16:23 1996 by Eric S. Raymond .\" -.TH _llseek 2 2023-03-30 "Linux man-pages 6.05.01" +.TH _llseek 2 2023-10-31 "Linux man-pages 6.7" .SH NAME _llseek \- reposition read/write file offset .SH LIBRARY @@ -16,12 +16,12 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS__llseek, unsigned int " fd ", unsigned long " offset_high , .BI " unsigned long " offset_low ", loff_t *" result , .BI " unsigned int " whence ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR _llseek (), @@ -32,7 +32,7 @@ Note: for information about the .BR llseek (3) library function, see .BR lseek64 (3). -.PP +.P The .BR _llseek () system call repositions the offset of the open file description associated @@ -41,7 +41,7 @@ with the file descriptor to the value .IP (offset_high << 32) | offset_low -.PP +.P This new offset is a byte offset relative to the beginning of the file, the current file offset, or the end of the file, depending on whether @@ -52,13 +52,13 @@ is or .BR SEEK_END , respectively. -.PP +.P The new file offset is returned in the argument .IR result . The type .I loff_t is a 64-bit signed type. -.PP +.P This system call exists on various 32-bit platforms to support seeking to large file offsets. .SH RETURN VALUE diff --git a/man2/lookup_dcookie.2 b/man2/lookup_dcookie.2 index 4543e45..006afe2 100644 --- a/man2/lookup_dcookie.2 +++ b/man2/lookup_dcookie.2 @@ -4,7 +4,7 @@ .\" .\" Modified 2004-06-17 Michael Kerrisk .\" -.TH lookup_dcookie 2 2023-03-30 "Linux man-pages 6.05.01" +.TH lookup_dcookie 2 2023-10-31 "Linux man-pages 6.7" .SH NAME lookup_dcookie \- return a directory entry's path .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_lookup_dcookie, uint64_t " cookie ", char *" buffer , .BI " size_t " len ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR lookup_dcookie (), @@ -30,7 +30,7 @@ Look up the full path of the directory entry specified by the value The cookie is an opaque identifier uniquely identifying a particular directory entry. The buffer given is filled in with the full path of the directory entry. -.PP +.P For .BR lookup_dcookie () to return successfully, @@ -69,7 +69,7 @@ The buffer was not large enough to hold the path of the directory entry. Linux. .SH HISTORY Linux 2.5.43. -.PP +.P The .B ENAMETOOLONG error was added in Linux 2.5.70. @@ -79,7 +79,7 @@ is a special-purpose system call, currently used only by the .BR oprofile (1) profiler. It relies on a kernel driver to register cookies for directory entries. -.PP +.P The path returned may be suffixed by the string " (deleted)" if the directory entry has been removed. .SH SEE ALSO diff --git a/man2/lseek.2 b/man2/lseek.2 index 7ef7930..93b3f6d 100644 --- a/man2/lseek.2 +++ b/man2/lseek.2 @@ -15,7 +15,7 @@ .\" Modified 2003-08-21 by Andries Brouwer .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE .\" -.TH lseek 2 2023-03-30 "Linux man-pages 6.05.01" +.TH lseek 2 2023-10-31 "Linux man-pages 6.7" .SH NAME lseek \- reposition read/write file offset .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); .fi .SH DESCRIPTION @@ -52,7 +52,7 @@ bytes. The file offset is set to the size of the file plus .I offset bytes. -.PP +.P .BR lseek () allows the file offset to be set beyond the end of the file (but this does not change the size of the file). @@ -87,19 +87,19 @@ If there is no hole past .IR offset , then the file offset is adjusted to the end of the file (i.e., there is an implicit hole at the end of any file). -.PP +.P In both of the above cases, .BR lseek () fails if .I offset points past the end of the file. -.PP +.P These operations allow applications to map holes in a sparsely allocated file. This can be useful for applications such as file backup tools, which can save space when creating backups and preserve holes, if they have a mechanism for discovering holes. -.PP +.P For the purposes of these operations, a hole is a sequence of zeros that (normally) has not been allocated in the underlying file storage. However, a filesystem is not obliged to report holes, @@ -122,7 +122,7 @@ it can be considered to consist of data that is a sequence of zeros). .\" https://lkml.org/lkml/2011/4/22/79 .\" http://lwn.net/Articles/440255/ .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data -.PP +.P The .B _GNU_SOURCE feature test macro must be defined in order to obtain the definitions of @@ -131,7 +131,7 @@ and .B SEEK_HOLE from .IR . -.PP +.P The .B SEEK_HOLE and @@ -216,7 +216,7 @@ on a terminal device fails with the error POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P .B SEEK_DATA and .B SEEK_HOLE @@ -229,7 +229,7 @@ See .BR open (2) for a discussion of the relationship between file descriptors, open file descriptions, and files. -.PP +.P If the .B O_APPEND file status flag is set on the open file description, @@ -238,7 +238,7 @@ then a .I always moves the file offset to the end of the file, regardless of the use of .BR lseek (). -.PP +.P Some devices are incapable of seeking and POSIX does not specify which devices must support .BR lseek (). diff --git a/man2/madvise.2 b/man2/madvise.2 index 5782574..c30ec4c 100644 --- a/man2/madvise.2 +++ b/man2/madvise.2 @@ -12,7 +12,7 @@ .\" 2011-09-18, Doug Goldstein .\" Document MADV_HUGEPAGE and MADV_NOHUGEPAGE .\" -.TH madvise 2 2023-04-03 "Linux man-pages 6.05.01" +.TH madvise 2 2023-10-31 "Linux man-pages 6.7" .SH NAME madvise \- give advice about use of memory .SH LIBRARY @@ -21,15 +21,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int madvise(void " addr [. length "], size_t " length ", int " advice ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR madvise (): .nf Since glibc 2.19: @@ -54,7 +54,7 @@ The value of is rounded up to a multiple of page size. In most cases, the goal of such advice is to improve system or application performance. -.PP +.P Initially, the system call supported a set of "conventional" .I advice values, which are also available on several other implementations. @@ -86,7 +86,7 @@ values listed here have analogs in the POSIX-specified .BR posix_madvise (3) function, and the values have the same meanings, with the exception of .BR MADV_DONTNEED . -.PP +.P The advice is indicated in the .I advice argument, which is one of the following: @@ -845,7 +845,7 @@ Other implementations typically implement at least the flags listed above under .IR "Conventional advice flags" , albeit with some variation in semantics. -.PP +.P POSIX.1-2001 describes .BR posix_madvise (3) with constants @@ -868,7 +868,7 @@ that are not mapped, the Linux version of ignores them and applies the call to the rest (but returns .B ENOMEM from the system call, as it should). -.PP +.P .I madvise(0,\ 0,\ advice) will return zero iff .I advice @@ -877,7 +877,7 @@ is supported by the kernel and can be relied on to probe for support. None. .SH HISTORY First appeared in 4.4BSD. -.PP +.P Since Linux 3.18, .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb support for this system call is optional, diff --git a/man2/mbind.2 b/man2/mbind.2 index 064b8a1..4b43aca 100644 --- a/man2/mbind.2 +++ b/man2/mbind.2 @@ -15,7 +15,7 @@ .\" Author: Lee Schermerhorn .\" Date: Thu Oct 25 14:16:32 2012 +0200 .\" -.TH mbind 2 2023-07-16 "Linux man-pages 6.05.01" +.TH mbind 2 2023-12-09 "Linux man-pages 6.7" .SH NAME mbind \- set memory policy for a memory range .SH LIBRARY @@ -24,7 +24,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "long mbind(void " addr [. len "], unsigned long " len ", int " mode , .BI " const unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)" .B " / ULONG_WIDTH]," @@ -40,7 +40,7 @@ and continuing for .I len bytes. The memory policy defines from which node memory is allocated. -.PP +.P If the memory range specified by the .IR addr " and " len arguments includes an "anonymous" region of memory\[em]that is @@ -62,7 +62,7 @@ an initial read access will allocate pages according to the memory policy of the thread that causes the page to be allocated. This may not be the thread that called .BR mbind (). -.PP +.P The specified policy will be ignored for any .B MAP_SHARED mappings in the specified memory range. @@ -70,7 +70,7 @@ Rather the pages will be allocated according to the memory policy of the thread that caused the page to be allocated. Again, this may not be the thread that called .BR mbind (). -.PP +.P If the specified memory range includes a shared memory region created using the .BR shmget (2) @@ -87,7 +87,7 @@ the huge pages will be allocated according to the policy specified only if the page allocation is caused by the process that calls .BR mbind () for that region. -.PP +.P By default, .BR mbind () has an effect only for new allocations; if the pages inside @@ -98,7 +98,7 @@ This default behavior may be overridden by the and .B MPOL_MF_MOVE_ALL flags described below. -.PP +.P The .I mode argument must specify one of @@ -115,7 +115,7 @@ require the caller to specify the node or nodes to which the mode applies, via the .I nodemask argument. -.PP +.P The .I mode argument may also include an optional @@ -124,6 +124,23 @@ The supported .I "mode flags" are: .TP +.BR MPOL_F_NUMA_BALANCING " (since Linux 5.15)" +.\" commit bda420b985054a3badafef23807c4b4fa38a3dff +.\" commit 6d2aec9e123bb9c49cb5c7fc654f25f81e688e8c +When +.I mode +is +.BR MPOL_BIND , +enable the kernel NUMA balancing for the task if it is supported by the kernel. +If the flag isn't supported by the kernel, or is used with +.I mode +other than +.BR MPOL_BIND , +\-1 is returned and +.I errno +is set to +.BR EINVAL . +.TP .BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)" A nonempty .I nodemask @@ -139,7 +156,7 @@ A nonempty .I nodemask specifies node IDs that are relative to the set of node IDs allowed by the thread's current cpuset. -.PP +.P .I nodemask points to a bit mask of nodes containing up to .I maxnode @@ -167,7 +184,7 @@ allowed by the thread's current cpuset context .B MPOL_F_STATIC_NODES mode flag is specified), and contains memory. -.PP +.P The .I mode argument must include one of the following values: @@ -265,7 +282,7 @@ By contrast, reverts to the memory policy of the thread (which may be set via .BR set_mempolicy (2)); that policy may be something other than "local allocation". -.PP +.P If .B MPOL_MF_STRICT is passed in @@ -281,7 +298,7 @@ if the existing pages in the memory range don't follow the policy. .\" --Lee Schermerhorn .\" In Linux 2.6.16 or later the kernel will also try to move pages .\" to the requested node with this flag. -.PP +.P If .B MPOL_MF_MOVE is specified in @@ -299,7 +316,7 @@ If the policy was specified, pages already residing on the specified nodes will not be moved such that they are interleaved. -.PP +.P If .B MPOL_MF_MOVE_ALL is passed in @@ -417,16 +434,16 @@ privilege. Linux. .SH HISTORY Linux 2.6.7. -.PP +.P Support for huge page policy was added with Linux 2.6.16. For interleave policy to be effective on huge page mappings the policied memory needs to be tens of megabytes or larger. -.PP +.P Before Linux 5.7. .\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0 .B MPOL_MF_STRICT was ignored on huge page mappings. -.PP +.P .B MPOL_MF_MOVE and .B MPOL_MF_MOVE_ALL @@ -434,12 +451,12 @@ are available only on Linux 2.6.16 and later. .SH NOTES For information on library support, see .BR numa (7). -.PP +.P NUMA policy is not supported on a memory-mapped file range that was mapped with the .B MAP_SHARED flag. -.PP +.P The .B MPOL_DEFAULT mode can have different effects for diff --git a/man2/membarrier.2 b/man2/membarrier.2 index f118fd0..ce5a9de 100644 --- a/man2/membarrier.2 +++ b/man2/membarrier.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH membarrier 2 2023-05-03 "Linux man-pages 6.05.01" +.TH membarrier 2 2023-10-31 "Linux man-pages 6.7" .SH NAME membarrier \- issue memory barriers on a set of threads .SH LIBRARY @@ -11,16 +11,16 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include " \ " /* Definition of " MEMBARRIER_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_membarrier, int " cmd ", unsigned int " flags \ ", int " cpu_id ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR membarrier (), @@ -36,12 +36,12 @@ effectively is .I not as simple as replacing memory barriers with this system call, but requires understanding of the details below. -.PP +.P Use of memory barriers needs to be done taking into account that a memory barrier always needs to be either matched with its memory barrier counterparts, or that the architecture's memory model doesn't require the matching barriers. -.PP +.P There are cases where one side of the matching barriers (which we will refer to as "fast side") is executed much more often than the other (which we will refer to as "slow side"). @@ -50,22 +50,22 @@ This is a prime target for the use of The key idea is to replace, for these matching barriers, the fast-side memory barriers by simple compiler barriers, for example: -.PP +.P .in +4n .EX asm volatile ("" : : : "memory") .EE .in -.PP +.P and replace the slow-side memory barriers by calls to .BR membarrier (). -.PP +.P This will add overhead to the slow side, and remove overhead from the fast side, thus resulting in an overall performance increase as long as the slow side is infrequent enough that the overhead of the .BR membarrier () calls does not outweigh the performance gain on the fast side. -.PP +.P The .I cmd argument is one of the following: @@ -183,7 +183,7 @@ Register the process's intent to use This is an alias for .B MEMBARRIER_CMD_GLOBAL that exists for header backward compatibility. -.PP +.P The .I flags argument must be specified as 0 unless the command is @@ -192,7 +192,7 @@ in which case .I flags can be either 0 or .BR MEMBARRIER_CMD_FLAG_CPU . -.PP +.P The .I cpu_id argument is ignored unless @@ -201,11 +201,11 @@ is .BR MEMBARRIER_CMD_FLAG_CPU , in which case it must specify the CPU targeted by this membarrier command. -.PP +.P All memory accesses performed in program order from each targeted thread are guaranteed to be ordered with respect to .BR membarrier (). -.PP +.P If we use the semantic .I barrier() to represent a compiler barrier forcing memory @@ -219,7 +219,7 @@ each pairing of and .IR smp_mb() . The pair ordering is detailed as (O: ordered, X: not ordered): -.PP +.P .RS .TS l c c c. @@ -246,7 +246,7 @@ On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P For a given command, with .I flags set to 0, this system call is @@ -284,9 +284,9 @@ commands. Linux. .SH HISTORY Linux 4.3. -.PP +.P Before Linux 5.10, the prototype was: -.PP +.P .in +4n .EX .BI "int membarrier(int " cmd ", int " flags ); @@ -301,10 +301,10 @@ matching barriers on other cores. For instance, a load fence can order loads prior to and following that fence with respect to stores ordered by store fences. -.PP +.P Program order is the order in which instructions are ordered in the program assembly code. -.PP +.P Examples where .BR membarrier () can be useful include implementations @@ -314,7 +314,7 @@ Assuming a multithreaded application where "fast_path()" is executed very frequently, and where "slow_path()" is executed infrequently, the following code (x86) can be transformed using .BR membarrier (): -.PP +.P .in +4n .\" SRC BEGIN (membarrier.c) .EX @@ -365,11 +365,11 @@ main(void) .EE .\" SRC END .in -.PP +.P The code above transformed to use .BR membarrier () becomes: -.PP +.P .in +4n .EX #define _GNU_SOURCE diff --git a/man2/memfd_create.2 b/man2/memfd_create.2 index fb18abc..c7cf859 100644 --- a/man2/memfd_create.2 +++ b/man2/memfd_create.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH memfd_create 2 2023-05-03 "Linux man-pages 6.05.01" +.TH memfd_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME memfd_create \- create an anonymous file .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int memfd_create(const char *" name ", unsigned int " flags ");" .fi .SH DESCRIPTION @@ -39,14 +39,14 @@ memory allocations such as those allocated using with the .B MAP_ANONYMOUS flag. -.PP +.P The initial size of the file is set to 0. Following the call, the file size should be set using .BR ftruncate (2). (Alternatively, the file may be populated by calls to .BR write (2) or similar.) -.PP +.P The name supplied in .I name is used as a filename and will be displayed @@ -57,7 +57,7 @@ The displayed name is always prefixed with and serves only for debugging purposes. Names do not affect the behavior of the file descriptor, and as such multiple files can have the same name without any side effects. -.PP +.P The following values may be bitwise ORed in .I flags to change the behavior of @@ -105,7 +105,11 @@ in .I flags is supported since Linux 4.16. .TP -.BR MFD_HUGE_2MB ", " MFD_HUGE_1GB ", " "..." +.B MFD_HUGE_2MB +.TQ +.B MFD_HUGE_1GB +.TQ +\&.\|.\|. Used in conjunction with .B MFD_HUGETLB to select alternative hugetlb page sizes (respectively, 2\ MB, 1\ GB, ...) @@ -117,11 +121,11 @@ huge page sizes are included in the header file For details on encoding huge page sizes not included in the header file, see the discussion of the similarly named constants in .BR mmap (2). -.PP +.P Unused bits in .I flags must be 0. -.PP +.P As its return value, .BR memfd_create () returns a new file descriptor that can be used to refer to the file. @@ -130,7 +134,7 @@ This file descriptor is opened for both reading and writing and .B O_LARGEFILE is set for the file descriptor. -.PP +.P With respect to .BR fork (2) and @@ -215,7 +219,7 @@ The primary purpose of is to create files and associated file descriptors that are used with the file-sealing APIs provided by .BR fcntl (2). -.PP +.P The .BR memfd_create () system call also has uses without file sealing @@ -247,13 +251,13 @@ location in the shared memory region. (Dealing with this possibility necessitates the use of a handler for the .B SIGBUS signal.) -.PP +.P Dealing with untrusted peers imposes extra complexity on code that employs shared memory. Memory sealing enables that extra complexity to be eliminated, by allowing a process to operate secure in the knowledge that its peer can't modify the shared memory in an undesired fashion. -.PP +.P An example of the usage of the sealing mechanism is as follows: .IP (1) 5 The first process creates a @@ -342,7 +346,7 @@ seal has not yet been applied). Below are shown two example programs that demonstrate the use of .BR memfd_create () and the file sealing API. -.PP +.P The first program, .IR t_memfd_create.c , creates a @@ -357,18 +361,18 @@ The first argument is the name to associate with the file, the second argument is the size to be set for the file, and the optional third argument is a string of characters that specify seals to be set on the file. -.PP +.P The second program, .IR t_get_seals.c , can be used to open an existing file that was created via .BR memfd_create () and inspect the set of seals that have been applied to that file. -.PP +.P The following shell session demonstrates the use of these programs. First we create a .BR tmpfs (5) file and set some seals on it: -.PP +.P .in +4n .EX $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP @@ -376,7 +380,7 @@ $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP PID: 11775; fd: 3; /proc/11775/fd/3 .EE .in -.PP +.P At this point, the .I t_memfd_create program continues to run in the background. @@ -392,7 +396,7 @@ Using that pathname, we inspect the content of the symbolic link, and use our .I t_get_seals program to view the seals that have been placed on the file: -.PP +.P .in +4n .EX $ \fBreadlink /proc/11775/fd/3\fP diff --git a/man2/memfd_secret.2 b/man2/memfd_secret.2 index fcc39f6..8b4fb48 100644 --- a/man2/memfd_secret.2 +++ b/man2/memfd_secret.2 @@ -7,7 +7,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH memfd_secret 2 2023-03-30 "Linux man-pages 6.05.01" +.TH memfd_secret 2 2023-10-31 "Linux man-pages 6.7" .SH NAME memfd_secret \- create an anonymous RAM-based file to access secret memory regions @@ -16,13 +16,13 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_memfd_secret, unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR memfd_secret (), @@ -40,7 +40,7 @@ it is automatically released. The initial size of the file is set to 0. Following the call, the file size should be set using .BR ftruncate (2). -.PP +.P The memory areas backing the file created with .BR memfd_secret (2) are visible only to the processes that have access to the file descriptor. @@ -50,7 +50,7 @@ map the corresponding physical memory. (Thus, the pages in the region can't be accessed by the kernel itself, so that, for example, pointers to the region can't be passed to system calls.) -.PP +.P The following values may be bitwise ORed in .I flags to control the behavior of @@ -64,7 +64,7 @@ See the description of the .B O_CLOEXEC flag in .BR open (2) -.PP +.P As its return value, .BR memfd_secret () returns a new file descriptor that refers to an anonymous file. @@ -73,7 +73,7 @@ This file descriptor is opened for both reading and writing and .B O_LARGEFILE is set for the file descriptor. -.PP +.P With respect to .BR fork (2) and @@ -86,7 +86,7 @@ and refers to the same file. The file descriptor is preserved across .BR execve (2), unless the close-on-exec flag has been set. -.PP +.P The memory region is locked into memory in the same way as with .BR mlock (2), so that it will never be written into swap, @@ -147,7 +147,7 @@ memory ranges backed by .BR memfd_secret () in any circumstances, but nevertheless, it is much harder to exfiltrate data from these regions. -.PP +.P .BR memfd_secret () provides the following protections: .IP \[bu] 3 @@ -181,14 +181,14 @@ either walk the page tables and create new ones, or spawn a new privileged user-space process to perform secrets exfiltration using .BR ptrace (2). -.PP +.P The way .BR memfd_secret () allocates and locks the memory may impact overall system performance, therefore the system call is disabled by default and only available if the system administrator turned it on using "secretmem.enable=y" kernel parameter. -.PP +.P To prevent potential data leaks of memory regions backed by .BR memfd_secret () from a hybernation image, diff --git a/man2/migrate_pages.2 b/man2/migrate_pages.2 index 177f463..8f2ee8e 100644 --- a/man2/migrate_pages.2 +++ b/man2/migrate_pages.2 @@ -6,7 +6,7 @@ .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. .\" Christoph Lameter .\" -.TH migrate_pages 2 2023-07-15 "Linux man-pages 6.05.01" +.TH migrate_pages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME migrate_pages \- move all pages in a process to another set of nodes .SH LIBRARY @@ -15,7 +15,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long migrate_pages(int " pid ", unsigned long " maxnode, .BI " const unsigned long *" old_nodes, .BI " const unsigned long *" new_nodes ); @@ -36,7 +36,7 @@ the kernel maintains the relative topology relationship inside .I old_nodes during the migration to .IR new_nodes . -.PP +.P The .I old_nodes and @@ -58,7 +58,7 @@ as in .BR mbind (2), but different from .BR select (2)). -.PP +.P The .I pid argument is the ID of the process whose pages are to be moved. @@ -72,7 +72,7 @@ If is 0, then .BR migrate_pages () moves pages of the calling process. -.PP +.P Pages shared with another process will be moved only if the initiating process has the .B CAP_SYS_NICE @@ -132,7 +132,7 @@ Linux 2.6.16. .SH NOTES For information on library support, see .BR numa (7). -.PP +.P Use .BR get_mempolicy (2) with the @@ -141,7 +141,7 @@ flag to obtain the set of nodes that are allowed by the calling process's cpuset. Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset. -.PP +.P Use of .BR migrate_pages () may result in pages whose location @@ -153,7 +153,7 @@ and/or the specified process (see That is, memory policy does not constrain the destination nodes used by .BR migrate_pages (). -.PP +.P The .I header is not included with glibc, but requires installing @@ -169,6 +169,6 @@ or a similar package. .BR numa (7), .BR migratepages (8), .BR numastat (8) -.PP +.P .I Documentation/vm/page_migration.rst in the Linux kernel source tree diff --git a/man2/mincore.2 b/man2/mincore.2 index 9ffca56..efba7fc 100644 --- a/man2/mincore.2 +++ b/man2/mincore.2 @@ -11,7 +11,7 @@ .\" after message from .\" 2007-01-08 mtk, rewrote various parts .\" -.TH mincore 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mincore 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mincore \- determine whether pages are resident in memory .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mincore(void " addr [. length "], size_t " length ", unsigned char *" vec ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mincore (): .nf Since glibc 2.19: @@ -47,7 +47,7 @@ starting at the address and continuing for .I length bytes. -.PP +.P The .I addr argument must be a multiple of the system page size. @@ -61,7 +61,7 @@ One may obtain the page size .RB ( PAGE_SIZE ) using .IR sysconf(_SC_PAGESIZE) . -.PP +.P The .I vec argument must point to an array containing at least @@ -122,9 +122,9 @@ None. .SH HISTORY Linux 2.3.99pre1, glibc 2.2. -.PP +.P First appeared in 4.4BSD. -.PP +.P NetBSD, FreeBSD, OpenBSD, Solaris 8, AIX 5.1, SunOS 4.1. .SH BUGS diff --git a/man2/mkdir.2 b/man2/mkdir.2 index c3342bd..d63059f 100644 --- a/man2/mkdir.2 +++ b/man2/mkdir.2 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH mkdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mkdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mkdir, mkdirat \- create a directory .SH LIBRARY @@ -15,20 +15,20 @@ Standard C library .nf .B #include .\" .B #include -.PP +.P .BI "int mkdir(const char *" pathname ", mode_t " mode ); -.PP +.P .BR "#include " "/* Definition of AT_* constants */" .B #include -.PP +.P .BI "int mkdirat(int " dirfd ", const char *" pathname ", mode_t " mode ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mkdirat (): .nf Since glibc 2.10: @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see .BR mkdir () attempts to create a directory named .IR pathname . -.PP +.P The argument .I mode specifies the mode for the new directory (see @@ -54,7 +54,7 @@ Whether other .I mode bits are honored for the created directory depends on the operating system. For Linux, see NOTES below. -.PP +.P The newly created directory will be owned by the effective user ID of the process. If the directory containing the file has the set-group-ID @@ -64,7 +64,7 @@ or, synonymously .IR "mount \-o grpid" ), the new directory will inherit the group ownership from its parent; otherwise it will be owned by the effective group ID of the process. -.PP +.P If the parent directory has the set-group-ID bit set, then so will the newly created directory. .\" @@ -75,7 +75,7 @@ The system call operates in exactly the same way as .BR mkdir (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -85,7 +85,7 @@ referred to by the file descriptor the calling process, as is done by .BR mkdir () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -97,13 +97,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR mkdir ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for diff --git a/man2/mknod.2 b/man2/mknod.2 index 0925aea..dd7905c 100644 --- a/man2/mknod.2 +++ b/man2/mknod.2 @@ -9,7 +9,7 @@ .\" Modified 2003-04-23 by Michael Kerrisk .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH mknod 2 2023-03-31 "Linux man-pages 6.05.01" +.TH mknod 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mknod, mknodat \- create a special or ordinary file .SH LIBRARY @@ -18,21 +18,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mknod(const char *" pathname ", mode_t " mode ", dev_t " dev ); -.PP +.P .BR "#include " "/* Definition of AT_* constants */" .B #include -.PP +.P .BI "int mknodat(int " dirfd ", const char *" pathname ", mode_t " mode \ ", dev_t " dev ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mknod (): .nf _XOPEN_SOURCE >= 500 @@ -50,7 +50,7 @@ with attributes specified by .I mode and .IR dev . -.PP +.P The .I mode argument specifies both the file mode to use and the type of node @@ -58,13 +58,13 @@ to be created. It should be a combination (using bitwise OR) of one of the file types listed below and zero or more of the file mode bits listed in .BR inode (7). -.PP +.P The file mode is modified by the process's .I umask in the usual way: in the absence of a default ACL, the permissions of the created node are .RI ( mode " & \[ti]" umask ). -.PP +.P The file type must be one of .BR S_IFREG , .BR S_IFCHR , @@ -78,7 +78,7 @@ special file, block special file, FIFO (named pipe), or UNIX domain socket, respectively. (Zero file type is equivalent to type .BR S_IFREG .) -.PP +.P If the file type is .B S_IFCHR or @@ -91,13 +91,13 @@ special file may be useful to build the value for .IR dev ); otherwise it is ignored. -.PP +.P If .I pathname already exists, or is a symbolic link, this call fails with an .B EEXIST error. -.PP +.P The newly created node will be owned by the effective user ID of the process. If the directory containing the node has the set-group-ID @@ -112,7 +112,7 @@ The system call operates in exactly the same way as .BR mknod (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -122,7 +122,7 @@ referred to by the file descriptor the calling process, as is done by .BR mknod () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -134,13 +134,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR mknod ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -258,7 +258,7 @@ However, nowadays one should never use for this purpose; one should use .BR mkfifo (3), a function especially defined for this purpose. -.PP +.P Under Linux, .BR mknod () cannot be used to create directories. diff --git a/man2/mlock.2 b/man2/mlock.2 index 1efe3dd..965e018 100644 --- a/man2/mlock.2 +++ b/man2/mlock.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH mlock 2 2023-04-08 "Linux man-pages 6.05.01" +.TH mlock 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mlock, mlock2, munlock, mlockall, munlockall \- lock and unlock memory .SH LIBRARY @@ -13,12 +13,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mlock(const void " addr [. len "], size_t " len ); .BI "int mlock2(const void " addr [. len "], size_t " len ", \ unsigned int " flags ); .BI "int munlock(const void " addr [. len "], size_t " len ); -.PP +.P .BI "int mlockall(int " flags ); .B int munlockall(void); .fi @@ -30,7 +30,7 @@ and lock part or all of the calling process's virtual address space into RAM, preventing that memory from being paged to the swap area. -.PP +.P .BR munlock () and .BR munlockall () @@ -38,7 +38,7 @@ perform the converse operation, unlocking part or all of the calling process's virtual address space, so that pages in the specified virtual address range can be swapped out again if required by the kernel memory manager. -.PP +.P Memory locking and unlocking are performed in units of whole pages. .SS mlock(), mlock2(), and munlock() .BR mlock () @@ -50,7 +50,7 @@ bytes. All pages that contain a part of the specified address range are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked. -.PP +.P .BR mlock2 () .\" commit a8ca5d0ecbdde5cc3d7accacbd69968b0c98764e .\" commit de60f5f10c58d4f34b68622442c0e04180367f3f @@ -64,7 +64,7 @@ However, the state of the pages contained in that range after the call returns successfully will depend on the value in the .I flags argument. -.PP +.P The .I flags argument can be either 0 or the following constant: @@ -73,14 +73,14 @@ argument can be either 0 or the following constant: Lock pages that are currently resident and mark the entire range so that the remaining nonresident pages are locked when they are populated by a page fault. -.PP +.P If .I flags is 0, .BR mlock2 () behaves exactly the same as .BR mlock (). -.PP +.P .BR munlock () unlocks pages in the address range starting at .I addr @@ -99,7 +99,7 @@ memory, and memory-mapped files. All mapped pages are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked. -.PP +.P The .I flags argument is constructed as the bitwise OR of one or more of the @@ -142,7 +142,7 @@ must be used with either or .B MCL_FUTURE or both. -.PP +.P If .B MCL_FUTURE has been specified, then a later system call (e.g., @@ -155,7 +155,7 @@ In the same circumstances, stack growth may likewise fail: the kernel will deny stack expansion and deliver a .B SIGSEGV signal to the process. -.PP +.P .BR munlockall () unlocks all pages mapped into the address space of the calling process. @@ -272,7 +272,7 @@ and allows an implementation to require that .I addr is page aligned, so portable applications should ensure this. -.PP +.P The .I VmLck field of the Linux-specific @@ -299,7 +299,7 @@ POSIX.1-2008. .TP .BR mlock2 () Linux. -.PP +.P On POSIX systems on which .BR mlock () and @@ -311,7 +311,7 @@ can be determined from the constant .B PAGESIZE (if defined) in \fI\fP or by calling .IR sysconf(_SC_PAGESIZE) . -.PP +.P On POSIX systems on which .BR mlockall () and @@ -356,7 +356,7 @@ software has erased the secrets in RAM and terminated. (But be aware that the suspend mode on laptops and some desktop computers will save a copy of the system's RAM to disk, regardless of memory locks.) -.PP +.P Real-time processes that are using .BR mlockall () to prevent delays on page faults should reserve enough @@ -369,7 +369,7 @@ This way, enough pages will be mapped for the stack and can be locked into RAM. The dummy writes ensure that not even copy-on-write page faults can occur in the critical section. -.PP +.P Memory locks are not inherited by a child created via .BR fork (2) and are automatically removed (unlocked) during an @@ -384,7 +384,7 @@ settings are not inherited by a child created via .BR fork (2) and are cleared during an .BR execve (2). -.PP +.P Note that .BR fork (2) will prepare the address space for a copy-on-write operation. @@ -398,11 +398,11 @@ or .BR mlock () operation\[em]not even from a thread which runs at a low priority within a process which also has a thread running at elevated priority. -.PP +.P The memory lock on an address range is automatically removed if the address range is unmapped via .BR munmap (2). -.PP +.P Memory locks do not stack, that is, pages which have been locked several times by calls to .BR mlock (), @@ -416,7 +416,7 @@ for the corresponding range or by Pages which are mapped to several locations or by several processes stay locked into RAM as long as they are locked at least at one location or by at least one process. -.PP +.P If a call to .BR mlockall () which uses the @@ -425,7 +425,7 @@ flag is followed by another call that does not specify this flag, the changes made by the .B MCL_FUTURE call will be lost. -.PP +.P The .BR mlock2 () .B MLOCK_ONFAULT @@ -443,7 +443,7 @@ a process must be privileged in order to lock memory and the .B RLIMIT_MEMLOCK soft resource limit defines a limit on how much memory the process may lock. -.PP +.P Since Linux 2.6.9, no limits are placed on the amount of memory that a privileged process can lock and the .B RLIMIT_MEMLOCK @@ -472,7 +472,7 @@ would fail on requests that should have succeeded. This bug was fixed .\" commit 0cf2f6f6dc605e587d2c1120f295934c77e810e8 in Linux 4.9. -.PP +.P In Linux 2.4 series of kernels up to and including Linux 2.4.17, a bug caused the .BR mlockall () @@ -480,7 +480,7 @@ a bug caused the flag to be inherited across a .BR fork (2). This was rectified in Linux 2.4.18. -.PP +.P Since Linux 2.6.9, if a privileged process calls .I mlockall(MCL_FUTURE) and later drops privileges (loses the diff --git a/man2/mmap.2 b/man2/mmap.2 index 3d9a887..300eb2b 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -18,7 +18,7 @@ .\" 2007-07-10, mtk, Added an example program. .\" 2008-11-18, mtk, document MAP_STACK .\" -.TH mmap 2 2023-07-20 "Linux man-pages 6.05.01" +.TH mmap 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mmap, munmap \- map or unmap files or devices into memory .SH LIBRARY @@ -27,13 +27,13 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *mmap(void " addr [. length "], size_t " length \ ", int " prot ", int " flags , .BI " int " fd ", off_t " offset ); .BI "int munmap(void " addr [. length "], size_t " length ); .fi -.PP +.P See NOTES for information on feature test macro requirements. .SH DESCRIPTION .BR mmap () @@ -44,7 +44,7 @@ The starting address for the new mapping is specified in The .I length argument specifies the length of the mapping (which must be greater than 0). -.PP +.P If .I addr is NULL, @@ -64,7 +64,7 @@ may or may not depend on the hint. .\" Before Linux 2.6.24, the address was rounded up to the next page .\" boundary; since Linux 2.6.24, it is rounded down! The address of the new mapping is returned as the result of the call. -.PP +.P The contents of a file mapping (as opposed to an anonymous mapping; see .B MAP_ANONYMOUS below), are initialized using @@ -76,13 +76,13 @@ in the file (or other object) referred to by the file descriptor .I offset must be a multiple of the page size as returned by .IR sysconf(_SC_PAGE_SIZE) . -.PP +.P After the .BR mmap () call has returned, the file descriptor, .IR fd , can be closed immediately without invalidating the mapping. -.PP +.P The .I prot argument describes the desired memory protection of the mapping @@ -147,7 +147,7 @@ the underlying file. It is unspecified whether changes made to the file after the .BR mmap () call are visible in the mapped region. -.PP +.P Both .B MAP_SHARED and @@ -155,7 +155,7 @@ and are described in POSIX.1-2001 and POSIX.1-2008. .B MAP_SHARED_VALIDATE is a Linux extension. -.PP +.P In addition, zero or more of the following values can be ORed in .IR flags : .TP @@ -299,7 +299,9 @@ See the Linux kernel source file .I Documentation/admin\-guide/mm/hugetlbpage.rst for further information, as well as NOTES, below. .TP -.BR MAP_HUGE_2MB ", " MAP_HUGE_1GB " (since Linux 3.8)" +.B MAP_HUGE_2MB +.TQ +.BR MAP_HUGE_1GB " (since Linux 3.8)" .\" See https://lwn.net/Articles/533499/ Used in conjunction with .B MAP_HUGETLB @@ -443,7 +445,7 @@ option. Because of the security implications, that option is normally enabled only on embedded devices (i.e., devices where one has complete control of the contents of user memory). -.PP +.P Of the above flags, only .B MAP_FIXED is specified in POSIX.1-2001 and POSIX.1-2008. @@ -465,7 +467,7 @@ The region is also automatically unmapped when the process is terminated. On the other hand, closing the file descriptor does not unmap the region. -.PP +.P The address .I addr must be a multiple of the page size (but @@ -488,7 +490,7 @@ On error, the value is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR munmap () returns 0. @@ -629,13 +631,14 @@ and is not a member of the group; see the description of .I /proc/sys/vm/sysctl_hugetlb_shm_group in +.BR proc_sys (5). .TP .B ETXTBSY .B MAP_DENYWRITE was set but the object specified by .I fd is open for writing. -.PP +.P Use of a mapped region can result in these signals: .TP .B SIGSEGV @@ -662,7 +665,6 @@ T{ .BR munmap () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On some hardware architectures (e.g., i386), .B PROT_WRITE @@ -676,7 +678,7 @@ or not. Portable programs should always set .B PROT_EXEC if they intend to execute code in the new mapping. -.PP +.P The portable way to create a mapping is to specify .I addr as 0 (NULL), and omit @@ -691,7 +693,7 @@ If the flag is specified, and .I addr is 0 (NULL), then the mapped address will be 0 (NULL). -.PP +.P Certain .I flags constants are defined only if suitable feature test macros are defined @@ -745,7 +747,7 @@ POSIX.1-2008. POSIX.1-2001, SVr4, 4.4BSD. .\" SVr4 documents additional error codes ENXIO and ENODEV. .\" SUSv2 documents additional error codes EMFILE and EOVERFLOW. -.PP +.P On POSIX systems on which .BR mmap (), .BR msync (2), @@ -765,7 +767,7 @@ Memory mapped by is preserved across .BR fork (2), with the same attributes. -.PP +.P A file is mapped in multiples of the page size. For a file that is not a multiple of the page size, @@ -775,7 +777,7 @@ and modifications to that region are not written out to the file. The effect of changing the size of the underlying file of a mapping on the pages that correspond to added or removed regions of the file is unspecified. -.PP +.P An application can determine which pages of a mapping are currently resident in the buffer/page cache using .BR mincore (2). @@ -792,7 +794,7 @@ otherwise, the use of .B MAP_FIXED is hazardous because it forcibly removes preexisting mappings, making it easy for a multithreaded process to corrupt its own address space. -.PP +.P For example, suppose that thread A looks through .IR /proc/ pid /maps in order to locate an unused address range that it can map using @@ -820,7 +822,7 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . -.PP +.P Since Linux 4.17, a multithreaded program can use the .B MAP_FIXED_NOREPLACE flag to avoid the hazard described above @@ -834,7 +836,7 @@ field for the mapped file may be updated at any time between the .BR mmap () and the corresponding unmapping; the first reference to a mapped page will update the field if it has not been already. -.PP +.P The .I st_ctime and @@ -859,7 +861,7 @@ and .BR munmap () differ somewhat from the requirements for mappings that use the native system page size. -.PP +.P For .BR mmap (), .I offset @@ -867,7 +869,7 @@ must be a multiple of the underlying huge page size. The system automatically aligns .I length to be a multiple of the underlying huge page size. -.PP +.P For .BR munmap (), .IR addr , @@ -880,14 +882,14 @@ On Linux, there are no guarantees like those suggested above under .BR MAP_NORESERVE . By default, any process can be killed at any moment when the system runs out of memory. -.PP +.P Before Linux 2.6.7, the .B MAP_POPULATE flag has effect only if .I prot is specified as .BR PROT_NONE . -.PP +.P SUSv3 specifies that .BR mmap () should fail if @@ -902,7 +904,7 @@ Since Linux 2.6.12, fails with the error .B EINVAL for this case. -.PP +.P POSIX specifies that the system shall always zero fill any partial page at the end of the object and that system will never write any modification of the @@ -1021,14 +1023,14 @@ main(int argc, char *argv[]) .BR userfaultfd (2), .BR shm_open (3), .BR shm_overview (7) -.PP +.P The descriptions of the following files in .BR proc (5): .IR /proc/ pid /maps , .IR /proc/ pid /map_files , and .IR /proc/ pid /smaps . -.PP +.P B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. .\" .\" Repeat after me: private read-only mappings are 100% equivalent to diff --git a/man2/mmap2.2 b/man2/mmap2.2 index e1704e3..e406c20 100644 --- a/man2/mmap2.2 +++ b/man2/mmap2.2 @@ -6,7 +6,7 @@ .\" Added description of mmap2 .\" Modified, 2004-11-25, mtk -- removed stray #endif in prototype .\" -.TH mmap2 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mmap2 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mmap2 \- map files or devices into memory .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .BR "#include " " /* Definition of " MAP_* " and " PROT_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "void *syscall(SYS_mmap2, unsigned long " addr ", unsigned long " length , .BI " unsigned long " prot ", unsigned long " flags , .BI " unsigned long " fd ", unsigned long " pgoffset ); @@ -26,7 +26,7 @@ Standard C library This is probably not the system call that you are interested in; instead, see .BR mmap (2), which describes the glibc wrapper function that invokes this system call. -.PP +.P The .BR mmap2 () system call provides the same interface as @@ -53,7 +53,7 @@ Problem with getting the data from user space. (Various platforms where the page size is not 4096 bytes.) .I "offset\ *\ 4096" is not a multiple of the system page size. -.PP +.P .BR mmap2 () can also return any of the errors described in .BR mmap (2). @@ -64,9 +64,9 @@ the glibc wrapper function invokes this system call rather than the .BR mmap (2) system call. -.PP +.P This system call does not exist on x86-64. -.PP +.P On ia64, the unit for .I offset is actually the system page size, rather than 4096 bytes. diff --git a/man2/modify_ldt.2 b/man2/modify_ldt.2 index 0364289..7ef2722 100644 --- a/man2/modify_ldt.2 +++ b/man2/modify_ldt.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH modify_ldt 2 2023-03-30 "Linux man-pages 6.05.01" +.TH modify_ldt 2 2023-10-31 "Linux man-pages 6.7" .SH NAME modify_ldt \- get or set a per-process LDT entry .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include " " /* Definition of " "struct user_desc" " */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_modify_ldt, int " func ", void " ptr [. bytecount ], .BI " unsigned long " bytecount ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR modify_ldt (), @@ -32,7 +32,7 @@ is an array of segment descriptors that can be referenced by user code. Linux allows processes to configure a per-process (actually per-mm) LDT. For more information about the LDT, see the Intel Software Developer's Manual or the AMD Architecture Programming Manual. -.PP +.P When .I func is 0, @@ -46,7 +46,7 @@ the LDT is padded with additional trailing zero bytes. On success, .BR modify_ldt () will return the number of bytes read. -.PP +.P When .I func is 1 or 0x11, @@ -60,11 +60,11 @@ structure and .I bytecount must equal the size of this structure. -.PP +.P The .I user_desc structure is defined in \fI\fP as: -.PP +.P .in +4n .EX struct user_desc { @@ -80,10 +80,10 @@ struct user_desc { }; .EE .in -.PP +.P In Linux 2.4 and earlier, this structure was named .IR modify_ldt_ldt_s . -.PP +.P The .I contents field is the segment type (data, expand-down data, non-conforming code, or @@ -91,7 +91,7 @@ conforming code). The other fields match their descriptions in the CPU manual, although .BR modify_ldt () cannot set the hardware-defined "accessed" bit described in the CPU manual. -.PP +.P A .I user_desc is considered "empty" if @@ -108,7 +108,7 @@ is 1, by setting both and .I limit to 0. -.PP +.P A conforming code segment (i.e., one with .IR contents==3 ) will be rejected if @@ -117,7 +117,7 @@ func is 1 or if .I seg_not_present is 0. -.PP +.P When .I func is 2, @@ -168,12 +168,12 @@ or .BR arch_prctl (2) instead, except on extremely old kernels that do not support those system calls. -.PP +.P The normal use for .BR modify_ldt () is to run legacy 16-bit or segmented 32-bit code. Not all kernels allow 16-bit segments to be installed, however. -.PP +.P Even on 64-bit kernels, .BR modify_ldt () cannot be used to create a long mode (i.e., 64-bit) code segment. diff --git a/man2/mount.2 b/man2/mount.2 index 916b68c..f2511c4 100644 --- a/man2/mount.2 +++ b/man2/mount.2 @@ -17,7 +17,7 @@ .\" 2008-10-06, mtk: move umount*() material into separate umount.2 page. .\" 2008-10-06, mtk: Add discussion of namespaces. .\" -.TH mount 2 2023-04-03 "Linux man-pages 6.05.01" +.TH mount 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mount \- mount filesystem .SH LIBRARY @@ -26,7 +26,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int mount(const char *" source ", const char *" target , .BI " const char *" filesystemtype ", unsigned long " mountflags , .BI " const void *_Nullable " data ); @@ -40,11 +40,11 @@ but can also be the pathname of a directory or file, or a dummy string) to the location (a directory or file) specified by the pathname in .IR target . -.PP +.P Appropriate privilege (Linux: the .B CAP_SYS_ADMIN capability) is required to mount filesystems. -.PP +.P Values for the .I filesystemtype argument supported by the kernel are listed in @@ -53,7 +53,7 @@ argument supported by the kernel are listed in "tmpfs", "cgroup", "proc", "mqueue", "nfs", "cifs", "iso9660"). Further types may become available when the appropriate modules are loaded. -.PP +.P The .I data argument is interpreted by the different filesystems. @@ -63,7 +63,7 @@ See .BR mount (8) for details of the options available for each filesystem type. This argument may be specified as NULL, if there are no options. -.PP +.P A call to .BR mount () performs one of a number of general types of operation, @@ -101,7 +101,7 @@ includes Create a new mount: .I mountflags includes none of the above flags. -.PP +.P Each of these operations is detailed later in this page. Further flags may be specified in .I mountflags @@ -284,13 +284,13 @@ and and .BR realpath (3) all still work properly. -.PP +.P From Linux 2.4 onward, some of the above flags are settable on a per-mount basis, while others apply to the superblock of the mounted filesystem, meaning that all mounts of the same filesystem share those flags. (Previously, all of the flags were per-superblock.) -.PP +.P The per-mount-point flags are as follows: .IP \[bu] 3 Since Linux 2.4: @@ -304,7 +304,7 @@ and .IP \[bu] Additionally, since Linux 2.6.20: .BR MS_RELATIME . -.PP +.P The following flags are per-superblock: .BR MS_DIRSYNC , .BR MS_LAZYTIME , @@ -320,7 +320,7 @@ Subsequently, the settings of the flags can be changed via a remount operation (see below). Such changes will be visible via all mounts associated with the filesystem. -.PP +.P Since Linux 2.6.16, .B MS_RDONLY can be set or cleared on a per-mount-point basis as well as on @@ -342,13 +342,13 @@ of an existing mount without having to unmount and remount the filesystem. should be the same value specified in the initial .BR mount () call. -.PP +.P The .I source and .I filesystemtype arguments are ignored. -.PP +.P The .I mountflags and @@ -356,7 +356,7 @@ and arguments should match the values used in the original .BR mount () call, except for those parameters that are being deliberately changed. -.PP +.P The following .I mountflags can be changed: @@ -398,7 +398,7 @@ flags during a remount are silently ignored. Note that changes to per-superblock flags are visible via all mounts of the associated filesystem (because the per-superblock flags are shared by all mounts). -.PP +.P Since Linux 3.17, .\" commit ffbc6f0ead47fa5a1dc9642b0331cb75c20a640e if none of @@ -412,7 +412,7 @@ is specified in then the remount operation preserves the existing values of these flags (rather than defaulting to .BR MS_RELATIME ). -.PP +.P Since Linux 2.6.26, the .B MS_REMOUNT flag can be used with @@ -424,13 +424,13 @@ flag on a mount without changing the underlying filesystem. Specifying .I mountflags as: -.PP +.P .in +4n .EX MS_REMOUNT | MS_BIND | MS_RDONLY .EE .in -.PP +.P will make access through this mountpoint read-only, without affecting other mounts. .\" @@ -447,13 +447,13 @@ another point within the single directory hierarchy. Bind mounts may cross filesystem boundaries and span .BR chroot (2) jails. -.PP +.P The .I filesystemtype and .I data arguments are ignored. -.PP +.P The remaining bits (other than .BR MS_REC , described below) in the @@ -463,7 +463,7 @@ argument are also ignored. the underlying mount.) However, see the discussion of remounting above, for a method of making an existing bind mount read-only. -.PP +.P By default, when a directory is bind mounted, only that directory is mounted; if there are any submounts under the directory tree, @@ -490,21 +490,21 @@ or (all available since Linux 2.6.15), then the propagation type of an existing mount is changed. If more than one of these flags is specified, an error results. -.PP +.P The only other flags that can be specified while changing the propagation type are .B MS_REC (described below) and .B MS_SILENT (which is ignored). -.PP +.P The .IR source , .IR filesystemtype , and .I data arguments are ignored. -.PP +.P The meanings of the propagation type flags are as follows: .TP .B MS_SHARED @@ -550,7 +550,7 @@ flags) is performed on a directory subtree, any unbindable mounts within the subtree are automatically pruned (i.e., not replicated) when replicating that subtree to produce the target subtree. -.PP +.P By default, changing the propagation type affects only the .I target mount. @@ -561,7 +561,7 @@ flag is also specified in then the propagation type of all mounts under .I target is also changed. -.PP +.P For further details regarding mount propagation types (including the default propagation type assigned to new mounts), see .BR mount_namespaces (7). @@ -578,7 +578,7 @@ specifies an existing mount and .I target specifies the new location to which that mount is to be relocated. The move is atomic: at no point is the subtree unmounted. -.PP +.P The remaining bits in the .I mountflags argument are ignored, as are the @@ -606,7 +606,7 @@ performs its default action: creating a new mount. specifies the source for the new mount, and .I target specifies the directory at which to create the mount point. -.PP +.P The .I filesystemtype and @@ -847,12 +847,12 @@ The definitions of and .B MS_UNBINDABLE were added to glibc headers in glibc 2.12. -.PP +.P Since Linux 2.4 a single filesystem can be mounted at multiple mount points, and multiple mounts can be stacked on the same mount point. .\" Multiple mounts on same mount point: since Linux 2.3.99pre7. -.PP +.P The .I mountflags argument may have the magic number 0xC0ED (\fBMS_MGC_VAL\fP) @@ -864,7 +864,7 @@ Specifying .B MS_MGC_VAL was required before Linux 2.4, but since Linux 2.4 is no longer required and is ignored if specified. -.PP +.P The original .B MS_SYNC flag was renamed @@ -873,7 +873,7 @@ in 1.1.69 when a different .B MS_SYNC was added to \fI\fP. -.PP +.P Before Linux 2.4 an attempt to execute a set-user-ID or set-group-ID program on a filesystem mounted with .B MS_NOSUID @@ -894,13 +894,13 @@ and changes to the namespace (i.e., mounts and unmounts) by one process are visible to all other processes sharing the same namespace. (The pre-2.4.19 Linux situation can be considered as one in which a single namespace was shared by every process on the system.) -.PP +.P A child process created by .BR fork (2) shares its parent's mount namespace; the mount namespace is preserved across an .BR execve (2). -.PP +.P A process can obtain a private mount namespace if: it was created using the .BR clone (2) @@ -920,7 +920,7 @@ of the namespace that it was previously sharing with other processes, so that future mounts and unmounts by the caller are invisible to other processes (except child processes that the caller subsequently creates) and vice versa. -.PP +.P For further details on mount namespaces, see .BR mount_namespaces (7). .\" @@ -928,7 +928,7 @@ For further details on mount namespaces, see Each mount has a parent mount. The overall parental relationship of all mounts defines the single directory hierarchy seen by the processes within a mount namespace. -.PP +.P The parent of a new mount is defined when the mount is created. In the usual case, the parent of a new mount is the mount of the filesystem @@ -936,7 +936,7 @@ containing the directory or file at which the new mount is attached. In the case where a new mount is stacked on top of an existing mount, the parent of the new mount is the previous mount that was stacked at that location. -.PP +.P The parental relationship between mounts can be discovered via the .IR /proc/ pid /mountinfo file (see below). diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index fafaba2..d59994b 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mount_setattr 2 2023-05-03 "Linux man-pages 6.05.01" +.TH mount_setattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mount_setattr \- change properties of a mount or mount tree .SH LIBRARY @@ -14,12 +14,12 @@ Standard C library .BR "#include " " /* Definition of " MOUNT_ATTR_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname , .BI " unsigned int " flags ", struct mount_attr *" attr \ ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR mount_setattr (), @@ -57,7 +57,7 @@ are changed. for an explanation of why the .I dirfd argument is useful.) -.PP +.P The .BR mount_setattr () system call uses an extensible structure @@ -75,7 +75,7 @@ zero-fill this structure on initialization. See the "Extensibility" subsection under .B NOTES for more details. -.PP +.P The .I size argument should usually be specified as @@ -96,7 +96,7 @@ For example, the macro for the size of the initial version of .I struct mount_attr is .BR MOUNT_ATTR_SIZE_VER0 . -.PP +.P The .I flags argument can be used to alter the pathname resolution behavior. @@ -118,13 +118,13 @@ Don't follow trailing symbolic links. .TP .B AT_NO_AUTOMOUNT Don't trigger automounts. -.PP +.P The .I attr argument of .BR mount_setattr () is a structure of the following form: -.PP +.P .in +4n .EX struct mount_attr { @@ -135,7 +135,7 @@ struct mount_attr { }; .EE .in -.PP +.P The .I attr_set and @@ -148,7 +148,7 @@ enable a property on a mount or mount tree, and flags set in .I attr_clr remove a property from a mount or mount tree. -.PP +.P When changing mount properties, the kernel will first clear the flags specified in the @@ -158,7 +158,7 @@ and then set the flags specified in the .I attr_set field. For example, these settings: -.PP +.P .in +4n .EX struct mount_attr attr = { @@ -167,9 +167,9 @@ struct mount_attr attr = { }; .EE .in -.PP +.P are equivalent to the following steps: -.PP +.P .in +4n .EX unsigned int current_mnt_flags = mnt\->mnt_flags; @@ -189,18 +189,18 @@ current_mnt_flags |= attr\->attr_set; mnt\->mnt_flags = current_mnt_flags; .EE .in -.PP +.P As a result of this change, the mount or mount tree (a) is read-only; (b) blocks the execution of set-user-ID and set-group-ID programs; (c) allows execution of programs; and (d) allows access to devices. -.PP +.P Multiple changes with the same set of flags requested in .I attr_clr and .I attr_set are guaranteed to be idempotent after the changes have been applied. -.PP +.P The following mount attributes can be specified in the .I attr_set or @@ -361,7 +361,7 @@ in .IR attr_clr . .IP For further details, see the subsection "ID-mapped mounts" under NOTES. -.PP +.P The .I propagation field is used to specify the propagation type of the mount or mount tree. @@ -380,7 +380,7 @@ Turn all mounts into dependent mounts. .TP .B MS_UNBINDABLE Turn all mounts into unbindable mounts. -.PP +.P For further details on the above propagation types, see .BR mount_namespaces (7). .SH RETURN VALUE @@ -597,7 +597,7 @@ visible only via a specific mount. All other users and locations where the filesystem is exposed are unaffected. It is a temporary change because the ownership changes are tied to the lifetime of the mount. -.PP +.P Whenever callers interact with the filesystem through an ID-mapped mount, the ID mapping of the mount will be applied to user and group IDs associated with filesystem objects. @@ -623,7 +623,7 @@ whenever user IDs or group IDs are stored in or .B ACL_GROUP entries. -.PP +.P The following conditions must be met in order to create an ID-mapped mount: .IP \[bu] 3 The caller must have the @@ -687,7 +687,7 @@ flag and it must not already have been visible in a mount namespace. the mount must not have been attached to the filesystem hierarchy with a system call such as .BR move_mount (2).) -.PP +.P ID mappings can be created for user IDs, group IDs, and project IDs. An ID mapping is essentially a mapping of a range of user or group IDs into another or the same range of user or group IDs. @@ -702,15 +702,15 @@ user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its ancestor user namespace. Since the map range is 1, only user ID 1000 is mapped. -.PP +.P It is possible to specify up to 340 ID mappings for each ID mapping type. If any user IDs or group IDs are not mapped, all files owned by that unmapped user or group ID will appear as being owned by the overflow user ID or overflow group ID respectively. -.PP +.P Further details on setting up ID mappings can be found in .BR user_namespaces (7). -.PP +.P In the common case, the user namespace passed in .I userns_fd (together with @@ -723,7 +723,7 @@ a user's login session as is the case for portable home directories in .BR systemd-homed.service (8)). It is also perfectly fine to create a dedicated user namespace for the sake of ID mapping a mount. -.PP +.P ID-mapped mounts can be useful in the following and a variety of other scenarios: .IP \[bu] 3 @@ -808,7 +808,7 @@ This extensibility design is very similar to other system calls such as .BR clone3 (2) and .BR openat2 (2). -.PP +.P Let .I usize be the size of the structure as specified by the user-space application, @@ -852,7 +852,7 @@ then \-1 is returned and is set to .BR E2BIG . This provides forwards-compatibility. -.PP +.P Because the definition of .I struct mount_attr may change in the future @@ -862,7 +862,7 @@ user-space applications should zero-fill to ensure that recompiling the program with new headers will not result in spurious errors at run time. The simplest way is to use a designated initializer: -.PP +.P .in +4n .EX struct mount_attr attr = { @@ -871,11 +871,11 @@ struct mount_attr attr = { }; .EE .in -.PP +.P Alternatively, the structure can be zero-filled using .BR memset (3) or similar functions: -.PP +.P .in +4n .EX struct mount_attr attr; @@ -884,7 +884,7 @@ attr.attr_set = MOUNT_ATTR_RDONLY; attr.attr_clr = MOUNT_ATTR_NODEV; .EE .in -.PP +.P A user-space application that wishes to determine which extensions the running kernel supports can do so by conducting a binary search on .I size diff --git a/man2/move_pages.2 b/man2/move_pages.2 index c2be4bb..e9627d1 100644 --- a/man2/move_pages.2 +++ b/man2/move_pages.2 @@ -1,4 +1,4 @@ -.\" SPDX-License-Identifier: Linux-man-pages-copyleft-2-para +.\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc. .\" Christoph Lameter @@ -8,7 +8,7 @@ .\" (e.g., compare with recommendation in mbind(2)). .\" Does this page need to give advice on this topic? .\" -.TH move_pages 2 2023-07-15 "Linux man-pages 6.05.01" +.TH move_pages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME move_pages \- move individual pages of a process to another node .SH LIBRARY @@ -17,7 +17,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long move_pages(int " pid ", unsigned long " count ", \ void *" pages [. count ], .BI " const int " nodes [. count "], int " status [. count "], \ @@ -36,7 +36,7 @@ The result of the move is reflected in The .I flags indicate constraints on the pages to be moved. -.PP +.P .I pid is the ID of the process in which pages are to be moved. If @@ -44,7 +44,7 @@ If is 0, then .BR move_pages () moves pages of the calling process. -.PP +.P To move pages in another process requires the following privileges: .IP \[bu] 3 Up to and including Linux 4.12: @@ -64,7 +64,7 @@ permission is governed by a ptrace access mode .B PTRACE_MODE_READ_REALCREDS check with respect to the target process; see .BR ptrace (2). -.PP +.P .I count is the number of pages to move. It defines the size of the three arrays @@ -72,7 +72,7 @@ It defines the size of the three arrays .IR nodes , and .IR status . -.PP +.P .I pages is an array of pointers to the pages that should be moved. These are pointers that should be aligned to page boundaries. @@ -80,7 +80,7 @@ These are pointers that should be aligned to page boundaries. .\" not aligned to page boundaries Addresses are specified as seen by the process specified by .IR pid . -.PP +.P .I nodes is an array of integers that specify the desired location for each page. Each element in the array is a node number. @@ -93,7 +93,7 @@ where each page currently resides, in the array. Obtaining the status of each page may be necessary to determine pages that need to be moved. -.PP +.P .I status is an array of integers that return the status of each page. The array contains valid values only if @@ -102,7 +102,7 @@ did not return an error. Preinitialization of the array to a value which cannot represent a real numa node or valid error of status array could help to identify pages that have been migrated. -.PP +.P .I flags specify what types of pages to move. .B MPOL_MF_MOVE @@ -214,7 +214,7 @@ Linux 2.6.18. .SH NOTES For information on library support, see .BR numa (7). -.PP +.P Use .BR get_mempolicy (2) with the @@ -225,7 +225,7 @@ flag to obtain the set of nodes that are allowed by the current cpuset. Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset. -.PP +.P Use of this function may result in pages whose location (node) violates the memory policy established for the specified addresses (See @@ -235,7 +235,7 @@ and/or the specified process (See That is, memory policy does not constrain the destination nodes used by .BR move_pages (). -.PP +.P The .I header is not included with glibc, but requires installing diff --git a/man2/mprotect.2 b/man2/mprotect.2 index 22aa42b..91812f5 100644 --- a/man2/mprotect.2 +++ b/man2/mprotect.2 @@ -10,7 +10,7 @@ .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and .\" a much improved example program. .\" -.TH mprotect 2 2023-05-03 "Linux man-pages 6.05.01" +.TH mprotect 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mprotect, pkey_mprotect \- set protection on a region of memory .SH LIBRARY @@ -19,12 +19,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mprotect(void " addr [. len "], size_t " len ", int " prot ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pkey_mprotect(void " addr [. len "], size_t " len ", int " prot ", int " pkey ");" .fi .SH DESCRIPTION @@ -34,12 +34,12 @@ containing any part of the address range in the interval [\fIaddr\fP,\ \fIaddr\fP+\fIlen\fP\-1]. .I addr must be aligned to a page boundary. -.PP +.P If the calling process tries to access memory in a manner that violates the protections, then the kernel generates a .B SIGSEGV signal for the process. -.PP +.P .I prot is a combination of the following access flags: .B PROT_NONE @@ -74,7 +74,7 @@ This feature is specific to the PowerPC architecture (version 2.06 of the architecture specification adds the SAO CPU feature, and it is available on POWER 7 or PowerPC A2, for example). -.PP +.P Additionally (since Linux 2.6.0), .I prot can have one of the following flags set: @@ -100,7 +100,7 @@ that grows downward (which should be a stack segment or a segment mapped with the .B MAP_GROWSDOWN flag set). -.PP +.P Like .BR mprotect (), .BR pkey_mprotect () @@ -199,14 +199,14 @@ POSIX says that the behavior of is unspecified if it is applied to a region of memory that was not obtained via .BR mmap (2). -.PP +.P On Linux, it is always permissible to call .BR mprotect () on any address in a process's address space (except for the kernel vsyscall area). In particular, it can be used to change existing code mappings to be writable. -.PP +.P Whether .B PROT_EXEC has any effect different from @@ -220,12 +220,12 @@ specifying .B PROT_READ will implicitly add .BR PROT_EXEC . -.PP +.P On some hardware architectures (e.g., i386), .B PROT_WRITE implies .BR PROT_READ . -.PP +.P POSIX.1 says that an implementation may permit access other than that specified in .IR prot , @@ -234,7 +234,7 @@ but at a minimum can allow write access only if has been set, and must not allow any access if .B PROT_NONE has been set. -.PP +.P Applications should be careful when mixing use of .BR mprotect () and @@ -247,7 +247,7 @@ set to .B PROT_EXEC a pkey may be allocated and set on the memory implicitly by the kernel, but only when the pkey was 0 previously. -.PP +.P On systems that do not support protection keys in hardware, .BR pkey_mprotect () may still be used, but @@ -280,10 +280,10 @@ The program below demonstrates the use of The program allocates four pages of memory, makes the third of these pages read-only, and then executes a loop that walks upward through the allocated region modifying bytes. -.PP +.P An example of what we might see when running the program is the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man2/mq_getsetattr.2 b/man2/mq_getsetattr.2 index b47e264..0fca73b 100644 --- a/man2/mq_getsetattr.2 +++ b/man2/mq_getsetattr.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_getsetattr 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mq_getsetattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_getsetattr \- get/set message queue attributes .SH SYNOPSIS @@ -10,13 +10,13 @@ mq_getsetattr \- get/set message queue attributes .BR "#include " " /* Definition of " "struct mq_attr" " */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_mq_getsetattr, mqd_t " mqdes , .BI " const struct mq_attr *" newattr ", struct mq_attr *" oldattr ); .fi .SH DESCRIPTION Do not use this system call. -.PP +.P This is the low-level system call used to implement .BR mq_getattr (3) and diff --git a/man2/mremap.2 b/man2/mremap.2 index f2b2b98..aa635dd 100644 --- a/man2/mremap.2 +++ b/man2/mremap.2 @@ -8,7 +8,7 @@ .\" Update for Linux 1.3.87 and later .\" 2005-10-11 mtk: Added NOTES for MREMAP_FIXED; revised EINVAL text. .\" -.TH mremap 2 2023-03-30 "Linux man-pages 6.05.01" +.TH mremap 2 2024-01-16 "Linux man-pages 6.7" .SH NAME mremap \- remap a virtual memory address .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void *mremap(void " old_address [. old_size "], size_t " old_size , .BI " size_t " new_size ", int " flags ", ... /* void *" new_address " */);" .fi @@ -27,7 +27,7 @@ Standard C library expands (or shrinks) an existing memory mapping, potentially moving it at the same time (controlled by the \fIflags\fP argument and the available virtual address space). -.PP +.P \fIold_address\fP is the old address of the virtual memory block that you want to expand (or shrink). Note that \fIold_address\fP has to be page @@ -41,11 +41,13 @@ An optional fifth argument, may be provided; see the description of .B MREMAP_FIXED below. -.PP +.P If the value of \fIold_size\fP is zero, and \fIold_address\fP refers to -a shareable mapping (see -.BR mmap (2) -.BR MAP_SHARED ), +a shareable mapping +(see the description of +.B MAP_SHARED +in +.BR mmap (2)), then .BR mremap () will create a new mapping of the same pages. @@ -57,7 +59,7 @@ below. If a new mapping is requested via this method, then the .B MREMAP_MAYMOVE flag must also be specified. -.PP +.P The \fIflags\fP bit-mask argument may be 0, or include the following flags: .TP .B MREMAP_MAYMOVE @@ -131,7 +133,7 @@ flag may be used to atomically move a mapping while leaving the source mapped. See NOTES for some possible applications of .BR MREMAP_DONTUNMAP . -.PP +.P If the memory segment specified by .I old_address and @@ -248,7 +250,7 @@ Linux. .\" 4.2BSD had a (never actually implemented) .\" .BR mremap (2) .\" call with completely different semantics. -.\" .PP +.\" .P Prior to glibc 2.4, glibc did not expose the definition of .BR MREMAP_FIXED , and the prototype for @@ -262,7 +264,7 @@ changes the mapping between virtual addresses and memory pages. This can be used to implement a very efficient .BR realloc (3). -.PP +.P In Linux, memory is divided into pages. A process has (one or) several linear virtual memory segments. @@ -276,7 +278,7 @@ if the memory is accessed incorrectly (e.g., writing to a read-only segment). Accessing virtual memory outside of the segments will also cause a segmentation violation. -.PP +.P If .BR mremap () is used to move or expand an area locked with @@ -321,7 +323,10 @@ if was zero and the mapping referred to by .I old_address was a private mapping -.RB ( mmap "(2) " MAP_PRIVATE ), +(see the description of +.B MAP_PRIVATE +in +.BR mmap (2)), .BR mremap () created a new private mapping unrelated to the original mapping. This behavior was unintended @@ -344,7 +349,7 @@ in this scenario. .BR sbrk (2), .BR malloc (3), .BR realloc (3) -.PP +.P Your favorite text book on operating systems for more information on paged memory (e.g., \fIModern Operating Systems\fP by Andrew S.\& Tanenbaum, diff --git a/man2/msgctl.2 b/man2/msgctl.2 index b905b0f..27aca82 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -16,7 +16,7 @@ .\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions .\" 2018-03-20, dbueso: Added MSG_STAT_ANY description. .\" -.TH msgctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH msgctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME msgctl \- System V message control operations .SH LIBRARY @@ -25,20 +25,20 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf ); +.P +.BI "int msgctl(int " msqid ", int " op ", struct msqid_ds *" buf ); .fi .SH DESCRIPTION .BR msgctl () performs the control operation specified by -.I cmd +.I op on the System\ V message queue with identifier .IR msqid . -.PP +.P The .I msqid_ds data structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct msqid_ds { @@ -55,7 +55,7 @@ struct msqid_ds { }; .EE .in -.PP +.P The fields of the .I msqid_ds structure are as follows: @@ -102,13 +102,13 @@ system call. ID of the process that performed the last .BR msgrcv (2) system call. -.PP +.P The .I ipc_perm structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): -.PP +.P .in +4n .EX struct ipc_perm { @@ -122,7 +122,7 @@ struct ipc_perm { }; .EE .in -.PP +.P The least significant 9 bits of the .I mode field of the @@ -138,11 +138,11 @@ l l. 0004 Read by others 0002 Write by others .TE -.PP +.P Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. -.PP +.P Valid values for -.I cmd +.I op are: .TP .B IPC_STAT @@ -312,7 +312,7 @@ or .B MSG_STAT_ANY operation returns the identifier of the queue whose index was given in .IR msqid . -.PP +.P On failure, \-1 is returned and .I errno is set to indicate the error. @@ -320,7 +320,7 @@ is set to indicate the error. .TP .B EACCES The argument -.I cmd +.I op is equal to .B IPC_STAT or @@ -333,7 +333,7 @@ capability in the user namespace that governs its IPC namespace. .TP .B EFAULT The argument -.I cmd +.I op has the value .B IPC_SET or @@ -347,7 +347,7 @@ The message queue was removed. .TP .B EINVAL Invalid value for -.I cmd +.I op or .IR msqid . Or: for a @@ -358,7 +358,7 @@ referred to an array slot that is currently unused. .TP .B EPERM The argument -.I cmd +.I op has the value .B IPC_SET or @@ -389,7 +389,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVID does not document the EIDRM error condition. -.PP +.P Various fields in the \fIstruct msqid_ds\fP were typed as .I short @@ -402,7 +402,7 @@ a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an .B IPC_64 flag in -.IR cmd .) +.IR op .) .SH NOTES The .BR IPC_INFO , diff --git a/man2/msgget.2 b/man2/msgget.2 index 0774f49..4a871d8 100644 --- a/man2/msgget.2 +++ b/man2/msgget.2 @@ -12,7 +12,7 @@ .\" Language and formatting clean-ups .\" Added notes on /proc files .\" -.TH msgget 2 2023-03-30 "Linux man-pages 6.05.01" +.TH msgget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME msgget \- get a System V message queue identifier .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int msgget(key_t " key ", int " msgflg ); .fi .SH DESCRIPTION @@ -39,7 +39,7 @@ is zero and does not have the value .BR IPC_PRIVATE ), or to create a new set. -.PP +.P A new message queue is created if .I key has the value @@ -54,7 +54,7 @@ exists, and .B IPC_CREAT is specified in .IR msgflg . -.PP +.P If .I msgflg specifies both @@ -73,7 +73,7 @@ set to .B O_CREAT | O_EXCL for .BR open (2).) -.PP +.P Upon creation, the least significant bits of the argument .I msgflg define the permissions of the message queue. @@ -83,7 +83,7 @@ as the permissions specified for the argument of .BR open (2). (The execute permissions are not used.) -.PP +.P If a new message queue is created, then its associated data structure .I msqid_ds @@ -120,7 +120,7 @@ is set to the current time. .I msg_qbytes is set to the system limit .BR MSGMNB . -.PP +.P If the message queue already exists the permissions are verified, and a check is made to see if it is marked for destruction. @@ -187,7 +187,7 @@ If this special value is used for the system call ignores everything but the least significant 9 bits of .I msgflg and creates a new message queue (on success). -.PP +.P The following is a system limit on message queue resources affecting a .BR msgget () call: diff --git a/man2/msgop.2 b/man2/msgop.2 index 381875e..e09c632 100644 --- a/man2/msgop.2 +++ b/man2/msgop.2 @@ -17,7 +17,7 @@ .\" Language and formatting clean-ups .\" Added notes on /proc files .\" -.TH MSGOP 2 2023-05-03 "Linux man-pages 6.05.01" +.TH MSGOP 2 2023-10-31 "Linux man-pages 6.7" .SH NAME msgrcv, msgsnd \- System V message queue operations .SH LIBRARY @@ -26,10 +26,10 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int msgsnd(int " msqid ", const void " msgp [. msgsz "], size_t " msgsz , .BI " int " msgflg ); -.PP +.P .BI "ssize_t msgrcv(int " msqid ", void " msgp [. msgsz "], size_t " msgsz \ ", long " msgtyp , .BI " int " msgflg ); @@ -43,12 +43,12 @@ system calls are used to send messages to, and receive messages from, a System\ V message queue. The calling process must have write permission on the message queue in order to send a message, and read permission to receive a message. -.PP +.P The .I msgp argument is a pointer to a caller-defined structure of the following general form: -.PP +.P .in +4n .EX struct msgbuf { @@ -57,7 +57,7 @@ struct msgbuf { }; .EE .in -.PP +.P The .I mtext field is an array (or other structure) whose size is specified by @@ -82,7 +82,7 @@ system call appends a copy of the message pointed to by to the message queue whose identifier is specified by .IR msqid . -.PP +.P If sufficient space is available in the queue, .BR msgsnd () succeeds immediately. @@ -109,7 +109,7 @@ This check is necessary to prevent an unlimited number of zero-length messages being placed on the queue. Although such messages contain no data, they nevertheless consume (locked) kernel memory. -.PP +.P If insufficient space is available in the queue, then the default behavior of .BR msgsnd () @@ -120,7 +120,7 @@ is specified in .IR msgflg , then the call instead fails with the error .BR EAGAIN . -.PP +.P A blocked .BR msgsnd () call may also fail if: @@ -143,7 +143,7 @@ is never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler.) -.PP +.P Upon successful completion the message queue data structure is updated as follows: .IP \[bu] 3 @@ -163,7 +163,7 @@ system call removes a message from the queue specified by and places it in the buffer pointed to by .IR msgp . -.PP +.P The argument .I msgsz specifies the maximum size in bytes for the member @@ -189,7 +189,7 @@ the system call fails returning \-1 with .I errno set to .BR E2BIG . -.PP +.P Unless .B MSG_COPY is specified in @@ -225,7 +225,7 @@ then the first message in the queue with the lowest type less than or equal to the absolute value of .I msgtyp will be read. -.PP +.P The .I msgflg argument is a bit mask constructed by ORing together zero or more @@ -279,7 +279,7 @@ from To truncate the message text if longer than .I msgsz bytes. -.PP +.P If no message of the requested type is available and .B IPC_NOWAIT isn't specified in @@ -304,7 +304,7 @@ is never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler.) -.PP +.P Upon successful completion the message queue data structure is updated as follows: .IP @@ -372,7 +372,7 @@ value (less than 0 or greater than the system value The system does not have enough memory to make a copy of the message pointed to by .IR msgp . -.PP +.P .BR msgrcv () can fail with the following errors: .TP @@ -451,7 +451,7 @@ and this kernel was configured without .BR CONFIG_CHECKPOINT_RESTORE . .SH STANDARDS POSIX.1-2008. -.PP +.P The .B MSG_EXCEPT and @@ -463,7 +463,7 @@ their definitions can be obtained by defining the feature test macro. .SH HISTORY POSIX.1-2001, SVr4. -.PP +.P The .I msgp argument is declared as \fIstruct msgbuf\ *\fP in @@ -495,7 +495,7 @@ using the .BR msgctl (2) .B IPC_SET operation. -.PP +.P The implementation has no intrinsic system-wide limits on the number of message headers .RB ( MSGTQL ) @@ -521,7 +521,7 @@ of whether that message was at the ordinal position This bug is fixed .\" commit 4f87dac386cc43d5525da7a939d4b4e7edbea22c in Linux 3.14. -.PP +.P Specifying both .B MSG_COPY and @@ -542,18 +542,18 @@ The program below demonstrates the use of .BR msgsnd () and .BR msgrcv (). -.PP +.P The example program is first run with the \fB\-s\fP option to send a message and then run again with the \fB\-r\fP option to receive a message. -.PP +.P The following shell session shows a sample run of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out \-s" sent: a message at Wed Mar 4 16:25:45 2015 -.PP +.P .RB "$" " ./a.out \-r" message received: a message at Wed Mar 4 16:25:45 2015 .EE diff --git a/man2/msync.2 b/man2/msync.2 index baa328d..64dffbd 100644 --- a/man2/msync.2 +++ b/man2/msync.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH msync 2 2023-03-30 "Linux man-pages 6.05.01" +.TH msync 2 2023-10-31 "Linux man-pages 6.7" .SH NAME msync \- synchronize a file with a memory map .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int msync(void " addr [. length "], size_t " length ", int " flags ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ corresponds to the memory area starting at and having length .I length is updated. -.PP +.P The .I flags argument should specify exactly one of @@ -112,14 +112,14 @@ in POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P This call was introduced in Linux 1.3.21, and then used .B EFAULT instead of .BR ENOMEM . In Linux 2.4.19, this was changed to the POSIX value .BR ENOMEM . -.PP +.P On POSIX systems on which .BR msync () is available, both @@ -136,5 +136,5 @@ to a value greater than 0. .\" glibc defines them to 1. .SH SEE ALSO .BR mmap (2) -.PP +.P B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\[en]129 and 389\[en]391. diff --git a/man2/nanosleep.2 b/man2/nanosleep.2 index 4693dc8..61242ea 100644 --- a/man2/nanosleep.2 +++ b/man2/nanosleep.2 @@ -12,7 +12,7 @@ .\" NOTES: describe case where clock_nanosleep() can be preferable. .\" NOTES: describe CLOCK_REALTIME versus CLOCK_NANOSLEEP .\" Replace crufty discussion of HZ with a pointer to time(7). -.TH nanosleep 2 2023-03-30 "Linux man-pages 6.05.01" +.TH nanosleep 2 2024-03-03 "Linux man-pages 6.7" .SH NAME nanosleep \- high-resolution sleep .SH LIBRARY @@ -21,16 +21,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int nanosleep(const struct timespec *" req , +.P +.BI "int nanosleep(const struct timespec *" duration , .BI " struct timespec *_Nullable " rem ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nanosleep (): .nf _POSIX_C_SOURCE >= 199309L @@ -39,11 +39,11 @@ Feature Test Macro Requirements for glibc (see .BR nanosleep () suspends the execution of the calling thread until either at least the time specified in -.I *req +.I *duration has elapsed, or the delivery of a signal that triggers the invocation of a handler in the calling thread or that terminates the process. -.PP +.P If the call is interrupted by a signal handler, .BR nanosleep () returns \-1, sets @@ -60,14 +60,14 @@ The value of can then be used to call .BR nanosleep () again and complete the specified pause (but see NOTES). -.PP +.P The .BR timespec (3) structure is used to specify intervals of time with nanosecond precision. -.PP +.P The value of the nanoseconds field must be in the range [0, 999999999]. -.PP +.P Compared to .BR sleep (3) and @@ -80,7 +80,7 @@ does not interact with signals; and it makes the task of resuming a sleep that has been interrupted by a signal handler easier. .SH RETURN VALUE -On successfully sleeping for the requested interval, +On successfully sleeping for the requested duration, .BR nanosleep () returns 0. If the call is interrupted by a signal handler or encounters an error, @@ -128,7 +128,7 @@ says that discontinuous changes in should not affect .BR nanosleep (): .RS -.PP +.P Setting the value of the .B CLOCK_REALTIME clock via @@ -138,14 +138,15 @@ have no effect on threads that are blocked waiting for a relative time service based upon this clock, including the .BR nanosleep () function; ... -Consequently, these time services shall expire when the requested relative -interval elapses, independently of the new or old value of the clock. +Consequently, +these time services shall expire when the requested duration elapses, +independently of the new or old value of the clock. .RE .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P In order to support applications requiring much more precise pauses (e.g., in order to control some time-critical hardware), .BR nanosleep () @@ -158,14 +159,14 @@ or This special extension was removed in Linux 2.5.39, and is thus not available in Linux 2.6.0 and later kernels. .SH NOTES -If the interval specified in -.I req +If the +.I duration is not an exact multiple of the granularity underlying clock (see .BR time (7)), then the interval will be rounded up to the next multiple. Furthermore, after the sleep completes, there may still be a delay before the CPU becomes free to once again execute the calling thread. -.PP +.P The fact that .BR nanosleep () sleeps for a relative interval can be problematic if the call @@ -194,7 +195,7 @@ To avoid such problems, use with the .B TIMER_ABSTIME flag to sleep to an absolute deadline. -.PP +.P In Linux 2.4, if .BR nanosleep () is stopped by a signal (e.g., diff --git a/man2/nfsservctl.2 b/man2/nfsservctl.2 index 5267f81..c0d4965 100644 --- a/man2/nfsservctl.2 +++ b/man2/nfsservctl.2 @@ -2,7 +2,7 @@ .\" This text is in the public domain. .\" %%%LICENSE_END .\" -.TH nfsservctl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH nfsservctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME nfsservctl \- syscall interface to kernel nfs daemon .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long nfsservctl(int " cmd ", struct nfsctl_arg *" argp , .BI " union nfsctl_res *" resp ); .fi @@ -22,7 +22,7 @@ It has been replaced by a set of files in the .I nfsd filesystem; see .BR nfsd (7). -.PP +.P .in +4n .EX /* diff --git a/man2/nice.2 b/man2/nice.2 index d26a1be..3e5854b 100644 --- a/man2/nice.2 +++ b/man2/nice.2 @@ -8,7 +8,7 @@ .\" Modified 2001-06-04 by aeb .\" Modified 2004-05-27 by Michael Kerrisk .\" -.TH nice 2 2023-03-30 "Linux man-pages 6.05.01" +.TH nice 2 2023-10-31 "Linux man-pages 6.7" .SH NAME nice \- change process priority .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int nice(int " inc ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nice (): .nf _XOPEN_SOURCE @@ -38,10 +38,10 @@ adds .I inc to the nice value for the calling thread. (A higher nice value means a lower priority.) -.PP +.P The range of the nice value is +19 (low priority) to \-20 (high priority). Attempts to set a nice value outside the range are clamped to the range. -.PP +.P Traditionally, only a privileged process could lower the nice value (i.e., set a higher priority). However, since Linux 2.6.12, an unprivileged process can decrease @@ -55,7 +55,7 @@ On success, the new nice value is returned (but see NOTES below). On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P A successful call can legitimately return \-1. To detect an error, set .I errno @@ -85,7 +85,7 @@ However, the raw Linux system call returns 0 on success. Likewise, the .BR nice () wrapper function provided in glibc 2.2.3 and earlier returns 0 on success. -.PP +.P Since glibc 2.2.4, the .BR nice () wrapper function provided by glibc provides conformance to POSIX.1 by calling @@ -101,7 +101,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .SH NOTES For further details on the nice value, see .BR sched (7). -.PP +.P .IR Note : the addition of the "autogroup" feature in Linux 2.6.38 means that the nice value no longer has its traditional effect in many circumstances. diff --git a/man2/open.2 b/man2/open.2 index 52286f6..a6982fa 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -28,7 +28,7 @@ .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and .\" O_TTYINIT. Eventually these may need to be documented. --mtk .\" -.TH open 2 2023-05-20 "Linux man-pages 6.05.01" +.TH open 2 2024-01-16 "Linux man-pages 6.7" .SH NAME open, openat, creat \- open and possibly create a file .SH LIBRARY @@ -37,25 +37,27 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int open(const char *" pathname ", int " flags ", ..." .BI " \fR/*\fP mode_t " mode " \fR*/\fP );" -.PP +.P .BI "int creat(const char *" pathname ", mode_t " mode ); -.PP +.P .BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..." .BI " \fR/*\fP mode_t " mode " \fR*/\fP );" -.PP -/* Documented separately, in \fBopenat2\fP(2): */ +.P +/* Documented separately, in \c +.BR openat2 (2):\c +\& */ .BI "int openat2(int " dirfd ", const char *" pathname , .BI " const struct open_how *" how ", size_t " size ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR openat (): .nf Since glibc 2.10: @@ -75,18 +77,23 @@ is specified in .IR flags ) be created by .BR open (). -.PP +.P The return value of .BR open () is a file descriptor, a small, nonnegative integer that is an index to an entry in the process's table of open file descriptors. The file descriptor is used in subsequent system calls -.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2), -etc.) to refer to the open file. +(\c +.BR read (2), +.BR write (2), +.BR lseek (2), +.BR fcntl (2), +etc.) +to refer to the open file. The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process. -.PP +.P By default, the new file descriptor is set to remain open across an .BR execve (2) (i.e., the @@ -98,7 +105,7 @@ is initially disabled); the flag, described below, can be used to change this default. The file offset is set to the beginning of the file (see .BR lseek (2)). -.PP +.P A call to .BR open () creates a new @@ -111,7 +118,7 @@ this reference is unaffected if .I pathname is subsequently removed or modified to refer to a different file. For further details on open file descriptions, see NOTES. -.PP +.P The argument .I flags must include one of the following @@ -119,7 +126,7 @@ must include one of the following .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR . These request opening the file read-only, write-only, or read/write, respectively. -.PP +.P In addition, zero or more file creation flags and file status flags can be bitwise ORed @@ -159,7 +166,7 @@ The file status flags can be retrieved and (in some cases) modified; see .BR fcntl (2) for details. -.PP +.P The full list of file creation flags and file status flags is as follows: .TP .B O_APPEND @@ -907,7 +914,7 @@ The system call operates in exactly the same way as .BR open (), except for the differences described here. -.PP +.P The .I dirfd argument is used in conjunction with the @@ -948,7 +955,7 @@ must be a directory that was opened for reading or using the .B O_PATH flag. -.PP +.P If the pathname given in .I pathname is relative, and @@ -1309,7 +1316,7 @@ Regardless of whether an implementation supports this option, it must at least support the use of .B O_SYNC for regular files. -.PP +.P Linux implements .B O_SYNC and @@ -1324,7 +1331,7 @@ to have the same value as is defined in the Linux header file .I on HP PA-RISC, but it is not used.) -.PP +.P .B O_SYNC provides synchronized I/O .I file @@ -1342,7 +1349,7 @@ to allow a subsequent read operation to complete successfully. Data integrity completion can reduce the number of disk operations that are required for applications that don't need the guarantees of file integrity completion. -.PP +.P To understand the difference between the two types of completion, consider two pieces of file metadata: the file last modification timestamp @@ -1359,7 +1366,7 @@ would only guarantee to flush updates to the file length metadata (whereas .B O_SYNC would also always flush the last modification timestamp metadata). -.PP +.P Before Linux 2.6.33, Linux implemented only the .B O_SYNC flag for @@ -1371,7 +1378,7 @@ integrity completion (i.e., .B O_SYNC was actually implemented as the equivalent of .BR O_DSYNC ). -.PP +.P Since Linux 2.6.33, proper .B O_SYNC support is provided. @@ -1408,10 +1415,10 @@ For certain architectures, this is also true before glibc 2.26. .TQ .BR openat () POSIX.1-2008. -.PP +.P .BR openat2 (2) Linux. -.PP +.P The .BR O_DIRECT , .BR O_NOATIME , @@ -1422,7 +1429,7 @@ flags are Linux-specific. One must define .B _GNU_SOURCE to obtain their definitions. -.PP +.P The .BR O_CLOEXEC , .BR O_DIRECTORY , @@ -1457,7 +1464,7 @@ For example, this may be used to open a device in order to get a file descriptor for use with .BR ioctl (2). -.PP +.P Note that .BR open () can open device special files, but @@ -1465,7 +1472,7 @@ can open device special files, but cannot create them; use .BR mknod (2) instead. -.PP +.P If the file is newly created, its .IR st_atime , .IR st_ctime , @@ -1488,7 +1495,7 @@ flag, its and .I st_mtime fields are set to the current time. -.PP +.P The files in the .IR /proc/ pid /fd directory show the open file descriptors of the process with the PID @@ -1499,7 +1506,7 @@ directory show even more information about these file descriptors. See .BR proc (5) for further details of both of these directories. -.PP +.P The Linux header file .B doesn't define @@ -1517,7 +1524,7 @@ variously also called an "open file object", a "file handle", an "open file table entry", or\[em]in kernel-developer parlance\[em]a .IR "struct file" . -.PP +.P When a file descriptor is duplicated (using .BR dup (2) or similar), @@ -1530,13 +1537,13 @@ a child process created via .BR fork (2) inherits duplicates of its parent's file descriptors, and those duplicates refer to the same open file descriptions. -.PP +.P Each .BR open () of a file creates a new open file description; thus, there may be multiple open file descriptions corresponding to a file inode. -.PP +.P On Linux, one can use the .BR kcmp (2) .B KCMP_FILE @@ -1548,7 +1555,7 @@ refer to the same open file description. There are many infelicities in the protocol underlying NFS, affecting amongst others .BR O_SYNC " and " O_NDELAY . -.PP +.P On NFS filesystems with UID mapping enabled, .BR open () may @@ -1587,7 +1594,7 @@ In other words, the combination .B "O_RDONLY | O_WRONLY" is a logical error, and certainly does not have the same meaning as .BR O_RDWR . -.PP +.P Linux reserves the special, nonstandard access mode 3 (binary 11) in .I flags to mean: @@ -1639,7 +1646,7 @@ address two problems with the older interfaces that preceded them. Here, the explanation is in terms of the .BR openat () call, but the rationale is analogous for the other interfaces. -.PP +.P First, .BR openat () allows an application to avoid race conditions that could @@ -1680,7 +1687,7 @@ even if the directory is renamed; and the open file descriptor prevents the underlying filesystem from being dismounted, just as when a process has a current working directory on a filesystem. -.PP +.P Second, .BR openat () allows the implementation of a per-thread "current working @@ -1689,7 +1696,7 @@ directory", via file descriptor(s) maintained by the application. on the use of .IR /proc/self/fd/ dirfd, but less efficiently.) -.PP +.P The .I dirfd argument for these APIs can be obtained by using @@ -1705,7 +1712,7 @@ Alternatively, such a file descriptor can be obtained by applying .BR dirfd (3) to a directory stream created using .BR opendir (3). -.PP +.P When these APIs are given a .I dirfd argument of @@ -1733,7 +1740,7 @@ I/Os also varies; they can either fail with .B EINVAL or fall back to buffered I/O. -.PP +.P Since Linux 6.1, .B O_DIRECT support and alignment restrictions for a file can be queried using @@ -1746,7 +1753,7 @@ Support for varies by filesystem; see .BR statx (2). -.PP +.P Some filesystems provide their own interfaces for querying .B O_DIRECT alignment restrictions, @@ -1756,7 +1763,7 @@ operation in .BR xfsctl (3). .B STATX_DIOALIGN should be used instead when it is available. -.PP +.P If none of the above is available, then direct I/O support and alignment restrictions can only be assumed from known characteristics of the filesystem, @@ -1775,13 +1782,13 @@ A block device's logical block size can be determined using the .BR ioctl (2) .B BLKSSZGET operation or from the shell using the command: -.PP +.P .in +4n .EX blockdev \-\-getss .EE .in -.PP +.P .B O_DIRECT I/Os should never be run concurrently with the .BR fork (2) @@ -1815,7 +1822,7 @@ with ensuring that it will not be available to the child after .BR fork (2). -.PP +.P The .B O_DIRECT flag was introduced in SGI IRIX, where it has alignment @@ -1825,7 +1832,7 @@ IRIX has also a call to query appropriate alignments, and sizes. FreeBSD 4.x introduced a flag of the same name, but without alignment restrictions. -.PP +.P .B O_DIRECT support was added in Linux 2.4.10. Older Linux kernels simply ignore this flag. @@ -1834,7 +1841,7 @@ Some filesystems may not implement the flag, in which case fails with the error .B EINVAL if it is used. -.PP +.P Applications should avoid mixing .B O_DIRECT and normal I/O to the same file, @@ -1845,7 +1852,7 @@ using either mode alone. Likewise, applications should avoid mixing .BR mmap (2) of files with direct I/O to the same files. -.PP +.P The behavior of .B O_DIRECT with NFS will differ from local filesystems. @@ -1867,7 +1874,7 @@ in the event of server power failure. The Linux NFS client places no alignment restrictions on .B O_DIRECT I/O. -.PP +.P In summary, .B O_DIRECT is a potentially powerful tool that should be used with caution. @@ -1885,7 +1892,7 @@ use to enable this flag. .\" FIXME . Check bugzilla report on open(O_ASYNC) .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993 -.PP +.P One must check for two different error codes, .B EISDIR and @@ -1893,7 +1900,7 @@ and when trying to determine whether the kernel supports .B O_TMPFILE functionality. -.PP +.P When both .B O_CREAT and diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index b5e3d75..26bb9c2 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH open_by_handle_at 2 2023-05-03 "Linux man-pages 6.05.01" +.TH open_by_handle_at 2 2023-10-31 "Linux man-pages 6.7" .SH NAME name_to_handle_at, open_by_handle_at \- obtain handle for a pathname and open file via a handle @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int name_to_handle_at(int " dirfd ", const char *" pathname , .BI " struct file_handle *" handle , .BI " int *" mount_id ", int " flags ); @@ -48,7 +48,7 @@ arguments. The file handle is returned via the argument .IR handle , which is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct file_handle { @@ -59,7 +59,7 @@ struct file_handle { }; .EE .in -.PP +.P It is the caller's responsibility to allocate the structure with a size large enough to hold the handle returned in .IR f_handle . @@ -78,7 +78,7 @@ Upon successful return, the .I handle_bytes field is updated to contain the number of bytes actually written to .IR f_handle . -.PP +.P The caller can discover the required size for the .I file_handle structure by making a call in which @@ -100,7 +100,7 @@ This case can be detected when the error is returned without .I handle_bytes being increased. -.PP +.P Other than the use of the .I handle_bytes field, the caller should treat the @@ -109,17 +109,44 @@ structure as an opaque data type: the .I handle_type and .I f_handle -fields are needed only by a subsequent call to +fields can be used in a subsequent call to .BR open_by_handle_at (). -.PP +The caller can also use the opaque +.I file_handle +to compare the identity of filesystem objects +that were queried at different times and possibly +at different paths. +The +.BR fanotify (7) +subsystem can report events +with an information record containing a +.I file_handle +to identify the filesystem object. +.P The .I flags argument is a bit mask constructed by ORing together zero or more of -.B AT_EMPTY_PATH +.BR AT_HANDLE_FID , +.BR AT_EMPTY_PATH , and .BR AT_SYMLINK_FOLLOW , described below. -.PP +.P +When +.I flags +contain the +.BR AT_HANDLE_FID " (since Linux 6.5)" +.\" commit 96b2b072ee62be8ae68c8ecf14854c4d0505a8f8 +flag, the caller indicates that the returned +.I file_handle +is needed to identify the filesystem object, +and not for opening the file later, +so it should be expected that a subsequent call to +.BR open_by_handle_at () +with the returned +.I file_handle +may fail. +.P Together, the .I pathname and @@ -172,7 +199,7 @@ or .BR AT_FDCWD , meaning the current working directory, and a handle is returned for the file to which it refers. -.PP +.P The .I mount_id argument returns an identifier for the filesystem @@ -188,7 +215,7 @@ that file descriptor can be used in a subsequent call to is returned both for a successful call and for a call that results in the error .BR EOVERFLOW . -.PP +.P By default, .BR name_to_handle_at () does not dereference @@ -201,7 +228,7 @@ is specified in .I pathname is dereferenced if it is a symbolic link (so that the call returns a handle for the file referred to by the link). -.PP +.P .BR name_to_handle_at () does not trigger a mount when the final component of the pathname is an automount point. @@ -225,7 +252,7 @@ system call opens the file referred to by .IR handle , a file handle returned by a previous call to .BR name_to_handle_at (). -.PP +.P The .I mount_fd argument is a file descriptor for any object (file, directory, etc.) @@ -235,7 +262,7 @@ should be interpreted. The special value .B AT_FDCWD can be specified, meaning the current working directory of the caller. -.PP +.P The .I flags argument @@ -248,7 +275,7 @@ refers to a symbolic link, the caller must specify the flag, and the symbolic link is not dereferenced; the .B O_NOFOLLOW flag, if specified, is ignored. -.PP +.P The caller must have the .B CAP_DAC_READ_SEARCH capability to invoke @@ -260,7 +287,7 @@ returns 0, and .BR open_by_handle_at () returns a file descriptor (a nonnegative integer). -.PP +.P In the event of an error, both system calls return \-1 and set .I errno to indicate the error. @@ -271,7 +298,7 @@ and can fail for the same errors as .BR openat (2). In addition, they can fail with the errors noted below. -.PP +.P .BR name_to_handle_at () can fail with the following errors: .TP @@ -322,7 +349,7 @@ When this error occurs, is updated to indicate the required size for the handle. .\" .\" -.PP +.P .BR open_by_handle_at () can fail with the following errors: .TP @@ -363,8 +390,14 @@ capability. .B ESTALE The specified .I handle -is not valid. +is not valid for opening a file. This error will occur if, for example, the file has been deleted. +This error can also occur if the +.I handle +was acquired using the +.B AT_HANDLE_FID +flag and the filesystem does not support +.BR open_by_handle_at (). .SH VERSIONS FreeBSD has a broadly similar pair of system calls in the form of .BR getfh () @@ -380,20 +413,23 @@ A file handle can be generated in one process using .BR name_to_handle_at () and later used in a different process that calls .BR open_by_handle_at (). -.PP +.P Some filesystem don't support the translation of pathnames to file handles, for example, .IR /proc , .IR /sys , and various network filesystems. -.PP +Some filesystems support the translation of pathnames to +file handles, but do not support using those file handles in +.BR open_by_handle_at (). +.P A file handle may become invalid ("stale") if a file is deleted, or for other filesystem-specific reasons. Invalid handles are notified by an .B ESTALE error from .BR open_by_handle_at (). -.PP +.P These system calls are designed for use by user-space file servers. For example, a user-space NFS server might generate a file handle and pass it to an NFS client. @@ -403,7 +439,7 @@ it could pass the handle back to the server. .\" "Open by handle" - Jonathan Corbet, 2010-02-23 This sort of functionality allows a user-space file server to operate in a stateless fashion with respect to the files it serves. -.PP +.P If .I pathname refers to a symbolic link and @@ -439,7 +475,7 @@ However, an application can use the information in the .I mountinfo record that corresponds to the mount ID to derive a persistent identifier. -.PP +.P For example, one can use the device name in the fifth field of the .I mountinfo record to search for the corresponding device UUID via the symbolic links in @@ -467,7 +503,7 @@ uses to obtain the file handle and mount ID for the file specified in its command-line argument; the handle and mount ID are written to standard output. -.PP +.P The second program .RI ( t_open_by_handle_at.c ) reads a mount ID and file handle from standard input. @@ -487,9 +523,9 @@ to find a record whose mount ID matches the mount ID read from standard input, and the mount directory specified in that record is opened. (These programs do not deal with the fact that mount IDs are not persistent.) -.PP +.P The following shell session demonstrates the use of these two programs: -.PP +.P .in +4n .EX $ \fBecho \[aq]Can you please think about it?\[aq] > cecilia.txt\fP @@ -501,7 +537,7 @@ Read 31 bytes $ \fBrm cecilia.txt\fP .EE .in -.PP +.P Now we delete and (quickly) re-create the file so that it has the same content and (by chance) the same inode. Nevertheless, @@ -510,7 +546,7 @@ Nevertheless, .\" counter that gets incremented in this case. recognizes that the original file referred to by the file handle no longer exists. -.PP +.P .in +4n .EX $ \fBstat \-\-printf="%i\en" cecilia.txt\fP # Display inode number @@ -739,7 +775,7 @@ main(int argc, char *argv[]) .BR blkid (8), .BR findfs (8), .BR mount (8) -.PP +.P The .I libblkid and diff --git a/man2/openat2.2 b/man2/openat2.2 index b98bbaf..4a19439 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -1,7 +1,7 @@ .\" Copyright (C) 2019 Aleksa Sarai .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH openat2 2 2023-04-23 "Linux man-pages 6.05.01" +.TH openat2 2 2024-02-25 "Linux man-pages 6.7" .SH NAME openat2 \- open and possibly create a file (extended) .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include " " /* Definition of " RESOLVE_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname , .BI " struct open_how *" how ", size_t " size ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR openat2 (), @@ -30,7 +30,7 @@ The system call is an extension of .BR openat (2) and provides a superset of its functionality. -.PP +.P The .BR openat2 () system call opens the file specified by @@ -40,7 +40,7 @@ If the specified file does not exist, it may optionally (if is specified in .IR how.flags ) be created. -.PP +.P As with .BR openat (2), if @@ -64,7 +64,7 @@ in which case .I pathname is resolved relative to .IR dirfd ). -.PP +.P Rather than taking a single .I flags argument, an extensible structure (\fIhow\fP) is passed to allow for @@ -90,7 +90,7 @@ This argument is a pointer to an structure, described in .BR open_how (2type). -.PP +.P Any future extensions to .BR openat2 () will be implemented as new fields appended to the @@ -105,7 +105,7 @@ initialization. (See the "Extensibility" section of the .B NOTES for more detail on why this is necessary.) -.PP +.P The fields of the .I open_how structure are as follows: @@ -374,7 +374,7 @@ in the kernel's lookup cache. If any kind of revalidation or I/O is needed to satisfy the lookup, .BR openat2 () fails with the error -.B EAGAIN . +.BR EAGAIN . This is useful in providing a fast-path open that can be performed without resorting to thread offload, or other mechanisms that an application might use to offload slower operations. @@ -421,7 +421,7 @@ information. The caller should retry without .B RESOLVE_CACHED set in -.I how.resolve . +.IR how.resolve . .TP .B EINVAL An unknown flag or invalid value was specified in @@ -471,7 +471,7 @@ Linux. .SH HISTORY Linux 5.6. .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179 -.PP +.P The semantics of .B RESOLVE_BENEATH were modeled after FreeBSD's @@ -495,7 +495,7 @@ This extensibility design is very similar to other system calls such as .BR perf_event_open (2), and .BR clone3 (2). -.PP +.P If we let .I usize be the size of the structure as specified by the user-space application, and @@ -538,7 +538,7 @@ If any unsupported extension fields are nonzero, then \-1 is returned and is set to .BR E2BIG . This provides forwards-compatibility. -.PP +.P Because the definition of .I struct open_how may change in the future (with new fields being added when system headers are @@ -548,18 +548,18 @@ to ensure that recompiling the program with new headers will not result in spurious errors at run time. The simplest way is to use a designated initializer: -.PP +.P .in +4n .EX struct open_how how = { .flags = O_RDWR, .resolve = RESOLVE_IN_ROOT }; .EE .in -.PP +.P or explicitly using .BR memset (3) or similar: -.PP +.P .in +4n .EX struct open_how how; @@ -568,7 +568,7 @@ how.flags = O_RDWR; how.resolve = RESOLVE_IN_ROOT; .EE .in -.PP +.P A user-space application that wishes to determine which extensions the running kernel supports can do so by conducting a binary search on .I size diff --git a/man2/outb.2 b/man2/outb.2 index 4a3f877..ce39f5a 100644 --- a/man2/outb.2 +++ b/man2/outb.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH outb 2 2023-03-30 "Linux man-pages 6.05.01" +.TH outb 2 2023-10-31 "Linux man-pages 6.7" .SH NAME outb, outw, outl, outsb, outsw, outsl, inb, inw, inl, insb, insw, insl, @@ -15,21 +15,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "unsigned char inb(unsigned short " port ); .BI "unsigned char inb_p(unsigned short " port ); .BI "unsigned short inw(unsigned short " port ); .BI "unsigned short inw_p(unsigned short " port ); .BI "unsigned int inl(unsigned short " port ); .BI "unsigned int inl_p(unsigned short " port ); -.PP +.P .BI "void outb(unsigned char " value ", unsigned short " port ); .BI "void outb_p(unsigned char " value ", unsigned short " port ); .BI "void outw(unsigned short " value ", unsigned short " port ); .BI "void outw_p(unsigned short " value ", unsigned short " port ); .BI "void outl(unsigned int " value ", unsigned short " port ); .BI "void outl_p(unsigned int " value ", unsigned short " port ); -.PP +.P .BI "void insb(unsigned short " port ", void " addr [. count ], .BI " unsigned long " count ); .BI "void insw(unsigned short " port ", void " addr [. count ], @@ -48,18 +48,18 @@ This family of functions is used to do low-level port input and output. The out* functions do port output, the in* functions do port input; the b-suffix functions are byte-width and the w-suffix functions word-width; the _p-suffix functions pause until the I/O completes. -.PP +.P They are primarily designed for internal kernel use, but can be used from user space. .\" , given the following information .\" in addition to that given in .\" .BR outb (9). -.PP +.P You must compile with \fB\-O\fP or \fB\-O2\fP or similar. The functions are defined as inline macros, and will not be substituted in without optimization enabled, causing unresolved references at link time. -.PP +.P You use .BR ioperm (2) or alternatively diff --git a/man2/pause.2 b/man2/pause.2 index 0e7bbcd..59e9345 100644 --- a/man2/pause.2 +++ b/man2/pause.2 @@ -7,7 +7,7 @@ .\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) .\" Modified 2000 by aeb, following Michael Kerrisk .\" -.TH pause 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pause 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pause \- wait for signal .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int pause(void); .fi .SH DESCRIPTION diff --git a/man2/pciconfig_read.2 b/man2/pciconfig_read.2 index 7913ba0..4c894aa 100644 --- a/man2/pciconfig_read.2 +++ b/man2/pciconfig_read.2 @@ -5,7 +5,7 @@ .\" May be freely distributed and modified. .\" %%%LICENSE_END .\" -.TH pciconfig_read 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pciconfig_read 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pciconfig_read, pciconfig_write, pciconfig_iobase \- pci device information handling @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pciconfig_read(unsigned long " bus ", unsigned long " dfn , .BI " unsigned long " off ", unsigned long " len , .BI " unsigned char *" buf ); diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index d9e7877..7af8e35 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -5,7 +5,7 @@ .\" This document is based on the perf_event.h header file, the .\" tools/perf/design.txt file, and a lot of bitter experience. .\" -.TH perf_event_open 2 2023-05-03 "Linux man-pages 6.05.01" +.TH perf_event_open 2 2023-11-19 "Linux man-pages 6.7" .SH NAME perf_event_open \- set up performance monitoring .SH LIBRARY @@ -17,12 +17,12 @@ Standard C library .BR "#include " " /* Definition of " HW_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_perf_event_open, struct perf_event_attr *" attr , .BI " pid_t " pid ", int " cpu ", int " group_fd \ ", unsigned long " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR perf_event_open (), @@ -32,7 +32,12 @@ necessitating the use of Given a list of parameters, .BR perf_event_open () returns a file descriptor, for use in subsequent system calls -.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)." +(\c +.BR read (2), +.BR mmap (2), +.BR prctl (2), +.BR fcntl (2), +etc.). .PP A call to .BR perf_event_open () @@ -41,14 +46,14 @@ information. Each file descriptor corresponds to one event that is measured; these can be grouped together to measure multiple events simultaneously. -.PP +.P Events can be enabled and disabled in two ways: via .BR ioctl (2) and via .BR prctl (2). When an event is disabled it does not count or generate overflows but does continue to exist and maintain its count value. -.PP +.P Events come in two flavors: counting and sampled. A .I counting @@ -95,7 +100,7 @@ value of less than 1. .TP .BR "pid == \-1" " and " "cpu == \-1" This setting is invalid and will return an error. -.PP +.P When .I pid is greater than zero, permission to perform this system call @@ -105,7 +110,7 @@ is governed by .B PTRACE_MODE_READ_REALCREDS check on older Linux versions; see .BR ptrace (2). -.PP +.P The .I group_fd argument allows event groups to be created. @@ -127,7 +132,7 @@ This means that the values of the member events can be meaningfully compared \[em]added, divided (to get ratios), and so on\[em] with each other, since they have counted events for the same set of executed instructions. -.PP +.P The .I flags argument is formed by ORing together zero or more of the following values: @@ -186,12 +191,12 @@ must be passed as the parameter. cgroup monitoring is available only for system-wide events and may therefore require extra permissions. -.PP +.P The .I perf_event_attr structure provides detailed configuration information for the event being created. -.PP +.P .in +4n .EX struct perf_event_attr { @@ -291,7 +296,7 @@ struct perf_event_attr { }; .EE .in -.PP +.P The fields of the .I perf_event_attr structure are described in more detail below: @@ -562,7 +567,7 @@ This counts context switches to a task in a different cgroup. In other words, if the next task is in the same cgroup, it won't count the switch. .RE -.PP +.P .RS If .I type @@ -575,7 +580,7 @@ can be obtained from under debugfs .I tracing/events/*/*/id if ftrace is enabled in the kernel. .RE -.PP +.P .RS If .I type @@ -586,7 +591,7 @@ To calculate the appropriate .I config value, use the following equation: .RS 4 -.PP +.P .in +4n .EX config = (perf_hw_cache_id) | @@ -594,7 +599,7 @@ config = (perf_hw_cache_id) | (perf_hw_cache_op_result_id << 16); .EE .in -.PP +.P where .I perf_hw_cache_id is one of: @@ -622,7 +627,7 @@ for measuring the branch prediction unit .\" commit 89d6c0b5bdbb1927775584dcf532d98b3efe1477 for measuring local memory accesses .RE -.PP +.P and .I perf_hw_cache_op_id is one of: @@ -637,7 +642,7 @@ for write accesses .B PERF_COUNT_HW_CACHE_OP_PREFETCH for prefetch accesses .RE -.PP +.P and .I perf_hw_cache_op_result_id is one of: @@ -650,7 +655,7 @@ to measure accesses to measure misses .RE .RE -.PP +.P If .I type is @@ -666,7 +671,7 @@ The libpfm4 library can be used to translate from the name in the architectural manuals to the raw hex value .BR perf_event_open () expects in this field. -.PP +.P If .I type is @@ -675,7 +680,7 @@ then leave .I config set to zero. Its parameters are set in other places. -.PP +.P If .I type is @@ -698,7 +703,13 @@ and for more details. .RE .TP -.IR kprobe_func ", " uprobe_path ", " kprobe_addr ", and " probe_offset +.I kprobe_func +.TQ +.I uprobe_path +.TQ +.I kprobe_addr +.TQ +.I probe_offset These fields describe the kprobe/uprobe for dynamic PMUs .B kprobe and @@ -721,7 +732,9 @@ use and .IR probe_offset . .TP -.IR sample_period ", " sample_freq +.I sample_period +.TQ +.I sample_freq A "sampling" event is one that generates an overflow notification every N events, where N is given by .IR sample_period . @@ -925,7 +938,7 @@ not both. It has the following format and the meaning of each field is dependent on the hardware implementation. -.PP +.P .in +4n .EX union perf_sample_weight { @@ -1354,7 +1367,9 @@ This enables synchronous signal delivery of .B SIGTRAP on event overflow. .TP -.IR wakeup_events ", " wakeup_watermark +.I wakeup_events +.TQ +.I wakeup_watermark This union sets how many samples .RI ( wakeup_events ) or bytes @@ -1400,7 +1415,7 @@ Count when we read or write the memory location. .TP .B HW_BREAKPOINT_X Count when we execute code at the memory location. -.PP +.P The values can be combined via a bitwise or, but the combination of .B HW_BREAKPOINT_R @@ -1474,7 +1489,7 @@ Branch target is in hypervisor. .TP .B PERF_SAMPLE_BRANCH_PLM_ALL A convenience value that is the three preceding values ORed together. -.PP +.P In addition to the privilege value, at least one or more of the following bits must be set. .TP @@ -1591,12 +1606,12 @@ The values that are there are specified by the field in the .I attr structure at open time. -.PP +.P If you attempt to read into a buffer that is not big enough to hold the data, the error .B ENOSPC results. -.PP +.P Here is the layout of the data returned by a read: .IP \[bu] 3 If @@ -1635,7 +1650,7 @@ struct read_format { }; .EE .in -.PP +.P The values read are as follows: .TP .I nr @@ -1644,7 +1659,9 @@ Available only if .B PERF_FORMAT_GROUP was specified. .TP -.IR time_enabled ", " time_running +.I time_enabled +.TQ +.I time_running Total time the event was enabled and running. Normally these values are the same. Multiplexing happens if the number of events is more than the @@ -1680,18 +1697,18 @@ mmap tracking) are logged into a ring-buffer. This ring-buffer is created and accessed through .BR mmap (2). -.PP +.P The mmap size should be 1+2\[ha]n pages, where the first page is a metadata page .RI ( "struct perf_event_mmap_page" ) that contains various bits of information such as where the ring-buffer head is. -.PP +.P Before Linux 2.6.39, there is a bug that means you must allocate an mmap ring buffer when sampling even if you do not plan to access it. -.PP +.P The structure of the first metadata mmap page is as follows: -.PP +.P .in +4n .EX struct perf_event_mmap_page { @@ -1729,7 +1746,7 @@ struct perf_event_mmap_page { } .EE .in -.PP +.P The following list describes the fields in the .I perf_event_mmap_page structure in more detail: @@ -1861,7 +1878,11 @@ count += pmc; .EE .in .TP -.IR time_shift ", " time_mult ", " time_offset +.I time_shift +.TQ +.I time_mult +.TQ +.I time_offset .IP If .IR cap_usr_time , @@ -1966,7 +1987,13 @@ where perf sample data begins. Contains the size of the perf sample region within the mmap buffer. .TP -.IR aux_head ", " aux_tail ", " aux_offset ", " aux_size " (since Linux 4.1)" +.I aux_head +.TQ +.I aux_tail +.TQ +.I aux_offset +.TQ +.I aux_size " (since Linux 4.1)" .\" commit 45bfb2e50471abbbfd83d40d28c986078b0d24ff The AUX region allows .BR mmap (2)-ing @@ -2011,9 +2038,9 @@ rules as the previous described .I data_head and .IR data_tail . -.PP +.P The following 2^n ring-buffer pages have the layout described below. -.PP +.P If .I perf_event_attr.sample_id_all is set, then all event types will @@ -2027,9 +2054,9 @@ fields, that is, at the end of the payload. This allows a newer perf.data file to be supported by older perf tools, with the new optional fields being ignored. -.PP +.P The mmap values start with a header: -.PP +.P .in +4n .EX struct perf_event_header { @@ -2039,7 +2066,7 @@ struct perf_event_header { }; .EE .in -.PP +.P Below, we describe the .I perf_event_header fields in more detail. @@ -2080,7 +2107,7 @@ Sample happened in the guest kernel. .\" commit 39447b386c846bbf1c56f6403c5282837486200f Sample happened in guest user code. .RE -.PP +.P .RS Since the following three statuses are generated by different record types, they alias to the same bit: @@ -2109,7 +2136,7 @@ record is generated, this bit indicates that the context switch is away from the current process (instead of into the current process). .RE -.PP +.P .RS In addition, the following bits can be set: .TP @@ -2260,7 +2287,9 @@ struct { .EE .in .TP -.BR PERF_RECORD_THROTTLE ", " PERF_RECORD_UNTHROTTLE +.B PERF_RECORD_THROTTLE +.TQ +.B PERF_RECORD_UNTHROTTLE This record indicates a throttle/unthrottle event. .IP .in +4n @@ -2373,7 +2402,9 @@ If is enabled, then a 64-bit instruction pointer value is included. .TP -.IR pid ", " tid +.I pid +.TQ +.I tid If .B PERF_SAMPLE_TID is enabled, then a 32-bit process ID @@ -2412,7 +2443,9 @@ the actual ID is returned, not the group leader. This ID is the same as the one returned by .BR PERF_FORMAT_ID . .TP -.IR cpu ", " res +.I cpu +.TQ +.I res If .B PERF_SAMPLE_CPU is enabled, this is a 32-bit value indicating @@ -2436,7 +2469,9 @@ value used at .BR perf_event_open () time. .TP -.IR nr ", " ips[nr] +.I nr +.TQ +.I ips[nr] If .B PERF_SAMPLE_CALLCHAIN is enabled, then a 64-bit number is included @@ -2444,7 +2479,9 @@ which indicates how many following 64-bit instruction pointers will follow. This is the current callchain. .TP -.IR size ", " data[size] +.I size +.TQ +.I data[size] If .B PERF_SAMPLE_RAW is enabled, then a 32-bit value indicating size @@ -2456,7 +2493,9 @@ The ABI doesn't make any promises with respect to the stability of its content, it may vary depending on event, hardware, and kernel version. .TP -.IR bnr ", " lbr[bnr] +.I bnr +.TQ +.I lbr[bnr] If .B PERF_SAMPLE_BRANCH_STACK is enabled, then a 64-bit value indicating @@ -2490,10 +2529,10 @@ The branch was in an aborted transactional memory transaction. .\" commit 71ef3c6b9d4665ee7afbbe4c208a98917dcfc32f This reports the number of cycles elapsed since the previous branch stack update. -.PP +.P The entries are from most to least recent, so the first entry has the most recent branch. -.PP +.P Support for .IR mispred , .IR predicted , @@ -2501,13 +2540,15 @@ and .I cycles is optional; if not supported, those values will be 0. -.PP +.P The type of branches recorded is specified by the .I branch_sample_type field. .RE .TP -.IR abi ", " regs[weight(mask)] +.I abi +.TQ +.I regs[weight(mask)] If .B PERF_SAMPLE_REGS_USER is enabled, then the user CPU registers are recorded. @@ -2530,7 +2571,11 @@ The number of values is the number of bits set in the .I sample_regs_user bit mask. .TP -.IR size ", " data[size] ", " dyn_size +.I size +.TQ +.I data[size] +.TQ +.I dyn_size If .B PERF_SAMPLE_STACK_USER is enabled, then the user stack is recorded. @@ -2754,7 +2799,9 @@ the high 32 bits of the field by shifting right by and masking with the value .BR PERF_TXN_ABORT_MASK . .TP -.IR abi ", " regs[weight(mask)] +.I abi +.TQ +.I regs[weight(mask)] If .B PERF_SAMPLE_REGS_INTR is enabled, then the user CPU registers are recorded. @@ -3254,13 +3301,13 @@ and .B F_SETSIG operations in .BR fcntl (2). -.PP +.P Overflows are generated only by sampling events .RI ( sample_period must have a nonzero value). -.PP +.P There are two ways to generate overflow notifications. -.PP +.P The first is to set a .I wakeup_events or @@ -3270,7 +3317,7 @@ or bytes have been written to the mmap ring buffer. In this case, .B POLL_IN is indicated. -.PP +.P The other way is by use of the .B PERF_EVENT_IOC_REFRESH ioctl. @@ -3282,13 +3329,13 @@ once the counter reaches 0 .B POLL_HUP is indicated and the underlying event is disabled. -.PP +.P Refreshing an event group leader refreshes all siblings and refreshing with a parameter of 0 currently enables infinite refreshes; these behaviors are unsupported and should not be relied on. .\" See https://lkml.org/lkml/2011/5/24/337 -.PP +.P Starting with Linux 3.18, .\" commit 179033b3e064d2cd3f5f9945e76b0a0f0fbf4883 .B POLL_HUP @@ -3302,12 +3349,12 @@ instruction to get low-latency reads without having to enter the kernel. Note that using .I rdpmc is not necessarily faster than other methods for reading event values. -.PP +.P Support for this can be detected with the .I cap_usr_rdpmc field in the mmap page; documentation on how to calculate event values can be found in that section. -.PP +.P Originally, when rdpmc support was enabled, any process (not just ones with an active perf event) could use the rdpmc instruction to access the counters. @@ -3567,10 +3614,10 @@ Maximum number of pages an unprivileged user can .BR mlock (2). The default is 516 (kB). .RE -.PP +.P Files in .I /sys/bus/event_source/devices/ -.PP +.P .RS 4 Since Linux 2.6.34, the kernel supports having multiple PMUs available for monitoring. @@ -3831,7 +3878,7 @@ The official way of knowing if support is enabled is checking for the existence of the file .IR /proc/sys/kernel/perf_event_paranoid . -.PP +.P .B CAP_PERFMON capability (since Linux 5.8) provides secure approach to performance monitoring and observability operations in a system @@ -3855,7 +3902,7 @@ option to is needed to properly get overflow signals in threads. This was introduced in Linux 2.6.32. .\" commit ba0a6c9f6fceed11c6a99e8326f0477fe383e6b5 -.PP +.P Prior to Linux 2.6.33 (at least for x86), .\" commit b690081d4d3f6a23541493f1682835c3cd5c54a1 the kernel did not check @@ -3865,40 +3912,40 @@ This means to see if a given set of events works you have to .BR perf_event_open (), start, then read before you know for sure you can get valid measurements. -.PP +.P Prior to Linux 2.6.34, .\" FIXME . cannot find a kernel commit for this one event constraints were not enforced by the kernel. In that case, some events would silently return "0" if the kernel scheduled them in an improper counter slot. -.PP +.P Prior to Linux 2.6.34, there was a bug when multiplexing where the wrong results could be returned. .\" commit 45e16a6834b6af098702e5ea6c9a40de42ff77d8 -.PP +.P Kernels from Linux 2.6.35 to Linux 2.6.39 can quickly crash the kernel if "inherit" is enabled and many threads are started. .\" commit 38b435b16c36b0d863efcf3f07b34a6fac9873fd -.PP +.P Prior to Linux 2.6.35, .\" commit 050735b08ca8a016bbace4445fa025b88fee770b .B PERF_FORMAT_GROUP did not work with attached processes. -.PP +.P There is a bug in the kernel code between Linux 2.6.36 and Linux 3.0 that ignores the "watermark" field and acts as if a wakeup_event was chosen if the union has a nonzero value in it. .\" commit 4ec8363dfc1451f8c8f86825731fe712798ada02 -.PP +.P From Linux 2.6.31 to Linux 3.4, the .B PERF_IOC_FLAG_GROUP ioctl argument was broken and would repeatedly operate on the event specified rather than iterating across all sibling events in a group. .\" commit 724b6daa13e100067c30cfc4d1ad06629609dc4e -.PP +.P From Linux 3.4 to Linux 3.11, the mmap .\" commit fa7315871046b9a4c48627905691dbde57e51033 .I cap_usr_rdpmc @@ -3910,7 +3957,7 @@ Code should migrate to the new and .I cap_user_time fields instead. -.PP +.P Always double-check your results! Various generalized events have had wrong values. For example, retired branches measured @@ -3920,7 +3967,7 @@ the wrong thing on AMD machines until Linux 2.6.35. The following is a short example that measures the total instruction count of a call to .BR printf (3). -.PP +.P .\" SRC BEGIN (perf_event_open.c) .EX #include @@ -3984,6 +4031,6 @@ main(void) .BR open (2), .BR prctl (2), .BR read (2) -.PP +.P .I Documentation/admin\-guide/perf\-security.rst in the kernel source tree diff --git a/man2/perfmonctl.2 b/man2/perfmonctl.2 index 2155bb4..fac1aa1 100644 --- a/man2/perfmonctl.2 +++ b/man2/perfmonctl.2 @@ -4,17 +4,17 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH perfmonctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH perfmonctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME perfmonctl \- interface to IA-64 performance monitoring unit .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .BI "long perfmonctl(int " fd ", int " cmd ", void " arg [. narg "], int " narg ");" .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see HISTORY. .SH DESCRIPTION @@ -25,7 +25,7 @@ PMU (performance monitoring unit). The PMU consists of PMD (performance monitoring data) registers and PMC (performance monitoring control) registers, which gather hardware statistics. -.PP +.P .BR perfmonctl () applies the operation .I cmd @@ -35,7 +35,7 @@ The number of arguments is defined by \fInarg\fR. The .I fd argument specifies the perfmon context to operate on. -.PP +.P Supported values for .I cmd are: @@ -180,14 +180,14 @@ Linux on IA-64. Added in Linux 2.4; .\" commit ecf5b72d5f66af843f189dfe9ce31598c3e48ad7 removed in Linux 5.10. -.PP +.P This system call was broken for many years, and ultimately removed in Linux 5.10. -.PP +.P glibc does not provide a wrapper for this system call; on kernels where it exists, call it using .BR syscall (2). .SH SEE ALSO .BR gprof (1) -.PP +.P The perfmon2 interface specification diff --git a/man2/personality.2 b/man2/personality.2 index e76af79..ae8db10 100644 --- a/man2/personality.2 +++ b/man2/personality.2 @@ -10,7 +10,7 @@ .\" changed prototype, documented 0xffffffff, aeb, 030101 .\" Modified 2004-11-03 patch from Martin Schulze .\" -.TH personality 2 2023-04-29 "Linux man-pages 6.05.01" +.TH personality 2 2023-10-31 "Linux man-pages 6.7" .SH NAME personality \- set the process execution domain .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int personality(unsigned long " persona ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ signal numbers into signal actions. The execution domain system allows Linux to provide limited support for binaries compiled under other UNIX-like operating systems. -.PP +.P If .I persona is not @@ -42,7 +42,7 @@ Specifying .I persona as 0xffffffff provides a way of retrieving the current persona without changing it. -.PP +.P A list of the available execution domains can be found in .IR . The execution domain is a 32-bit value in which the top three @@ -108,7 +108,7 @@ kernel version-numbering switch from Linux 2.6.x to Linux 3.x. .TP .BR WHOLE_SECONDS " (since Linux 1.2.0)" No effect. -.PP +.P The available execution domains are: .TP .BR PER_BSD " (since Linux 1.2.0)" diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 index 9e3af2a..918f1d2 100644 --- a/man2/pidfd_getfd.2 +++ b/man2/pidfd_getfd.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pidfd_getfd 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pidfd_getfd 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pidfd_getfd \- obtain a duplicate of another process's file descriptor .SH LIBRARY @@ -12,11 +12,11 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_pidfd_getfd, int " pidfd ", int " targetfd , .BI " unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pidfd_getfd (), @@ -30,7 +30,7 @@ This new file descriptor is a duplicate of an existing file descriptor, .IR targetfd , in the process referred to by the PID file descriptor .IR pidfd . -.PP +.P The duplicate file descriptor refers to the same open file description (see .BR open (2)) as the original file descriptor in the process referred to by @@ -40,19 +40,19 @@ Furthermore, operations on the underlying file object (for example, assigning an address to a socket object using .BR bind (2)) can equally be performed via the duplicate file descriptor. -.PP +.P The close-on-exec flag .RB ( FD_CLOEXEC ; see .BR fcntl (2)) is set on the file descriptor returned by .BR pidfd_getfd (). -.PP +.P The .I flags argument is reserved for future use. Currently, it must be specified as 0. -.PP +.P Permission to duplicate another process's file descriptor is governed by a ptrace access mode .B PTRACE_MODE_ATTACH_REALCREDS @@ -111,7 +111,7 @@ Linux 5.6. .SH NOTES For a description of PID file descriptors, see .BR pidfd_open (2). -.PP +.P The effect of .BR pidfd_getfd () is similar to the use of diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2 index 8321e82..32e92c0 100644 --- a/man2/pidfd_open.2 +++ b/man2/pidfd_open.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pidfd_open 2 2023-05-03 "Linux man-pages 6.05.01" +.TH pidfd_open 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pidfd_open \- obtain a file descriptor that refers to a process .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_pidfd_open, pid_t " pid ", unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pidfd_open (), @@ -29,7 +29,7 @@ the process whose PID is specified in .IR pid . The file descriptor is returned as the function result; the close-on-exec flag is set on the file descriptor. -.PP +.P The .I flags argument either has the value 0, or contains the following flag: @@ -88,7 +88,7 @@ Linux 5.3. The following code sequence can be used to obtain a file descriptor for the child of .BR fork (2): -.PP +.P .in +4n .EX pid = fork(); @@ -98,7 +98,7 @@ if (pid > 0) { /* If parent */ } .EE .in -.PP +.P Even if the child has already terminated by the time of the .BR pidfd_open () call, its PID will not have been recycled and the returned @@ -127,7 +127,7 @@ the zombie process was not reaped elsewhere in the program (e.g., either by an asynchronously executed signal handler or by .BR wait (2) or similar in another thread). -.PP +.P If any of these conditions does not hold, then the child process (along with a PID file descriptor that refers to it) should instead be created using @@ -181,7 +181,7 @@ A PID file descriptor can be used as the argument of .BR process_madvise (2) in order to provide advice on the memory usage patterns of the process referred to by the file descriptor. -.PP +.P The .BR pidfd_open () system call is the preferred way of obtaining a PID file descriptor diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2 index 670ea71..ae884b8 100644 --- a/man2/pidfd_send_signal.2 +++ b/man2/pidfd_send_signal.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pidfd_send_signal 2 2023-05-03 "Linux man-pages 6.05.01" +.TH pidfd_send_signal 2 2023-11-01 "Linux man-pages 6.7" .SH NAME pidfd_send_signal \- send a signal to a process specified by a file descriptor .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include " " /* Definition of " SI_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_pidfd_send_signal, int " pidfd ", int " sig , .BI " siginfo_t *_Nullable " info ", unsigned int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pidfd_send_signal (), @@ -34,23 +34,23 @@ to the target process referred to by a PID file descriptor that refers to a process. .\" See the very detailed commit message for kernel commit .\" 3eb39f47934f9d5a3027fe00d906a45fe3a15fad -.PP +.P If the .I info argument points to a .I siginfo_t buffer, that buffer should be populated as described in .BR rt_sigqueueinfo (2). -.PP +.P If the .I info -argument is a NULL pointer, +argument is a null pointer, this is equivalent to specifying a pointer to a .I siginfo_t buffer whose fields match the values that are implicitly supplied when a signal is sent using .BR kill (2): -.PP +.P .PD 0 .IP \[bu] 3 .I si_signo @@ -69,12 +69,12 @@ is set to the caller's PID; and .I si_uid is set to the caller's real user ID. .PD -.PP +.P The calling process must either be in the same PID namespace as the process referred to by .IR pidfd , or be in an ancestor of that namespace. -.PP +.P The .I flags argument is reserved for future use; @@ -145,7 +145,7 @@ or that specifies the .B CLONE_PIDFD flag. -.PP +.P The .BR pidfd_send_signal () system call allows the avoidance of race conditions that occur diff --git a/man2/pipe.2 b/man2/pipe.2 index d8142f9..55e631d 100644 --- a/man2/pipe.2 +++ b/man2/pipe.2 @@ -13,7 +13,7 @@ .\" to EXAMPLE text. .\" 2008-10-10, mtk: add description of pipe2() .\" -.TH pipe 2 2023-07-30 "Linux man-pages 6.05.01" +.TH pipe 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pipe, pipe2 \- create pipe .SH LIBRARY @@ -22,20 +22,20 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pipe(int " pipefd [2]); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .BR "#include " " /* Definition of " O_* " constants */" .B #include -.PP +.P .BI "int pipe2(int " pipefd "[2], int " flags ); -.PP +.P /* On Alpha, IA-64, MIPS, SuperH, and SPARC/SPARC64, pipe() has the following prototype; see VERSIONS */ -.PP +.P .B #include -.PP +.P .B struct fd_pair { .B " long fd[2];" .B "};" @@ -56,7 +56,7 @@ Data written to the write end of the pipe is buffered by the kernel until it is read from the read end of the pipe. For further details, see .BR pipe (7). -.PP +.P If .I flags is 0, then @@ -148,7 +148,7 @@ On error, \-1 is returned, is set to indicate the error, and .I pipefd is left unchanged. -.PP +.P On Linux (and other systems), .BR pipe () does not modify diff --git a/man2/pivot_root.2 b/man2/pivot_root.2 index a4077ef..3e0e55e 100644 --- a/man2/pivot_root.2 +++ b/man2/pivot_root.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pivot_root 2 2023-05-03 "Linux man-pages 6.05.01" +.TH pivot_root 2 2024-02-25 "Linux man-pages 6.7" .SH NAME pivot_root \- change the root mount .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_pivot_root, const char *" new_root \ ", const char *" put_old ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR pivot_root (), @@ -32,7 +32,7 @@ directory \fIput_old\fP and makes \fInew_root\fP the new root mount. The calling process must have the .B CAP_SYS_ADMIN capability in the user namespace that owns the caller's mount namespace. -.PP +.P .BR pivot_root () changes the root directory and the current working directory of each process or thread in the same mount namespace to @@ -45,7 +45,7 @@ does not change the caller's current working directory (unless it is on the old root directory), and thus it should be followed by a \fBchdir("/")\fP call. -.PP +.P The following restrictions apply: .IP \[bu] 3 .I new_root @@ -66,7 +66,7 @@ must yield the same directory as \fInew_root\fP. .IP \[bu] .I new_root must be a path to a mount point, but can't be -.IR """/""" . +.IR \[dq]/\[dq] . A path that is not already a mount point can be converted into one by bind mounting the path onto itself. .IP \[bu] @@ -115,7 +115,7 @@ is on the current root mount. (This error covers the pathological case where .I new_root is -.IR """/""" .) +.IR \[dq]/\[dq] .) .TP .B EINVAL .I new_root @@ -158,7 +158,7 @@ Linux 2.3.41. .SH NOTES A command-line interface for this system call is provided by .BR pivot_root (8). -.PP +.P .BR pivot_root () allows the caller to switch to a new root filesystem while at the same time placing the old root mount at a location under @@ -168,7 +168,7 @@ from where it can subsequently be unmounted. or current working directory on the old root directory to the new root frees the old root directory of users, allowing the old root mount to be unmounted more easily.) -.PP +.P One use of .BR pivot_root () is during system startup, when the @@ -178,7 +178,7 @@ then mounts the real root filesystem, and eventually turns the latter into the root directory of all relevant processes and threads. A modern use is to set up a root filesystem during the creation of a container. -.PP +.P The fact that .BR pivot_root () modifies process root and current working directories in the @@ -187,7 +187,7 @@ is necessary in order to prevent kernel threads from keeping the old root mount busy with their root and current working directories, even if they never access the filesystem in any way. -.PP +.P The rootfs (initial ramfs) cannot be .BR pivot_root ()ed. The recommended method of changing the root filesystem in this case is @@ -207,7 +207,7 @@ and may be the same directory. In particular, the following sequence allows a pivot-root operation without needing to create and remove a temporary directory: -.PP +.P .in +4n .EX chdir(new_root); @@ -215,7 +215,7 @@ pivot_root(".", "."); umount2(".", MNT_DETACH); .EE .in -.PP +.P This sequence succeeds because the .BR pivot_root () call stacks the old root mount point @@ -227,7 +227,7 @@ working directory refer to the new root mount point During the subsequent .BR umount () call, resolution of -.I """.""" +.I \[dq].\[dq] starts with .I new_root and then moves up the list of mounts stacked at @@ -237,7 +237,7 @@ with the result that old root mount point is unmounted. .SS Historical notes For many years, this manual page carried the following text: .RS -.PP +.P .BR pivot_root () may or may not change the current root and the current working directory of any processes or threads which use the old @@ -250,7 +250,7 @@ An easy way to ensure this is to change their root and current working directory to \fInew_root\fP before invoking .BR pivot_root (). .RE -.PP +.P This text, written before the system call implementation was even finalized in the kernel, was probably intended to warn users at that time that the implementation might change before final release. @@ -269,12 +269,12 @@ After pivoting to the root directory named in the program's first command-line argument, the child created by .BR clone (2) then executes the program named in the remaining command-line arguments. -.PP +.P We demonstrate the program by creating a directory that will serve as the new root filesystem and placing a copy of the (statically linked) .BR busybox (1) executable in that directory. -.PP +.P .in +4n .EX $ \fBmkdir /tmp/rootfs\fP @@ -296,7 +296,7 @@ hello world .in .SS Program source \& -.PP +.P .\" SRC BEGIN (pivot_root.c) .EX /* pivot_root_demo.c */ diff --git a/man2/pkey_alloc.2 b/man2/pkey_alloc.2 index 53d8f2a..5d72fb9 100644 --- a/man2/pkey_alloc.2 +++ b/man2/pkey_alloc.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pkey_alloc 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pkey_alloc 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pkey_alloc, pkey_free \- allocate or free a protection key .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pkey_alloc(unsigned int " flags ", unsigned int " access_rights ");" .BI "int pkey_free(int " pkey ");" .fi @@ -20,12 +20,12 @@ Standard C library .BR pkey_alloc () allocates a protection key (pkey) and allows it to be passed to .BR pkey_mprotect (2). -.PP +.P The .BR pkey_alloc () .I flags is reserved for future use and currently must always be specified as 0. -.PP +.P The .BR pkey_alloc () .I access_rights @@ -36,13 +36,13 @@ Disable all data access to memory covered by the returned protection key. .TP .B PKEY_DISABLE_WRITE Disable write access to memory covered by the returned protection key. -.PP +.P .BR pkey_free () frees a protection key and makes it available for later allocations. After a protection key has been freed, it may no longer be used in any protection-key-related operations. -.PP +.P An application should not call .BR pkey_free () on any protection key which has been assigned to an address @@ -96,7 +96,7 @@ It can be used in lieu of any other mechanism for detecting pkey support and will simply fail with the error .B ENOSPC if the operating system has no pkey support. -.PP +.P The kernel guarantees that the contents of the hardware rights register (PKRU) will be preserved only for allocated protection keys. diff --git a/man2/poll.2 b/man2/poll.2 index 2b024d3..36e89f8 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -7,7 +7,7 @@ .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and .\" formatting changes. .\" -.TH poll 2 2023-07-08 "Linux man-pages 6.05.01" +.TH poll 2 2023-10-31 "Linux man-pages 6.7" .SH NAME poll, ppoll \- wait for some event on a file descriptor .SH LIBRARY @@ -16,12 +16,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds , .BI " const struct timespec *_Nullable " tmo_p , .BI " const sigset_t *_Nullable " sigmask ); @@ -36,11 +36,11 @@ The Linux-specific .BR epoll (7) API performs a similar task, but offers features beyond those found in .BR poll (). -.PP +.P The set of file descriptors to be monitored is specified in the .I fds argument, which is an array of structures of the following form: -.PP +.P .in +4n .EX struct pollfd { @@ -50,12 +50,12 @@ struct pollfd { }; .EE .in -.PP +.P The caller should specify the number of items in the .I fds array in .IR nfds . -.PP +.P The field .I fd contains a file descriptor for an open file. @@ -70,7 +70,7 @@ file descriptor for a single call: simply set the .I fd field to its bitwise complement.) -.PP +.P The field .I events is an input parameter, a bit mask specifying the events the application @@ -85,7 +85,7 @@ are and .B POLLNVAL (see below). -.PP +.P The field .I revents is an output parameter, filled by the kernel with the events that @@ -104,12 +104,12 @@ or field, and will be set in the .I revents field whenever the corresponding condition is true.) -.PP +.P If none of the events requested (and no error) has occurred for any of the file descriptors, then .BR poll () blocks until one of the events occurs. -.PP +.P The .I timeout argument specifies the number of milliseconds that @@ -122,7 +122,7 @@ a file descriptor becomes ready; the call is interrupted by a signal handler; or .IP \[bu] the timeout expires. -.PP +.P Being "ready" means that the requested operation will not block; thus, .BR poll ()ing regular files, @@ -130,7 +130,7 @@ block devices, and other files with no reasonable polling semantic .I always returns instantly as ready to read and write. -.PP +.P Note that the .I timeout interval will be rounded up to the system clock granularity, @@ -144,7 +144,7 @@ Specifying a of zero causes .BR poll () to return immediately, even if no file descriptors are ready. -.PP +.P The bits that may be set/returned in .I events and @@ -214,7 +214,7 @@ not open (only returned in .IR revents ; ignored in .IR events ). -.PP +.P When compiling with .B _XOPEN_SOURCE defined, one also has the following, @@ -234,7 +234,7 @@ Equivalent to .TP .B POLLWRBAND Priority data may be written. -.PP +.P Linux also knows about, but does not use .BR POLLMSG . .SS ppoll() @@ -251,23 +251,23 @@ like .BR ppoll () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P Other than the difference in the precision of the .I timeout argument, the following .BR ppoll () call: -.PP +.P .in +4n .EX ready = ppoll(&fds, nfds, tmo_p, &sigmask); .EE .in -.PP +.P is nearly equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -280,7 +280,7 @@ ready = poll(&fds, nfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The above code segment is described as .I nearly equivalent because whereas a negative @@ -291,13 +291,13 @@ is interpreted as an infinite timeout, a negative value expressed in .I *tmo_p results in an error from .BR ppoll (). -.PP +.P See the description of .BR pselect (2) for an explanation of why .BR ppoll () is necessary. -.PP +.P If the .I sigmask argument is specified as NULL, then @@ -309,7 +309,7 @@ differs from only in the precision of the .I timeout argument). -.PP +.P The .I tmo_p argument specifies an upper limit on the amount of time that @@ -318,7 +318,7 @@ will block. This argument is a pointer to a .BR timespec (3) structure. -.PP +.P If .I tmo_p is specified as NULL, then @@ -334,7 +334,7 @@ whose fields have been set to a nonzero value (indicating an event or an error). A return value of zero indicates that the system call timed out before any file descriptors became ready. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -379,7 +379,7 @@ Portable programs may wish to check for .B EAGAIN and loop, just as with .BR EINTR . -.PP +.P Some implementations define the nonstandard constant .B INFTIM with the value \-1 for use as a @@ -401,7 +401,7 @@ Thus, the glibc function does not modify its .I tmo_p argument. -.PP +.P The raw .BR ppoll () system call has a fifth argument, @@ -452,7 +452,7 @@ and is not affected by the .B O_NONBLOCK flag. -.PP +.P For a discussion of what may happen if a file descriptor being monitored by .BR poll () is closed in another thread, see @@ -482,27 +482,27 @@ if the file descriptor was not readable, but some other event occurred (presumably .BR POLLHUP ), closes the file descriptor. -.PP +.P Suppose we run the program in one terminal, asking it to open a FIFO: -.PP +.P .in +4n .EX $ \fBmkfifo myfifo\fP $ \fB./poll_input myfifo\fP .EE .in -.PP +.P In a second terminal window, we then open the FIFO for writing, write some data to it, and close the FIFO: -.PP +.P .in +4n .EX $ \fBecho aaaaabbbbbccccc > myfifo\fP .EE .in -.PP +.P In the terminal where we are running the program, we would then see: -.PP +.P .in +4n .EX Opened "myfifo" on fd 3 @@ -522,7 +522,7 @@ Ready: 1 All file descriptors closed; bye .EE .in -.PP +.P In the above output, we see that .BR poll () returned three times: diff --git a/man2/posix_fadvise.2 b/man2/posix_fadvise.2 index 38e9745..96c06a7 100644 --- a/man2/posix_fadvise.2 +++ b/man2/posix_fadvise.2 @@ -6,7 +6,7 @@ .\" 2005-04-08 mtk, noted kernel version and added BUGS .\" 2010-10-09, mtk, document arm_fadvise64_64() .\" -.TH posix_fadvise 2 2023-03-30 "Linux man-pages 6.05.01" +.TH posix_fadvise 2 2023-10-31 "Linux man-pages 6.7" .SH NAME posix_fadvise \- predeclare an access pattern for file data .SH LIBRARY @@ -15,17 +15,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int posix_fadvise(int " fd ", off_t " offset ", off_t " len \ ", int " advice ");" .fi -.PP +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR posix_fadvise (): .nf _POSIX_C_SOURCE >= 200112L @@ -36,14 +36,14 @@ Programs can use to announce an intention to access file data in a specific pattern in the future, thus allowing the kernel to perform appropriate optimizations. -.PP +.P The \fIadvice\fP applies to a (not necessarily existent) region starting at \fIoffset\fP and extending for \fIlen\fP bytes (or until the end of the file if \fIlen\fP is 0) within the file referred to by \fIfd\fP. The \fIadvice\fP is not binding; it merely constitutes an expectation on behalf of the application. -.PP +.P Permissible values for \fIadvice\fP include: .TP .B POSIX_FADV_NORMAL @@ -159,16 +159,16 @@ Therefore, these architectures define a version of the system call that orders the arguments suitably, but is otherwise exactly the same as .BR posix_fadvise (). -.PP +.P For example, since Linux 2.6.14, ARM has the following system call: -.PP +.P .in +4n .EX .BI "long arm_fadvise64_64(int " fd ", int " advice , .BI " loff_t " offset ", loff_t " len ); .EE .in -.PP +.P These architecture-specific details are generally hidden from applications by the glibc .BR posix_fadvise () @@ -178,7 +178,7 @@ which invokes the appropriate architecture-specific system call. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Kernel support first appeared in Linux 2.5.60; the underlying system call is called .BR fadvise64 (). @@ -186,14 +186,14 @@ the underlying system call is called Library support has been provided since glibc 2.2, via the wrapper function .BR posix_fadvise (). -.PP +.P Since Linux 3.18, .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb support for the underlying system call is optional, depending on the setting of the .B CONFIG_ADVISE_SYSCALLS configuration option. -.PP +.P The type of the .I len argument was changed from @@ -206,7 +206,7 @@ The contents of the kernel buffer cache can be cleared via the .I /proc/sys/vm/drop_caches interface described in .BR proc (5). -.PP +.P One can obtain a snapshot of which pages of a file are resident in the buffer cache by opening a file, mapping it with .BR mmap (2), diff --git a/man2/prctl.2 b/man2/prctl.2 index a592bba..c6dae6d 100644 --- a/man2/prctl.2 +++ b/man2/prctl.2 @@ -36,7 +36,7 @@ .\" 2014-11-10 Dave Hansen, document PR_MPX_{EN,DIS}ABLE_MANAGEMENT .\" .\" -.TH prctl 2 2023-07-28 "Linux man-pages 6.05.01" +.TH prctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME prctl \- operations on a process or thread .SH LIBRARY @@ -45,8 +45,8 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int prctl(int " option ", ..." +.P +.BI "int prctl(int " op ", ..." .BI " \fR/*\fP unsigned long " arg2 ", unsigned long " arg3 , .BI " unsigned long " arg4 ", unsigned long " arg5 " \fR*/\fP );" .fi @@ -54,12 +54,12 @@ Standard C library .BR prctl () manipulates various aspects of the behavior of the calling thread or process. -.PP +.P Note that careless use of some .BR prctl () operations can confuse the user-space run-time environment, so these operations should be used with care. -.PP +.P .BR prctl () is called with a first argument describing what to do (with values defined in \fI\fP), and further @@ -379,7 +379,7 @@ can operate only when this bit is Applications that use the O32 FPXX ABI can operate with either .B FR=0 or -.B FR=1 . +.BR FR=1 . .TP .B PR_FP_MODE_FRE Enable emulation of 32-bit floating-point mode. @@ -414,7 +414,7 @@ so FPU emulation is not required and the FPU always operates in .B FR=1 mode. .IP -This option is mainly intended for use by the dynamic linker +This operation is mainly intended for use by the dynamic linker .RB ( ld.so (8)). .IP The arguments @@ -674,7 +674,7 @@ value. The requirements for the address are the same as for the .B PR_SET_MM_START_BRK option. -.PP +.P The following options are available since Linux 3.5. .\" commit fe8c7f5cbf91124987106faa3bdf0c8b955c4cf7 .TP @@ -741,7 +741,7 @@ This restriction was enforced for security reasons that were subsequently deemed specious, and the restriction was removed in Linux 4.10 because some user-space applications needed to perform this operation more than once. -.PP +.P The following options are available since Linux 3.18. .\" commit f606b77f1a9e362451aca8f81d8f36a3a112139e .TP @@ -806,7 +806,9 @@ except \[aq][\[aq], \[aq]]\[aq], \[aq]\e\[aq], \[aq]$\[aq], and \[aq]\[ga]\[aq]. .RE .\" prctl PR_MPX_ENABLE_MANAGEMENT .TP -.BR PR_MPX_ENABLE_MANAGEMENT ", " PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86)" +.B PR_MPX_ENABLE_MANAGEMENT +.TQ +.BR PR_MPX_DISABLE_MANAGEMENT " (since Linux 3.19, removed in Linux 5.4; only on x86)" .\" commit fe3d197f84319d3bce379a9c0dc17b1f48ad358c .\" See also http://lwn.net/Articles/582712/ .\" See also https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler @@ -2041,6 +2043,36 @@ the copy will be truncated. Return (as the function result) the full length of the auxiliary vector. \fIarg4\fP and \fIarg5\fP must be 0. +.TP +.BR PR_SET_MDWE " (since Linux 6.3)" +.\" commit b507808ebce23561d4ff8c2aa1fb949fe402bc61 +Set the calling process' Memory-Deny-Write-Execute protection mask. +Once protection bits are set, +they can not be changed. +.I arg2 +must be a bit mask of: +.RS +.TP +.B PR_MDWE_REFUSE_EXEC_GAIN +New memory mapping protections can't be writable and executable. +Non-executable mappings can't become executable. +.TP +.B PR_MDWE_NO_INHERIT " (since Linux 6.6)" +.\" commit 2a87e5520554034e8c423479740f95bea4a086a0 +Do not propagate MDWE protection to child processes on +.BR fork (2). +Setting this bit requires setting +.B PR_MDWE_REFUSE_EXEC_GAIN +too. +.RE +.TP +.BR PR_GET_MDWE " (since Linux 6.3)" +.\" commit b507808ebce23561d4ff8c2aa1fb949fe402bc61 +Return (as the function result) the Memory-Deny-Write-Execute protection mask +of the calling process. +(See +.B PR_SET_MDWE +for information on the protection mask bits.) .SH RETURN VALUE On success, .BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET , @@ -2064,7 +2096,7 @@ and (if it returns) .B PR_GET_SECCOMP return the nonnegative values described above. All other -.I option +.I op values return 0 on success. On error, \-1 is returned, and .I errno @@ -2072,7 +2104,7 @@ is set to indicate the error. .SH ERRORS .TP .B EACCES -.I option +.I op is .B PR_SET_SECCOMP and @@ -2088,7 +2120,7 @@ attribute (see the discussion of above). .TP .B EACCES -.I option +.I op is .BR PR_SET_MM , and @@ -2098,7 +2130,7 @@ is the file is not executable. .TP .B EBADF -.I option +.I op is .BR PR_SET_MM , .I arg3 @@ -2109,7 +2141,7 @@ and the file descriptor passed in is not valid. .TP .B EBUSY -.I option +.I op is .BR PR_SET_MM , .I arg3 @@ -2124,7 +2156,7 @@ symbolic link, which is prohibited. is an invalid address. .TP .B EFAULT -.I option +.I op is .BR PR_SET_SECCOMP , .I arg2 @@ -2137,7 +2169,7 @@ and is an invalid address. .TP .B EFAULT -.I option +.I op is .B PR_SET_SYSCALL_USER_DISPATCH and @@ -2146,12 +2178,12 @@ has an invalid address. .TP .B EINVAL The value of -.I option +.I op is not recognized, or not supported on this system. .TP .B EINVAL -.I option +.I op is .B PR_MCE_KILL or @@ -2165,10 +2197,10 @@ arguments were not specified as zero. .B EINVAL .I arg2 is not valid value for this -.IR option . +.IR op . .TP .B EINVAL -.I option +.I op is .B PR_SET_SECCOMP or @@ -2177,7 +2209,7 @@ and the kernel was not configured with .BR CONFIG_SECCOMP . .TP .B EINVAL -.I option +.I op is .BR PR_SET_SECCOMP , .I arg2 @@ -2187,7 +2219,7 @@ and the kernel was not configured with .BR CONFIG_SECCOMP_FILTER . .TP .B EINVAL -.I option +.I op is .BR PR_SET_MM , and one of the following is true @@ -2227,7 +2259,7 @@ resource limit to be exceeded. .RE .TP .B EINVAL -.I option +.I op is .B PR_SET_PTRACER and @@ -2237,7 +2269,7 @@ is not 0, or the PID of an existing process. .TP .B EINVAL -.I option +.I op is .B PR_SET_PDEATHSIG and @@ -2245,7 +2277,7 @@ and is not a valid signal number. .TP .B EINVAL -.I option +.I op is .B PR_SET_DUMPABLE and @@ -2256,7 +2288,7 @@ nor .BR SUID_DUMP_USER . .TP .B EINVAL -.I option +.I op is .B PR_SET_TIMING and @@ -2265,7 +2297,7 @@ is not .BR PR_TIMING_STATISTICAL . .TP .B EINVAL -.I option +.I op is .B PR_SET_NO_NEW_PRIVS and @@ -2279,7 +2311,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_GET_NO_NEW_PRIVS and @@ -2291,7 +2323,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_SET_THP_DISABLE and @@ -2302,7 +2334,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_GET_THP_DISABLE and @@ -2314,7 +2346,7 @@ or is nonzero. .TP .B EINVAL -.I option +.I op is .B PR_CAP_AMBIENT and an unused argument @@ -2339,7 +2371,7 @@ and does not specify a valid capability. .TP .B EINVAL -.I option +.I op was .B PR_GET_SPECULATION_CTRL or @@ -2347,8 +2379,9 @@ or and unused arguments to .BR prctl () are not 0. +.TP .B EINVAL -.I option +.I op is .B PR_PAC_RESET_KEYS and the arguments are invalid or unsupported. @@ -2357,7 +2390,7 @@ See the description of above for details. .TP .B EINVAL -.I option +.I op is .B PR_SVE_SET_VL and the arguments are invalid or unsupported, @@ -2367,13 +2400,13 @@ See the description of above for details. .TP .B EINVAL -.I option +.I op is .B PR_SVE_GET_VL and SVE is not available on this platform. .TP .B EINVAL -.I option +.I op is .B PR_SET_SYSCALL_USER_DISPATCH and one of the following is true: @@ -2395,7 +2428,7 @@ is invalid. .RE .TP .B EINVAL -.I option +.I op is .B PR_SET_TAGGED_ADDR_CTRL and the arguments are invalid or unsupported. @@ -2404,7 +2437,7 @@ See the description of above for details. .TP .B EINVAL -.I option +.I op is .B PR_GET_TAGGED_ADDR_CTRL and the arguments are invalid or unsupported. @@ -2413,13 +2446,13 @@ See the description of above for details. .TP .B ENODEV -.I option +.I op was .B PR_SET_SPECULATION_CTRL the kernel or CPU does not support the requested speculation misfeature. .TP .B ENXIO -.I option +.I op was .B PR_MPX_ENABLE_MANAGEMENT or @@ -2428,7 +2461,7 @@ and the kernel or the CPU does not support MPX management. Check that the kernel and processor have MPX support. .TP .B ENXIO -.I option +.I op was .B PR_SET_SPECULATION_CTRL implies that the control of the selected speculation misfeature is not possible. @@ -2437,7 +2470,7 @@ See for the bit fields to determine which option is available. .TP .B EOPNOTSUPP -.I option +.I op is .B PR_SET_FP_MODE and @@ -2445,7 +2478,7 @@ and has an invalid or unsupported value. .TP .B EPERM -.I option +.I op is .BR PR_SET_SECUREBITS , and the caller does not have the @@ -2457,7 +2490,7 @@ or tried to set a flag whose corresponding locked flag was set .BR capabilities (7)). .TP .B EPERM -.I option +.I op is .B PR_SET_SPECULATION_CTRL wherein the speculation was disabled with @@ -2465,7 +2498,7 @@ wherein the speculation was disabled with and caller tried to enable it again. .TP .B EPERM -.I option +.I op is .BR PR_SET_KEEPCAPS , and the caller's @@ -2475,7 +2508,7 @@ flag is set .BR capabilities (7)). .TP .B EPERM -.I option +.I op is .BR PR_CAPBSET_DROP , and the caller does not have the @@ -2483,7 +2516,7 @@ and the caller does not have the capability. .TP .B EPERM -.I option +.I op is .BR PR_SET_MM , and the caller does not have the @@ -2491,7 +2524,7 @@ and the caller does not have the capability. .TP .B EPERM -.I option +.I op is .B PR_CAP_AMBIENT and @@ -2506,7 +2539,7 @@ or the securebit has been set. .TP .B ERANGE -.I option +.I op was .B PR_SET_SPECULATION_CTRL and @@ -2523,14 +2556,14 @@ IRIX has a system call (also introduced in Linux 2.1.44 as irix_prctl on the MIPS architecture), with prototype -.PP +.P .in +4n .EX -.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 ); +.BI "ptrdiff_t prctl(int " op ", int " arg2 ", int " arg3 ); .EE .in -.PP -and options to get the maximum number of processes per user, +.P +and operations to get the maximum number of processes per user, get the maximum number of processors the calling process can use, find out whether a specified process is currently blocked, get or set the maximum stack size, and so on. diff --git a/man2/pread.2 b/man2/pread.2 index 9764e53..4ff94c0 100644 --- a/man2/pread.2 +++ b/man2/pread.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pread 2 2023-03-30 "Linux man-pages 6.05.01" +.TH pread 2 2023-10-31 "Linux man-pages 6.7" .SH NAME pread, pwrite \- read from or write to a file descriptor at a given offset .SH LIBRARY @@ -11,18 +11,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t pread(int " fd ", void " buf [. count "], size_t " count , .BI " off_t " offset ); .BI "ssize_t pwrite(int " fd ", const void " buf [. count "], size_t " count , .BI " off_t " offset ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pread (), .BR pwrite (): .nf @@ -40,7 +40,7 @@ at offset (from the start of the file) into the buffer starting at .IR buf . The file offset is not changed. -.PP +.P .BR pwrite () writes up to .I count @@ -51,7 +51,7 @@ to the file descriptor at offset .IR offset . The file offset is not changed. -.PP +.P The file referenced by .I fd must be capable of seeking. @@ -63,13 +63,13 @@ returns the number of bytes read and .BR pwrite () returns the number of bytes written. -.PP +.P Note that it is not an error for a successful call to transfer fewer bytes than requested (see .BR read (2) and .BR write (2)). -.PP +.P On error, \-1 is returned and .I errno is set to indicate the error. @@ -92,7 +92,7 @@ or POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Added in Linux 2.1.60; the entries in the i386 system call table were added in Linux 2.1.69. C library support (including emulation using @@ -114,7 +114,7 @@ The glibc and .BR pwrite () wrapper functions transparently deal with the change. -.PP +.P On some 32-bit architectures, the calling signature for these system calls differ, for the reasons described in diff --git a/man2/process_madvise.2 b/man2/process_madvise.2 index b95f4e3..37ec5fd 100644 --- a/man2/process_madvise.2 +++ b/man2/process_madvise.2 @@ -5,7 +5,7 @@ .\" .\" Commit ecb8ac8b1f146915aa6b96449b66dd48984caacc .\" -.TH process_madvise 2 2023-03-30 "Linux man-pages 6.05.01" +.TH process_madvise 2 2024-02-28 "Linux man-pages 6.7" .SH NAME process_madvise \- give advice about use of memory to a process .SH LIBRARY @@ -13,23 +13,12 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.BR "#include " " /* Definition of " MADV_* " constants */" -.BR "#include " " /* Definition of " SYS_* " constants */" -.BR "#include " " /* Definition of " "struct iovec" " type */" -.B #include -.PP -.BI "ssize_t syscall(SYS_process_madvise, int " pidfd , -.BI " const struct iovec *" iovec ", size_t " vlen \ -", int " advice , -.BI " unsigned int " flags ");" +.B #include +.P +.BI "ssize_t process_madvise(int " pidfd ", const struct iovec " iovec [. n ], +.BI " size_t " n ", int " advice \ +", unsigned int " flags ); .fi -.PP -.IR Note : -glibc provides no wrapper for -.BR process_madvise (), -necessitating the use of -.BR syscall (2). -.\" FIXME: See .SH DESCRIPTION The .BR process_madvise () @@ -38,23 +27,23 @@ address ranges of another process or of the calling process. It provides the advice for the address ranges described by .I iovec and -.IR vlen . +.IR n . The goal of such advice is to improve system or application performance. -.PP +.P The .I pidfd argument is a PID file descriptor (see .BR pidfd_open (2)) that specifies the process to which the advice is to be applied. -.PP +.P The pointer .I iovec points to an array of .I iovec structures, described in .BR iovec (3type). -.PP -.I vlen +.P +.I n specifies the number of elements in the array of .I iovec structures. @@ -64,7 +53,7 @@ This value must be less than or equal to .I or accessible via the call .IR sysconf(_SC_IOV_MAX) ). -.PP +.P The .I advice argument is one of the following values: @@ -84,31 +73,31 @@ See .B MADV_WILLNEED See .BR madvise (2). -.PP +.P The .I flags argument is reserved for future use; currently, this argument must be specified as 0. -.PP +.P The -.I vlen +.I n and .I iovec arguments are checked before applying any advice. If -.I vlen +.I n is too big, or .I iovec is invalid, then an error will be returned immediately and no advice will be applied. -.PP +.P The advice might be applied to only a part of .I iovec if one of its elements points to an invalid memory region in the remote process. No further elements will be processed beyond that point. (See the discussion regarding partial advice in RETURN VALUE.) -.PP +.P .\" commit 96cfe2c0fd23ea7c2368d14f769d287e7ae1082e Starting in Linux 5.12, permission to apply advice to another process is governed by @@ -133,7 +122,7 @@ if an error occurred after some elements were already processed. The caller should check the return value to determine whether a partial advice occurred. -.PP +.P On error, \-1 is returned and .I errno is set to indicate the error. @@ -163,7 +152,7 @@ overflows a value. .TP .B EINVAL -.I vlen +.I n is too large. .TP .B ENOMEM @@ -177,7 +166,7 @@ The caller does not have permission to access the address space of the process .TP .B ESRCH The target process does not exist (i.e., it has terminated and been waited on). -.PP +.P See .BR madvise (2) for @@ -187,13 +176,15 @@ errors. Linux. .SH HISTORY Linux 5.10. -.\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc -.PP +.\" Linux commit ecb8ac8b1f146915aa6b96449b66dd48984caacc +glibc 2.36. +.\" glibc commit d19ee3473d68ca0e794f3a8b7677a0983ae1342e +.P Support for this system call is optional, depending on the setting of the .B CONFIG_ADVISE_SYSCALLS configuration option. -.PP +.P When this system call first appeared in Linux 5.10, permission to apply advice to another process was entirely governed by ptrace access mode diff --git a/man2/process_vm_readv.2 b/man2/process_vm_readv.2 index 86da35c..23c9111 100644 --- a/man2/process_vm_readv.2 +++ b/man2/process_vm_readv.2 @@ -6,7 +6,7 @@ .\" .\" Commit fcf634098c00dd9cd247447368495f0b79be12d1 .\" -.TH process_vm_readv 2 2023-05-03 "Linux man-pages 6.05.01" +.TH process_vm_readv 2 2023-10-31 "Linux man-pages 6.7" .SH NAME process_vm_readv, process_vm_writev \- transfer data between process address spaces @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t process_vm_readv(pid_t " pid , .BI " const struct iovec *" local_iov , .BI " unsigned long " liovcnt , @@ -30,12 +30,12 @@ Standard C library .BI " unsigned long " riovcnt , .BI " unsigned long " flags ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR process_vm_readv (), .BR process_vm_writev (): .nf @@ -48,7 +48,7 @@ of the calling process ("the local process") and the process identified by ("the remote process"). The data moves directly between the address spaces of the two processes, without passing through kernel space. -.PP +.P The .BR process_vm_readv () system call transfers data from the remote process to the local process. @@ -73,7 +73,7 @@ and .I liovcnt specifies the number of elements in .IR local_iov . -.PP +.P The .BR process_vm_writev () system call is the converse of @@ -87,7 +87,7 @@ and .I remote_iov have the same meaning as for .BR process_vm_readv (). -.PP +.P The .I local_iov and @@ -96,7 +96,7 @@ arguments point to an array of .I iovec structures, described in .BR iovec (3type). -.PP +.P Buffers are processed in array order. This means that .BR process_vm_readv () @@ -110,7 +110,7 @@ Likewise, is completely read before proceeding to .IR remote_iov[1] , and so on. -.PP +.P Similarly, .BR process_vm_writev () writes out the entire contents of @@ -121,7 +121,7 @@ and it completely fills .I remote_iov[0] before proceeding to .IR remote_iov[1] . -.PP +.P The lengths of .I remote_iov[i].iov_len and @@ -129,11 +129,11 @@ and do not have to be the same. Thus, it is possible to split a single local buffer into multiple remote buffers, or vice versa. -.PP +.P The .I flags argument is currently unused and must be set to 0. -.PP +.P The values specified in the .I liovcnt and @@ -146,7 +146,7 @@ or accessible via the call .IR sysconf(_SC_IOV_MAX) ). .\" In time, glibc might provide a wrapper that works around this limit, .\" as is done for readv()/writev() -.PP +.P The count arguments and .I local_iov are checked before doing any transfers. @@ -156,7 +156,7 @@ is invalid, or the addresses refer to regions that are inaccessible to the local process, none of the vectors will be processed and an error will be returned immediately. -.PP +.P Note, however, that these system calls do not check the memory regions in the remote process until just before doing the read/write. Consequently, a partial read/write (see RETURN VALUE) @@ -176,7 +176,7 @@ elements and have them merge back into a single write entry. The first read entry goes up to the page boundary, while the second starts on the next page boundary.) -.PP +.P Permission to read from or write to another process is governed by a ptrace access mode .B PTRACE_MODE_ATTACH_REALCREDS @@ -198,7 +198,7 @@ These system calls won't perform a partial transfer that splits a single element.) The caller should check the return value to determine whether a partial read/write occurred. -.PP +.P On error, \-1 is returned and .I errno is set to indicate the error. @@ -260,7 +260,7 @@ The data transfers performed by and .BR process_vm_writev () are not guaranteed to be atomic in any way. -.PP +.P These system calls were designed to permit fast message passing by allowing messages to be exchanged with a single copy operation (rather than the double copy that would be required @@ -276,7 +276,7 @@ and writes the first 10 bytes into .I buf1 and the second 10 bytes into .IR buf2 . -.PP +.P .\" SRC BEGIN (process_vm_readv.c) .EX #define _GNU_SOURCE diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 4149a32..1cd9966 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -83,7 +83,7 @@ .\" .\" and others that can be found in the arch/*/include/uapi/asm/ptrace files .\" -.TH ptrace 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ptrace 2 2024-03-03 "Linux man-pages 6.7" .SH NAME ptrace \- process trace .SH LIBRARY @@ -92,8 +92,8 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "long ptrace(enum __ptrace_request " request ", pid_t " pid , +.P +.BI "long ptrace(enum __ptrace_request " op ", pid_t " pid , .BI " void *" addr ", void *" data ); .fi .SH DESCRIPTION @@ -104,7 +104,7 @@ may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. It is primarily used to implement breakpoint debugging and system call tracing. -.PP +.P A tracee first needs to be attached to the tracer. Attachment and subsequent commands are per thread: in a multithreaded process, @@ -115,23 +115,23 @@ Therefore, "tracee" always means "(one) thread", never "a (possibly multithreaded) process". Ptrace commands are always sent to a specific tracee using a call of the form -.PP +.P .in +4n .EX ptrace(PTRACE_foo, pid, ...) .EE .in -.PP +.P where .I pid is the thread ID of the corresponding Linux thread. -.PP +.P (Note that in this page, a "multithreaded process" means a thread group consisting of threads created using the .BR clone (2) .B CLONE_THREAD flag.) -.PP +.P A process can initiate a trace by calling .BR fork (2) and having the resulting child do a @@ -142,7 +142,7 @@ Alternatively, one process may commence tracing another process using .B PTRACE_ATTACH or .BR PTRACE_SEIZE . -.PP +.P While being traced, the tracee will stop each time a signal is delivered, even if the signal is being ignored. (An exception is @@ -155,11 +155,11 @@ The tracer will be notified at its next call to value containing information that indicates the cause of the stop in the tracee. While the tracee is stopped, -the tracer can use various ptrace requests to inspect and modify the tracee. +the tracer can use various ptrace operations to inspect and modify the tracee. The tracer then causes the tracee to continue, optionally ignoring the delivered signal (or even delivering a different signal instead). -.PP +.P If the .B PTRACE_O_TRACEEXEC option is not in effect, all successful calls to @@ -169,18 +169,18 @@ by the traced process will cause it to be sent a signal, giving the parent a chance to gain control before the new program begins execution. -.PP +.P When the tracer is finished tracing, it can cause the tracee to continue executing in a normal, untraced mode via .BR PTRACE_DETACH . -.PP +.P The value of -.I request -determines the action to be performed: +.I op +determines the operation to be performed: .TP .B PTRACE_TRACEME Indicate that this process is to be traced by its parent. -A process probably shouldn't make this request if its parent +A process probably shouldn't make this operation if its parent isn't expecting to trace it. .RI ( pid , .IR addr , @@ -190,12 +190,12 @@ are ignored.) .IP The .B PTRACE_TRACEME -request is used only by the tracee; -the remaining requests are used only by the tracer. -In the following requests, +operation is used only by the tracee; +the remaining operations are used only by the tracer. +In the following operations, .I pid specifies the thread ID of the tracee to be acted on. -For requests other than +For operations other than .BR PTRACE_ATTACH , .BR PTRACE_SEIZE , .BR PTRACE_INTERRUPT , @@ -203,14 +203,16 @@ and .BR PTRACE_KILL , the tracee must be stopped. .TP -.BR PTRACE_PEEKTEXT ", " PTRACE_PEEKDATA +.B PTRACE_PEEKTEXT +.TQ +.B PTRACE_PEEKDATA Read a word at the address .I addr in the tracee's memory, returning the word as the result of the .BR ptrace () call. Linux does not have separate text and data address spaces, -so these two requests are currently equivalent. +so these two operations are currently equivalent. .RI ( data is ignored; but see NOTES.) .TP @@ -232,7 +234,9 @@ See NOTES. .RI ( data is ignored; but see NOTES.) .TP -.BR PTRACE_POKETEXT ", " PTRACE_POKEDATA +.B PTRACE_POKETEXT +.TQ +.B PTRACE_POKEDATA Copy the word .I data to the address @@ -242,7 +246,7 @@ As for .B PTRACE_PEEKTEXT and .BR PTRACE_PEEKDATA , -these two requests are currently equivalent. +these two operations are currently equivalent. .TP .B PTRACE_POKEUSER .\" PTRACE_POKEUSR in kernel source, but glibc uses PTRACE_POKEUSER, @@ -260,7 +264,9 @@ some modifications to the USER area are disallowed. .\" FIXME In the preceding sentence, which modifications are disallowed, .\" and when they are disallowed, how does user space discover that fact? .TP -.BR PTRACE_GETREGS ", " PTRACE_GETFPREGS +.B PTRACE_GETREGS +.TQ +.B PTRACE_GETFPREGS Copy the tracee's general-purpose or floating-point registers, respectively, to the address .I data @@ -304,7 +310,9 @@ On return, the kernel modifies .B iov.len to indicate the actual number of bytes returned. .TP -.BR PTRACE_SETREGS ", " PTRACE_SETFPREGS +.B PTRACE_SETREGS +.TQ +.B PTRACE_SETFPREGS Modify the tracee's general-purpose or floating-point registers, respectively, from the address .I data @@ -391,7 +399,7 @@ field includes information .RB ( __SI_CHLD , .BR __SI_FAULT , etc.) that are not otherwise exposed to user space. -.PP +.P .in +4n .EX struct ptrace_peeksiginfo_args { @@ -696,7 +704,9 @@ whether a signal sent to the tracee is delivered or not. .RI ( addr is ignored.) .TP -.BR PTRACE_SYSCALL ", " PTRACE_SINGLESTEP +.B PTRACE_SYSCALL +.TQ +.B PTRACE_SINGLESTEP Restart the stopped tracee as for .BR PTRACE_CONT , but arrange for the tracee to be stopped at @@ -730,7 +740,7 @@ argument. The .I addr argument is ignored. -This request is currently +This operation is currently .\" As of 4.19-rc2 supported only on arm (and arm64, though only for backwards compatibility), .\" commit 27aa55c5e5123fa8b8ad0156559d34d7edff58ca @@ -740,7 +750,9 @@ system call number in). .\" see change_syscall in tools/testing/selftests/seccomp/seccomp_bpf.c .\" and also strace's linux/*/set_scno.c files. .TP -.BR PTRACE_SYSEMU ", " PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" +.B PTRACE_SYSEMU +.TQ +.BR PTRACE_SYSEMU_SINGLESTEP " (since Linux 2.6.14)" For .BR PTRACE_SYSEMU , continue and stop on entry to the next system call, @@ -758,7 +770,7 @@ argument is treated as for The .I addr argument is ignored. -These requests are currently +These operations are currently .\" As at 3.7 supported only on x86. .TP @@ -1130,7 +1142,7 @@ all threads exit. Tracees report their death to their tracer(s). Notification of this event is delivered via .BR waitpid (2). -.PP +.P Note that the killing signal will first cause signal-delivery-stop (on one tracee only), and only after it is injected by the tracer @@ -1139,7 +1151,7 @@ will death from the signal happen on .I all tracees within a multithreaded process. (The term "signal-delivery-stop" is explained below.) -.PP +.P .B SIGKILL does not generate signal-delivery-stop and therefore the tracer can't suppress it. @@ -1151,16 +1163,16 @@ The net effect is that .B SIGKILL always kills the process (all its threads), even if some threads of the process are ptraced. -.PP +.P When the tracee calls .BR _exit (2), it reports its death to its tracer. Other threads are not affected. -.PP +.P When any thread executes .BR exit_group (2), every tracee in its thread group reports its death to its tracer. -.PP +.P If the .B PTRACE_O_TRACEEXIT option is on, @@ -1175,7 +1187,7 @@ depending on the kernel version; see BUGS below), and when threads are torn down on .BR execve (2) in a multithreaded process. -.PP +.P The tracer cannot assume that the ptrace-stopped tracee exists. There are many scenarios when the tracee may die while stopped (such as .BR SIGKILL ). @@ -1199,8 +1211,8 @@ ptrace operation returned .I waitpid(WNOHANG) may return 0 instead. In other words, the tracee may be "not yet fully dead", -but already refusing ptrace requests. -.PP +but already refusing ptrace operations. +.P The tracer can't assume that the tracee .I always ends its life by reporting @@ -1236,11 +1248,11 @@ in group-stop before it will not respond to signals until .B SIGCONT is received. -.PP +.P There are many kinds of states when the tracee is stopped, and in ptrace discussions they are often conflated. Therefore, it is important to use precise terms. -.PP +.P In this manual page, any stopped state in which the tracee is ready to accept ptrace commands from the tracer is called .IR ptrace-stop . @@ -1252,18 +1264,18 @@ be further subdivided into .IR "PTRACE_EVENT stops" , and so on. These stopped states are described in detail below. -.PP +.P When the running tracee enters ptrace-stop, it notifies its tracer using .BR waitpid (2) (or one of the other "wait" system calls). Most of this manual page assumes that the tracer waits with: -.PP +.P .in +4n .EX pid = waitpid(pid_or_minus_1, &status, __WALL); .EE .in -.PP +.P Ptrace-stopped tracees are reported as returns with .I pid greater than 0 and @@ -1275,7 +1287,7 @@ true. .\" rules different if user wants to use waitid? Will waitid require .\" WEXITED? .\" -.PP +.P The .B __WALL flag does not include the @@ -1283,14 +1295,14 @@ flag does not include the and .B WEXITED flags, but implies their functionality. -.PP +.P Setting the .B WCONTINUED flag when calling .BR waitpid (2) is not recommended: the "continued" state is per-process and consuming it can confuse the real parent of the tracee. -.PP +.P Use of the .B WNOHANG flag may cause @@ -1298,7 +1310,7 @@ flag may cause to return 0 ("no wait results available yet") even if the tracer knows there should be a notification. Example: -.PP +.P .in +4n .EX errno = 0; @@ -1313,7 +1325,7 @@ if (errno == ESRCH) { .\" FIXME . .\" waitid usage? WNOWAIT? .\" describe how wait notifications queue (or not queue) -.PP +.P The following kinds of ptrace-stops exist: signal-delivery-stops, group-stops, .B PTRACE_EVENT @@ -1343,7 +1355,7 @@ If the selected thread is traced, it enters signal-delivery-stop. At this point, the signal is not yet delivered to the process, and can be suppressed by the tracer. If the tracer doesn't suppress the signal, -it passes the signal to the tracee in the next ptrace restart request. +it passes the signal to the tracee in the next ptrace restart operation. This second step of signal delivery is called .I "signal injection" in this manual page. @@ -1352,7 +1364,7 @@ signal-delivery-stop doesn't happen until the signal is unblocked, with the usual exception that .B SIGSTOP can't be blocked. -.PP +.P Signal-delivery-stop is observed by the tracer as .BR waitpid (2) returning with @@ -1369,16 +1381,16 @@ returns a stopping signal, this may be a group-stop; see below. .SS Signal injection and suppression After signal-delivery-stop is observed by the tracer, the tracer should restart the tracee with the call -.PP +.P .in +4n .EX ptrace(PTRACE_restart, pid, 0, sig) .EE .in -.PP +.P where .B PTRACE_restart -is one of the restarting ptrace requests. +is one of the restarting ptrace operations. If .I sig is 0, then a signal is not delivered. @@ -1388,13 +1400,13 @@ is delivered. This operation is called .I "signal injection" in this manual page, to distinguish it from signal-delivery-stop. -.PP +.P The .I sig value may be different from the .I WSTOPSIG(status) value: the tracer can cause a different signal to be injected. -.PP +.P Note that a suppressed signal still causes system calls to return prematurely. In this case, system calls will be restarted: the tracer will @@ -1410,7 +1422,7 @@ signal is suppressed; however, kernel bugs exist which cause some system calls to fail with .B EINTR even though no observable signal is injected to the tracee. -.PP +.P Restarting ptrace commands issued in ptrace-stops other than signal-delivery-stop are not guaranteed to inject a signal, even if .I sig @@ -1421,26 +1433,26 @@ may simply be ignored. Ptrace users should not try to "create a new signal" this way: use .BR tgkill (2) instead. -.PP -The fact that signal injection requests may be ignored +.P +The fact that signal injection operations may be ignored when restarting the tracee after ptrace stops that are not signal-delivery-stops is a cause of confusion among ptrace users. One typical scenario is that the tracer observes group-stop, mistakes it for signal-delivery-stop, restarts the tracee with -.PP +.P .in +4n .EX ptrace(PTRACE_restart, pid, 0, stopsig) .EE .in -.PP +.P with the intention of injecting .IR stopsig , but .I stopsig gets ignored and the tracee continues to run. -.PP +.P The .B SIGCONT signal has a side effect of waking up (all threads of) @@ -1460,11 +1472,11 @@ was delivered. In other words, .B SIGCONT may be not the first signal observed by the tracee after it was sent. -.PP +.P Stopping signals cause (all threads of) a process to enter group-stop. This side effect happens after signal injection, and therefore can be suppressed by the tracer. -.PP +.P In Linux 2.4 and earlier, the .B SIGSTOP signal can't be injected. @@ -1474,7 +1486,7 @@ signal can't be injected. .\" /* The debugger continued. Ignore SIGSTOP. */ .\" if (signr == SIGSTOP) .\" continue; -.PP +.P .B PTRACE_GETSIGINFO can be used to retrieve a .I siginfo_t @@ -1503,7 +1515,7 @@ will group-stop be initiated on tracees within the multithreaded process. As usual, every tracee reports its group-stop separately to the corresponding tracer. -.PP +.P Group-stop is observed by the tracer as .BR waitpid (2) returning with @@ -1512,13 +1524,13 @@ true, with the stopping signal available via .IR WSTOPSIG(status) . The same result is returned by some other classes of ptrace-stops, therefore the recommended practice is to perform the call -.PP +.P .in +4n .EX ptrace(PTRACE_GETSIGINFO, pid, 0, &siginfo) .EE .in -.PP +.P The call can be avoided if the signal is not .BR SIGSTOP , .BR SIGTSTP , @@ -1539,7 +1551,7 @@ then it is definitely a group-stop. ("no such process") if a .B SIGKILL killed the tracee.) -.PP +.P If tracee was attached using .BR PTRACE_SEIZE , group-stop is indicated by @@ -1549,7 +1561,7 @@ This allows detection of group-stops without requiring an extra .B PTRACE_GETSIGINFO call. -.PP +.P As of Linux 2.6.38, after the tracer sees the tracee ptrace-stop and until it restarts or kills it, the tracee will not run, @@ -1558,7 +1570,7 @@ and will not send notifications (except death) to the tracer, even if the tracer enters into another .BR waitpid (2) call. -.PP +.P The kernel behavior described in the previous paragraph causes a problem with transparent handling of stopping signals. If the tracer restarts the tracee after group-stop, @@ -1572,7 +1584,7 @@ signals will not be reported to the tracer; this would cause the .B SIGCONT signals to have no effect on the tracee. -.PP +.P Since Linux 3.4, there is a method to overcome this problem: instead of .BR PTRACE_CONT , a @@ -1589,7 +1601,7 @@ If the tracer sets options, the tracee will enter ptrace-stops called .B PTRACE_EVENT stops. -.PP +.P .B PTRACE_EVENT stops are observed by the tracer as .BR waitpid (2) @@ -1606,13 +1618,13 @@ An additional bit is set in the higher byte of the status word: the value .I status>>8 will be -.PP +.P .in +4n .EX ((PTRACE_EVENT_foo<<8) | SIGTRAP). .EE .in -.PP +.P The following events exist: .TP .B PTRACE_EVENT_VFORK @@ -1649,7 +1661,7 @@ with the .B CLONE_VFORK flag, but after the child unblocked this tracee by exiting or execing. -.PP +.P For all four stops described above, the stop occurs in the parent (i.e., the tracee), not in the newly created thread. @@ -1698,7 +1710,7 @@ portion of the seccomp filter rule) can be retrieved with .BR PTRACE_GETEVENTMSG . The semantics of this stop are described in detail in a separate section below. -.PP +.P .B PTRACE_GETSIGINFO on .B PTRACE_EVENT @@ -1737,7 +1749,7 @@ Note that all mentions .B PTRACE_SYSEMU apply equally to .BR PTRACE_SYSEMU_SINGLESTEP . -.PP +.P However, even if the tracee was continued using .BR PTRACE_SYSCALL , it is not guaranteed that the next stop will be a syscall-exit-stop. @@ -1754,7 +1766,7 @@ or die silently (if it is a thread group leader, the happened in another thread, and that thread is not traced by the same tracer; this situation is discussed later). -.PP +.P Syscall-enter-stop and syscall-exit-stop are observed by the tracer as .BR waitpid (2) returning with @@ -1769,7 +1781,7 @@ option was set by the tracer, then .I WSTOPSIG(status) will give the value .IR "(SIGTRAP\ |\ 0x80)" . -.PP +.P Syscall-stops can be distinguished from signal-delivery-stop with .B SIGTRAP by querying @@ -1786,7 +1798,7 @@ for example, a system call etc.), expiration of a POSIX timer, change of state on a POSIX message queue, -or completion of an asynchronous I/O request. +or completion of an asynchronous I/O operation. .TP .IR si_code " == SI_KERNEL (0x80)" .B SIGTRAP @@ -1794,12 +1806,12 @@ was sent by the kernel. .TP .IR si_code " == SIGTRAP or " si_code " == (SIGTRAP|0x80)" This is a syscall-stop. -.PP +.P However, syscall-stops happen very often (twice per system call), and performing .B PTRACE_GETSIGINFO for every syscall-stop may be somewhat expensive. -.PP +.P Some architectures allow the cases to be distinguished by examining registers. For example, on x86, @@ -1822,13 +1834,13 @@ looks like "syscall-stop which is not syscall-enter-stop"; in other words, it looks like a "stray syscall-exit-stop" and can be detected this way. But such detection is fragile and is best avoided. -.PP +.P Using the .B PTRACE_O_TRACESYSGOOD option is the recommended method to distinguish syscall-stops from other kinds of ptrace-stops, since it is reliable and does not incur a performance penalty. -.PP +.P Syscall-enter-stop and syscall-exit-stop are indistinguishable from each other by the tracer. The tracer needs to keep track of the sequence of @@ -1843,12 +1855,12 @@ However, note that seccomp stops (see below) can cause syscall-exit-stops, without preceding syscall-entry-stops. If seccomp is in use, care needs to be taken not to misinterpret such stops as syscall-entry-stops. -.PP +.P If after syscall-enter-stop, the tracer uses a restarting command other than .BR PTRACE_SYSCALL , syscall-exit-stop is not generated. -.PP +.P .B PTRACE_GETSIGINFO on syscall-stops returns .B SIGTRAP @@ -1869,7 +1881,7 @@ of ptrace stops has changed between kernel versions. This documents the behavior from their introduction until Linux 4.7 (inclusive). The behavior in later kernel versions is documented in the next section. -.PP +.P A .B PTRACE_EVENT_SECCOMP stop occurs whenever a @@ -1879,7 +1891,7 @@ This is independent of which methods was used to restart the system call. Notably, seccomp still runs even if the tracee was restarted using .B PTRACE_SYSEMU and this system call is unconditionally skipped. -.PP +.P Restarts from this stop will behave as if the stop had occurred right before the system call in question. In particular, both @@ -1909,7 +1921,7 @@ Note that seccomp no longer runs (and no .B PTRACE_EVENT_SECCOMP will be reported) if the system call is skipped due to .BR PTRACE_SYSEMU . -.PP +.P Functionally, a .B PTRACE_EVENT_SECCOMP stop functions comparably @@ -1920,7 +1932,7 @@ the system call number may be changed and any other modified registers are visible to the to-be-executed system call as well). Note that there may be, but need not have been a preceding syscall-entry-stop. -.PP +.P After a .B PTRACE_EVENT_SECCOMP stop, seccomp will be rerun, with a @@ -1947,12 +1959,12 @@ and .BR PTRACE_KILL ) require the tracee to be in a ptrace-stop, otherwise they fail with .BR ESRCH . -.PP +.P When the tracee is in ptrace-stop, the tracer can read and write data to the tracee using informational commands. These commands leave the tracee in ptrace-stopped state: -.PP +.P .in +4n .EX ptrace(PTRACE_PEEKTEXT/PEEKDATA/PEEKUSER, pid, addr, 0); @@ -1967,7 +1979,7 @@ ptrace(PTRACE_GETEVENTMSG, pid, 0, &long_var); ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); .EE .in -.PP +.P Note that some errors are not reported. For example, setting signal information .RI ( siginfo ) @@ -1978,15 +1990,15 @@ querying .B PTRACE_GETEVENTMSG may succeed and return some random value if current ptrace-stop is not documented as returning a meaningful event message. -.PP +.P The call -.PP +.P .in +4n .EX ptrace(PTRACE_SETOPTIONS, pid, 0, PTRACE_O_flags); .EE .in -.PP +.P affects one tracee. The tracee's current flags are replaced. Flags are inherited by new tracees created and "auto-attached" via active @@ -1995,16 +2007,16 @@ Flags are inherited by new tracees created and "auto-attached" via active or .B PTRACE_O_TRACECLONE options. -.PP +.P Another group of commands makes the ptrace-stopped tracee run. They have the form: -.PP +.P .in +4n .EX ptrace(cmd, pid, 0, sig); .EE .in -.PP +.P where .I cmd is @@ -2027,21 +2039,21 @@ recommended practice is to always pass 0 in .IR sig .) .SS Attaching and detaching A thread can be attached to the tracer using the call -.PP +.P .in +4n .EX ptrace(PTRACE_ATTACH, pid, 0, 0); .EE .in -.PP +.P or -.PP +.P .in +4n .EX ptrace(PTRACE_SEIZE, pid, 0, PTRACE_O_flags); .EE .in -.PP +.P .B PTRACE_ATTACH sends .B SIGSTOP @@ -2065,14 +2077,14 @@ may race and the concurrent may be lost. .\" .\" FIXME Describe how to attach to a thread which is already group-stopped. -.PP +.P Since attaching sends .B SIGSTOP and the tracer usually suppresses it, this may cause a stray .B EINTR return from the currently executing system call in the tracee, as described in the "Signal injection and suppression" section. -.PP +.P Since Linux 3.4, .B PTRACE_SEIZE can be used instead of @@ -2084,30 +2096,30 @@ it after attach (or at any other time) without sending it any signals, use .B PTRACE_INTERRUPT command. -.PP -The request -.PP +.P +The operation +.P .in +4n .EX ptrace(PTRACE_TRACEME, 0, 0, 0); .EE .in -.PP +.P turns the calling thread into a tracee. The thread continues to run (doesn't enter ptrace-stop). A common practice is to follow the .B PTRACE_TRACEME with -.PP +.P .in +4n .EX raise(SIGSTOP); .EE .in -.PP +.P and allow the parent (which is our tracer now) to observe our signal-delivery-stop. -.PP +.P If the .BR PTRACE_O_TRACEFORK , .BR PTRACE_O_TRACEVFORK , @@ -2131,15 +2143,15 @@ are automatically attached to the same tracer which traced their parent. .B SIGSTOP is delivered to the children, causing them to enter signal-delivery-stop after they exit the system call which created them. -.PP +.P Detaching of the tracee is performed by: -.PP +.P .in +4n .EX ptrace(PTRACE_DETACH, pid, 0, sig); .EE .in -.PP +.P .B PTRACE_DETACH is a restarting operation; therefore it requires the tracee to be in ptrace-stop. @@ -2147,7 +2159,7 @@ If the tracee is in signal-delivery-stop, a signal can be injected. Otherwise, the .I sig parameter may be silently ignored. -.PP +.P If the tracee is running when the tracer wants to detach it, the usual solution is to send .B SIGSTOP @@ -2171,7 +2183,7 @@ because no signal delivery happens while it is\[em]not even .BR SIGSTOP . .\" FIXME Describe how to detach from a group-stopped tracee so that it .\" doesn't run, but continues to wait for SIGCONT. -.PP +.P If the tracer dies, all tracees are automatically detached and restarted, unless they were in group-stop. Handling of restart from group-stop is currently buggy, @@ -2243,10 +2255,10 @@ If the thread group leader was not traced .BR execve (2) it will appear as if it has become a tracee of the tracer of the execing tracee. -.PP +.P All of the above effects are the artifacts of the thread ID change in the tracee. -.PP +.P The .B PTRACE_O_TRACEEXEC option is the recommended tool for dealing with this situation. @@ -2266,13 +2278,13 @@ option disables legacy .B SIGTRAP generation on .BR execve (2). -.PP +.P When the tracer receives .B PTRACE_EVENT_EXEC stop notification, it is guaranteed that except this tracee and the thread group leader, no other threads from the process are alive. -.PP +.P On receiving the .B PTRACE_EVENT_EXEC stop notification, @@ -2280,17 +2292,17 @@ the tracer should clean up all its internal data structures describing the threads of this process, and retain only one data structure\[em]one which describes the single still running tracee, with -.PP +.P .in +4n .EX thread ID == thread group ID == process ID. .EE .in -.PP +.P Example: two threads call .BR execve (2) at the same time: -.PP +.P .nf *** we get syscall-enter-stop in thread 1: ** PID1 execve("/bin/foo", "foo" @@ -2302,7 +2314,7 @@ PID2 execve("/bin/bar", "bar" *** we get syscall-exit-stop for PID0: ** PID0 <... execve resumed> ) = 0 .fi -.PP +.P If the .B PTRACE_O_TRACEEXEC option is @@ -2329,7 +2341,7 @@ set to 0 .RI ( SI_USER ). This signal may be blocked by signal mask, and thus may be delivered (much) later. -.PP +.P Usually, the tracer (for example, .BR strace (1)) would not want to show this extra post-execve @@ -2357,10 +2369,10 @@ This used to cause the real parent of the process to stop receiving several kinds of .BR waitpid (2) notifications when the child process is traced by some other process. -.PP +.P Many of these bugs have been fixed, but as of Linux 2.6.38 several still exist; see BUGS below. -.PP +.P As of Linux 2.6.38, the following is believed to work correctly: .IP \[bu] 3 exit/death by signal is reported first to the tracer, then, @@ -2373,21 +2385,21 @@ the report is sent only once. .SH RETURN VALUE On success, the .B PTRACE_PEEK* -requests return the requested data (but see NOTES), +operations return the requested data (but see NOTES), the .B PTRACE_SECCOMP_GET_FILTER -request returns the number of instructions in the BPF program, +operation returns the number of instructions in the BPF program, the .B PTRACE_GET_SYSCALL_INFO -request returns the number of bytes available to be written by the kernel, -and other requests return zero. -.PP -On error, all requests return \-1, and +operation returns the number of bytes available to be written by the kernel, +and other operations return zero. +.P +On error, all operations return \-1, and .I errno is set to indicate the error. Since the value returned by a successful .B PTRACE_PEEK* -request may be \-1, the caller must clear +operation may be \-1, the caller must clear .I errno before the call, and then check it afterward to determine whether or not an error occurred. @@ -2411,11 +2423,11 @@ more or less arbitrarily. An attempt was made to set an invalid option. .TP .B EIO -.I request +.I op is invalid, or an attempt was made to read from or write to an invalid area in the tracer's or the tracee's memory, or there was a word-alignment violation, -or an invalid signal was specified during a restart request. +or an invalid signal was specified during a restart operation. .TP .B EPERM The specified process cannot be traced. @@ -2433,12 +2445,12 @@ or (before Linux 2.6.26) be .B ESRCH The specified process does not exist, or is not currently being traced by the caller, or is not stopped -(for requests that require a stopped tracee). +(for operations that require a stopped tracee). .SH STANDARDS None. .SH HISTORY SVr4, 4.3BSD. -.PP +.P Before Linux 2.6.26, .\" See commit 00cd5c37afd5f431ac186dd131705048c0a11fdb .BR init (1), @@ -2450,7 +2462,7 @@ are interpreted according to the prototype given, glibc currently declares .BR ptrace () as a variadic function with only the -.I request +.I op argument fixed. It is recommended to always supply four arguments, even if the requested operation does not use them, @@ -2458,20 +2470,20 @@ setting unused/ignored arguments to .I 0L or .IR "(void\ *)\ 0". -.PP +.P A tracees parent continues to be the tracer even if that tracer calls .BR execve (2). -.PP +.P The layout of the contents of memory and the USER area are quite operating-system- and architecture-specific. The offset supplied, and the data returned, might not entirely match with the definition of .IR "struct user" . .\" See http://lkml.org/lkml/2008/5/8/375 -.PP +.P The size of a "word" is determined by the operating-system variant (e.g., for 32-bit Linux it is 32 bits). -.PP +.P This page documents the way the .BR ptrace () call works currently in Linux. @@ -2497,7 +2509,7 @@ whether or not the "target" process is dumpable, and the results of checks performed by any enabled Linux Security Module (LSM)\[em]for example, SELinux, Yama, or Smack\[em]and by the commoncap LSM (which is always invoked). -.PP +.P Prior to Linux 2.6.27, all access checks were of a single type. Since Linux 2.6.27, .\" commit 006ebb40d3d65338bd74abb03b945f8d60e362bd @@ -2541,7 +2553,7 @@ was effectively the default before Linux 2.6.27.) .\" about proper handling of /proc/pid/fd. Arguably that one might belong .\" back in the _ATTACH camp. .\" -.PP +.P Since Linux 4.5, .\" commit caaee6234d05a58c5b4d05e7bf766131b810a657 the above access mode checks are combined (ORed) with @@ -2555,7 +2567,7 @@ or effective capabilities for LSM checks. .B PTRACE_MODE_REALCREDS Use the caller's real UID and GID or permitted capabilities for LSM checks. This was effectively the default before Linux 4.5. -.PP +.P Because combining one of the credential modifiers with one of the aforementioned access modes is typical, some macros are defined in the kernel sources for the combinations: @@ -2575,7 +2587,7 @@ Defined as .B PTRACE_MODE_ATTACH_REALCREDS Defined as .BR "PTRACE_MODE_ATTACH | PTRACE_MODE_REALCREDS" . -.PP +.P One further modifier can be ORed with the access mode: .TP .BR PTRACE_MODE_NOAUDIT " (since Linux 3.3)" @@ -2591,7 +2603,7 @@ In these cases, accessing the file is not a security violation and there is no reason to generate a security audit record. This modifier suppresses the generation of such an audit record for the particular access check. -.PP +.P Note that all of the .B PTRACE_MODE_* constants described in this subsection are kernel-internal, @@ -2602,7 +2614,7 @@ and accesses to various pseudofiles (e.g., under .IR /proc ). These names are used in other manual pages to provide a simple shorthand for labeling the different kernel checks. -.PP +.P The algorithm employed for ptrace access mode checking determines whether the calling process is allowed to perform the corresponding action on the target process. @@ -2724,7 +2736,7 @@ a compromised process can ptrace-attach to other sensitive processes (e.g., a GPG agent or an SSH session) owned by the user in order to gain additional credentials that may exist in memory and thus expand the scope of the attack. -.PP +.P More precisely, the Yama LSM limits two types of operations: .IP \[bu] 3 Any operation that performs a ptrace access mode @@ -2736,7 +2748,7 @@ check\[em]for example, .IP \[bu] .BR ptrace () .BR PTRACE_TRACEME . -.PP +.P A process that has the .B CAP_SYS_PTRACE capability can update the @@ -2796,7 +2808,7 @@ operations or trace children that employ .BR PTRACE_TRACEME . .IP Once this value has been written to the file, it cannot be changed. -.PP +.P With respect to values 1 and 2, note that creating a new user namespace effectively removes the protection offered by Yama. @@ -2817,7 +2829,7 @@ At the system call level, the .BR PTRACE_PEEKDATA , and .B PTRACE_PEEKUSER -requests have a different API: they store the result +operations have a different API: they store the result at the address specified by the .I data parameter, and the return value is the error flag. @@ -2834,10 +2846,10 @@ This can be worked around by redefining to .BR PTRACE_OLDSETOPTIONS , if that is defined. -.PP +.P Group-stop notifications are sent to the tracer, but not to real parent. Last confirmed on 2.6.38.6. -.PP +.P If a thread group leader is traced and exits by calling .BR _exit (2), .\" Note from Denys Vlasenko: @@ -2868,7 +2880,7 @@ One possible workaround is to the thread group leader instead of restarting it in this case. Last confirmed on 2.6.38.6. .\" FIXME . need to test/verify this scenario -.PP +.P A .B SIGKILL signal may still cause a @@ -2878,7 +2890,7 @@ This may be changed in the future; .B SIGKILL is meant to always immediately kill tasks even under ptrace. Last confirmed on Linux 3.13. -.PP +.P Some system calls return with .B EINTR if a signal was sent to a tracee, but delivery was suppressed by the tracer. @@ -2896,40 +2908,40 @@ from an file descriptor. The usual symptom of this bug is that when you attach to a quiescent process with the command -.PP +.P .in +4n .EX strace \-p .EE .in -.PP +.P then, instead of the usual and expected one-line output such as -.PP +.P .in +4n .EX restart_syscall(<... resuming interrupted call ...>_ .EE .in -.PP +.P or -.PP +.P .in +4n .EX select(6, [5], NULL, [5], NULL_ .EE .in -.PP +.P ('_' denotes the cursor position), you observe more than one line. For example: -.PP +.P .in +4n .EX clock_gettime(CLOCK_MONOTONIC, {15370, 690928118}) = 0 epoll_wait(4,_ .EE .in -.PP +.P What is not visible here is that the process was blocked in .BR epoll_wait (2) before @@ -2949,7 +2961,7 @@ again. errors may behave in an unintended way upon an .BR strace (1) attach.) -.PP +.P Contrary to the normal rules, the glibc wrapper for .BR ptrace () can set diff --git a/man2/query_module.2 b/man2/query_module.2 index 519650a..f2b163a 100644 --- a/man2/query_module.2 +++ b/man2/query_module.2 @@ -5,13 +5,13 @@ .\" 2006-02-09, some reformatting by Luc Van Oostenryck; some .\" reformatting and rewordings by mtk .\" -.TH query_module 2 2023-03-30 "Linux man-pages 6.05.01" +.TH query_module 2 2023-10-31 "Linux man-pages 6.7" .SH NAME query_module \- query the kernel for various bits pertaining to modules .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int query_module(const char *" name ", int " which , .BI " void " buf [. bufsize "], \ size_t " bufsize , @@ -20,7 +20,7 @@ size_t " bufsize , .SH DESCRIPTION .IR Note : This system call is present only before Linux 2.6. -.PP +.P .BR query_module () requests information from the kernel about loadable modules. The returned information is placed in the buffer pointed to by @@ -37,7 +37,7 @@ Some operations require to identify a currently loaded module, some allow .I name to be NULL, indicating the kernel proper. -.PP +.P The following values can be specified for .IR which : .TP @@ -167,7 +167,7 @@ Linux. .SH VERSIONS Removed in Linux 2.6. .\" Removed in Linux 2.5.48 -.PP +.P Some of the information that was formerly available via .BR query_module () can be obtained from @@ -175,7 +175,7 @@ can be obtained from .IR /proc/kallsyms , and the files under the directory .IR /sys/module . -.PP +.P The .BR query_module () system call is not supported by glibc. diff --git a/man2/quotactl.2 b/man2/quotactl.2 index 716f934..3cfaaf5 100644 --- a/man2/quotactl.2 +++ b/man2/quotactl.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH quotactl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH quotactl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME quotactl \- manipulate disk quotas .SH LIBRARY @@ -16,8 +16,8 @@ Standard C library .BR "#include " " /* Definition of " Q_X* " and " XFS_QUOTA_* \ " constants" .RB " (or " "; see NOTES) */" -.PP -.BI "int quotactl(int " cmd ", const char *_Nullable " special ", int " id , +.P +.BI "int quotactl(int " op ", const char *_Nullable " special ", int " id , .BI " caddr_t " addr ); .fi .SH DESCRIPTION @@ -30,19 +30,19 @@ The soft limit can be exceeded, but warnings will ensue. Moreover, the user can't exceed the soft limit for more than grace period duration (one week by default) at a time; after this, the soft limit counts as a hard limit. -.PP +.P The .BR quotactl () call manipulates disk quotas. The -.I cmd -argument indicates a command to be applied to the user or +.I op +argument indicates an operation to be applied to the user or group ID specified in .IR id . To initialize the -.I cmd +.I op argument, use the -.I QCMD(subcmd, type) +.I QCMD(subop, type) macro. The .I type @@ -55,24 +55,24 @@ for group quotas, or (since Linux 4.1) .BR PRJQUOTA , for project quotas. The -.I subcmd +.I subop value is described below. -.PP +.P The .I special argument is a pointer to a null-terminated string containing the pathname of the (mounted) block special device for the filesystem being manipulated. -.PP +.P The .I addr -argument is the address of an optional, command-specific, data structure +argument is the address of an optional, operation-specific, data structure that is copied in or out of the system. The interpretation of .I addr is given with each operation below. -.PP +.P The -.I subcmd +.I subop value is one of the following operations: .TP .B Q_QUOTAON @@ -380,7 +380,7 @@ This operation is obsolete and was removed in Linux 2.4.22. Files in .I /proc/sys/fs/quota/ carry the information instead. -.PP +.P For XFS filesystems making use of the XFS Quota Manager (XQM), the above operations are bypassed and the following operations are used: .TP @@ -649,7 +649,7 @@ structure) which identify what types of quota should be removed. (Note that the quota type passed in the -.I cmd +.I op argument is ignored, but should remain valid in order to pass preliminary quotactl syscall handler checks.) .IP @@ -681,7 +681,7 @@ is set to indicate the error. .SH ERRORS .TP .B EACCES -.I cmd +.I op is .BR Q_QUOTAON , and the quota file pointed to by @@ -691,7 +691,7 @@ is not on the filesystem pointed to by .IR special . .TP .B EBUSY -.I cmd +.I op is .BR Q_QUOTAON , but another @@ -705,20 +705,20 @@ or is invalid. .TP .B EINVAL -.I cmd +.I op or .I type is invalid. .TP .B EINVAL -.I cmd +.I op is .BR Q_QUOTAON , but the specified quota file is corrupted. .TP .BR EINVAL " (since Linux 5.5)" .\" 3dd4d40b420846dd35869ccc8f8627feef2cff32 -.I cmd +.I op is .BR Q_XQUOTARM , but @@ -747,7 +747,7 @@ The caller lacked the required privilege for the specified operation. .TP .B ERANGE -.I cmd +.I op is .BR Q_SETQUOTA , but the specified limits are out of the range allowed by the quota format. @@ -757,13 +757,13 @@ No disk quota is found for the indicated user. Quotas have not been turned on for this filesystem. .TP .B ESRCH -.I cmd +.I op is .BR Q_QUOTAON , but the specified quota format was not found. .TP .B ESRCH -.I cmd +.I op is .B Q_GETNEXTQUOTA or diff --git a/man2/read.2 b/man2/read.2 index 955efa4..973993e 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -13,7 +13,7 @@ .\" Modified Sat Jul 12 20:45:39 1997 by Michael Haardt .\" .\" -.TH read 2 2023-04-03 "Linux man-pages 6.05.01" +.TH read 2 2024-03-12 "Linux man-pages 6.7" .SH NAME read \- read from a file descriptor .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t read(int " fd ", void " buf [. count "], size_t " count ); .fi .SH DESCRIPTION @@ -33,7 +33,7 @@ bytes from file descriptor .I fd into the buffer starting at .IR buf . -.PP +.P On files that support seeking, the read operation commences at the file offset, and the file offset is incremented by the number of bytes read. @@ -41,7 +41,7 @@ If the file offset is at or past the end of file, no bytes are read, and .BR read () returns zero. -.PP +.P If .I count is zero, @@ -56,7 +56,7 @@ does not check for errors, a with a .I count of 0 returns zero and has no other effects. -.PP +.P According to POSIX.1, if .I count is greater than @@ -73,7 +73,7 @@ because we are reading from a pipe, or from a terminal), or because .BR read () was interrupted by a signal. See also NOTES. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -160,7 +160,7 @@ for further details. .B EISDIR .I fd refers to a directory. -.PP +.P Other errors may occur, depending on the object connected to .IR fd . .SH STANDARDS @@ -175,7 +175,7 @@ On Linux, returning the number of bytes actually transferred. .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 (This is true on both 32-bit and 64-bit systems.) -.PP +.P On NFS filesystems, reading small amounts of data will update the timestamp only the first time, subsequent calls may not do so. This is caused @@ -194,13 +194,13 @@ increase server load and decrease performance. .SH BUGS According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions with Regular File Operations"): -.PP +.P .RS 4 All of the following functions shall be atomic with respect to each other in the effects specified in POSIX.1-2008 when they operate on regular files or symbolic links: ... .RE -.PP +.P Among the APIs subsequently listed are .BR read () and @@ -216,7 +216,7 @@ perform a (or .BR readv (2)) at the same time, then the I/O operations were not atomic -with respect updating the file offset, +with respect to updating the file offset, with the result that the reads in the two processes might (incorrectly) overlap in the blocks of data that they obtained. This problem was fixed in Linux 3.14. diff --git a/man2/readahead.2 b/man2/readahead.2 index b97f085..701efde 100644 --- a/man2/readahead.2 +++ b/man2/readahead.2 @@ -5,7 +5,7 @@ .\" 2004-05-40 Created by Michael Kerrisk .\" 2004-10-05 aeb, minor correction .\" -.TH readahead 2 2023-07-15 "Linux man-pages 6.05.01" +.TH readahead 2 2023-10-31 "Linux man-pages 6.7" .SH NAME readahead \- initiate file readahead into page cache .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #define _FILE_OFFSET_BITS 64 .B #include -.PP +.P .BI "ssize_t readahead(int " fd ", off_t " offset ", size_t " count ); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ initiates readahead on a file so that subsequent reads from that file will be satisfied from the cache, and not block on disk I/O (assuming the readahead was initiated early enough and that other activity on the system did not in the meantime flush pages from the cache). -.PP +.P The .I fd argument is a file descriptor identifying the file which is diff --git a/man2/readdir.2 b/man2/readdir.2 index 6b06ff4..dbb91e1 100644 --- a/man2/readdir.2 +++ b/man2/readdir.2 @@ -7,7 +7,7 @@ .\" In 1.3.X, returns only one entry each time; return value is different. .\" Modified 2004-12-01, mtk, fixed headers listed in SYNOPSIS .\" -.TH readdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH readdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME readdir \- read directory entry .SH LIBRARY @@ -17,11 +17,11 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_readdir, unsigned int " fd , .BI " struct old_linux_dirent *" dirp ", unsigned int " count ); .fi -.PP +.P .IR Note : There is no definition of .BR "struct old_linux_dirent" ; @@ -34,7 +34,7 @@ for the POSIX conforming C library interface. This page documents the bare kernel system call interface, which is superseded by .BR getdents (2). -.PP +.P .BR readdir () reads one .I old_linux_dirent @@ -48,13 +48,13 @@ The argument is ignored; at most one .I old_linux_dirent structure is read. -.PP +.P The .I old_linux_dirent structure is declared (privately in Linux kernel file .BR fs/readdir.c ) as follows: -.PP +.P .in +4n .EX struct old_linux_dirent { @@ -65,7 +65,7 @@ struct old_linux_dirent { } .EE .in -.PP +.P .I d_ino is an inode number. .I d_offset @@ -107,7 +107,7 @@ structure yourself. However, probably you should use .BR readdir (3) instead. -.PP +.P This system call does not exist on x86-64. .SH STANDARDS Linux. diff --git a/man2/readlink.2 b/man2/readlink.2 index fe2369d..c476091 100644 --- a/man2/readlink.2 +++ b/man2/readlink.2 @@ -13,7 +13,7 @@ .\" 2011-09-20, Guillem Jover : .\" Added text on dynamically allocating buffer + example program .\" -.TH readlink 2 2023-05-03 "Linux man-pages 6.05.01" +.TH readlink 2 2023-11-01 "Linux man-pages 6.7" .SH NAME readlink, readlinkat \- read value of a symbolic link .SH LIBRARY @@ -22,29 +22,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t readlink(const char *restrict " pathname ", char *restrict " buf , .BI " size_t " bufsiz ); -.PP +.P .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "ssize_t readlinkat(int " dirfd ", const char *restrict " pathname , .BI " char *restrict " buf ", size_t " bufsiz ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR readlink (): .nf _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR readlinkat (): .nf Since glibc 2.10: @@ -72,7 +72,7 @@ The system call operates in exactly the same way as .BR readlink (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -82,7 +82,7 @@ referred to by the file descriptor the calling process, as is done by .BR readlink () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -94,13 +94,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR readlink ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P Since Linux 2.6.39, .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d .I pathname @@ -114,7 +114,7 @@ with the and .B O_NOFOLLOW flags). -.PP +.P See .BR openat (2) for an explanation of the need for @@ -199,7 +199,7 @@ POSIX.1-2001, POSIX.1-2008. POSIX.1-2008. Linux 2.6.16, glibc 2.4. -.PP +.P Up to and including glibc 2.4, the return type of .BR readlink () was declared as @@ -253,7 +253,7 @@ falling back to a buffer of size in cases where .BR lstat (2) reports a size of zero. -.PP +.P .\" SRC BEGIN (readlink.c) .EX #include @@ -307,7 +307,7 @@ main(int argc, char *argv[]) null byte (\[aq]\e0\[aq]). */ printf("\[aq]%s\[aq] points to \[aq]%.*s\[aq]\en", argv[1], (int) nbytes, buf); \& - /* If the return value was equal to the buffer size, then the + /* If the return value was equal to the buffer size, then the link target was larger than expected (perhaps because the target was changed between the call to lstat() and the call to readlink()). Warn the user that the returned target may have diff --git a/man2/readv.2 b/man2/readv.2 index db6abbc..c1295cd 100644 --- a/man2/readv.2 +++ b/man2/readv.2 @@ -9,7 +9,7 @@ .\" add more details. .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() .\" -.TH readv 2 2023-05-03 "Linux man-pages 6.05.01" +.TH readv 2 2023-10-31 "Linux man-pages 6.7" .SH NAME readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers @@ -19,26 +19,26 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); -.PP +.P .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ); -.PP +.P .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ", int " flags ); .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , .BI " off_t " offset ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR preadv (), .BR pwritev (): .nf @@ -57,7 +57,7 @@ buffers from the file associated with the file descriptor into the buffers described by .I iov ("scatter input"). -.PP +.P The .BR writev () system call writes @@ -67,7 +67,7 @@ buffers of data described by to the file associated with the file descriptor .I fd ("gather output"). -.PP +.P The pointer .I iov points to an array of @@ -75,19 +75,19 @@ points to an array of structures, described in .BR iovec (3type). -.PP +.P The .BR readv () system call works just like .BR read (2) except that multiple buffers are filled. -.PP +.P The .BR writev () system call works just like .BR write (2) except that multiple buffers are written out. -.PP +.P Buffers are processed in array order. This means that .BR readv () @@ -106,7 +106,7 @@ writes out the entire contents of before proceeding to .IR iov[1] , and so on. -.PP +.P The data transfers performed by .BR readv () and @@ -136,7 +136,7 @@ but adds a fourth argument, .IR offset , which specifies the file offset at which the input operation is to be performed. -.PP +.P The .BR pwritev () system call combines the functionality of @@ -149,7 +149,7 @@ but adds a fourth argument, .IR offset , which specifies the file offset at which the output operation is to be performed. -.PP +.P The file offset is not changed by these system calls. The file referred to by .I fd @@ -162,7 +162,7 @@ and calls, but add a fifth argument, .IR flags , which modifies the behavior on a per-call basis. -.PP +.P Unlike .BR preadv () and @@ -170,7 +170,7 @@ and if the .I offset argument is \-1, then the current file offset is used and updated. -.PP +.P The .I flags argument contains a bitwise OR of zero or more of the following flags: @@ -249,13 +249,13 @@ return the number of bytes read; and .BR pwritev2 () return the number of bytes written. -.PP +.P Note that it is not an error for a successful call to transfer fewer bytes than requested (see .BR read (2) and .BR write (2)). -.PP +.P On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. .SH ERRORS The errors are as given for @@ -297,9 +297,9 @@ corresponding GNU C library wrapper functions shown in the SYNOPSIS. The final argument, .IR offset , is unpacked by the wrapper functions into two arguments in the system calls: -.PP +.P .BI " unsigned long " pos_l ", unsigned long " pos -.PP +.P These arguments contain, respectively, the low order and high order 32 bits of .IR offset . .SH STANDARDS @@ -329,12 +329,12 @@ POSIX.1-2001, .\" and \fIint\fP as the return type. .\" The readv/writev system calls were buggy before Linux 1.3.40. .\" (Says release.libc.) -.PP +.P .BR preadv (), .BR pwritev (): Linux 2.6.30, glibc 2.10. -.PP +.P .BR preadv2 (), .BR pwritev2 (): Linux 4.6, @@ -365,7 +365,7 @@ The wrapper function for .BR writev () performed the analogous task using a temporary buffer and a call to .BR write (2). -.PP +.P The need for this extra effort in the glibc wrapper functions went away with Linux 2.2 and later. However, glibc continued to provide this behavior until glibc 2.10. @@ -405,7 +405,7 @@ flag may return 0 even when not at end of file. .SH EXAMPLES The following code sample demonstrates the use of .BR writev (): -.PP +.P .in +4n .EX char *str0 = "hello "; diff --git a/man2/reboot.2 b/man2/reboot.2 index 681087f..7ca639c 100644 --- a/man2/reboot.2 +++ b/man2/reboot.2 @@ -5,7 +5,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH reboot 2 2023-03-30 "Linux man-pages 6.05.01" +.TH reboot 2 2024-03-03 "Linux man-pages 6.7" .SH NAME reboot \- reboot or enable/disable Ctrl-Alt-Del .SH LIBRARY @@ -15,23 +15,23 @@ Standard C library .nf .RB "/* Since Linux 2.1.30 there are symbolic names " LINUX_REBOOT_* for the constants and a fourth argument to the call: */ -.PP +.P .BR "#include " \ "/* Definition of " LINUX_REBOOT_* " constants */" .BR "#include " "/* Definition of " SYS_* " constants */" .B #include -.PP -.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " cmd ", void *" arg ); -.PP +.P +.BI "int syscall(SYS_reboot, int " magic ", int " magic2 ", int " op ", void *" arg ); +.P /* Under glibc and most alternative libc's (including uclibc, dietlibc, musl and a few others), some of the constants involved have gotten .RB " symbolic names " RB_* ", and the library call is a 1-argument" wrapper around the system call: */ -.PP +.P .BR "#include " "/* Definition of " RB_* " constants */" .B #include -.PP -.BI "int reboot(int " cmd ); +.P +.BI "int reboot(int " op ); .fi .SH DESCRIPTION The @@ -40,7 +40,7 @@ call reboots the system, or enables/disables the reboot keystroke (abbreviated CAD, since the default is Ctrl-Alt-Delete; it can be changed using .BR loadkeys (1)). -.PP +.P This system call fails (with the error .BR EINVAL ) unless @@ -64,9 +64,9 @@ and since Linux 2.5.71 also are permitted as values for .IR magic2 . (The hexadecimal values of these constants are meaningful.) -.PP +.P The -.I cmd +.I op argument can have the following values: .TP .B LINUX_REBOOT_CMD_CAD_OFF @@ -138,10 +138,10 @@ data will be lost. The system is suspended (hibernated) to disk. This option is available only if the kernel was configured with .BR CONFIG_HIBERNATION . -.PP +.P Only the superuser may call .BR reboot (). -.PP +.P The precise effect of the above actions depends on the architecture. For the i386 architecture, the additional argument does not do anything at present (2.1.122), but the type of reboot can be @@ -157,20 +157,22 @@ if is called from a PID namespace other than the initial PID namespace with one of the -.I cmd +.I op values listed below, it performs a "reboot" of that namespace: the "init" process of the PID namespace is immediately terminated, with the effects described in .BR pid_namespaces (7). -.PP +.P The values that can be supplied in -.I cmd +.I op when calling .BR reboot () in this case are as follows: .TP -.BR LINUX_REBOOT_CMD_RESTART ", " LINUX_REBOOT_CMD_RESTART2 +.B LINUX_REBOOT_CMD_RESTART +.TQ +.B LINUX_REBOOT_CMD_RESTART2 The "init" process is terminated, and .BR wait (2) @@ -178,16 +180,18 @@ in the parent process reports that the child was killed with a .B SIGHUP signal. .TP -.BR LINUX_REBOOT_CMD_POWER_OFF ", " LINUX_REBOOT_CMD_HALT +.B LINUX_REBOOT_CMD_POWER_OFF +.TQ +.B LINUX_REBOOT_CMD_HALT The "init" process is terminated, and .BR wait (2) in the parent process reports that the child was killed with a .B SIGINT signal. -.PP +.P For the other -.I cmd +.I op values, .BR reboot () returns \-1 and @@ -196,13 +200,13 @@ is set to .BR EINVAL . .SH RETURN VALUE For the values of -.I cmd +.I op that stop or restart the system, a successful call to .BR reboot () does not return. For the other -.I cmd +.I op values, zero is returned on success. In all cases, \-1 is returned on failure, and .I errno @@ -214,7 +218,8 @@ Problem with getting user-space data under .BR LINUX_REBOOT_CMD_RESTART2 . .TP .B EINVAL -Bad magic numbers or \fIcmd\fP. +Bad magic numbers or +.IR op . .TP .B EPERM The calling process has insufficient privilege to call diff --git a/man2/recv.2 b/man2/recv.2 index 395236d..916cca3 100644 --- a/man2/recv.2 +++ b/man2/recv.2 @@ -10,7 +10,7 @@ .\" Modified 1998,1999 by Andi Kleen .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin .\" -.TH recv 2 2023-07-18 "Linux man-pages 6.05.01" +.TH recv 2 2024-02-18 "Linux man-pages 6.7" .SH NAME recv, recvfrom, recvmsg \- receive a message from a socket .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t recv(int " sockfd ", void " buf [. len "], size_t " len , .BI " int " flags ); .BI "ssize_t recvfrom(int " sockfd ", void " buf "[restrict ." len "], size_t " len , @@ -39,7 +39,7 @@ They may be used to receive data on both connectionless and connection-oriented sockets. This page first describes common features of all three system calls, and then describes the differences between the calls. -.PP +.P The only difference between .BR recv () and @@ -54,27 +54,27 @@ is generally equivalent to .BR read (2) (but see NOTES). Also, the following call -.PP +.P .in +4n .EX recv(sockfd, buf, len, flags); .EE .in -.PP +.P is equivalent to -.PP +.P .in +4n .EX recvfrom(sockfd, buf, len, flags, NULL, NULL); .EE .in -.PP +.P All three calls return the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from. -.PP +.P If no messages are available at the socket, the receive calls wait for a message to arrive, unless the socket is nonblocking (see .BR fcntl (2)), @@ -84,7 +84,7 @@ is set to .BR EAGAIN " or " EWOULDBLOCK . The receive calls normally return any data available, up to the requested amount, rather than waiting for receipt of the full amount requested. -.PP +.P An application can use .BR select (2), .BR poll (2), @@ -123,7 +123,7 @@ is a per-call option, whereas is a setting on the open file description (see .BR open (2)), which will affect all threads in the calling process -and as well as other processes that hold file descriptors +as well as other processes that hold file descriptors referring to the same open file description. .TP .BR MSG_ERRQUEUE " (since Linux 2.2)" @@ -250,7 +250,7 @@ places the received message into the buffer .IR buf . The caller must specify the size of the buffer in .IR len . -.PP +.P If .I src_addr is not NULL, @@ -278,7 +278,7 @@ The returned address is truncated if the buffer provided is too small; in this case, .I addrlen will return a value greater than was supplied to the call. -.PP +.P If the caller is not interested in the source address, .I src_addr and @@ -293,7 +293,7 @@ call is normally used only on a socket (see .BR connect (2)). It is equivalent to the call: -.PP +.P .in +4n .EX recvfrom(fd, buf, len, flags, NULL, 0); @@ -308,7 +308,7 @@ call uses a structure to minimize the number of directly supplied arguments. This structure is defined as follows in .IR : -.PP +.P .in +4n .EX struct msghdr { @@ -322,7 +322,7 @@ struct msghdr { }; .EE .in -.PP +.P The .I msg_name field points to a caller-allocated buffer that is used to @@ -336,14 +336,14 @@ will contain the length of the returned address. If the application does not need to know the source address, .I msg_name can be specified as NULL. -.PP +.P The fields .I msg_iov and .I msg_iovlen describe scatter-gather locations, as discussed in .BR readv (2). -.PP +.P The field .IR msg_control , which has length @@ -358,9 +358,9 @@ should contain the length of the available buffer in .IR msg_control ; upon return from a successful call it will contain the length of the control message sequence. -.PP +.P The messages are of the form: -.PP +.P .in +4n .EX struct cmsghdr { @@ -373,10 +373,10 @@ struct cmsghdr { }; .EE .in -.PP +.P Ancillary data should be accessed only by the macros defined in .BR cmsg (3). -.PP +.P As an example, Linux uses this ancillary data mechanism to pass extended errors, IP options, or file descriptors over UNIX domain sockets. For further information on the use of ancillary data in various @@ -384,7 +384,7 @@ socket domains, see .BR unix (7) and .BR ip (7). -.PP +.P The .I msg_flags field in the @@ -427,14 +427,14 @@ if an error occurred. In the event of an error, .I errno is set to indicate the error. -.PP +.P When a stream socket peer has performed an orderly shutdown, the return value will be 0 (the traditional "end-of-file" return). -.PP +.P Datagram sockets in various domains (e.g., the UNIX and Internet domains) permit zero-length datagrams. When such a datagram is received, the return value is 0. -.PP +.P The value 0 may also be returned if the requested number of bytes to receive from a stream socket was 0. .SH ERRORS @@ -515,7 +515,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD). -.PP +.P POSIX.1 describes only the .BR MSG_OOB , .BR MSG_PEEK , @@ -535,7 +535,7 @@ In this circumstance, has no effect (the datagram remains pending), while .BR recv () consumes the pending datagram. -.PP +.P See .BR recvmmsg (2) for information about a Linux-specific system call diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2 index d5b0f5a..f732d03 100644 --- a/man2/recvmmsg.2 +++ b/man2/recvmmsg.2 @@ -8,7 +8,7 @@ .\" Author: Arnaldo Carvalho de Melo .\" Date: Mon Oct 12 23:40:10 2009 -0700 .\" -.TH recvmmsg 2 2023-05-03 "Linux man-pages 6.05.01" +.TH recvmmsg 2 2023-10-31 "Linux man-pages 6.7" .SH NAME recvmmsg \- receive multiple messages on a socket .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int recvmmsg(int " sockfd ", struct mmsghdr *" msgvec \ ", unsigned int " vlen "," .BI " int " flags ", struct timespec *" timeout ");" @@ -34,11 +34,11 @@ using a single system call. A further extension over .BR recvmsg (2) is support for a timeout on the receive operation. -.PP +.P The .I sockfd argument is the file descriptor of the socket to receive data from. -.PP +.P The .I msgvec argument is a pointer to an array of @@ -46,13 +46,13 @@ argument is a pointer to an array of structures. The size of this array is specified in .IR vlen . -.PP +.P The .I mmsghdr structure is defined in .I as: -.PP +.P .in +4n .EX struct mmsghdr { @@ -61,7 +61,7 @@ struct mmsghdr { }; .EE .in -.PP +.P The .I msg_hdr field is a @@ -74,7 +74,7 @@ field is the number of bytes returned for the message in the entry. This field has the same value as the return value of a single .BR recvmsg (2) on the header. -.PP +.P The .I flags argument contains flags ORed together. @@ -86,7 +86,7 @@ with the following addition: Turns on .B MSG_DONTWAIT after the first message has been received. -.PP +.P The .I timeout argument points to a @@ -101,7 +101,7 @@ may overrun by a small amount.) If .I timeout is NULL, then the operation blocks indefinitely. -.PP +.P A blocking .BR recvmmsg () call blocks until @@ -112,7 +112,7 @@ A nonblocking call reads as many messages as are available (up to the limit specified by .IR vlen ) and returns immediately. -.PP +.P On return from .BR recvmmsg (), successive elements of @@ -143,7 +143,7 @@ In addition, the following error can occur: .B EINVAL .I timeout is invalid. -.PP +.P See also BUGS. .SH STANDARDS Linux. @@ -161,7 +161,7 @@ so that if up to .I vlen\-1 datagrams are received before the timeout expires, but then no further datagrams are received, the call will block forever. -.PP +.P If an error occurs after at least one message has been received, the call succeeds, and returns the number of messages received. The error code is expected to be returned on a subsequent call to @@ -176,20 +176,20 @@ to receive multiple messages on a socket and stores them in multiple buffers. The call returns if all buffers are filled or if the timeout specified has expired. -.PP +.P The following snippet periodically generates UDP datagrams containing a random number: -.PP +.P .in +4n .EX .RB "$" " while true; do echo $RANDOM > /dev/udp/127.0.0.1/1234;" .B " sleep 0.25; done" .EE .in -.PP +.P These datagrams are read by the example application, which can give the following output: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man2/remap_file_pages.2 b/man2/remap_file_pages.2 index ab4ee51..f662c46 100644 --- a/man2/remap_file_pages.2 +++ b/man2/remap_file_pages.2 @@ -5,7 +5,7 @@ .\" 2003-12-10 Initial creation, Michael Kerrisk .\" 2004-10-28 aeb, corrected prototype, prot must be 0 .\" -.TH remap_file_pages 2 2023-03-30 "Linux man-pages 6.05.01" +.TH remap_file_pages 2 2023-10-31 "Linux man-pages 6.7" .SH NAME remap_file_pages \- create a nonlinear file mapping .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "[[deprecated]] int remap_file_pages(void " addr [. size "], size_t " size , .BI " int " prot ", size_t " pgoff ", \ int " flags ); @@ -34,7 +34,7 @@ This change was made because the kernel code for this system call was complex, and it is believed to be little used or perhaps even completely unused. While it had some use cases in database applications on 32-bit systems, those use cases don't exist on 64-bit systems. -.PP +.P The .BR remap_file_pages () system call is used to create a nonlinear mapping, that is, a mapping @@ -46,7 +46,7 @@ over using repeated calls to .BR mmap (2) is that the former approach does not require the kernel to create additional VMA (Virtual Memory Area) data structures. -.PP +.P To create a nonlinear mapping we perform the following steps: .TP 3 1. @@ -64,7 +64,7 @@ to rearrange the correspondence between the pages of the mapping and the pages of the file. It is possible to map the same page of a file into multiple locations within the mapped region. -.PP +.P The .I pgoff and @@ -75,7 +75,7 @@ within the mapping: is a file offset in units of the system page size; .I size is the length of the region in bytes. -.PP +.P The .I addr argument serves two purposes. @@ -93,7 +93,7 @@ identified by and .I size will be placed. -.PP +.P The values specified in .I addr and @@ -107,11 +107,11 @@ to the nearest multiple of the page size. .\" This rounding is weird, and not consistent with the treatment of .\" the analogous arguments for munmap()/mprotect() and for mlock(). .\" MTK, 14 Sep 2005 -.PP +.P The .I prot argument must be specified as 0. -.PP +.P The .I flags argument has the same meaning as for diff --git a/man2/removexattr.2 b/man2/removexattr.2 index 1a9f53f..50a567e 100644 --- a/man2/removexattr.2 +++ b/man2/removexattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH removexattr 2 2023-04-08 "Linux man-pages 6.05.01" +.TH removexattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME removexattr, lremovexattr, fremovexattr \- remove an extended attribute .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int removexattr(const char *" path ", const char *" name ); .BI "int lremovexattr(const char *" path ", const char *" name ); .BI "int fremovexattr(int " fd ", const char *" name ); @@ -27,20 +27,20 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR removexattr () removes the extended attribute identified by .I name and associated with the given .I path in the filesystem. -.PP +.P .BR lremovexattr () is identical to .BR removexattr (), except in the case of a symbolic link, where the extended attribute is removed from the link itself, not the file that it refers to. -.PP +.P .BR fremovexattr () is identical to .BR removexattr (), @@ -50,7 +50,7 @@ only the extended attribute is removed from the open file referred to by .BR open (2)) in place of .IR path . -.PP +.P An extended attribute name is a null-terminated string. The .I name @@ -73,7 +73,7 @@ The named attribute does not exist. .TP .B ENOTSUP Extended attributes are not supported by the filesystem, or are disabled. -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. diff --git a/man2/rename.2 b/man2/rename.2 index 9963af6..6b538d4 100644 --- a/man2/rename.2 +++ b/man2/rename.2 @@ -10,7 +10,7 @@ .\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt .\" 2007-03-25, mtk, added various text to DESCRIPTION. .\" -.TH rename 2 2023-03-30 "Linux man-pages 6.05.01" +.TH rename 2 2023-10-31 "Linux man-pages 6.7" .SH NAME rename, renameat, renameat2 \- change the name or location of a file .SH LIBRARY @@ -19,31 +19,31 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int rename(const char *" oldpath ", const char *" newpath ); -.PP +.P .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int renameat(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath ); .BI "int renameat2(int " olddirfd ", const char *" oldpath , .BI " int " newdirfd ", const char *" newpath \ ", unsigned int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR renameat (): Since glibc 2.10: _POSIX_C_SOURCE >= 200809L Before glibc 2.10: _ATFILE_SOURCE -.PP +.P .BR renameat2 (): _GNU_SOURCE .fi @@ -56,10 +56,10 @@ are unaffected. Open file descriptors for .I oldpath are also unaffected. -.PP +.P Various restrictions determine whether or not the rename operation succeeds: see ERRORS below. -.PP +.P If .I newpath already exists, it will be atomically replaced, so that there is @@ -71,7 +71,7 @@ However, there will probably be a window in which both and .I newpath refer to the file being renamed. -.PP +.P If .I oldpath and @@ -79,7 +79,7 @@ and are existing hard links referring to the same file, then .BR rename () does nothing, and returns a success status. -.PP +.P If .I newpath exists but the operation fails for some reason, @@ -87,13 +87,13 @@ exists but the operation fails for some reason, guarantees to leave an instance of .I newpath in place. -.PP +.P .I oldpath can specify a directory. In this case, .I newpath must either not exist, or it must specify an empty directory. -.PP +.P If .I oldpath refers to a symbolic link, the link is renamed; if @@ -105,7 +105,7 @@ The system call operates in exactly the same way as .BR rename (), except for the differences described here. -.PP +.P If the pathname given in .I oldpath is relative, then it is interpreted relative to the directory @@ -115,7 +115,7 @@ referred to by the file descriptor the calling process, as is done by .BR rename () for a relative pathname). -.PP +.P If .I oldpath is relative and @@ -127,13 +127,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR rename ()). -.PP +.P If .I oldpath is absolute, then .I olddirfd is ignored. -.PP +.P The interpretation of .I newpath is as for @@ -141,7 +141,7 @@ is as for except that a relative pathname is interpreted relative to the directory referred to by the file descriptor .IR newdirfd . -.PP +.P See .BR openat (2) for an explanation of the need for @@ -157,7 +157,7 @@ call with a zero .I flags argument is equivalent to .BR renameat (). -.PP +.P The .I flags argument is a bit mask consisting of zero or more of the following flags: @@ -414,7 +414,7 @@ are not on the same mounted filesystem. .BR rename () does not work across different mount points, even if the same filesystem is mounted on both.) -.PP +.P The following additional errors can occur for .BR renameat () and @@ -437,7 +437,7 @@ or similar for .I newpath and .I newdirfd -.PP +.P The following additional errors can occur for .BR renameat2 (): .TP diff --git a/man2/request_key.2 b/man2/request_key.2 index 80187d1..dd2e39d 100644 --- a/man2/request_key.2 +++ b/man2/request_key.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH request_key 2 2023-05-03 "Linux man-pages 6.05.01" +.TH request_key 2 2024-02-25 "Linux man-pages 6.7" .SH NAME request_key \- request a key from the kernel's key management facility .SH LIBRARY @@ -13,7 +13,7 @@ Linux Key Management Utilities .SH SYNOPSIS .nf .B #include -.PP +.P .BI "key_serial_t request_key(const char *" type ", const char *" description , .BI " const char *_Nullable " callout_info , .BI " key_serial_t " dest_keyring ); @@ -30,13 +30,13 @@ If the key is found or created, attaches it to the keyring whose ID is specified in .I dest_keyring and returns the key's serial number. -.PP +.P .BR request_key () first recursively searches for a matching key in all of the keyrings attached to the calling process. The keyrings are searched in the order: thread-specific keyring, process-specific keyring, and then session keyring. -.PP +.P If .BR request_key () is called from a program invoked by @@ -48,7 +48,7 @@ supplementary group IDs, and security context to determine access. .\" David Howells: we can then have an arbitrarily long sequence .\" of "recursive" request-key upcalls. There is no limit, other .\" than number of PIDs, etc. -.PP +.P The search of the keyring tree is breadth-first: the keys in each keyring searched are checked for a match before any child keyrings are recursed into. @@ -57,18 +57,18 @@ Only keys for which the caller has permission be found, and only keyrings for which the caller has .I search permission may be searched. -.PP +.P If the key is not found and .I callout is NULL, then the call fails with the error .BR ENOKEY . -.PP +.P If the key is not found and .I callout is not NULL, then the kernel attempts to invoke a user-space program to instantiate the key. The details are given below. -.PP +.P The .I dest_keyring serial number may be that of a valid keyring for which the caller has @@ -94,13 +94,13 @@ This specifies the caller's UID-specific keyring (see .B KEY_SPEC_USER_SESSION_KEYRING This specifies the caller's UID-session keyring (see .BR user\-session\-keyring (7)). -.PP +.P When the .I dest_keyring is specified as 0 and no key construction has been performed, then no additional linking is done. -.PP +.P Otherwise, if .I dest_keyring is 0 and a new key is constructed, the new key will be linked @@ -180,7 +180,7 @@ This keyring is also expected to always exist. .\" .\" will all create a keyring under some circumstances. Whereas the rest, .\" such as KEYCTL_GET_SECURITY, KEYCTL_READ and KEYCTL_REVOKE, won't. -.PP +.P If the .BR keyctl (2) .B KEYCTL_SET_REQKEY_KEYRING @@ -227,7 +227,7 @@ The authorization key is constructed as follows: .RS .IP \[bu] 3 The key type is -.IR """.request_key_auth""" . +.IR \[dq].request_key_auth\[dq] . .IP \[bu] The key's UID and GID are the same as the corresponding filesystem IDs of the requesting process. @@ -263,10 +263,10 @@ This program is supplied with the following command-line arguments: .RS .IP [0] 5 The string -.IR """/sbin/request\-key""" . +.IR \[dq]/sbin/request\-key\[dq] . .IP [1] The string -.I """create""" +.I \[dq]create\[dq] (indicating that a key is to be created). .IP [2] The ID of the key that is to be instantiated. @@ -337,7 +337,7 @@ At this point, the .BR request_key () call completes, and the requesting program can continue execution. .RE -.PP +.P If these steps are unsuccessful, then an .B ENOKEY error will be returned to the caller of @@ -353,7 +353,7 @@ The purpose of this negatively instantiated key is to prevent (that require expensive .BR request\-key (8) upcalls) for a key that can't (at the moment) be positively instantiated. -.PP +.P Once the key has been instantiated, the authorization key .RB ( KEY_SPEC_REQKEY_AUTH_KEY ) is revoked, and the destination keyring @@ -361,7 +361,7 @@ is revoked, and the destination keyring is no longer accessible from the .BR request\-key (8) program. -.PP +.P If a key is created, then\[em]regardless of whether it is a valid key or a negatively instantiated key\[em]it will displace any other key with the same type and description from the keyring specified in @@ -429,7 +429,7 @@ argument started with a period (\[aq].\[aq]). Linux. .SH HISTORY Linux 2.6.10. -.PP +.P The ability to instantiate keys upon request was added .\" commit 3e30148c3d524a9c1c63ca28261bc24c457eb07a in Linux 2.6.13. @@ -444,11 +444,11 @@ and arguments for the system call are taken from the values supplied in the command-line arguments. The call specifies the session keyring as the target keyring. -.PP +.P In order to demonstrate this program, we first create a suitable entry in the file .IR /etc/request\-key.conf . -.PP +.P .in +4n .EX $ sudo sh @@ -457,7 +457,7 @@ $ sudo sh # \fBexit\fP .EE .in -.PP +.P This entry specifies that when a new "user" key with the prefix "mtk:" must be instantiated, that task should be performed via the .BR keyctl (1) @@ -482,11 +482,11 @@ See for details of these .I % specifiers. -.PP +.P Then we run the program and check the contents of .I /proc/keys to verify that the requested key has been instantiated: -.PP +.P .in +4n .EX $ \fB./t_request_key user mtk:key1 "Payload data"\fP @@ -494,7 +494,7 @@ $ \fBgrep \[aq]2dddaf50\[aq] /proc/keys\fP 2dddaf50 I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mtk:key1: 12 .EE .in -.PP +.P For another example of the use of this program, see .BR keyctl (2). .SS Program source @@ -549,7 +549,7 @@ main(int argc, char *argv[]) .BR user\-keyring (7), .BR user\-session\-keyring (7), .BR request\-key (8) -.PP +.P The kernel source files .I Documentation/security/keys/core.rst and diff --git a/man2/restart_syscall.2 b/man2/restart_syscall.2 index 4b0e101..87e8705 100644 --- a/man2/restart_syscall.2 +++ b/man2/restart_syscall.2 @@ -10,14 +10,14 @@ .\" .\" See also Section 11.3.3 of Understanding the Linux Kernel, 3rd edition .\" -.TH restart_syscall 2 2023-03-30 "Linux man-pages 6.05.01" +.TH restart_syscall 2 2023-10-31 "Linux man-pages 6.7" .SH NAME restart_syscall \- restart a system call after interruption by a stop signal .SH SYNOPSIS .nf .B long restart_syscall(void); .fi -.PP +.P .IR Note : There is no glibc wrapper for this system call; see NOTES. .SH DESCRIPTION @@ -32,7 +32,7 @@ is later resumed after receiving a .B SIGCONT signal. This system call is designed only for internal use by the kernel. -.PP +.P .BR restart_syscall () is used for restarting only those system calls that, when restarted, should adjust their time-related parameters\[em]namely @@ -83,7 +83,7 @@ Linux 2.6. There is no glibc wrapper for this system call, because it is intended for use only by the kernel and should never be called by applications. -.PP +.P The kernel uses .BR restart_syscall () to ensure that when a system call is restarted @@ -105,7 +105,7 @@ Notable examples of system calls that suffer this problem are .BR select (2), and .BR pselect (2). -.PP +.P From user space, the operation of .BR restart_syscall () is largely invisible: diff --git a/man2/rmdir.2 b/man2/rmdir.2 index 5bd7370..a1dc594 100644 --- a/man2/rmdir.2 +++ b/man2/rmdir.2 @@ -7,7 +7,7 @@ .\" Modified 1997-01-31 by Eric S. Raymond .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH rmdir 2 2023-03-30 "Linux man-pages 6.05.01" +.TH rmdir 2 2023-10-31 "Linux man-pages 6.7" .SH NAME rmdir \- delete a directory .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int rmdir(const char *" pathname ); .fi .SH DESCRIPTION diff --git a/man2/rt_sigqueueinfo.2 b/man2/rt_sigqueueinfo.2 index b8b0157..d2d2eec 100644 --- a/man2/rt_sigqueueinfo.2 +++ b/man2/rt_sigqueueinfo.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH rt_sigqueueinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.TH rt_sigqueueinfo 2 2023-10-31 "Linux man-pages 6.7" .SH NAME rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data .SH LIBRARY @@ -13,13 +13,13 @@ Standard C library .BR "#include " " /* Definition of " SI_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_rt_sigqueueinfo, pid_t " tgid , .BI " int " sig ", siginfo_t *" info ); .BI "int syscall(SYS_rt_tgsigqueueinfo, pid_t " tgid ", pid_t " tid , .BI " int " sig ", siginfo_t *" info ); .fi -.PP +.P .IR Note : There are no glibc wrappers for these system calls; see NOTES. .SH DESCRIPTION @@ -34,13 +34,13 @@ by establishing a signal handler with the .BR sigaction (2) .B SA_SIGINFO flag. -.PP +.P These system calls are not intended for direct application use; they are provided to allow the implementation of .BR sigqueue (3) and .BR pthread_sigqueue (3). -.PP +.P The .BR rt_sigqueueinfo () system call sends the signal @@ -52,7 +52,7 @@ to the thread group with the ID corresponds to the traditional UNIX process ID.) The signal will be delivered to an arbitrary member of the thread group (i.e., one of the threads that is not currently blocking the signal). -.PP +.P The .I info argument specifies the data to accompany the signal. @@ -103,14 +103,14 @@ For more information, see the description of the last .RI ( "union sigval" ) argument of .BR sigqueue (3). -.PP +.P Internally, the kernel sets the .I si_signo field to the value specified in .IR sig , so that the receiver of the signal can also obtain the signal number via that field. -.PP +.P The .BR rt_tgsigqueueinfo () system call is like @@ -158,7 +158,7 @@ is invalid. No thread group matching .I tgid was found. -.PP +.P .BR rt_tgsigqueinfo (): No thread matching .I tgid @@ -179,7 +179,7 @@ Since these system calls are not intended for application use, there are no glibc wrapper functions; use .BR syscall (2) in the unlikely case that you want to call them directly. -.PP +.P As with .BR kill (2), the null signal (0) can be used to check if the specified process diff --git a/man2/s390_guarded_storage.2 b/man2/s390_guarded_storage.2 index 63d5c83..b2038e5 100644 --- a/man2/s390_guarded_storage.2 +++ b/man2/s390_guarded_storage.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH s390_guarded_storage 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_guarded_storage 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_guarded_storage \- operations with z/Architecture guarded storage facility .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .BR "#include " \ "/* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_s390_guarded_storage, int " command , .BI " struct gs_cb *" gs_cb ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR s390_guarded_storage (), @@ -29,7 +29,7 @@ The .BR s390_guarded_storage () system call enables the use of the Guarded Storage Facility (a z/Architecture-specific feature) for user-space processes. -.PP +.P .\" The description is based on .\" http://www-05.ibm.com/de/linux-on-z-ws-us/agenda/pdfs/8_-_Linux_Whats_New_-_Stefan_Raspl.pdf .\" and "z/Architecture Principles of Operation" obtained from @@ -40,7 +40,7 @@ reading a pointer with a newly introduced "Load Guarded" (LGG) or "Load Logical and Shift Guarded" (LLGFSG) instructions will cause a range check on the loaded value and invoke a (previously set up) user-space handler if one of the guarded regions is affected. -.PP +.P The .\" The command description is copied from v4.12-rc1~139^2~56^2 commit message .I command @@ -88,7 +88,7 @@ The broadcast guarded storage control block is consumed; a second broadcast without a refresh of the stored control block with .B GS_SET_BC_CB will not have any effect. -.PP +.P The .I gs_cb argument specifies the address of a guarded storage control block structure @@ -99,7 +99,7 @@ command; all other aforementioned commands ignore this argument. On success, the return value of .BR s390_guarded_storage () is 0. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -138,7 +138,7 @@ instructions and Guarded Storage Control Block and Guarded Storage Event Parameter List structure layouts is available in "z/Architecture Principles of Operations" beginning from the twelfth edition. -.PP +.P The .I gs_cb structure has a field @@ -153,7 +153,7 @@ field), and its layout is available as a structure type definition in the .I asm/guarded_storage.h header. -.\" .PP +.\" .P .\" For the example of using the guarded storage facility, see .\" .UR https://developer.ibm.com/javasdk/2017/09/25/concurrent-scavenge-using-guarded-storage-facility-works/ .\" the article with the description of its usage in the Java Garbage Collection diff --git a/man2/s390_pci_mmio_write.2 b/man2/s390_pci_mmio_write.2 index 07788e9..f6b8c46 100644 --- a/man2/s390_pci_mmio_write.2 +++ b/man2/s390_pci_mmio_write.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH s390_pci_mmio_write 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_pci_mmio_write 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_pci_mmio_write, s390_pci_mmio_read \- transfer data to/from PCI MMIO memory page @@ -14,14 +14,14 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_s390_pci_mmio_write, unsigned long " mmio_addr , .BI " const void " user_buffer [. length "], \ size_t " length ); .BI "int syscall(SYS_s390_pci_mmio_read, unsigned long " mmio_addr , .BI " void " user_buffer [. length "], size_t " length ); .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -44,7 +44,7 @@ data from the PCI MMIO memory location specified by .I mmio_addr to the user-space buffer .IR user_buffer . -.PP +.P These system calls must be used instead of the simple assignment or data-transfer operations that are used to access the PCI MMIO memory areas mapped to user space on the Linux System z platform. diff --git a/man2/s390_runtime_instr.2 b/man2/s390_runtime_instr.2 index fb1be13..a01421b 100644 --- a/man2/s390_runtime_instr.2 +++ b/man2/s390_runtime_instr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH s390_runtime_instr 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_runtime_instr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_runtime_instr \- enable/disable s390 CPU run-time instrumentation .SH LIBRARY @@ -14,10 +14,10 @@ Standard C library .BR "#include " " /* Definition of " S390_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_s390_runtime_instr, int " command ", int " signum ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR s390_runtime_instr (), @@ -28,7 +28,7 @@ The .BR s390_runtime_instr () system call starts or stops CPU run-time instrumentation for the calling thread. -.PP +.P The .I command argument controls whether run-time instrumentation is started @@ -36,7 +36,7 @@ argument controls whether run-time instrumentation is started 1) or stopped .RB ( S390_RUNTIME_INSTR_STOP , 2) for the calling thread. -.PP +.P The .I signum argument specifies the number of a real-time signal. @@ -90,7 +90,7 @@ The header file is available .\" commit df2f815a7df7edb5335a3bdeee6a8f9f6f9c35c4 since Linux 4.16. -.PP +.P Starting with Linux 4.4, support for signalling was removed, as was the check whether .I signum diff --git a/man2/s390_sthyi.2 b/man2/s390_sthyi.2 index 9c6af82..1b0023e 100644 --- a/man2/s390_sthyi.2 +++ b/man2/s390_sthyi.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH s390_sthyi 2 2023-03-30 "Linux man-pages 6.05.01" +.TH s390_sthyi 2 2023-10-31 "Linux man-pages 6.7" .SH NAME s390_sthyi \- emulate STHYI instruction .SH LIBRARY @@ -14,12 +14,12 @@ Standard C library .BR "#include " " /* Definition of " STHYI_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_s390_sthyi, unsigned long " function_code , .BI " void *" resp_buffer ", uint64_t *" return_code , .BI " unsigned long " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR s390_sthyi (), @@ -33,7 +33,7 @@ It provides hardware resource information for the machine and its virtualization levels. This includes CPU type and capacity, as well as the machine model and other metrics. -.PP +.P The .I function_code argument indicates which function to perform. @@ -42,7 +42,7 @@ The following code(s) are supported: .B STHYI_FC_CP_IFL_CAP Return CP (Central Processor) and IFL (Integrated Facility for Linux) capacity information. -.PP +.P The .I resp_buffer argument specifies the address of a response buffer. @@ -54,7 +54,7 @@ the buffer must be one page (4K) in size. If the system call returns 0, the response buffer will be filled with CPU capacity information. Otherwise, the response buffer's content is unchanged. -.PP +.P The .I return_code argument stores the return code of the STHYI instruction, @@ -65,14 +65,14 @@ Success. .TP 4 Unsupported function code. -.PP +.P For further details about .IR return_code , .IR function_code , and .IR resp_buffer , see the reference given in NOTES. -.PP +.P The .I flags argument is provided to allow for future extensions and currently @@ -88,7 +88,7 @@ A return value of 3 indicates "unsupported function code" and the content of .I *resp_buffer is unchanged. The return values 1 and 2 are reserved. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -122,11 +122,11 @@ For details of the STHYI instruction, see .UR https://www.ibm.com\:/support\:/knowledgecenter\:/SSB27U_6.3.0\:/com.ibm.zvm.v630.hcpb4\:/hcpb4sth.htm the documentation page .UE . -.PP +.P When the system call interface is used, the response buffer doesn't have to fulfill alignment requirements described in the STHYI instruction definition. -.PP +.P The kernel caches the response (for up to one second, as of Linux 4.16). Subsequent system call invocations may return the cached response. .SH SEE ALSO diff --git a/man2/sched_get_priority_max.2 b/man2/sched_get_priority_max.2 index 491e134..30a66fa 100644 --- a/man2/sched_get_priority_max.2 +++ b/man2/sched_get_priority_max.2 @@ -7,7 +7,7 @@ .\" 1996-04-10 Markus Kuhn .\" revision .\" -.TH sched_get_priority_max 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_get_priority_max 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_get_priority_max, sched_get_priority_min \- get static priority range .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sched_get_priority_max(int " policy ); .BI "int sched_get_priority_min(int " policy ); .fi @@ -41,7 +41,7 @@ and .BR SCHED_DEADLINE . Further details about these policies can be found in .BR sched (7). -.PP +.P Processes with numerically higher priority values are scheduled before processes with numerically lower priority values. Thus, the value @@ -50,7 +50,7 @@ returned by will be greater than the value returned by .BR sched_get_priority_min (). -.PP +.P Linux allows the static priority range 1 to 99 for the .B SCHED_FIFO and @@ -58,7 +58,7 @@ and policies, and the priority 0 for the remaining policies. Scheduling priority ranges for the various policies are not alterable. -.PP +.P The range of scheduling priorities may vary on other POSIX systems, thus it is a good idea for portable applications to use a virtual priority range and map it to the interval given by @@ -71,7 +71,7 @@ a spread of at least 32 between the maximum and the minimum values for .B SCHED_FIFO and .BR SCHED_RR . -.PP +.P POSIX systems on which .BR sched_get_priority_max () and diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2 index cbd6247..b547cf2 100644 --- a/man2/sched_rr_get_interval.2 +++ b/man2/sched_rr_get_interval.2 @@ -7,7 +7,7 @@ .\" 1996-04-10 Markus Kuhn .\" revision .\" -.TH sched_rr_get_interval 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_rr_get_interval 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_rr_get_interval \- get the SCHED_RR interval for the named process .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sched_rr_get_interval(pid_t " pid ", struct timespec *" tp ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ the round-robin time quantum for the process identified by The specified process should be running under the .B SCHED_RR scheduling policy. -.PP +.P If .I pid is zero, the time quantum for the calling process is written into diff --git a/man2/sched_setaffinity.2 b/man2/sched_setaffinity.2 index 9389e09..7512129 100644 --- a/man2/sched_setaffinity.2 +++ b/man2/sched_setaffinity.2 @@ -12,7 +12,7 @@ .\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a .\" separate CPU_SET(3) page. .\" -.TH sched_setaffinity 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sched_setaffinity 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setaffinity, sched_getaffinity \- \ set and get a thread's CPU affinity mask @@ -23,7 +23,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize , .BI " const cpu_set_t *" mask ); .BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize , @@ -43,14 +43,14 @@ Restricting a thread to run on a single CPU also avoids the performance cost caused by the cache invalidation that occurs when a thread ceases to execute on one CPU and then recommences execution on a different CPU. -.PP +.P A CPU affinity mask is represented by the .I cpu_set_t structure, a "CPU set", pointed to by .IR mask . A set of macros for manipulating CPU sets is described in .BR CPU_SET (3). -.PP +.P .BR sched_setaffinity () sets the CPU affinity mask of the thread whose ID is .I pid @@ -65,14 +65,14 @@ is the length (in bytes) of the data pointed to by .IR mask . Normally this argument would be specified as .IR "sizeof(cpu_set_t)" . -.PP +.P If the thread specified by .I pid is not currently running on one of the CPUs specified in .IR mask , then that thread is migrated to one of the CPUs specified in .IR mask . -.PP +.P .BR sched_getaffinity () writes the affinity mask of the thread whose ID is .I pid @@ -139,7 +139,7 @@ Linux. .SH HISTORY Linux 2.5.8, glibc 2.3. -.PP +.P Initially, the glibc interfaces included a .I cpusetsize argument, typed as @@ -161,7 +161,7 @@ runs if the "cpuset" mechanism described in is being used. These restrictions on the actual set of CPUs on which the thread will run are silently imposed by the kernel. -.PP +.P There are various ways of determining the number of CPUs available on the system, including: inspecting the contents of .IR /proc/cpuinfo ; @@ -173,10 +173,10 @@ and .B _SC_NPROCESSORS_ONLN parameters; and inspecting the list of CPU directories under .IR /sys/devices/system/cpu/ . -.PP +.P .BR sched (7) has a description of the Linux scheduling scheme. -.PP +.P The affinity mask is a per-thread attribute that can be adjusted independently for each of the threads in a thread group. The value returned from a call to @@ -193,7 +193,7 @@ will set the attribute for the main thread of the thread group. .BR pthread_setaffinity_np (3) instead of .BR sched_setaffinity ().) -.PP +.P The .I isolcpus boot option can be used to isolate one or more CPUs at boot time, @@ -211,7 +211,7 @@ As noted in that file, is the preferred mechanism of isolating CPUs (versus the alternative of manually setting the CPU affinity of all processes on the system). -.PP +.P A child created via .BR fork (2) inherits its parent's CPU affinity mask. @@ -225,7 +225,7 @@ being typed as .IR "unsigned long\ *" , reflecting the fact that the underlying implementation of CPU sets is a simple bit mask. -.PP +.P On success, the raw .BR sched_getaffinity () system call returns the number of bytes placed copied into the @@ -249,13 +249,13 @@ meaning that the maximum CPU number that can be represented is 1023. .\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html If the kernel CPU affinity mask is larger than 1024, then calls of the form: -.PP +.P .in +4n .EX sched_getaffinity(pid, sizeof(cpu_set_t), &mask); .EE .in -.PP +.P fail with the error .BR EINVAL , the error produced by the underlying system call for the case where the @@ -265,7 +265,7 @@ size specified in is smaller than the size of the affinity mask used by the kernel. (Depending on the system CPU topology, the kernel affinity mask can be substantially larger than the number of active CPUs in the system.) -.PP +.P When working on systems with large kernel CPU affinity masks, one must dynamically allocate the .I mask @@ -276,7 +276,7 @@ of the required mask using .BR sched_getaffinity () calls with increasing mask sizes (until the call does not fail with the error .BR EINVAL ). -.PP +.P Be aware that .BR CPU_ALLOC (3) may allocate a slightly larger CPU set than requested @@ -300,16 +300,16 @@ The program takes three command-line arguments: the CPU number for the parent, the CPU number for the child, and the number of loop iterations that both processes should perform. -.PP +.P As the sample runs below demonstrate, the amount of real and CPU time consumed when running the program will depend on intra-core caching effects and whether the processes are using the same CPU. -.PP +.P We first employ .BR lscpu (1) to determine that this (x86) system has two cores, each with two CPUs: -.PP +.P .in +4n .EX $ \fBlscpu | egrep \-i \[aq]core.*:|socket\[aq]\fP @@ -318,12 +318,12 @@ Core(s) per socket: 2 Socket(s): 1 .EE .in -.PP +.P We then time the operation of the example program for three cases: both processes running on the same CPU; both processes running on different CPUs on the same core; and both processes running on different CPUs on different cores. -.PP +.P .in +4n .EX $ \fBtime \-p ./a.out 0 0 100000000\fP diff --git a/man2/sched_setattr.2 b/man2/sched_setattr.2 index b4975c6..546ac31 100644 --- a/man2/sched_setattr.2 +++ b/man2/sched_setattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sched_setattr 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_setattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setattr, sched_getattr \- set and get scheduling policy and attributes @@ -15,14 +15,14 @@ Standard C library .BR "#include " " /* Definition of " SCHED_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_sched_setattr, pid_t " pid ", struct sched_attr *" attr , .BI " unsigned int " flags ); .BI "int syscall(SYS_sched_getattr, pid_t " pid ", struct sched_attr *" attr , .BI " unsigned int " size ", unsigned int " flags ); .fi .\" FIXME . Add feature test macro requirements -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -38,7 +38,7 @@ If .I pid equals zero, the scheduling policy and attributes of the calling thread will be set. -.PP +.P Currently, Linux supports the following "normal" (i.e., non-real-time) scheduling policies as values that may be specified in .IR policy : @@ -55,7 +55,7 @@ for "batch" style execution of processes; and for running .I very low priority background jobs. -.PP +.P Various "real-time" policies are also supported, for special time-critical applications that need precise control over the way in which runnable threads are selected for execution. @@ -70,20 +70,20 @@ a first-in, first-out policy; and .TP .B SCHED_RR a round-robin policy. -.PP +.P Linux also provides the following policy: .TP 14 .B SCHED_DEADLINE a deadline scheduling policy; see .BR sched (7) for details. -.PP +.P The .I attr argument is a pointer to a structure that defines the new scheduling policy and attributes for the specified thread. This structure has the following form: -.PP +.P .in +4n .EX struct sched_attr { @@ -101,7 +101,7 @@ struct sched_attr { }; .EE .in -.PP +.P The fields of the .I sched_attr structure are as follows: @@ -228,7 +228,7 @@ The value is expressed in nanoseconds. .I sched_period This field specifies the "Period" parameter for deadline scheduling. The value is expressed in nanoseconds. -.PP +.P The .I flags argument is provided to allow for future extensions to the interface; @@ -246,7 +246,7 @@ If equals zero, the scheduling policy and attributes of the calling thread will be retrieved. -.PP +.P The .I size argument should be set to the size of the @@ -256,7 +256,7 @@ The value must be at least as large as the size of the initially published .I sched_attr structure, or the call fails with the error .BR EINVAL . -.PP +.P The retrieved scheduling attributes are placed in the fields of the .I sched_attr structure pointed to by @@ -266,7 +266,7 @@ The kernel sets to the size of its .I sched_attr structure. -.PP +.P If the caller-provided .I attr buffer is larger than the kernel's @@ -280,7 +280,7 @@ outside the provided space. As with .BR sched_setattr (), these semantics allow for future extensibility of the interface. -.PP +.P The .I flags argument is provided to allow for future extensions to the interface; @@ -312,7 +312,7 @@ is not zero. The thread whose ID is .I pid could not be found. -.PP +.P In addition, .BR sched_getattr () can fail for the following reasons: @@ -329,7 +329,7 @@ is too small. is invalid; that is, it is smaller than the initial version of the .I sched_attr structure (48 bytes) or larger than the system page size. -.PP +.P In addition, .BR sched_setattr () can fail for the following reasons: @@ -380,7 +380,7 @@ Linux 3.14. .SH NOTES glibc does not provide wrappers for these system calls; call them using .BR syscall (2). -.PP +.P .BR sched_setattr () provides a superset of the functionality of .BR sched_setscheduler (2), @@ -406,7 +406,7 @@ failed with the error instead of .B E2BIG for the case described in ERRORS. -.PP +.P Up to Linux 5.3, .BR sched_getattr () failed with the error diff --git a/man2/sched_setparam.2 b/man2/sched_setparam.2 index f054f5d..3e69961 100644 --- a/man2/sched_setparam.2 +++ b/man2/sched_setparam.2 @@ -8,7 +8,7 @@ .\" revision .\" Modified 2004-05-27 by Michael Kerrisk .\" -.TH sched_setparam 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_setparam 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setparam, sched_getparam \- set and get scheduling parameters .SH LIBRARY @@ -17,10 +17,10 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sched_setparam(pid_t " pid ", const struct sched_param *" param ); .BI "int sched_getparam(pid_t " pid ", struct sched_param *" param ); -.PP +.P \fBstruct sched_param { ... int \fIsched_priority\fB; @@ -40,13 +40,13 @@ policy of the thread identified by See .BR sched (7) for a description of the scheduling policies supported under Linux. -.PP +.P .BR sched_getparam () retrieves the scheduling parameters for the thread identified by \fIpid\fP. If \fIpid\fP is zero, then the parameters of the calling thread are retrieved. -.PP +.P .BR sched_setparam () checks the validity of \fIparam\fP for the scheduling policy of the thread. @@ -55,11 +55,11 @@ range given by .BR sched_get_priority_min (2) and .BR sched_get_priority_max (2). -.PP +.P For a discussion of the privileges and resource limits related to scheduling priority and policy, see .BR sched (7). -.PP +.P POSIX systems on which .BR sched_setparam () and diff --git a/man2/sched_setscheduler.2 b/man2/sched_setscheduler.2 index 20ad5c2..ec67aef 100644 --- a/man2/sched_setscheduler.2 +++ b/man2/sched_setscheduler.2 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH sched_setscheduler 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sched_setscheduler 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_setscheduler, sched_getscheduler \- set and get scheduling policy/parameters @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sched_setscheduler(pid_t " pid ", int " policy , .BI " const struct sched_param *" param ); .BI "int sched_getscheduler(pid_t " pid ); @@ -26,11 +26,11 @@ sets both the scheduling policy and parameters for the thread whose ID is specified in \fIpid\fP. If \fIpid\fP equals zero, the scheduling policy and parameters of the calling thread will be set. -.PP +.P The scheduling parameters are specified in the .I param argument, which is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct sched_param { @@ -40,13 +40,13 @@ struct sched_param { }; .EE .in -.PP +.P In the current implementation, the structure contains only one field, .IR sched_priority . The interpretation of .I param depends on the selected policy. -.PP +.P Currently, Linux supports the following "normal" (i.e., non-real-time) scheduling policies as values that may be specified in .IR policy : @@ -63,11 +63,11 @@ for "batch" style execution of processes; and for running .I very low priority background jobs. -.PP +.P For each of the above policies, .I param\->sched_priority must be 0. -.PP +.P Various "real-time" policies are also supported, for special time-critical applications that need precise control over the way in which runnable threads are selected for execution. @@ -82,7 +82,7 @@ a first-in, first-out policy; and .TP .B SCHED_RR a round-robin policy. -.PP +.P For each of the above policies, .I param\->sched_priority specifies a scheduling priority for the thread. @@ -93,7 +93,7 @@ and with the specified .IR policy . On Linux, these system calls return, respectively, 1 and 99. -.PP +.P Since Linux 2.6.32, the .B SCHED_RESET_ON_FORK flag can be ORed in @@ -106,7 +106,7 @@ do not inherit privileged scheduling policies. See .BR sched (7) for details. -.PP +.P .BR sched_getscheduler () returns the current scheduling policy of the thread identified by \fIpid\fP. @@ -155,7 +155,7 @@ and details vary across systems. For example, the Solaris 7 manual page says that the real or effective user ID of the caller must match the real user ID or the save set-user-ID of the target. -.PP +.P The scheduling policy and parameters are in fact per-thread attributes on Linux. The value returned from a call to @@ -178,7 +178,7 @@ instead of the system calls.) .SH STANDARDS POSIX.1-2008 (but see BUGS below). -.PP +.P .B SCHED_BATCH and .B SCHED_IDLE @@ -194,7 +194,7 @@ That page also describes an additional policy, .BR SCHED_DEADLINE , which is settable only via .BR sched_setattr (2). -.PP +.P POSIX systems on which .BR sched_setscheduler () and diff --git a/man2/sched_yield.2 b/man2/sched_yield.2 index 154fd4f..caf7792 100644 --- a/man2/sched_yield.2 +++ b/man2/sched_yield.2 @@ -7,7 +7,7 @@ .\" 1996-04-10 Markus Kuhn .\" revision .\" -.TH sched_yield 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sched_yield 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sched_yield \- yield the processor .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int sched_yield(void); .fi .SH DESCRIPTION @@ -40,7 +40,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001 (but optional). POSIX.1-2008. -.PP +.P Before POSIX.1-2008, systems on which .BR sched_yield () @@ -59,12 +59,12 @@ Use of with nondeterministic scheduling policies such as .B SCHED_OTHER is unspecified and very likely means your application design is broken. -.PP +.P If the calling thread is the only thread in the highest priority list at that time, it will continue to run after a call to .BR sched_yield (). -.PP +.P Avoid calling .BR sched_yield () unnecessarily or inappropriately diff --git a/man2/seccomp.2 b/man2/seccomp.2 index 6b32eec..b3f8026 100644 --- a/man2/seccomp.2 +++ b/man2/seccomp.2 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH seccomp 2 2023-05-03 "Linux man-pages 6.05.01" +.TH seccomp 2 2023-10-31 "Linux man-pages 6.7" .SH NAME seccomp \- operate on Secure Computing state of the process .SH LIBRARY @@ -23,11 +23,11 @@ Standard C library .\" need .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_seccomp, unsigned int " operation ", unsigned int " flags , .BI " void *" args ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR seccomp (), @@ -38,7 +38,7 @@ The .BR seccomp () system call operates on the Secure Computing (seccomp) state of the calling process. -.PP +.P Currently, Linux supports the following .I operation values: @@ -290,7 +290,7 @@ When adding filters via .BR SECCOMP_SET_MODE_FILTER , .I args points to a filter program: -.PP +.P .in +4n .EX struct sock_fprog { @@ -300,9 +300,9 @@ struct sock_fprog { }; .EE .in -.PP +.P Each program must contain one or more BPF instructions: -.PP +.P .in +4n .EX struct sock_filter { /* Filter block */ @@ -313,7 +313,7 @@ struct sock_filter { /* Filter block */ }; .EE .in -.PP +.P When executing the instructions, the BPF program operates on the system call information made available (i.e., use the .B BPF_ABS @@ -324,7 +324,7 @@ addressing mode) as a (read-only) .\" that would need to use ptrace to catch the call and directly .\" modify the registers before continuing with the call. buffer of the following form: -.PP +.P .in +4n .EX struct seccomp_data { @@ -336,7 +336,7 @@ struct seccomp_data { }; .EE .in -.PP +.P Because numbering of system calls varies between architectures and some architectures (e.g., x86-64) allow user-space code to use the calling conventions of multiple architectures @@ -346,7 +346,7 @@ to execute binaries that employ the different conventions), it is usually necessary to verify the value of the .I arch field. -.PP +.P It is strongly recommended to use an allow-list approach whenever possible because such an approach is more robust and simple. A deny-list will have to be updated whenever a potentially @@ -357,7 +357,7 @@ a deny-list bypass. See also .I Caveats below. -.PP +.P The .I arch field is not unique for all calling conventions. @@ -379,7 +379,7 @@ is used on the system call number to tell the two ABIs apart. .\" will have a value that is not all-ones, and this will trigger .\" an extra instruction in system_call to mask off the extra bit, .\" so that the syscall table indexing still works. -.PP +.P This means that a policy must either deny all syscalls with .B __X32_SYSCALL_BIT or it must recognize syscalls with and without @@ -393,7 +393,7 @@ values with .B __X32_SYSCALL_BIT set can be bypassed by a malicious program that sets .BR __X32_SYSCALL_BIT . -.PP +.P Additionally, kernels prior to Linux 5.4 incorrectly permitted .I nr in the ranges 512-547 as well as the corresponding non-x32 syscalls ORed @@ -415,7 +415,7 @@ On Linux 5.4 and newer, such system calls will fail with the error .BR ENOSYS , without doing anything. -.PP +.P The .I instruction_pointer field provides the address of the machine-language instruction that @@ -429,7 +429,7 @@ made the system call. and .BR mprotect (2) system calls to prevent the program from subverting such checks.) -.PP +.P When checking values from .IR args , keep in mind that arguments are often @@ -443,7 +443,7 @@ a system call that takes an argument of type .IR int , the more-significant half of the argument register is ignored by the system call, but visible in the seccomp data. -.PP +.P A seccomp filter returns a 32-bit value consisting of two parts: the most significant 16 bits (corresponding to the mask defined by the constant @@ -452,7 +452,7 @@ contain one of the "action" values listed below; the least significant 16-bits (defined by the constant .BR SECCOMP_RET_DATA ) are "data" to be associated with this return value. -.PP +.P If multiple filters exist, they are \fIall\fP executed, in reverse order of their addition to the filter tree\[em]that is, the most recently installed filter is executed first. @@ -476,7 +476,7 @@ avoiding a check for this uncommon case.) The return value for the evaluation of a given system call is the first-seen action value of highest precedence (along with its accompanying data) returned by execution of all of the filters. -.PP +.P In decreasing order of precedence, the action values that may be returned by a seccomp filter are: .TP @@ -680,7 +680,7 @@ file. .TP .B SECCOMP_RET_ALLOW This value results in the system call being executed. -.PP +.P If an action value other than one of the above is specified, then the filter action is treated as either .B SECCOMP_RET_KILL_PROCESS @@ -871,21 +871,21 @@ Rather than hand-coding seccomp filters as shown in the example below, you may prefer to employ the .I libseccomp library, which provides a front-end for generating seccomp filters. -.PP +.P The .I Seccomp field of the .IR /proc/ pid /status file provides a method of viewing the seccomp mode of a process; see .BR proc (5). -.PP +.P .BR seccomp () provides a superset of the functionality provided by the .BR prctl (2) .B PR_SET_SECCOMP operation (which does not support .IR flags ). -.PP +.P Since Linux 4.4, the .BR ptrace (2) .B PTRACE_SECCOMP_GET_FILTER @@ -966,14 +966,14 @@ but starting in glibc 2.26, the implementation switched to calling .BR openat (2) on all architectures. .RE -.PP +.P The consequence of the above points is that it may be necessary to filter for a system call other than might be expected. Various manual pages in Section 2 provide helpful details about the differences between wrapper functions and the underlying system calls in subsections entitled .IR "C library/kernel differences" . -.PP +.P Furthermore, note that the application of seccomp filters even risks causing bugs in an application, when the filters cause unexpected failures for legitimate operations @@ -1019,7 +1019,7 @@ If the program attempts to execute the system call with the specified number, the BPF filter causes the system call to fail, with .I errno being set to the specified error number. -.PP +.P The remaining command-line arguments specify the pathname and additional arguments of a program that the example program should attempt to execute using @@ -1028,11 +1028,11 @@ that the example program should attempt to execute using .BR execve (2) system call). Some example runs of the program are shown below. -.PP +.P First, we display the architecture that we are running on (x86-64) and then construct a shell function that looks up system call numbers on this architecture: -.PP +.P .in +4n .EX $ \fBuname \-m\fP @@ -1043,25 +1043,25 @@ $ \fBsyscall_nr() { }\fP .EE .in -.PP +.P When the BPF filter rejects a system call (case [2] above), it causes the system call to fail with the error number specified on the command line. In the experiments shown here, we'll use error number 99: -.PP +.P .in +4n .EX $ \fBerrno 99\fP EADDRNOTAVAIL 99 Cannot assign requested address .EE .in -.PP +.P In the following example, we attempt to run the command .BR whoami (1), but the BPF filter rejects the .BR execve (2) system call, so that the command is not even executed: -.PP +.P .in +4n .EX $ \fBsyscall_nr execve\fP @@ -1074,13 +1074,13 @@ $ \fB./a.out 59 0xC000003E 99 /bin/whoami\fP execv: Cannot assign requested address .EE .in -.PP +.P In the next example, the BPF filter rejects the .BR write (2) system call, so that, although it is successfully started, the .BR whoami (1) command is not able to write output: -.PP +.P .in +4n .EX $ \fBsyscall_nr write\fP @@ -1088,12 +1088,12 @@ $ \fBsyscall_nr write\fP $ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP .EE .in -.PP +.P In the final example, the BPF filter rejects a system call that is not used by the .BR whoami (1) command, so it is able to successfully execute and produce output: -.PP +.P .in +4n .EX $ \fBsyscall_nr preadv\fP @@ -1218,7 +1218,7 @@ main(int argc, char *argv[]) .BR proc (5), .BR signal (7), .BR socket (7) -.PP +.P Various pages from the .I libseccomp library, including: @@ -1228,7 +1228,7 @@ library, including: .BR seccomp_load (3), and .BR seccomp_rule_add (3). -.PP +.P The kernel source files .I Documentation/networking/filter.txt and @@ -1237,7 +1237,7 @@ and (or .I Documentation/prctl/seccomp_filter.txt before Linux 4.13). -.PP +.P McCanne, S.\& and Jacobson, V.\& (1992) .IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" , Proceedings of the USENIX Winter 1993 Conference diff --git a/man2/seccomp_unotify.2 b/man2/seccomp_unotify.2 index 156fbce..7c2084b 100644 --- a/man2/seccomp_unotify.2 +++ b/man2/seccomp_unotify.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH seccomp_unotify 2 2023-05-03 "Linux man-pages 6.05.01" +.TH seccomp_unotify 2 2023-10-31 "Linux man-pages 6.7" .SH NAME seccomp_unotify \- Seccomp user-space notification mechanism .SH LIBRARY @@ -13,12 +13,12 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "int seccomp(unsigned int " operation ", unsigned int " flags \ ", void *" args ); -.PP +.P .B #include -.PP +.P .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_RECV," .BI " struct seccomp_notif *" req ); .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SEND," @@ -51,7 +51,7 @@ the handling of the system call to another user-space process. Note that this mechanism is explicitly .B not intended as a method implementing security policy; see NOTES. -.PP +.P In the discussion that follows, the thread(s) on which the seccomp filter is installed is (are) referred to as the @@ -59,7 +59,7 @@ referred to as the and the process that is notified by the user-space notification mechanism is referred to as the .IR supervisor . -.PP +.P A suitably privileged supervisor can use the user-space notification mechanism to perform actions on behalf of the target. The advantage of the user-space notification mechanism is that @@ -69,7 +69,7 @@ performed system call that the seccomp filter itself cannot. (A seccomp filter is limited in the information it can obtain and the actions that it can perform because it is running on a virtual machine inside the kernel.) -.PP +.P An overview of the steps performed by the target and the supervisor is as follows: .\"------------------------------------- @@ -285,7 +285,7 @@ the system call in the target thread unblocks, returning the information that was provided by the supervisor in the notification response. .\"------------------------------------- -.PP +.P As a variation on the last two steps, the supervisor can send a response that tells the kernel that it should execute the target thread's system call; see the discussion of @@ -317,7 +317,7 @@ The third argument is a pointer to a structure of the following form which contains information about the event. This structure must be zeroed out before the call. -.PP +.P .in +4n .EX struct seccomp_notif { @@ -328,7 +328,7 @@ struct seccomp_notif { }; .EE .in -.PP +.P The fields in this structure are as follows: .TP .I id @@ -367,7 +367,7 @@ This is the same structure that is passed to the seccomp filter. See .BR seccomp (2) for details of this structure. -.PP +.P On success, this operation returns 0; on failure, \-1 is returned, and .I errno is set to indicate the cause of the error. @@ -423,7 +423,7 @@ returned by an earlier operation is still valid (i.e., that the target still exists and its system call is still blocked waiting for a response). -.PP +.P The third .BR ioctl (2) argument is a pointer to the cookie @@ -431,7 +431,7 @@ argument is a pointer to the cookie returned by the .B SECCOMP_IOCTL_NOTIF_RECV operation. -.PP +.P This operation is necessary to avoid race conditions that can occur when the .I pid returned by the @@ -458,7 +458,7 @@ the file for the TID obtained in step 1, with the intention of (say) inspecting the memory location(s) that containing the argument(s) of the system call that triggered the notification in step 1. -.PP +.P In the above scenario, the risk is that the supervisor may try to access the memory of a process other than the target. This race can be avoided by following the call to @@ -478,11 +478,11 @@ from the file descriptor may return 0, indicating end of file.) .\" PID, or something like that. (Actually, it is associated .\" with the "struct pid", which is not reused, instead of the .\" numeric PID. -.PP +.P See NOTES for a discussion of other cases where .B SECCOMP_IOCTL_NOTIF_ID_VALID checks must be performed. -.PP +.P On success (i.e., the notification ID is still valid), this operation returns 0. On failure (i.e., the notification ID is no longer valid), @@ -499,7 +499,7 @@ is used to send a notification response back to the kernel. The third .BR ioctl (2) argument of this structure is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct seccomp_notif_resp { @@ -510,7 +510,7 @@ struct seccomp_notif_resp { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I id @@ -537,7 +537,7 @@ This is a bit mask that includes zero or more of the following flags: Tell the kernel to execute the target's system call. .\" commit fb3c5386b382d4097476ce9647260fc89b34afdb .RE -.PP +.P Two kinds of response are possible: .IP \[bu] 3 A response to the kernel telling it to execute the @@ -571,11 +571,11 @@ fields of the structure. The supervisor should set the fields of this structure as follows: .RS -.IP + 3 +.IP \[bu] 3 .I flags does not contain .BR SECCOMP_USER_NOTIF_FLAG_CONTINUE . -.IP + +.IP \[bu] .I error is set either to 0 for a spoofed "success" return or to a negative error number for a spoofed "failure" return. @@ -589,7 +589,7 @@ to return \-1, and is assigned the negated .I error value. -.IP + +.IP \[bu] .I val is set to a value that will be used as the return value for a spoofed "success" return for the target's system call. @@ -609,7 +609,7 @@ field contains a nonzero value. .\" verify that val and err are both 0 when CONTINUE is specified (as you .\" pointed out correctly above). .RE -.PP +.P On success, this operation returns 0; on failure, \-1 is returned, and .I errno is set to indicate the cause of the error. @@ -656,7 +656,7 @@ messages described in this operation is semantically equivalent to duplicating a file descriptor from the supervisor's file descriptor table into the target's file descriptor table. -.PP +.P The .B SECCOMP_IOCTL_NOTIF_ADDFD operation permits the supervisor to emulate a target system call (such as @@ -670,10 +670,10 @@ and then use this operation to allocate a file descriptor that refers to the same open file description in the target. (For an explanation of open file descriptions, see .BR open (2).) -.PP +.P Once this operation has been performed, the supervisor can close its copy of the file descriptor. -.PP +.P In the target, the received file descriptor is subject to the same Linux Security Module (LSM) checks as are applied to a file descriptor @@ -686,11 +686,11 @@ it inherits the cgroup version 1 network controller settings and .IR netprioidx ) of the target. -.PP +.P The third .BR ioctl (2) argument is a pointer to a structure of the following form: -.PP +.P .in +4n .EX struct seccomp_notif_addfd { @@ -704,7 +704,7 @@ struct seccomp_notif_addfd { }; .EE .in -.PP +.P The fields in this structure are as follows: .TP .I id @@ -774,7 +774,7 @@ Currently, only the following flag is implemented: .B O_CLOEXEC Set the close-on-exec flag on the received file descriptor. .RE -.PP +.P On success, this .BR ioctl (2) call returns the number of the file descriptor that was allocated @@ -787,11 +787,11 @@ this value can be used as the return value that is supplied in the response that is subsequently sent with the .B SECCOMP_IOCTL_NOTIF_SEND operation. -.PP +.P On error, \-1 is returned and .I errno is set to indicate the cause of the error. -.PP +.P This operation can fail with the following errors: .TP .B EBADF @@ -838,12 +838,12 @@ exceeds the limit specified in The blocked system call in the target has been interrupted by a signal handler or the target has terminated. -.PP +.P Here is some sample code (with error handling omitted) that uses the .B SECCOMP_ADDFD_FLAG_SETFD operation (here, to emulate a call to .BR openat (2)): -.PP +.P .EX .in +4n int fd, removeFd; @@ -942,12 +942,12 @@ to allow system calls to be performed on behalf of the target. The target's system call should either be handled by the supervisor or allowed to continue normally in the kernel (where standard security policies will be applied). -.PP +.P .BR "Note well" : this mechanism must not be used to make security policy decisions about the system call, which would be inherently race-prone for reasons described next. -.PP +.P The .B SECCOMP_USER_NOTIF_FLAG_CONTINUE flag must be used with caution. @@ -956,7 +956,7 @@ However, there is a time-of-check, time-of-use race here, since an attacker could exploit the interval of time where the target is blocked waiting on the "continue" response to do things such as rewriting the system call arguments. -.PP +.P Note furthermore that a user-space notifier can be bypassed if the existing filters allow the use of .BR seccomp (2) @@ -966,7 +966,7 @@ to install a filter that returns an action value with a higher precedence than .B SECCOMP_RET_USER_NOTIF (see .BR seccomp (2)). -.PP +.P It should thus be absolutely clear that the seccomp user-space notification mechanism .B can not @@ -994,7 +994,7 @@ However, the use of this .BR ioctl (2) operation is also necessary in other situations, as explained in the following paragraphs. -.PP +.P Consider the following scenario, where the supervisor tries to read the pathname argument of a target's blocked .BR mount (2) @@ -1031,7 +1031,7 @@ contain the pathname. The supervisor now calls .BR mount (2) with some arbitrary bytes obtained in the previous step. -.PP +.P The conclusion from the above scenario is this: since the target's blocked system call may be interrupted by a signal handler, the supervisor must be written to expect that the @@ -1040,7 +1040,7 @@ target may abandon its system call at time; in such an event, any information that the supervisor obtained from the target's memory must be considered invalid. -.PP +.P To prevent such scenarios, every read from the target's memory must be separated from use of the bytes so obtained by a @@ -1048,7 +1048,7 @@ the bytes so obtained by a check. In the above example, the check would be placed between the two final steps. An example of such a check is shown in EXAMPLES. -.PP +.P Following on from the above, it should be clear that a write by the supervisor into the target's memory can .B never @@ -1059,7 +1059,7 @@ Suppose that the target performs a blocking system call (e.g., .BR accept (2)) that the supervisor should handle. The supervisor might then in turn execute the same blocking system call. -.PP +.P In this scenario, it is important to note that if the target's system call is now interrupted by a signal, the supervisor is @@ -1077,7 +1077,7 @@ holding a port number that the target perhaps closed its listening socket) might expect to be able to reuse in a .BR bind (2) call. -.PP +.P Therefore, when the supervisor wishes to emulate a blocking system call, it must do so in such a way that it gets informed if the target's system call is interrupted by a signal handler. @@ -1095,7 +1095,7 @@ to monitor both the notification file descriptor .BR accept (2) call has been interrupted) and the listening file descriptor (so as to know when a connection is available). -.PP +.P If the target's system call is interrupted, the supervisor must take care to release resources (e.g., file descriptors) that it acquired on behalf of the target. @@ -1121,14 +1121,14 @@ When (if) the supervisor attempts to send a notification response, the operation will fail with the .B ENOENT error. -.PP +.P In this scenario, the kernel will restart the target's system call. Consequently, the supervisor will receive another user-space notification. Thus, depending on how many times the blocked system call is interrupted by a signal handler, the supervisor may receive multiple notifications for the same instance of a system call in the target. -.PP +.P One oddity is that system call restarting as described in this scenario will occur even for the blocking system calls listed in .BR signal (7) @@ -1156,7 +1156,7 @@ flag. .\" calls because it's impossible for the kernel to restart the call .\" with the right timeout value. I wonder what happens when those .\" system calls are restarted in the scenario we're discussing.) -.PP +.P Furthermore, if the supervisor response is a file descriptor added with .BR SECCOMP_IOCTL_NOTIF_ADDFD , @@ -1195,7 +1195,7 @@ The child process then calls once for each of the supplied command-line arguments, and reports the result returned by the call. After processing all arguments, the child process terminates. -.PP +.P The parent process acts as the supervisor, listening for the notifications that are generated when the target process calls .BR mkdir (2). @@ -1232,14 +1232,14 @@ call appears to fail with the error ("Operation not supported"). Additionally, if the specified pathname is exactly "/bye", then the supervisor terminates. -.PP +.P This program can be used to demonstrate various aspects of the behavior of the seccomp user-space notification mechanism. To help aid such demonstrations, the program logs various messages to show the operation of the target process (lines prefixed "T:") and the supervisor (indented lines prefixed "S:"). -.PP +.P In the following example, the target attempts to create the directory .IR /tmp/x . Upon receiving the notification, the supervisor creates the directory on the @@ -1247,7 +1247,7 @@ target's behalf, and spoofs a success return to be received by the target process's .BR mkdir (2) call. -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /tmp/x\fP @@ -1264,14 +1264,14 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P In the above output, note that the spoofed return value seen by the target process is 6 (the length of the pathname .IR /tmp/x ), whereas a normal .BR mkdir (2) call returns 0 on success. -.PP +.P In the next example, the target attempts to create a directory using the relative pathname .IR ./sub . @@ -1282,7 +1282,7 @@ response to the kernel, and the kernel then (successfully) executes the target process's .BR mkdir (2) call. -.PP +.P .in +4n .EX $ \fB./seccomp_unotify ./sub\fP @@ -1298,7 +1298,7 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P If the target process attempts to create a directory with a pathname that doesn't start with "." and doesn't begin with the prefix "/tmp/", then the supervisor spoofs an error return @@ -1307,7 +1307,7 @@ a pathname that doesn't start with "." and doesn't begin with the prefix for the target's .BR mkdir (2) call (which is not executed): -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /xxx\fP @@ -1323,7 +1323,7 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P In the next example, the target process attempts to create a directory with the pathname .BR /tmp/nosuchdir/b . @@ -1337,7 +1337,7 @@ Consequently, the supervisor spoofs an error return that passes the error that it received back to the target process's .BR mkdir (2) call. -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /tmp/nosuchdir/b\fP @@ -1354,7 +1354,7 @@ T: terminating S: target has terminated; bye .EE .in -.PP +.P If the supervisor receives a notification and sees that the argument of the target's .BR mkdir (2) @@ -1370,7 +1370,7 @@ fail with the error .B ENOSYS ("Function not implemented"). This is demonstrated by the following example: -.PP +.P .in +4n .EX $ \fB./seccomp_unotify /bye /tmp/y\fP @@ -2006,6 +2006,6 @@ main(int argc, char *argv[]) .BR pidfd_getfd (2), .BR pidfd_open (2), .BR seccomp (2) -.PP +.P A further example program can be found in the kernel source file .IR samples/seccomp/user-trap.c . diff --git a/man2/select.2 b/man2/select.2 index 41cb7e6..e544918 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -17,7 +17,7 @@ .\" 2005-03-11, mtk, modified pselect() text (it is now a system .\" call in Linux 2.6.16. .\" -.TH select 2 2023-05-03 "Linux man-pages 6.05.01" +.TH select 2 2023-10-31 "Linux man-pages 6.7" .SH NAME select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \- synchronous I/O multiplexing @@ -27,31 +27,31 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " fd_set; -.PP +.P .BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds , .BI " fd_set *_Nullable restrict " writefds , .BI " fd_set *_Nullable restrict " exceptfds , .BI " struct timeval *_Nullable restrict " timeout ); -.PP +.P .BI "void FD_CLR(int " fd ", fd_set *" set ); .BI "int FD_ISSET(int " fd ", fd_set *" set ); .BI "void FD_SET(int " fd ", fd_set *" set ); .BI "void FD_ZERO(fd_set *" set ); -.PP +.P .BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds , .BI " fd_set *_Nullable restrict " writefds , .BI " fd_set *_Nullable restrict " exceptfds , .BI " const struct timespec *_Nullable restrict " timeout , .BI " const sigset_t *_Nullable restrict " sigmask ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pselect (): .nf _POSIX_C_SOURCE >= 200112L @@ -68,7 +68,7 @@ All modern applications should instead use or .BR epoll (7), which do not suffer this limitation. -.PP +.P .BR select () allows a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" @@ -99,14 +99,14 @@ Each of the .I fd_set arguments may be specified as NULL if no file descriptors are to be watched for the corresponding class of events. -.PP +.P .BR "Note well" : Upon return, each of the file descriptor sets is modified in place to indicate which file descriptors are currently "ready". Thus, if using .BR select () within a loop, the sets \fImust be reinitialized\fP before each call. -.PP +.P The contents of a file descriptor set can be manipulated using the following macros: .TP @@ -237,7 +237,7 @@ The .BR pselect () system call allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P The operation of .BR select () and @@ -267,7 +267,7 @@ argument, and behaves as .BR pselect () called with NULL .IR sigmask . -.PP +.P .I sigmask is a pointer to a signal mask (see .BR sigprocmask (2)); @@ -283,24 +283,24 @@ is NULL, the signal mask is not modified during the .BR pselect () call.) -.PP +.P Other than the difference in the precision of the .I timeout argument, the following .BR pselect () call: -.PP +.P .in +4n .EX ready = pselect(nfds, &readfds, &writefds, &exceptfds, timeout, &sigmask); .EE .in -.PP +.P is equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -310,7 +310,7 @@ ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The reason that .BR pselect () is needed is that if one wants to wait for either a signal @@ -336,7 +336,7 @@ The argument for .BR select () is a structure of the following type: -.PP +.P .in +4n .EX struct timeval { @@ -345,13 +345,13 @@ struct timeval { }; .EE .in -.PP +.P The corresponding argument for .BR pselect () is a .BR timespec (3) structure. -.PP +.P On Linux, .BR select () modifies @@ -370,7 +370,7 @@ Consider to be undefined after .BR select () returns. -.\" .PP - it is rumored that: +.\" .P - it is rumored that: .\" On BSD, when a timeout occurs, the file descriptor bits are not changed. .\" - it is certainly true that: .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. @@ -386,7 +386,7 @@ descriptor sets (that is, the total number of bits that are set in .IR exceptfds ). The return value may be zero if the timeout expired before any file descriptors became ready. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error; @@ -464,7 +464,7 @@ The following header also provides the .I fd_set type: .IR . -.PP +.P An .I fd_set is a fixed size buffer. @@ -481,7 +481,7 @@ in undefined behavior. Moreover, POSIX requires .I fd to be a valid file descriptor. -.PP +.P The operation of .BR select () and @@ -525,7 +525,7 @@ and the event notifications provided by .BR poll (2) and .BR epoll (7): -.PP +.P .in +4n .EX #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN | @@ -564,7 +564,7 @@ However, in the glibc implementation, the .I fd_set type is fixed in size. See also BUGS. -.PP +.P The .BR pselect () interface described in this page is implemented by glibc. @@ -572,7 +572,7 @@ The underlying Linux system call is named .BR pselect6 (). This system call has somewhat different behavior from the glibc wrapper function. -.PP +.P The Linux .BR pselect6 () system call modifies its @@ -587,13 +587,13 @@ function does not modify its .I timeout argument; this is the behavior required by POSIX.1-2001. -.PP +.P The final argument of the .BR pselect6 () system call is not a .I "sigset_t\ *" pointer, but is instead a structure of the form: -.PP +.P .in +4n .EX struct { @@ -603,7 +603,7 @@ struct { }; .EE .in -.PP +.P This allows the system call to obtain both a pointer to the signal set and its size, while allowing for the fact that most architectures @@ -619,7 +619,7 @@ glibc 2.0 provided an incorrect version of that did not take a .I sigmask argument. -.PP +.P From glibc 2.1 to glibc 2.2.1, one must define .B _GNU_SOURCE @@ -645,14 +645,14 @@ To monitor file descriptors greater than 1023, use or .BR epoll (7) instead. -.PP +.P The implementation of the .I fd_set arguments as value-result arguments is a design error that is avoided in .BR poll (2) and .BR epoll (7). -.PP +.P According to POSIX, .BR select () should check all specified file descriptors in the three file descriptor sets, @@ -664,7 +664,7 @@ that the process currently has open. According to POSIX, any such file descriptor that is specified in one of the sets should result in the error .BR EBADF . -.PP +.P Starting with glibc 2.1, glibc provided an emulation of .BR pselect () that was implemented using @@ -677,7 +677,7 @@ was designed to prevent. Modern versions of glibc use the (race-free) .BR pselect () system call on kernels where it is provided. -.PP +.P On Linux, .BR select () may report a socket file descriptor as "ready for reading", while @@ -693,7 +693,7 @@ Thus it may be safer to use .B O_NONBLOCK on sockets that should not block. .\" Maybe the kernel should have returned EIO in such a situation? -.PP +.P On Linux, .BR select () also modifies @@ -760,6 +760,6 @@ main(void) .BR timespec (3), .BR epoll (7), .BR time (7) -.PP +.P For a tutorial with discussion and examples, see .BR select_tut (2). diff --git a/man2/select_tut.2 b/man2/select_tut.2 index e860de3..cbb6953 100644 --- a/man2/select_tut.2 +++ b/man2/select_tut.2 @@ -9,7 +9,7 @@ .\" various other changes .\" 2008-01-26, mtk, substantial changes and rewrites .\" -.TH SELECT_TUT 2 2023-05-03 "Linux man-pages 6.05.01" +.TH SELECT_TUT 2 2023-10-31 "Linux man-pages 6.7" .SH NAME select, pselect \- synchronous I/O multiplexing .SH LIBRARY @@ -27,7 +27,7 @@ system calls are used to efficiently monitor multiple file descriptors, to see if any of them is, or becomes, "ready"; that is, to see whether I/O becomes possible, or an "exceptional condition" has occurred on any of the file descriptors. -.PP +.P This page provides background and tutorial information on the use of these system calls. For details of the arguments and semantics of @@ -54,7 +54,7 @@ This behavior is essential so that signals can be processed in the main loop of the program, otherwise .BR select () would block indefinitely. -.PP +.P Now, somewhere in the main loop will be a conditional to check the global flag. So we must ask: @@ -82,7 +82,7 @@ call would enable .B SIGCHLD by using an empty signal mask. Our program would look like: -.PP +.P .EX static volatile sig_atomic_t got_SIGCHLD = 0; \& @@ -310,7 +310,7 @@ can be used to solve many problems in a portable and efficient way that naive programmers try to solve in a more complicated manner using threads, forking, IPCs, signals, memory sharing, and so on. -.PP +.P The .BR poll (2) system call has the same functionality as @@ -319,7 +319,7 @@ and is somewhat more efficient when monitoring sparse file descriptor sets. It is nowadays widely available, but historically was less portable than .BR select (). -.PP +.P The Linux-specific .BR epoll (7) API provides an interface that is more efficient than @@ -332,7 +332,7 @@ Here is an example that better demonstrates the true utility of .BR select (). The listing below is a TCP forwarding program that forwards from one TCP port to another. -.PP +.P .\" SRC BEGIN (select.c) .EX #include @@ -604,7 +604,7 @@ main(int argc, char *argv[]) } .EE .\" SRC END -.PP +.P The above program properly forwards most kinds of TCP connections including OOB signal data transmitted by \fBtelnet\fP servers. It handles the tricky problem of having data flow in both directions @@ -617,7 +617,7 @@ Another idea is to set nonblocking I/O using .BR fcntl (2). This also has its problems because you end up using inefficient timeouts. -.PP +.P The program does not handle more than one simultaneous connection at a time, although it could easily be extended to do this with a linked list of buffers\[em]one for each connection. diff --git a/man2/semctl.2 b/man2/semctl.2 index 6069169..c3724e4 100644 --- a/man2/semctl.2 +++ b/man2/semctl.2 @@ -20,7 +20,7 @@ .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. .\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. .\" -.TH semctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH semctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME semctl \- System V semaphore control operations .SH LIBRARY @@ -29,26 +29,26 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" +.P +.BI "int semctl(int " semid ", int " semnum ", int " op ", ...);" .fi .SH DESCRIPTION .BR semctl () performs the control operation specified by -.I cmd +.I op on the System\ V semaphore set identified by .IR semid , or on the .IR semnum -th semaphore of that set. (The semaphores in a set are numbered starting at 0.) -.PP +.P This function has three or four arguments, depending on -.IR cmd . +.IR op . When there are four, the fourth has the type .IR "union semun" . The \fIcalling program\fP must define this union as follows: -.PP +.P .in +4n .EX union semun { @@ -60,11 +60,11 @@ union semun { }; .EE .in -.PP +.P The .I semid_ds data structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct semid_ds { @@ -76,7 +76,7 @@ struct semid_ds { }; .EE .in -.PP +.P The fields of the .I semid_ds structure are as follows: @@ -108,13 +108,13 @@ ranging from .B 0 to .IR sem_nsems\-1 . -.PP +.P The .I ipc_perm structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): -.PP +.P .in +4n .EX struct ipc_perm { @@ -128,7 +128,7 @@ struct ipc_perm { }; .EE .in -.PP +.P The least significant 9 bits of the .I mode field of the @@ -144,12 +144,12 @@ l l. 0004 Read by others 0002 Write by others .TE -.PP +.P In effect, "write" means "alter" for a semaphore set. Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. -.PP +.P Valid values for -.I cmd +.I op are: .TP .B IPC_STAT @@ -380,7 +380,7 @@ The calling process must have alter permission on the semaphore set. On success, .BR semctl () returns a nonnegative value depending on -.I cmd +.I op as follows: .TP .B GETNCNT @@ -420,11 +420,11 @@ the identifier of the semaphore set whose index was given in .B SEM_STAT_ANY as for .BR SEM_STAT . -.PP +.P All other -.I cmd +.I op values return 0 on success. -.PP +.P On failure, .BR semctl () returns \-1 and sets @@ -434,7 +434,7 @@ to indicate the error. .TP .B EACCES The argument -.I cmd +.I op has one of the values .BR GETALL , .BR GETPID , @@ -464,7 +464,7 @@ The semaphore set was removed. .TP .B EINVAL Invalid value for -.I cmd +.I op or .IR semid . Or: for a @@ -475,7 +475,7 @@ referred to an array slot that is currently unused. .TP .B EPERM The argument -.I cmd +.I op has the value .B IPC_SET or @@ -493,7 +493,7 @@ capability. .TP .B ERANGE The argument -.I cmd +.I op has the value .B SETALL or @@ -525,7 +525,7 @@ and explicitly notes that this value is set by a successful call, with the implication that no other interface affects the .I sempid value. -.PP +.P While some implementations conform to the behavior specified in POSIX.1, others do not. (The fault here probably lies with POSIX.1 inasmuch as it likely failed @@ -543,7 +543,7 @@ on process termination as a consequence of the use of the .B SEM_UNDO flag (see .BR semop (2)). -.PP +.P Linux also updates .I sempid for @@ -563,7 +563,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 documents more error conditions EINVAL and EOVERFLOW. -.PP +.P Various fields in a \fIstruct semid_ds\fP were typed as .I short under Linux 2.2 @@ -575,8 +575,8 @@ a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an .B IPC_64 flag in -.IR cmd .) -.PP +.IR op .) +.P In some earlier versions of glibc, the .I semun union was defined in \fI\fP, but POSIX.1 requires @@ -598,7 +598,7 @@ program to provide information on allocated resources. In the future these may modified or moved to a .I /proc filesystem interface. -.PP +.P The following system limit on semaphore sets affects a .BR semctl () call: @@ -607,7 +607,7 @@ call: Maximum value for .BR semval : implementation dependent (32767). -.PP +.P For greater portability, it is best to always call .BR semctl () with four arguments. diff --git a/man2/semget.2 b/man2/semget.2 index bd2b693..50813ba 100644 --- a/man2/semget.2 +++ b/man2/semget.2 @@ -14,7 +14,7 @@ .\" Rewrote BUGS note about semget()'s failure to initialize .\" semaphore values .\" -.TH semget 2 2023-05-03 "Linux man-pages 6.05.01" +.TH semget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME semget \- get a System V semaphore set identifier .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .nf .B #include .fi -.PP +.P .BI "int semget(key_t " key , .BI "int " nsems , .BI "int " semflg ); @@ -42,7 +42,7 @@ is zero and does not have the value .BR IPC_PRIVATE ), or to create a new set. -.PP +.P A new set of .I nsems semaphores is created if @@ -55,7 +55,7 @@ and .B IPC_CREAT is specified in .IR semflg . -.PP +.P If .I semflg specifies both @@ -74,7 +74,7 @@ set to .B O_CREAT | O_EXCL for .BR open (2).) -.PP +.P Upon creation, the least significant 9 bits of the argument .I semflg define the permissions (for owner, group, and others) @@ -87,7 +87,7 @@ argument of (though the execute permissions are not meaningful for semaphores, and write permissions mean permission to alter semaphore values). -.PP +.P When creating a new semaphore set, .BR semget () initializes the set's associated data structure, @@ -120,7 +120,7 @@ is set to 0. .IP \[bu] .I sem_ctime is set to the current time. -.PP +.P The argument .I nsems can be 0 @@ -131,7 +131,7 @@ Otherwise, must be greater than 0 and less than or equal to the maximum number of semaphores per semaphore set .RB ( SEMMSL ). -.PP +.P If the semaphore set already exists, the permissions are verified. .\" and a check is made to see if it is marked for destruction. @@ -225,7 +225,7 @@ it should explicitly initialize the semaphores to the desired values. .\" In truth, every one of the many implementations that I've tested sets .\" the values to zero, but I suppose there is/was some obscure .\" implementation out there that does not. -.PP +.P Initialization can be done using .BR semctl (2) .B SETVAL @@ -310,12 +310,12 @@ and flags for the call to .BR semget (). The usage of this program is demonstrated below. -.PP +.P We first create two files that will be used to generate keys using .BR ftok (3), create two semaphore sets using those files, and then list the sets using .BR ipcs (1): -.PP +.P .in +4n .EX $ \fBtouch mykey mykey2\fP @@ -331,7 +331,7 @@ key semid owner perms nsems 0x70041368 10 mtk 600 2 .EE .in -.PP +.P Next, we demonstrate that when .BR semctl (2) is given the same @@ -339,20 +339,20 @@ is given the same (as generated by the same arguments to .BR ftok (3)), it returns the ID of the already existing semaphore set: -.PP +.P .in +4n .EX $ \fB./t_semget \-c mykey p 1\fP ID = 9 .EE .in -.PP +.P Finally, we demonstrate the kind of collision that can occur when .BR ftok (3) is given different .I pathname arguments that have the same inode number: -.PP +.P .in +4n .EX $ \fBln mykey link\fP diff --git a/man2/semop.2 b/man2/semop.2 index ece7a0e..b04fe6a 100644 --- a/man2/semop.2 +++ b/man2/semop.2 @@ -12,7 +12,7 @@ .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop() .\" 2007-07-09, mtk, Added an EXAMPLE code segment. .\" -.TH semop 2 2023-05-03 "Linux man-pages 6.05.01" +.TH semop 2 2023-10-31 "Linux man-pages 6.7" .SH NAME semop, semtimedop \- System V semaphore operations .SH LIBRARY @@ -21,17 +21,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int semop(int " semid ", struct sembuf *" sops ", size_t " nsops ); .BI "int semtimedop(int " semid ", struct sembuf *" sops ", size_t " nsops , .BI " const struct timespec *_Nullable " timeout ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR semtimedop (): .nf _GNU_SOURCE @@ -39,7 +39,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION Each semaphore in a System\ V semaphore set has the following associated values: -.PP +.P .in +4n .EX unsigned short semval; /* semaphore value */ @@ -49,7 +49,7 @@ pid_t sempid; /* PID of process that last modified the semaphore value */ .EE .in -.PP +.P .BR semop () performs operations on selected semaphores in the set indicated by .IR semid . @@ -62,7 +62,7 @@ specifies an operation to be performed on a single semaphore. The elements of this structure are of type .IR "struct sembuf" , containing the following members: -.PP +.P .in +4n .EX unsigned short sem_num; /* semaphore number */ @@ -70,7 +70,7 @@ short sem_op; /* semaphore operation */ short sem_flg; /* operation flags */ .EE .in -.PP +.P Flags recognized in .I sem_flg are @@ -80,7 +80,7 @@ and If an operation specifies .BR SEM_UNDO , it will be automatically undone when the process terminates. -.PP +.P The set of operations contained in .I sops is performed in @@ -95,14 +95,14 @@ performed immediately depends on the presence of the flag in the individual .I sem_flg fields, as noted below. -.PP +.P Each operation is performed on the .IR sem_num \-th semaphore of the semaphore set, where the first semaphore of the set is numbered 0. There are three types of operation, distinguished by the value of .IR sem_op . -.PP +.P If .I sem_op is a positive integer, the operation adds this value to @@ -117,7 +117,7 @@ from the semaphore adjustment value for this semaphore. This operation can always proceed\[em]it never forces a thread to wait. The calling process must have alter permission on the semaphore set. -.PP +.P If .I sem_op is zero, the process must have read permission on the semaphore @@ -165,7 +165,7 @@ fails, with .I errno set to .BR EINTR . -.PP +.P If .I sem_op is less than zero, the process must have alter permission on the @@ -229,7 +229,7 @@ fails, with .I errno set to .BR EINTR . -.PP +.P On successful completion, the .I sempid value for each semaphore specified in the array pointed to by @@ -270,7 +270,7 @@ then .BR semtimedop () behaves exactly like .BR semop (). -.PP +.P Note that if .BR semtimedop () is interrupted by a signal, causing the call to fail with the error @@ -370,13 +370,13 @@ structures of a process aren't inherited by the child produced by but they are inherited across an .BR execve (2) system call. -.PP +.P .BR semop () is never automatically restarted after being interrupted by a signal handler, regardless of the setting of the .B SA_RESTART flag when establishing a signal handler. -.PP +.P A semaphore adjustment .RI ( semadj ) value is a per-process, per-semaphore integer that is the negated sum @@ -409,7 +409,7 @@ flag allows more than one process to share a list; see .BR clone (2) for details. -.PP +.P The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values for a semaphore can all be retrieved using appropriate .BR semctl (2) @@ -443,7 +443,7 @@ array. Maximum allowable value for .IR semval : implementation dependent (32767). -.PP +.P The implementation has no intrinsic limits for the adjust on exit maximum value .RB ( SEMAEM ), @@ -471,7 +471,7 @@ is specified for a semaphore operation). Linux adopts a third approach: decreasing the semaphore value as far as possible (i.e., to zero) and allowing process termination to proceed immediately. -.PP +.P In Linux 2.6.x, x <= 10, there is a bug that in some circumstances prevents a thread that is waiting for a semaphore value to become zero from being woken up when the value does actually become zero. @@ -485,7 +485,7 @@ The following code segment uses .BR semop () to atomically wait for the value of semaphore 0 to become zero, and then increment the semaphore value by one. -.PP +.P .in +4n .EX struct sembuf sops[2]; @@ -507,7 +507,7 @@ if (semop(semid, sops, 2) == \-1) { } .EE .in -.PP +.P A further example of the use of .BR semop () can be found in diff --git a/man2/send.2 b/man2/send.2 index 16c58b5..79abcc7 100644 --- a/man2/send.2 +++ b/man2/send.2 @@ -9,7 +9,7 @@ .\" Modified Oct 2003 by aeb .\" Modified 2004-07-01 by mtk .\" -.TH send 2 2023-03-30 "Linux man-pages 6.05.01" +.TH send 2 2024-02-18 "Linux man-pages 6.7" .SH NAME send, sendto, sendmsg \- send a message on a socket .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t send(int " sockfd ", const void " buf [. len "], size_t " len \ ", int " flags ); .BI "ssize_t sendto(int " sockfd ", const void " buf [. len "], size_t " len \ @@ -34,7 +34,7 @@ The system calls and .BR sendmsg () are used to transmit a message to another socket. -.PP +.P The .BR send () call may be used only when the socket is in a @@ -53,25 +53,25 @@ argument, is equivalent to .BR write (2). Also, the following call -.PP +.P .in +4n .EX send(sockfd, buf, len, flags); .EE .in -.PP +.P is equivalent to -.PP +.P .in +4n .EX sendto(sockfd, buf, len, flags, NULL, 0); .EE .in -.PP +.P The argument .I sockfd is the file descriptor of the sending socket. -.PP +.P If .BR sendto () is used on a connection-mode @@ -99,7 +99,7 @@ the address of the target is given by with .I msg.msg_namelen specifying its size. -.PP +.P For .BR send () and @@ -115,16 +115,16 @@ the message is pointed to by the elements of the array The .BR sendmsg () call also allows sending ancillary data (also known as control information). -.PP +.P If the message is too long to pass atomically through the underlying protocol, the error .B EMSGSIZE is returned, and the message is not transmitted. -.PP +.P No indication of failure to deliver is implicit in a .BR send (). Locally detected errors are indicated by a return value of \-1. -.PP +.P When the message does not fit into the send buffer of the socket, .BR send () normally blocks, unless the socket has been placed in nonblocking I/O @@ -184,7 +184,7 @@ is a per-call option, whereas is a setting on the open file description (see .BR open (2)), which will affect all threads in the calling process -and as well as other processes that hold file descriptors +as well as other processes that hold file descriptors referring to the same open file description. .TP .BR MSG_EOR " (since Linux 2.2)" @@ -273,7 +273,7 @@ The definition of the structure employed by .BR sendmsg () is as follows: -.PP +.P .in +4n .EX struct msghdr { @@ -287,7 +287,7 @@ struct msghdr { }; .EE .in -.PP +.P The .I msg_name field is used on an unconnected socket to specify the target @@ -297,14 +297,14 @@ It points to a buffer containing the address; the field should be set to the size of the address. For a connected socket, these fields should be specified as NULL and 0, respectively. -.PP +.P The .I msg_iov and .I msg_iovlen fields specify scatter-gather locations, as for .BR writev (2). -.PP +.P You may send control information (ancillary data) using the .I msg_control and @@ -320,7 +320,7 @@ socket domains, see .BR unix (7) and .BR ip (7). -.PP +.P The .I msg_flags field is ignored. @@ -458,13 +458,13 @@ but glibc currently types both as .\" as (at least with GCC) is int. .SH STANDARDS POSIX.1-2008. -.PP +.P .B MSG_CONFIRM is a Linux extension. .SH HISTORY 4.4BSD, SVr4, POSIX.1-2001. (first appeared in 4.2BSD). -.PP +.P POSIX.1-2001 describes only the .B MSG_OOB and diff --git a/man2/sendfile.2 b/man2/sendfile.2 index d9c3451..e013fa6 100644 --- a/man2/sendfile.2 +++ b/man2/sendfile.2 @@ -11,7 +11,7 @@ .\" .\" 2005-03-31 Martin Pool mmap() improvements .\" -.TH sendfile 2 2023-07-15 "Linux man-pages 6.05.01" +.TH sendfile 2 2023-12-21 "Linux man-pages 6.7" .SH NAME sendfile \- transfer data between file descriptors .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t sendfile(int" " out_fd" ", int" " in_fd" ", \ off_t *_Nullable " offset , .BI " size_t" " count" ); @@ -48,12 +48,12 @@ is more efficient than the combination of and .BR write (2), which would require transferring data to and from user space. -.PP +.P .I in_fd should be a file descriptor opened for reading and .I out_fd should be a descriptor opened for writing. -.PP +.P If .I offset is not NULL, then it points @@ -74,29 +74,38 @@ does not modify the file offset of otherwise the file offset is adjusted to reflect the number of bytes read from .IR in_fd . -.PP +.P If .I offset is NULL, then data will be read from .I in_fd starting at the file offset, and the file offset will be updated by the call. -.PP +.P .I count is the number of bytes to copy between the file descriptors. -.PP +.P The .I in_fd argument must correspond to a file which supports .BR mmap (2)-like operations (i.e., it cannot be a socket). -.PP +Except since Linux 5.12 +.\" commit b964bf53e540262f2d12672b3cca10842c0172e7 +and if +.I out_fd +is a pipe, in which case +.BR sendfile () +desugars to a +.BR splice (2) +and its restrictions apply. +.P Before Linux 2.6.33, .I out_fd must refer to a socket. Since Linux 2.6.33 it can be any file. -If it is a regular file, then +If it's seekable, then .BR sendfile () changes the file offset appropriately. .SH RETURN VALUE @@ -108,7 +117,7 @@ Note that a successful call to may write fewer bytes than requested; the caller should be prepared to retry the call if there were unsent bytes. See also NOTES. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -169,13 +178,13 @@ None. .SH HISTORY Linux 2.2, glibc 2.1. -.PP +.P In Linux 2.4 and earlier, .I out_fd could also refer to a regular file; this possibility went away in the Linux 2.6.x kernel series, but was restored in Linux 2.6.33. -.PP +.P The original Linux .BR sendfile () system call was not designed to handle large file offsets. @@ -193,7 +202,7 @@ will transfer at most 0x7ffff000 (2,147,479,552) bytes, returning the number of bytes actually transferred. .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 (This is true on both 32-bit and 64-bit systems.) -.PP +.P If you plan to use .BR sendfile () for sending files to a TCP socket, but need @@ -203,7 +212,7 @@ it useful to employ the option, described in .BR tcp (7), to minimize the number of packets and to tune performance. -.PP +.P Applications may wish to fall back to .BR read (2) and @@ -214,7 +223,7 @@ fails with .B EINVAL or .BR ENOSYS . -.PP +.P If .I out_fd refers to a socket or pipe with zero-copy support, callers must ensure the @@ -223,7 +232,7 @@ transferred portions of the file referred to by remain unmodified until the reader on the other end of .I out_fd has consumed the transferred data. -.PP +.P The Linux-specific .BR splice (2) call supports transferring data between arbitrary file descriptors diff --git a/man2/sendmmsg.2 b/man2/sendmmsg.2 index 283c4a5..64a4da0 100644 --- a/man2/sendmmsg.2 +++ b/man2/sendmmsg.2 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sendmmsg 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sendmmsg 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sendmmsg \- send multiple messages on a socket .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int sendmmsg(int " sockfd ", struct mmsghdr *" msgvec \ ", unsigned int " vlen "," .BI " int " flags ");" @@ -29,12 +29,12 @@ that allows the caller to transmit multiple messages on a socket using a single system call. (This has performance benefits for some applications.) .\" See commit 228e548e602061b08ee8e8966f567c12aa079682 -.PP +.P The .I sockfd argument is the file descriptor of the socket on which data is to be transmitted. -.PP +.P The .I msgvec argument is a pointer to an array of @@ -42,13 +42,13 @@ argument is a pointer to an array of structures. The size of this array is specified in .IR vlen . -.PP +.P The .I mmsghdr structure is defined in .I as: -.PP +.P .in +4n .EX struct mmsghdr { @@ -57,7 +57,7 @@ struct mmsghdr { }; .EE .in -.PP +.P The .I msg_hdr field is a @@ -71,13 +71,13 @@ field is used to return the number of bytes sent from the message in (i.e., the same as the return value from a single .BR sendmsg (2) call). -.PP +.P The .I flags argument contains flags ORed together. The flags are the same as for .BR sendmsg (2). -.PP +.P A blocking .BR sendmmsg () call blocks until @@ -87,7 +87,7 @@ A nonblocking call sends as many messages as possible (up to the limit specified by .IR vlen ) and returns immediately. -.PP +.P On return from .BR sendmmsg (), the @@ -109,7 +109,7 @@ if this is less than the caller can retry with a further .BR sendmmsg () call to send the remaining messages. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -163,7 +163,7 @@ and .I three in two distinct UDP datagrams using one system call. The contents of the first datagram originates from a pair of buffers. -.PP +.P .\" SRC BEGIN (sendmmsg.c) .EX #define _GNU_SOURCE diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2 index a7f561d..58e3959 100644 --- a/man2/set_mempolicy.2 +++ b/man2/set_mempolicy.2 @@ -7,7 +7,7 @@ .\" 2007-08-27, Lee Schermerhorn .\" more precise specification of behavior. .\" -.TH set_mempolicy 2 2023-07-16 "Linux man-pages 6.05.01" +.TH set_mempolicy 2 2023-10-31 "Linux man-pages 6.7" .SH NAME set_mempolicy \- set default NUMA memory policy for a thread and its children .SH LIBRARY @@ -16,7 +16,7 @@ NUMA (Non-Uniform Memory Access) policy library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "long set_mempolicy(int " mode ", const unsigned long *" nodemask , .BI " unsigned long " maxnode ); .fi @@ -30,12 +30,12 @@ to the values specified by the and .I maxnode arguments. -.PP +.P A NUMA machine has different memory controllers with different distances to specific CPUs. The memory policy defines from which node memory is allocated for the thread. -.PP +.P This system call defines the default policy for the thread. The thread policy governs allocation of pages in the process's address space outside of memory ranges @@ -56,7 +56,7 @@ The policy is applied only when a new page is allocated for the thread. For anonymous memory this is when the page is first touched by the thread. -.PP +.P The .I mode argument must specify one of @@ -73,7 +73,7 @@ require the caller to specify the node or nodes to which the mode applies, via the .I nodemask argument. -.PP +.P The .I mode argument may also include an optional @@ -113,7 +113,7 @@ Linux will not remap the when the process moves to a different cpuset context, nor when the set of nodes allowed by the process's current cpuset context changes. -.PP +.P .I nodemask points to a bit mask of node IDs that contains up to .I maxnode @@ -133,7 +133,7 @@ is zero, the .I nodemask argument is ignored. -.PP +.P Where a .I nodemask is required, it must contain at least one node that is on-line, @@ -154,7 +154,7 @@ the memory policy reverts to This effectively overrides the specified policy until the process's cpuset context includes one or more of the nodes specified by .IR nodemask . -.PP +.P The .I mode argument must include one of the following values: @@ -234,7 +234,7 @@ If the "local node" is not allowed by the process's current cpuset context, the kernel will try to allocate memory from other nodes. The kernel will allocate memory from the "local node" whenever it becomes allowed by the process's current cpuset context. -.PP +.P The thread memory policy is preserved across an .BR execve (2), and is inherited by child threads created using @@ -311,7 +311,7 @@ Memory policy is not remembered if the page is swapped out. When such a page is paged back in, it will use the policy of the thread or memory range that is in effect at the time the page is allocated. -.PP +.P For information on library support, see .BR numa (7). .SH SEE ALSO diff --git a/man2/set_thread_area.2 b/man2/set_thread_area.2 index b982112..389d65b 100644 --- a/man2/set_thread_area.2 +++ b/man2/set_thread_area.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH set_thread_area 2 2023-03-30 "Linux man-pages 6.05.01" +.TH set_thread_area 2 2023-10-31 "Linux man-pages 6.7" .SH NAME get_thread_area, set_thread_area \- manipulate thread-local storage information .SH LIBRARY @@ -14,25 +14,25 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .B #if defined __i386__ || defined __x86_64__ .BR "# include " " /* Definition of " "struct user_desc" " */" -.PP +.P .BI "int syscall(SYS_get_thread_area, struct user_desc *" u_info ); .BI "int syscall(SYS_set_thread_area, struct user_desc *" u_info ); -.PP +.P .B #elif defined __m68k__ -.PP +.P .B "int syscall(SYS_get_thread_area);" .BI "int syscall(SYS_set_thread_area, unsigned long " tp ); -.PP -.B #elif defined __mips__ -.PP +.P +.B #elif defined __mips__ || defined __csky__ +.P .BI "int syscall(SYS_set_thread_area, unsigned long " addr ); -.PP +.P .B #endif .fi -.PP +.P .IR Note : glibc provides no wrappers for these system calls, necessitating the use of @@ -42,31 +42,31 @@ These calls provide architecture-specific support for a thread-local storage implementation. At the moment, .BR set_thread_area () -is available on m68k, MIPS, and x86 (both 32-bit and 64-bit variants); +is available on m68k, MIPS, C-SKY, and x86 (both 32-bit and 64-bit variants); .BR get_thread_area () is available on m68k and x86. -.PP -On m68k and MIPS, +.P +On m68k, MIPS and C-SKY, .BR set_thread_area () allows storing an arbitrary pointer (provided in the .B tp argument on m68k and in the .B addr -argument on MIPS) +argument on MIPS and C-SKY) in the kernel data structure associated with the calling thread; this pointer can later be retrieved using .BR get_thread_area () (see also NOTES for information regarding obtaining the thread pointer on MIPS). -.PP +.P On x86, Linux dedicates three global descriptor table (GDT) entries for thread-local storage. For more information about the GDT, see the Intel Software Developer's Manual or the AMD Architecture Programming Manual. -.PP +.P Both of these system calls take an argument that is a pointer to a structure of the following type: -.PP +.P .in +4n .EX struct user_desc { @@ -85,16 +85,16 @@ struct user_desc { }; .EE .in -.PP +.P .BR get_thread_area () reads the GDT entry indicated by .I u_info\->entry_number and fills in the rest of the fields in .IR u_info . -.PP +.P .BR set_thread_area () sets a TLS entry in the GDT. -.PP +.P The TLS array entry set by .BR set_thread_area () corresponds to the value of @@ -105,7 +105,7 @@ If this value is in bounds, writes the TLS descriptor pointed to by .I u_info into the thread's TLS array. -.PP +.P When .BR set_thread_area () is passed an @@ -116,7 +116,7 @@ If finds a free TLS entry, the value of .I u_info\->entry_number is set upon return to show which entry was changed. -.PP +.P A .I user_desc is considered "empty" if @@ -128,7 +128,7 @@ If an "empty" descriptor is passed to .BR set_thread_area (), the corresponding TLS entry will be cleared. See BUGS for additional details. -.PP +.P Since Linux 3.19, .BR set_thread_area () cannot be used to write non-present segments, 16-bit segments, or code @@ -138,8 +138,8 @@ On x86, these system calls return 0 on success, and \-1 on failure, with .I errno set to indicate the error. -.PP -On MIPS and m68k, +.P +On C-SKY, MIPS and m68k, .BR set_thread_area () always returns 0. On m68k, @@ -175,7 +175,7 @@ Linux 2.5.29. Linux 2.5.32. .SH NOTES These system calls are generally intended for use only by threading libraries. -.PP +.P .BR arch_prctl (2) can interfere with .BR set_thread_area () @@ -186,16 +186,16 @@ for more details. This is not normally a problem, as .BR arch_prctl (2) is normally used only by 64-bit programs. -.PP +.P On MIPS, the current value of the thread area pointer can be obtained using the instruction: -.PP +.P .in +4n .EX rdhwr dest, $29 .EE .in -.PP +.P This instruction traps and is handled by kernel. .SH BUGS On 64-bit kernels before Linux 3.19, @@ -219,7 +219,7 @@ consisting entirely of zeros except for .I entry_number will also be interpreted as a request to clear a TLS entry, but this behaved differently on older kernels. -.PP +.P Prior to Linux 3.19, the DS and ES segment registers must not reference TLS entries. .SH SEE ALSO diff --git a/man2/set_tid_address.2 b/man2/set_tid_address.2 index 180b909..d174105 100644 --- a/man2/set_tid_address.2 +++ b/man2/set_tid_address.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH set_tid_address 2 2023-03-30 "Linux man-pages 6.05.01" +.TH set_tid_address 2 2023-10-31 "Linux man-pages 6.7" .SH NAME set_tid_address \- set pointer to thread ID .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "pid_t syscall(SYS_set_tid_address, int *" tidptr ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR set_tid_address (), @@ -54,14 +54,14 @@ flag, is set to the value passed in the .I ctid argument of that system call. -.PP +.P The system call .BR set_tid_address () sets the .I clear_child_tid value for the calling thread to .IR tidptr . -.PP +.P When a thread whose .I clear_child_tid is not NULL terminates, then, @@ -69,13 +69,13 @@ if the thread is sharing memory with other threads, then 0 is written at the address specified in .I clear_child_tid and the kernel performs the following operation: -.PP +.P .in +4n .EX futex(clear_child_tid, FUTEX_WAKE, 1, NULL, NULL, 0); .EE .in -.PP +.P The effect of this operation is to wake a single thread that is performing a futex wait on the memory location. Errors from the futex wake operation are ignored. @@ -89,7 +89,7 @@ always succeeds. Linux. .SH HISTORY Linux 2.5.48. -.PP +.P Details as given here are valid since Linux 2.5.49. .SH SEE ALSO .BR clone (2), diff --git a/man2/seteuid.2 b/man2/seteuid.2 index 0c47f6a..c1cae7c 100644 --- a/man2/seteuid.2 +++ b/man2/seteuid.2 @@ -6,7 +6,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH seteuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH seteuid 2 2024-02-11 "Linux man-pages 6.7" .SH NAME seteuid, setegid \- set effective user or group ID .SH LIBRARY @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int seteuid(uid_t " euid ); .BI "int setegid(gid_t " egid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR seteuid (), .BR setegid (): .nf @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see sets the effective user ID of the calling process. Unprivileged processes may only set the effective user ID to the real user ID, the effective user ID or the saved set-user-ID. -.PP +.P Precisely the same holds for .BR setegid () with "group" instead of "user". @@ -50,7 +50,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR seteuid () @@ -86,7 +86,7 @@ saved set-user-ID (saved set-group-ID) is possible since Linux 1.1.37 (1.1.38). On an arbitrary system one should check .BR _POSIX_SAVED_IDS . -.PP +.P Under glibc 2.0, .BI seteuid( euid ) is equivalent to @@ -102,7 +102,7 @@ with the difference that the change in implementation from to .BI setresgid(\-1, " egid" ", \-1)" occurred in glibc 2.2 or 2.3 (depending on the hardware architecture). -.PP +.P According to POSIX.1, .BR seteuid () .RB ( setegid ()) @@ -117,9 +117,9 @@ On Linux, and .BR setegid () are implemented as library functions that call, respectively, -.BR setreuid (2) +.BR setresuid (2) and -.BR setregid (2). +.BR setresgid (2). .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 index 43b5507..8cb8403 100644 --- a/man2/setfsgid.2 +++ b/man2/setfsgid.2 @@ -9,7 +9,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH setfsgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setfsgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setfsgid \- set group identity used for filesystem checks .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int setfsgid(gid_t " fsgid ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ for permissions checking when accessing filesystem objects, while the effective group ID is used for some other kinds of permissions checks (see .BR credentials (7)). -.PP +.P Normally, the value of the process's filesystem group ID is the same as the value of its effective group ID. This is so, because whenever a process's effective group ID is changed, @@ -39,7 +39,7 @@ from its effective group ID by using .BR setfsgid () to change its filesystem group ID to the value given in .IR fsgid . -.PP +.P .BR setfsgid () will succeed only if the caller is the superuser or if .I fsgid @@ -75,7 +75,7 @@ for a discussion of why the use of both and .BR setfsgid () is nowadays unneeded. -.PP +.P The original Linux .BR setfsgid () system call supported only 16-bit group IDs. diff --git a/man2/setfsuid.2 b/man2/setfsuid.2 index 56964b0..cd55bc3 100644 --- a/man2/setfsuid.2 +++ b/man2/setfsuid.2 @@ -9,7 +9,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH setfsuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setfsuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setfsuid \- set user identity used for filesystem checks .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int setfsuid(uid_t " fsuid ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ for permissions checking when accessing filesystem objects, while the effective user ID is used for various other kinds of permissions checks (see .BR credentials (7)). -.PP +.P Normally, the value of the process's filesystem user ID is the same as the value of its effective user ID. This is so, because whenever a process's effective user ID is changed, @@ -39,7 +39,7 @@ from its effective user ID by using .BR setfsuid () to change its filesystem user ID to the value given in .IR fsuid . -.PP +.P Explicit calls to .BR setfsuid () and @@ -50,7 +50,7 @@ corresponding change in the real and effective user and group IDs. A change in the normal user IDs for a program such as the NFS server is (was) a security hole that can expose it to unwanted signals. (However, this issue is historical; see below.) -.PP +.P .BR setfsuid () will succeed only if the caller is the superuser or if .I fsuid @@ -65,7 +65,7 @@ Linux. Linux 1.2. .\" Linux 1.1.44 .\" and in libc since libc 4.7.6. -.PP +.P At the time when this system call was introduced, one process could send a signal to another process with the same effective user ID. This meant that if a privileged process changed its effective user ID @@ -84,7 +84,7 @@ Thus, is nowadays unneeded and should be avoided in new applications (likewise for .BR setfsgid (2)). -.PP +.P The original Linux .BR setfsuid () system call supported only 16-bit user IDs. diff --git a/man2/setgid.2 b/man2/setgid.2 index f618887..cb65798 100644 --- a/man2/setgid.2 +++ b/man2/setgid.2 @@ -7,7 +7,7 @@ .\" Modified 1997-01-31 by Eric S. Raymond .\" Modified 2002-03-09 by aeb .\" -.TH setgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setgid \- set group identity .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setgid(gid_t " gid ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ If the calling process is privileged (more precisely: has the .B CAP_SETGID capability in its user namespace), the real GID and saved set-group-ID are also set. -.PP +.P Under Linux, .BR setgid () is implemented like the POSIX version with the @@ -73,7 +73,7 @@ For details, see POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. -.PP +.P The original Linux .BR setgid () system call supported only 16-bit group IDs. diff --git a/man2/setns.2 b/man2/setns.2 index 13565de..5bd3385 100644 --- a/man2/setns.2 +++ b/man2/setns.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH setns 2 2023-05-03 "Linux man-pages 6.05.01" +.TH setns 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setns \- reassociate thread with a namespace .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int setns(int " fd ", int " nstype ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ directory (or a bind mount to such a link); .IP \[bu] a PID file descriptor (see .BR pidfd_open (2)). -.PP +.P The .I nstype argument is interpreted differently in each case. @@ -49,7 +49,7 @@ argument. In this usage, each call to .BR setns () changes just one of the caller's namespace memberships. -.PP +.P The .I nstype argument specifies which type of namespace @@ -93,7 +93,7 @@ must refer to a user namespace. .BR CLONE_NEWUTS " (since Linux 3.0)" .I fd must refer to a UTS namespace. -.PP +.P Specifying .I nstype as 0 suffices if the caller knows (or does not care) @@ -121,7 +121,7 @@ In this usage, atomically moves the calling thread into one or more of the same namespaces as the thread referred to by .IR fd . -.PP +.P The .I nstype argument is a bit mask specified by ORing together @@ -133,11 +133,11 @@ The caller is moved into each of the target thread's namespaces that is specified in .IR nstype ; the caller's memberships in the remaining namespaces are left unchanged. -.PP +.P For example, the following code would move the caller into the same user, network, and UTS namespaces as PID 1234, but would leave the caller's other namespace memberships unchanged: -.PP +.P .in +4n .EX int fd = pidfd_open(1234, 0); @@ -312,7 +312,7 @@ For further information on the .IR /proc/ pid /ns/ magic links, see .BR namespaces (7). -.PP +.P Not all of the attributes that can be shared when a new thread is created using .BR clone (2) @@ -327,7 +327,7 @@ The remaining arguments specify a command and its arguments. The program opens the namespace file, joins that namespace using .BR setns (), and executes the specified command inside that namespace. -.PP +.P The following shell session demonstrates the use of this program (compiled as a binary named .IR ns_exec ) @@ -337,7 +337,7 @@ example program in the .BR clone (2) man page (complied as a binary named .IR newuts ). -.PP +.P We begin by executing the example program in .BR clone (2) in the background. @@ -345,7 +345,7 @@ That program creates a child in a separate UTS namespace. The child changes the hostname in its namespace, and then both processes display the hostnames in their UTS namespaces, so that we can see that they are different. -.PP +.P .in +4n .EX $ \fBsu\fP # Need privilege for namespace operations @@ -359,12 +359,12 @@ uts.nodename in parent: antero antero .EE .in -.PP +.P We then run the program shown below, using it to execute a shell. Inside that shell, we verify that the hostname is the one set by the child created by the first program: -.PP +.P .in +4n .EX # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP diff --git a/man2/setpgid.2 b/man2/setpgid.2 index 2d8bc96..b3983c4 100644 --- a/man2/setpgid.2 +++ b/man2/setpgid.2 @@ -17,7 +17,7 @@ .\" 2007-07-25, mtk, fairly substantial rewrites and rearrangements .\" of text. .\" -.TH setpgid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setpgid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setpgid, getpgid, setpgrp, getpgrp \- set/get process group .SH LIBRARY @@ -26,29 +26,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setpgid(pid_t " pid ", pid_t " pgid ); .BI "pid_t getpgid(pid_t " pid ); -.PP +.P .BR "pid_t getpgrp(void);" " /* POSIX.1 version */" .BI "[[deprecated]] pid_t getpgrp(pid_t " pid ");\fR /* BSD version */" -.PP +.P .BR "int setpgrp(void);" " /* System V version */" .BI "[[deprecated]] int setpgrp(pid_t " pid ", pid_t " pgid ");\fR /* BSD version */" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpgid (): .nf _XOPEN_SOURCE >= 500 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L .fi -.PP +.P .BR setpgrp "() (POSIX.1):" .nf _XOPEN_SOURCE >= 500 @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE .fi -.PP +.P .BR setpgrp "() (BSD)," .BR getpgrp "() (BSD):" .nf @@ -74,7 +74,7 @@ The preferred, POSIX.1-specified ways of doing this are: for retrieving the calling process's PGID; and .BR setpgid (), for setting a process's PGID. -.PP +.P .BR setpgid () sets the PGID of the process specified by .I pid @@ -99,12 +99,12 @@ and In this case, the \fIpgid\fP specifies an existing process group to be joined and the session ID of that group must match the session ID of the joining process. -.PP +.P The POSIX.1 version of .BR getpgrp (), which takes no arguments, returns the PGID of the calling process. -.PP +.P .BR getpgid () returns the PGID of the process specified by .IR pid . @@ -115,12 +115,12 @@ is zero, the process ID of the calling process is used. necessary, and the POSIX.1 .BR getpgrp () is preferred for that task.) -.PP +.P The System\ V-style .BR setpgrp (), which takes no arguments, is equivalent to .IR "setpgid(0,\ 0)" . -.PP +.P The BSD-specific .BR setpgrp () call, which takes arguments @@ -128,13 +128,13 @@ call, which takes arguments and .IR pgid , is a wrapper function that calls -.PP +.P .in +4n .EX setpgid(pid, pgid) .EE .in -.PP +.P .\" The true BSD setpgrp() system call differs in allowing the PGID .\" to be set to arbitrary values, rather than being restricted to .\" PGIDs in the same session. @@ -145,19 +145,19 @@ function is no longer exposed by calls should be replaced with the .BR setpgid () call shown above. -.PP +.P The BSD-specific .BR getpgrp () call, which takes a single .I pid argument, is a wrapper function that calls -.PP +.P .in +4n .EX getpgid(pid) .EE .in -.PP +.P Since glibc 2.19, the BSD-specific .BR getpgrp () function is no longer exposed by @@ -177,11 +177,11 @@ return zero. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P The POSIX.1 .BR getpgrp () always returns the PGID of the caller. -.PP +.P .BR getpgid (), and the BSD-specific .BR getpgrp () @@ -266,12 +266,12 @@ A child created via inherits its parent's process group ID. The PGID is preserved across an .BR execve (2). -.PP +.P Each process group is a member of a session and each process is a member of the session of which its process group is a member. (See .BR credentials (7).) -.PP +.P A session can have a controlling terminal. At any time, one (and only one) of the process groups in the session can be the foreground process group @@ -298,7 +298,7 @@ and .BR tcsetpgrp (3) functions are used to get/set the foreground process group of the controlling terminal. -.PP +.P The .BR setpgid () and @@ -306,7 +306,7 @@ and calls are used by programs such as .BR bash (1) to create process groups in order to implement shell job control. -.PP +.P If the termination of a process causes a process group to become orphaned, and if any member of the newly orphaned process group is stopped, then a .B SIGHUP diff --git a/man2/setresuid.2 b/man2/setresuid.2 index 97f0af9..9c6499b 100644 --- a/man2/setresuid.2 +++ b/man2/setresuid.2 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified, 2003-05-26, Michael Kerrisk, -.TH setresuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setresuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setresuid, setresgid \- set real, effective, and saved user or group ID .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid ); .BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid ); .fi @@ -22,22 +22,22 @@ Standard C library .BR setresuid () sets the real user ID, the effective user ID, and the saved set-user-ID of the calling process. -.PP +.P An unprivileged process may change its real UID, effective UID, and saved set-user-ID, each to one of: the current real UID, the current effective UID, or the current saved set-user-ID. -.PP +.P A privileged process (on Linux, one having the \fBCAP_SETUID\fP capability) may set its real UID, effective UID, and saved set-user-ID to arbitrary values. -.PP +.P If one of the arguments equals \-1, the corresponding value is not changed. -.PP +.P Regardless of what changes are made to the real UID, effective UID, and saved set-user-ID, the filesystem UID is always set to the same value as the (possibly new) effective UID. -.PP +.P Completely analogously, .BR setresgid () sets the real GID, effective GID, and saved set-group-ID @@ -49,7 +49,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR setresuid () @@ -119,7 +119,7 @@ None. Linux 2.1.44, glibc 2.3.2. HP-UX, FreeBSD. -.PP +.P The original Linux .BR setresuid () and diff --git a/man2/setreuid.2 b/man2/setreuid.2 index 121deb4..e887619 100644 --- a/man2/setreuid.2 +++ b/man2/setreuid.2 @@ -15,7 +15,7 @@ .\" 2004-07-04 by aeb .\" 2004-05-27 by Michael Kerrisk .\" -.TH setreuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setreuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setreuid, setregid \- set real and/or effective user or group ID .SH LIBRARY @@ -24,16 +24,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setreuid(uid_t " ruid ", uid_t " euid ); .BI "int setregid(gid_t " rgid ", gid_t " egid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setreuid (), .BR setregid (): .nf @@ -45,22 +45,22 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION .BR setreuid () sets real and effective user IDs of the calling process. -.PP +.P Supplying a value of \-1 for either the real or effective user ID forces the system to leave that ID unchanged. -.PP +.P Unprivileged processes may only set the effective user ID to the real user ID, the effective user ID, or the saved set-user-ID. -.PP +.P Unprivileged users may only set the real user ID to the real user ID or the effective user ID. -.PP +.P If the real user ID is set (i.e., .I ruid is not \-1) or the effective user ID is set to a value not equal to the previous real user ID, the saved set-user-ID will be set to the new effective user ID. -.PP +.P Completely analogously, .BR setregid () sets real and effective group ID's of the calling process, @@ -70,7 +70,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR setreuid () @@ -137,18 +137,18 @@ and the effective group ID can be changed to the value of the real group ID or the saved set-group-ID. The precise details of what ID changes are permitted vary across implementations. -.PP +.P POSIX.1 makes no specification about the effect of these calls on the saved set-user-ID and saved set-group-ID. .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD (first appeared in 4.2BSD). -.PP +.P Setting the effective user (group) ID to the saved set-user-ID (saved set-group-ID) is possible since Linux 1.1.37 (1.1.38). -.PP +.P The original Linux .BR setreuid () and diff --git a/man2/setsid.2 b/man2/setsid.2 index ae04028..a437a1b 100644 --- a/man2/setsid.2 +++ b/man2/setsid.2 @@ -9,7 +9,7 @@ .\" tiny changes from a man page by Charles Livingston). .\" Modified Sun Jul 21 14:45:46 1996 .\" -.TH setsid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setsid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setsid \- creates a session and sets the process group ID .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B pid_t setsid(void); .fi .SH DESCRIPTION @@ -30,10 +30,10 @@ The calling process is the leader of the new session The calling process also becomes the process group leader of a new process group in the session (i.e., its process group ID is made the same as its process ID). -.PP +.P The calling process will be the only process in the new process group and in the new session. -.PP +.P Initially, the new session has no controlling terminal. For details of how a session acquires a controlling terminal, see .BR credentials (7). @@ -61,7 +61,7 @@ A child created via inherits its parent's session ID. The session ID is preserved across an .BR execve (2). -.PP +.P A process group leader is a process whose process group ID equals its PID. Disallowing a process group leader from calling .BR setsid () @@ -78,14 +78,14 @@ and have the parent .BR _exit (2), while the child (which by definition can't be a process group leader) calls .BR setsid (). -.PP +.P If a session has a controlling terminal, and the .B CLOCAL flag for that terminal is not set, and a terminal hangup occurs, then the session leader is sent a .B SIGHUP signal. -.PP +.P If a process that is a session leader terminates, then a .B SIGHUP signal is sent to each process in the foreground diff --git a/man2/setuid.2 b/man2/setuid.2 index 80284d6..e9a283e 100644 --- a/man2/setuid.2 +++ b/man2/setuid.2 @@ -8,7 +8,7 @@ .\" , aeb 970616. .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements -.TH setuid 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setuid 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setuid \- set user identity .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setuid(uid_t " uid ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ If the calling process is privileged .B CAP_SETUID capability in its user namespace), the real UID and saved set-user-ID are also set. -.PP +.P Under Linux, .BR setuid () is implemented like the POSIX version with the @@ -37,7 +37,7 @@ feature. This allows a set-user-ID (other than root) program to drop all of its user privileges, do some un-privileged work, and then reengage the original effective user ID in a secure manner. -.PP +.P If the user is root or the program is set-user-ID-root, special care must be taken: .BR setuid () @@ -46,7 +46,7 @@ the superuser, all process-related user ID's are set to .IR uid . After this has occurred, it is impossible for the program to regain root privileges. -.PP +.P Thus, a set-user-ID-root program wishing to temporarily drop root privileges, assume the identity of an unprivileged user, and then regain root privileges afterward cannot use @@ -58,7 +58,7 @@ On success, zero is returned. On error, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P .IR Note : there are cases where .BR setuid () @@ -119,11 +119,11 @@ For details, see POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. -.PP +.P Not quite compatible with the 4.4BSD call, which sets all of the real, saved, and effective user IDs. .\" SVr4 documents an additional EINVAL error condition. -.PP +.P The original Linux .BR setuid () system call supported only 16-bit user IDs. @@ -141,7 +141,7 @@ The call also sets the filesystem user ID of the calling process. See .BR setfsuid (2). -.PP +.P If .I uid is different from the old effective UID, the process will diff --git a/man2/setup.2 b/man2/setup.2 index 61a6002..c2d0b52 100644 --- a/man2/setup.2 +++ b/man2/setup.2 @@ -11,7 +11,7 @@ .\" Modified Wed Nov 6 04:05:28 1996 by Eric S. Raymond .\" Modified Sat Jan 29 01:08:23 2000 by aeb .\" -.TH setup 2 2023-03-30 "Linux man-pages 6.05.01" +.TH setup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setup \- setup devices and filesystems, mount root filesystem .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B [[deprecated]] int setup(void); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ is called once from within .IR linux/init/main.c . It calls initialization functions for devices and filesystems configured into the kernel and then mounts the root filesystem. -.PP +.P No user process may call .BR setup (). Any user process, even a process with superuser permission, @@ -46,7 +46,7 @@ Always, for a user process. Linux. .SH VERSIONS Removed in Linux 2.1.121. -.PP +.P The calling sequence varied: at some times .BR setup () has had a single argument diff --git a/man2/setxattr.2 b/man2/setxattr.2 index cc2a6b0..636462e 100644 --- a/man2/setxattr.2 +++ b/man2/setxattr.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH setxattr 2 2023-07-28 "Linux man-pages 6.05.01" +.TH setxattr 2 2023-10-31 "Linux man-pages 6.7" .SH NAME setxattr, lsetxattr, fsetxattr \- set an extended attribute value .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setxattr(const char *" path ", const char *" name , .BI " const void " value [. size "], size_t " size ", int " flags ); .BI "int lsetxattr(const char *" path ", const char *" name , @@ -30,7 +30,7 @@ with all inodes in the system (i.e., the data). A complete overview of extended attributes concepts can be found in .BR xattr (7). -.PP +.P .BR setxattr () sets the .I value @@ -44,13 +44,13 @@ The argument specifies the size (in bytes) of .IR value ; a zero-length value is permitted. -.PP +.P .BR lsetxattr () is identical to .BR setxattr (), except in the case of a symbolic link, where the extended attribute is set on the link itself, not the file that it refers to. -.PP +.P .BR fsetxattr () is identical to .BR setxattr (), @@ -60,7 +60,7 @@ only the extended attribute is set on the open file referred to by .BR open (2)) in place of .IR path . -.PP +.P An extended attribute name is a null-terminated string. The .I name @@ -70,7 +70,7 @@ The .I value of an extended attribute is a chunk of arbitrary textual or binary data of specified length. -.PP +.P By default (i.e., .I flags @@ -125,7 +125,7 @@ Extended attributes are not supported by the filesystem, or are disabled, The file is marked immutable or append-only. (See .BR ioctl_iflags (2).) -.PP +.P In addition, the errors documented in .BR stat (2) can also occur. diff --git a/man2/sgetmask.2 b/man2/sgetmask.2 index d0c99a2..e1701c2 100644 --- a/man2/sgetmask.2 +++ b/man2/sgetmask.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sgetmask 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sgetmask 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sgetmask, ssetmask \- manipulation of signal mask (obsolete) .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .B [[deprecated]] long syscall(SYS_sgetmask, void); .BI "[[deprecated]] long syscall(SYS_ssetmask, long " newmask ); .fi @@ -22,15 +22,15 @@ These system calls are obsolete. use .BR sigprocmask (2) instead. -.PP +.P .BR sgetmask () returns the signal mask of the calling process. -.PP +.P .BR ssetmask () sets the signal mask of the calling process to the value given in .IR newmask . The previous signal mask is returned. -.PP +.P The signal masks dealt with by these two system calls are plain bit masks (unlike the .I sigset_t @@ -58,9 +58,9 @@ option. .SH NOTES These system calls are unaware of signal numbers greater than 31 (i.e., real-time signals). -.PP +.P These system calls do not exist on x86-64. -.PP +.P It is not possible to block .B SIGSTOP or diff --git a/man2/shmctl.2 b/man2/shmctl.2 index 4bfb2c5..5d5176a 100644 --- a/man2/shmctl.2 +++ b/man2/shmctl.2 @@ -24,7 +24,7 @@ .\" 2005-08-02, mtk: Added IPC_INFO, SHM_INFO, SHM_STAT descriptions. .\" 2018-03-20, dbueso: Added SHM_STAT_ANY description. .\" -.TH shmctl 2 2023-03-30 "Linux man-pages 6.05.01" +.TH shmctl 2 2024-03-03 "Linux man-pages 6.7" .SH NAME shmctl \- System V shared memory control .SH LIBRARY @@ -33,21 +33,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int shmctl(int " shmid ", int " cmd ", struct shmid_ds *" buf ); +.P +.BI "int shmctl(int " shmid ", int " op ", struct shmid_ds *" buf ); .fi .SH DESCRIPTION .BR shmctl () performs the control operation specified by -.I cmd +.I op on the System\ V shared memory segment whose identifier is given in .IR shmid . -.PP +.P The .I buf argument is a pointer to a \fIshmid_ds\fP structure, defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct shmid_ds { @@ -64,7 +64,7 @@ struct shmid_ds { }; .EE .in -.PP +.P The fields of the .I shmid_ds structure are as follows: @@ -106,13 +106,13 @@ system call on this segment. .TP .I shm_nattch Number of processes that have this segment attached. -.PP +.P The .I ipc_perm structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): -.PP +.P .in +4n .EX struct ipc_perm { @@ -127,7 +127,7 @@ struct ipc_perm { }; .EE .in -.PP +.P The least significant 9 bits of the .I mode field of the @@ -143,7 +143,7 @@ l l. 0004 Read by others 0002 Write by others .TE -.PP +.P Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. (It is not necessary to have execute permission on a segment in order to perform a @@ -151,9 +151,9 @@ in order to perform a call with the .B SHM_EXEC flag.) -.PP +.P Valid values for -.I cmd +.I op are: .TP .B IPC_STAT @@ -307,9 +307,11 @@ is not checked for read access for meaning that any user can employ this operation (just as any user may read .I /proc/sysvipc/shm to obtain the same information). -.PP +.P The caller can prevent or allow swapping of a shared -memory segment with the following \fIcmd\fP values: +memory segment with the following +.I op +values: .TP .BR SHM_LOCK " (Linux-specific)" Prevent swapping of the shared memory segment. @@ -325,7 +327,7 @@ will be set. .TP .BR SHM_UNLOCK " (Linux-specific)" Unlock the segment, allowing it to be swapped out. -.PP +.P Before Linux 2.6.10, only a privileged process could employ .B SHM_LOCK @@ -363,7 +365,7 @@ operation returns the identifier of the shared memory segment whose index was given in .IR shmid . Other operations return 0 on success. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -379,7 +381,7 @@ capability in the user namespace that governs its IPC namespace. .TP .B EFAULT The argument -.I cmd +.I op has value .B IPC_SET or @@ -392,8 +394,10 @@ isn't accessible. \fIshmid\fP points to a removed identifier. .TP .B EINVAL -\fIshmid\fP is not a valid identifier, or \fIcmd\fP -is not a valid command. +.I shmid +is not a valid identifier, or +.I op +is not a valid operation. Or: for a .B SHM_STAT or @@ -456,7 +460,7 @@ POSIX.1-2001, SVr4. .\" SVr4 documents additional error conditions EINVAL, .\" ENOENT, ENOSPC, ENOMEM, EEXIST. Neither SVr4 nor SVID documents .\" an EIDRM error condition. -.PP +.P Various fields in a \fIstruct shmid_ds\fP were typed as .I short under Linux 2.2 @@ -468,7 +472,7 @@ a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by an .B IPC_64 flag in -.IR cmd .) +.IR op .) .SH NOTES The .BR IPC_INFO , diff --git a/man2/shmget.2 b/man2/shmget.2 index 074e83e..685963a 100644 --- a/man2/shmget.2 +++ b/man2/shmget.2 @@ -15,7 +15,7 @@ .\" Language and formatting clean-ups .\" Added notes on /proc files .\" -.TH shmget 2 2023-03-30 "Linux man-pages 6.05.01" +.TH shmget 2 2023-10-31 "Linux man-pages 6.7" .SH NAME shmget \- allocates a System V shared memory segment .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int shmget(key_t " key ", size_t " size ", int " shmflg ); .fi .SH DESCRIPTION @@ -40,7 +40,7 @@ is zero and does not have the value .BR IPC_PRIVATE ), or to create a new set. -.PP +.P A new shared memory segment, with size equal to the value of .I size rounded up to a multiple of @@ -59,7 +59,7 @@ exists, and .B IPC_CREAT is specified in .IR shmflg . -.PP +.P If .I shmflg specifies both @@ -78,7 +78,7 @@ set to .B O_CREAT | O_EXCL for .BR open (2).) -.PP +.P The value .I shmflg is composed of: @@ -102,7 +102,9 @@ See the Linux kernel source file .I Documentation/admin\-guide/mm/hugetlbpage.rst for further information. .TP -.BR SHM_HUGE_2MB ", " SHM_HUGE_1GB " (since Linux 3.8)" +.B SHM_HUGE_2MB +.TQ +.BR SHM_HUGE_1GB " (since Linux 3.8)" .\" See https://lwn.net/Articles/533499/ Used in conjunction with .B SHM_HUGETLB @@ -143,7 +145,7 @@ in .BR proc (5). .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also .\" specified. -.PP +.P In addition to the above flags, the least significant 9 bits of .I shmflg specify the permissions granted to the owner, group, and others. @@ -153,7 +155,7 @@ meaning, as the argument of .BR open (2). Presently, execute permissions are not used by the system. -.PP +.P When a new shared memory segment is created, its contents are initialized to zero values, and its associated data structure, @@ -190,7 +192,7 @@ are set to 0. .IP \[bu] .I shm_ctime is set to the current time. -.PP +.P If the shared memory segment already exists, the permissions are verified, and a check is made to see if it is marked for destruction. .SH RETURN VALUE @@ -263,7 +265,7 @@ in .BR proc (5). .SH STANDARDS POSIX.1-2008. -.PP +.P .B SHM_HUGETLB and .B SHM_NORESERVE @@ -380,7 +382,7 @@ On Linux, this limit can be read and modified via .\" Kernels between Linux 2.4.x and Linux 2.6.8 had an off-by-one error .\" that meant that we could create one more segment than SHMMNI -- MTK .\" This /proc file is not available in Linux 2.2 and earlier -- MTK -.PP +.P The implementation has no specific limits for the per-process maximum number of shared memory segments .RB ( SHMSEG ). diff --git a/man2/shmop.2 b/man2/shmop.2 index 09168ec..a763420 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -17,7 +17,7 @@ .\" Changed wording and placement of sentence regarding attachment .\" of segments marked for destruction .\" -.TH SHMOP 2 2023-05-03 "Linux man-pages 6.05.01" +.TH SHMOP 2 2023-10-31 "Linux man-pages 6.7" .SH NAME shmat, shmdt \- System V shared memory operations .SH LIBRARY @@ -26,7 +26,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *shmat(int " shmid ", const void *_Nullable " shmaddr ", \ int " shmflg ); .BI "int shmdt(const void *" shmaddr ); @@ -62,7 +62,7 @@ rounded down to the nearest multiple of Otherwise, .I shmaddr must be a page-aligned address at which the attach occurs. -.PP +.P In addition to .BR SHM_RND , the following flags may be specified in the @@ -93,14 +93,14 @@ error would result if a mapping already exists in this address range.) In this case, .I shmaddr must not be NULL. -.PP +.P The .BR brk (2) value of the calling process is not altered by the attach. The segment will automatically be detached at process exit. The same segment may be attached as a read and as a read-write one, and more than once, in the process's address space. -.PP +.P A successful .BR shmat () call updates the members of the @@ -129,7 +129,7 @@ attached with equal to the value returned by the attaching .BR shmat () call. -.PP +.P On a successful .BR shmdt () call, the system updates the members of the @@ -154,7 +154,7 @@ returns the address of the attached shared memory segment; on error, is returned, and .I errno is set to indicate the error. -.PP +.P On success, .BR shmdt () returns 0; on error \-1 is returned, and @@ -189,7 +189,7 @@ was NULL. .TP .B ENOMEM Could not allocate memory for the descriptor or for the page tables. -.PP +.P .BR shmdt () can fail with one of the following errors: .TP @@ -205,7 +205,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 documents an additional error condition EMFILE. -.PP +.P In SVID 3 (or perhaps earlier), the type of the \fIshmaddr\fP argument was changed from .I "char\ *" @@ -221,15 +221,15 @@ into After a .BR fork (2), the child inherits the attached shared memory segments. -.PP +.P After an .BR execve (2), all attached shared memory segments are detached from the process. -.PP +.P Upon .BR _exit (2), all attached shared memory segments are detached from the process. -.PP +.P Using .BR shmat () with @@ -241,12 +241,12 @@ may be attached at different addresses in different processes. Therefore, any pointers maintained within the shared memory must be made relative (typically to the starting address of the segment), rather than absolute. -.PP +.P On Linux, it is possible to attach a shared memory segment even if it is already marked to be deleted. However, POSIX.1 does not specify this behavior and many other implementations do not support it. -.PP +.P The following system parameter affects .BR shmat (): .TP @@ -264,7 +264,7 @@ is normally some multiple of the system page size. (On many Linux architectures, .B SHMLBA is the same as the system page size.) -.PP +.P The implementation places no intrinsic per-process limit on the number of shared memory segments .RB ( SHMSEG ). @@ -272,37 +272,37 @@ number of shared memory segments The two programs shown below exchange a string using a shared memory segment. Further details about the programs are given below. First, we show a shell session demonstrating their use. -.PP +.P In one terminal window, we run the "reader" program, which creates a System V shared memory segment and a System V semaphore set. The program prints out the IDs of the created objects, and then waits for the semaphore to change value. -.PP +.P .in +4n .EX $ \fB./svshm_string_read\fP shmid = 1114194; semid = 15 .EE .in -.PP +.P In another terminal window, we run the "writer" program. The "writer" program takes three command-line arguments: the IDs of the shared memory segment and semaphore set created by the "reader", and a string. It attaches the existing shared memory segment, copies the string to the shared memory, and modifies the semaphore value. -.PP +.P .in +4n .EX $ \fB./svshm_string_write 1114194 15 \[aq]Hello, world\[aq]\fP .EE .in -.PP +.P Returning to the terminal where the "reader" is running, we see that the program has ceased waiting on the semaphore and has printed the string that was copied into the shared memory segment by the writer: -.PP +.P .in +4n .EX Hello, world @@ -311,7 +311,7 @@ Hello, world .\" .SS Program source: svshm_string.h The following header file is included by the "reader" and "writer" programs: -.PP +.P .in +4n .\" SRC BEGIN (svshm_string.h) .EX @@ -352,7 +352,7 @@ and initializes the semaphore value to 1. Finally, the program waits for the semaphore value to become 0, and afterwards prints the string that has been copied into the shared memory segment by the "writer". -.PP +.P .in +4n .\" SRC BEGIN (svshm_string_read.c) .EX @@ -434,7 +434,7 @@ that have already been created by the "reader", and a string. It attaches the shared memory segment into its address space, and then decrements the semaphore value to 0 in order to inform the "reader" that it can now examine the contents of the shared memory. -.PP +.P .in +4n .\" SRC BEGIN (svshm_string_write.c) .EX diff --git a/man2/shutdown.2 b/man2/shutdown.2 index d9cbcc1..6f45f9f 100644 --- a/man2/shutdown.2 +++ b/man2/shutdown.2 @@ -9,7 +9,7 @@ .\" Modified Tue Oct 22 22:04:51 1996 by Eric S. Raymond .\" Modified 1998 by Andi Kleen .\" -.TH shutdown 2 2023-03-30 "Linux man-pages 6.05.01" +.TH shutdown 2 2023-10-31 "Linux man-pages 6.7" .SH NAME shutdown \- shut down part of a full-duplex connection .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int shutdown(int " sockfd ", int " how ); .fi .SH DESCRIPTION diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 8edde42..bbe4d5a 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -25,7 +25,7 @@ .\" 2015-01-17, Kees Cook .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. .\" -.TH sigaction 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sigaction 2 2024-02-25 "Linux man-pages 6.7" .SH NAME sigaction, rt_sigaction \- examine and change a signal action .SH LIBRARY @@ -34,22 +34,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigaction(int " signum , .BI " const struct sigaction *_Nullable restrict " act , .BI " struct sigaction *_Nullable restrict " oldact ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigaction (): .nf _POSIX_C_SOURCE .fi -.PP +.P .IR siginfo_t : .nf _POSIX_C_SOURCE >= 199309L @@ -62,13 +62,13 @@ receipt of a specific signal. (See .BR signal (7) for an overview of signals.) -.PP +.P .I signum specifies the signal and can be any valid signal except .B SIGKILL and .BR SIGSTOP . -.PP +.P If .I act is non-NULL, the new action for signal @@ -79,11 +79,11 @@ If .I oldact is non-NULL, the previous action is saved in .IR oldact . -.PP +.P The .I sigaction structure is defined as something like: -.PP +.P .in +4n .EX struct sigaction { @@ -95,12 +95,12 @@ struct sigaction { }; .EE .in -.PP +.P On some architectures a union is involved: do not assign to both .I sa_handler and .IR sa_sigaction . -.PP +.P The .I sa_restorer field is not intended for application use. @@ -109,7 +109,7 @@ field is not intended for application use. field.) Some further details of the purpose of this field can be found in .BR sigreturn (2). -.PP +.P .I sa_handler specifies the action to be associated with .I signum @@ -123,7 +123,7 @@ to ignore this signal. .IP \[bu] A pointer to a signal handling function. This function receives the signal number as its only argument. -.PP +.P If .B SA_SIGINFO is specified in @@ -135,7 +135,7 @@ then specifies the signal-handling function for .IR signum . This function receives three arguments, as described below. -.PP +.P .I sa_mask specifies a mask of signals which should be blocked (i.e., added to the signal mask of the thread in which @@ -145,7 +145,7 @@ In addition, the signal which triggered the handler will be blocked, unless the .B SA_NODEFER flag is used. -.PP +.P .I sa_flags specifies a set of flags which modify the behavior of the signal. It is formed by the bitwise OR of zero or more of the following: @@ -292,7 +292,7 @@ the signal handler address is passed via the .I act.sa_sigaction field. This handler takes three arguments, as follows: -.PP +.P .in +4n .EX void @@ -302,7 +302,7 @@ handler(int sig, siginfo_t *info, void *ucontext) } .EE .in -.PP +.P These three arguments are as follows .TP .I sig @@ -329,11 +329,11 @@ structure can be found in and .BR signal (7). Commonly, the handler function doesn't make any use of the third argument. -.PP +.P The .I siginfo_t data type is a structure with the following fields: -.PP +.P .in +4n .EX siginfo_t { @@ -380,7 +380,7 @@ siginfo_t { } .EE .in -.PP +.P .IR si_signo ", " si_errno " and " si_code are defined for all signals. .RI ( si_errno @@ -595,13 +595,13 @@ event, will contain .B SIGTRAP and have the ptrace event in the high byte: -.PP +.P .in +4n .EX (SIGTRAP | PTRACE_EVENT_foo << 8). .EE .in -.PP +.P For a .RB non- ptrace (2) event, the values that can appear in @@ -624,12 +624,12 @@ or .IP \[bu] .B _POSIX_C_SOURCE with the value 200809L or greater. -.PP +.P For the .B TRAP_* constants, the symbol definitions are provided only in the first two cases. Before glibc 2.20, no feature test macros were required to obtain these symbols. -.PP +.P For a regular signal, the following list shows the values which can be placed in .I si_code @@ -672,7 +672,7 @@ or .\" It appears to have been an idea that was tried during 2.5.6 .\" through to Linux 2.5.24 and then was backed out. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -704,7 +704,7 @@ Coprocessor error. .B ILL_BADSTK Internal stack error. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -736,7 +736,7 @@ Floating-point invalid operation. .B FPE_FLTSUB Subscript out of range. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -762,7 +762,7 @@ See The protection key which applied to this access is available via .IR si_pkey . .RE -.PP +.P The following values can be placed in .I si_code for a @@ -785,7 +785,7 @@ Hardware memory error consumed on a machine check; action required. .BR BUS_MCEERR_AO " (since Linux 2.6.32)" Hardware memory error detected in process but not consumed; action optional. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -805,7 +805,7 @@ Process taken branch trap. .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)" Hardware breakpoint/watchpoint. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -831,7 +831,7 @@ Child has stopped. .BR CLD_CONTINUED " (since Linux 2.6.9)" Stopped child has continued. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -857,7 +857,7 @@ High priority input available. .B POLL_HUP Device disconnected. .RE -.PP +.P The following value can be placed in .I si_code for a @@ -884,7 +884,7 @@ However, historically, a second .BR sigaction () call would typically leave those bits set in .IR oldact\->sa_flags . -.PP +.P This means that support for new flags cannot be detected simply by testing for a flag in .IR sa_flags , @@ -892,7 +892,7 @@ and a program must test that .B SA_UNSUPPORTED has been cleared before relying on the contents of .IR sa_flags . -.PP +.P Since the behavior of the signal handler cannot be guaranteed unless the check passes, it is wise to either block the affected signal @@ -901,12 +901,12 @@ or where this is not possible, for example if the signal is synchronous, to issue the second .BR sigaction () in the signal handler itself. -.PP +.P In kernels that do not support a specific flag, the kernel's behavior is as if the flag was not set, even if the flag was set in .IR act\->sa_flags . -.PP +.P The flags .BR SA_NOCLDSTOP , .BR SA_NOCLDWAIT , @@ -922,7 +922,7 @@ because they were introduced before Linux 5.11. However, in general, programs may assume that these flags are supported, since they have all been supported since Linux 2.6, which was released in the year 2003. -.PP +.P See EXAMPLES below for a demonstration of the use of .BR SA_UNSUPPORTED . .SH RETURN VALUE @@ -953,7 +953,7 @@ used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P On architectures where the signal trampoline resides in the C library, the glibc wrapper function for .BR sigaction () @@ -966,7 +966,7 @@ flag in the field. See .BR sigreturn (2). -.PP +.P The original Linux system call was named .BR sigaction (). However, with the addition of real-time signals in Linux 2.2, @@ -999,7 +999,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 does not document the EINTR condition. -.PP +.P POSIX.1-1990 disallowed setting the action for .B SIGCHLD to @@ -1016,27 +1016,34 @@ terminated children do not become zombies is to catch the signal and perform a .BR wait (2) or similar. -.PP +.P POSIX.1-1990 specified only .BR SA_NOCLDSTOP . POSIX.1-2001 added -.BR SA_NOCLDSTOP , .BR SA_NOCLDWAIT , .BR SA_NODEFER , .BR SA_ONSTACK , .BR SA_RESETHAND , .BR SA_RESTART , and -.BR SA_SIGINFO . +.B SA_SIGINFO +as XSI extensions. +POSIX.1-2008 moved +.BR SA_NODEFER , +.BR SA_RESETHAND , +.BR SA_RESTART , +and +.B SA_SIGINFO +to the base specifications. Use of these latter values in .I sa_flags may be less portable in applications intended for older UNIX implementations. -.PP +.P The .B SA_RESETHAND flag is compatible with the SVr4 flag of the same name. -.PP +.P The .B SA_NODEFER flag is compatible with the SVr4 flag of the same name under kernels @@ -1054,7 +1061,7 @@ During an .BR execve (2), the dispositions of handled signals are reset to the default; the dispositions of ignored signals are left unchanged. -.PP +.P According to POSIX, the behavior of a process is undefined after it ignores a .BR SIGFPE , @@ -1072,23 +1079,23 @@ signal. (Also dividing the most negative integer by \-1 may generate .BR SIGFPE .) Ignoring this signal might lead to an endless loop. -.PP +.P .BR sigaction () can be called with a NULL second argument to query the current signal handler. It can also be used to check whether a given signal is valid for the current machine by calling it with NULL second and third arguments. -.PP +.P It is not possible to block .BR SIGKILL " or " SIGSTOP (by specifying them in .IR sa_mask ). Attempts to do so are silently ignored. -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P See .BR signal\-safety (7) for a list of the async-signal-safe functions that can be @@ -1119,7 +1126,7 @@ the kernel does not always provide meaningful values for all of the fields of the .I siginfo_t that are relevant for that signal. -.PP +.P Up to and including Linux 2.6.13, specifying .B SA_NODEFER in @@ -1140,7 +1147,7 @@ if is determined to be supported, and .B EXIT_FAILURE otherwise. -.PP +.P .\" SRC BEGIN (sigaction.c) .EX #include diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 index 0ebfebd..82ba812 100644 --- a/man2/sigaltstack.2 +++ b/man2/sigaltstack.2 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" aeb, various minor fixes -.TH sigaltstack 2 2023-07-20 "Linux man-pages 6.05.01" +.TH sigaltstack 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigaltstack \- set and/or get signal stack context .SH LIBRARY @@ -13,16 +13,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigaltstack(const stack_t *_Nullable restrict " ss , .BI " stack_t *_Nullable restrict " old_ss ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigaltstack (): .nf _XOPEN_SOURCE >= 500 @@ -39,7 +39,7 @@ An alternate signal stack is used during the execution of a signal handler if the establishment of that handler (see .BR sigaction (2)) requested it. -.PP +.P The normal sequence of events for using an alternate signal stack is the following: .TP 3 @@ -59,18 +59,18 @@ When establishing a signal handler using inform the system that the signal handler should be executed on the alternate signal stack by specifying the \fBSA_ONSTACK\fP flag. -.PP +.P The \fIss\fP argument is used to specify a new alternate signal stack, while the \fIold_ss\fP argument is used to retrieve information about the currently established signal stack. If we are interested in performing just one of these tasks, then the other argument can be specified as NULL. -.PP +.P The .I stack_t type used to type the arguments of this function is defined as follows: -.PP +.P .in +4n .EX typedef struct { @@ -80,7 +80,7 @@ typedef struct { } stack_t; .EE .in -.PP +.P To establish a new alternate signal stack, the fields of this structure are set as follows: .TP @@ -119,14 +119,14 @@ The constant \fBSIGSTKSZ\fP is defined to be large enough to cover the usual size requirements for an alternate signal stack, and the constant \fBMINSIGSTKSZ\fP defines the minimum size required to execute a signal handler. -.PP +.P To disable an existing stack, specify \fIss.ss_flags\fP as \fBSS_DISABLE\fP. In this case, the kernel ignores any other flags in .I ss.ss_flags and the remaining fields in \fIss\fP. -.PP +.P If \fIold_ss\fP is not NULL, then it is used to return information about the alternate signal stack which was in effect prior to the call to @@ -162,7 +162,7 @@ using a further call to .B SS_AUTODISARM The alternate signal stack has been marked to be autodisarmed as described above. -.PP +.P By specifying .I ss as NULL, and @@ -207,10 +207,9 @@ T{ .BR sigaltstack () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. -.PP +.P .B SS_AUTODISARM is a Linux extension. .SH HISTORY @@ -223,7 +222,7 @@ standard stack is exhausted: in this case, a signal handler for .B SIGSEGV cannot be invoked on the standard stack; if we wish to handle it, we must use an alternate signal stack. -.PP +.P Establishing an alternate signal stack is useful if a thread expects that it may exhaust its standard stack. This may occur, for example, because the stack grows so large @@ -233,13 +232,13 @@ If the standard stack is exhausted, the kernel sends the thread a \fBSIGSEGV\fP signal. In these circumstances the only way to catch this signal is on an alternate signal stack. -.PP +.P On most hardware architectures supported by Linux, stacks grow downward. .BR sigaltstack () automatically takes account of the direction of stack growth. -.PP +.P Functions called from a signal handler executing on an alternate signal stack will also use the alternate signal stack. (This also applies to any handlers invoked for other signals while @@ -248,7 +247,7 @@ Unlike the standard stack, the system does not automatically extend the alternate signal stack. Exceeding the allocated size of the alternate signal stack will lead to unpredictable results. -.PP +.P A successful call to .BR execve (2) removes any existing alternate @@ -264,7 +263,7 @@ and do not include .BR CLONE_VFORK , in which case any alternate signal stack that was established in the parent is disabled in the child process. -.PP +.P .BR sigaltstack () supersedes the older .BR sigstack () @@ -327,7 +326,7 @@ to install an alternate signal stack that is employed by a handler for the .B SIGSEGV signal: -.PP +.P .in +4n .EX stack_t ss; diff --git a/man2/signal.2 b/man2/signal.2 index 619babf..77f7b19 100644 --- a/man2/signal.2 +++ b/man2/signal.2 @@ -13,7 +13,7 @@ .\" various sections. .\" 2008-07-11, mtk: rewrote and expanded portability discussion. .\" -.TH signal 2 2023-03-30 "Linux man-pages 6.05.01" +.TH signal 2 2023-10-31 "Linux man-pages 6.7" .SH NAME signal \- ANSI C signal handling .SH LIBRARY @@ -22,9 +22,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B typedef void (*sighandler_t)(int); -.PP +.P .BI "sighandler_t signal(int " signum ", sighandler_t " handler ); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ and has also varied historically across different versions of Linux. .BR sigaction (2) instead. See \fIPortability\fP below. -.PP +.P .BR signal () sets the disposition of the signal .I signum @@ -47,7 +47,7 @@ which is either .BR SIG_IGN , .BR SIG_DFL , or the address of a programmer-defined function (a "signal handler"). -.PP +.P If the signal .I signum is delivered to the process, then one of the following happens: @@ -74,7 +74,7 @@ is called with argument .IR signum . If invocation of the handler caused the signal to be blocked, then the signal is unblocked upon return from the handler. -.PP +.P The signals .B SIGKILL and @@ -113,7 +113,7 @@ is defined. Without use of such a type, the declaration of .BR signal () is the somewhat harder to read: -.PP +.P .in +4n .EX .BI "void ( *" signal "(int " signum ", void (*" handler ")(int)) ) (int);" @@ -131,7 +131,7 @@ The semantics when using to establish a signal handler vary across systems (and POSIX.1 explicitly permits this variation); .B do not use it for this purpose. -.PP +.P POSIX.1 solved the portability mess by specifying .BR sigaction (2), which provides explicit control of the semantics when a @@ -141,7 +141,7 @@ signal handler is invoked; use that interface instead of C11, POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001. -.PP +.P In the original UNIX systems, when a handler that was established using .BR signal () was invoked by the delivery of a signal, @@ -151,20 +151,20 @@ and the system did not block delivery of further instances of the signal. This is equivalent to calling .BR sigaction (2) with the following flags: -.PP +.P .in +4n .EX sa.sa_flags = SA_RESETHAND | SA_NODEFER; .EE .in -.PP +.P System\ V also provides these semantics for .BR signal (). This was bad because the signal might be delivered again before the handler had a chance to reestablish itself. Furthermore, rapid deliveries of the same signal could result in recursive invocations of the handler. -.PP +.P BSD improved on this situation, but unfortunately also changed the semantics of the existing .BR signal () @@ -179,13 +179,13 @@ restarted if interrupted by a signal handler (see The BSD semantics are equivalent to calling .BR sigaction (2) with the following flags: -.PP +.P .in +4n .EX sa.sa_flags = SA_RESTART; .EE .in -.PP +.P The situation on Linux is as follows: .IP \[bu] 3 The kernel's @@ -214,7 +214,7 @@ provides System\ V semantics. .\" System V semantics are also provided if one uses the separate .\" .BR sysv_signal (3) .\" function. -.\" .IP * +.\" .IP \[bu] .\" The .\" .BR signal () .\" function in Linux libc4 and libc5 provide System\ V semantics. @@ -229,7 +229,7 @@ provides System\ V semantics. The effects of .BR signal () in a multithreaded process are unspecified. -.PP +.P According to POSIX, the behavior of a process is undefined after it ignores a .BR SIGFPE , @@ -247,14 +247,14 @@ signal. (Also dividing the most negative integer by \-1 may generate .BR SIGFPE .) Ignoring this signal might lead to an endless loop. -.PP +.P See .BR sigaction (2) for details on what happens when the disposition .B SIGCHLD is set to .BR SIG_IGN . -.PP +.P See .BR signal\-safety (7) for a list of the async-signal-safe functions that can be diff --git a/man2/signalfd.2 b/man2/signalfd.2 index 9af22b0..fba622c 100644 --- a/man2/signalfd.2 +++ b/man2/signalfd.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH signalfd 2 2023-05-03 "Linux man-pages 6.05.01" +.TH signalfd 2 2023-10-31 "Linux man-pages 6.7" .SH NAME signalfd \- create a file descriptor for accepting signals .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ and has the advantage that the file descriptor may be monitored by .BR poll (2), and .BR epoll (7). -.PP +.P The .I mask argument specifies the set of signals that the caller @@ -46,7 +46,7 @@ or signals via a signalfd file descriptor; these signals are silently ignored if specified in .IR mask . -.PP +.P If the .I fd argument is \-1, @@ -60,7 +60,7 @@ is not \-1, then it must specify a valid existing signalfd file descriptor, and .I mask is used to replace the signal set associated with that file descriptor. -.PP +.P Starting with Linux 2.6.27, the following values may be bitwise ORed in .I flags to change the behavior of @@ -85,11 +85,11 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P Up to Linux 2.6.26, the .I flags argument is unused, and must be specified as zero. -.PP +.P .BR signalfd () returns a file descriptor that supports the following operations: .TP @@ -131,7 +131,11 @@ or fails with the error .B EAGAIN if the file descriptor has been made nonblocking. .TP -.BR poll "(2), " select "(2) (and similar)" +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) The file descriptor is readable (the .BR select (2) @@ -161,7 +165,7 @@ The format of the structure(s) returned by .BR read (2)s from a signalfd file descriptor is as follows: -.PP +.P .in +4n .EX struct signalfd_siginfo { @@ -192,7 +196,7 @@ struct signalfd_siginfo { }; .EE .in -.PP +.P Each of the fields in this structure is analogous to the similarly named field in the .I siginfo_t @@ -338,7 +342,7 @@ The glibc .BR signalfd () wrapper function does not include this argument, since it provides the required value for the underlying system call. -.PP +.P There are two underlying Linux system calls: .BR signalfd () and the more recent @@ -379,7 +383,7 @@ If a signal appears in the .I mask of more than one of the file descriptors, then occurrences of that signal can be read (once) from any one of the file descriptors. -.PP +.P Attempts to include .B SIGKILL and @@ -387,7 +391,7 @@ and in .I mask are silently ignored. -.PP +.P The signal mask employed by a signalfd file descriptor can be viewed via the entry for the corresponding file descriptor in the process's .IR /proc/ pid /fdinfo @@ -405,7 +409,7 @@ or the .B SIGFPE signal that results from an arithmetic error. Such signals can be caught only via signal handler. -.PP +.P As described above, in normal usage one blocks the signals that will be accepted via .BR signalfd (). @@ -443,7 +447,7 @@ The program terminates after accepting a .B SIGQUIT signal. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " ./signalfd_demo" diff --git a/man2/sigpending.2 b/man2/sigpending.2 index e1b3158..cd67531 100644 --- a/man2/sigpending.2 +++ b/man2/sigpending.2 @@ -6,7 +6,7 @@ .\" .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 .\" -.TH sigpending 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigpending 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigpending, rt_sigpending \- examine pending signals .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigpending(sigset_t *" set ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigpending (): .nf _POSIX_C_SOURCE @@ -79,16 +79,16 @@ when the kernel provides it. See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P If a signal is both blocked and has a disposition of "ignored", it is .I not added to the mask of pending signals when generated. -.PP +.P The set of signals that is pending for a thread is the union of the set of signals that is pending for that thread and the set of signals that is pending for the process as a whole; see .BR signal (7). -.PP +.P A child created via .BR fork (2) initially has an empty pending signal set; diff --git a/man2/sigprocmask.2 b/man2/sigprocmask.2 index a89c1ed..f0017b4 100644 --- a/man2/sigprocmask.2 +++ b/man2/sigprocmask.2 @@ -6,7 +6,7 @@ .\" .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 .\" -.TH sigprocmask 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigprocmask 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigprocmask, rt_sigprocmask \- examine and change blocked signals .SH LIBRARY @@ -14,33 +14,33 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .B #include -.PP +.P .nf /* Prototype for the glibc wrapper function */ .BI "int sigprocmask(int " how ", const sigset_t *_Nullable restrict " set , .BI " sigset_t *_Nullable restrict " oldset ); -.PP +.P .BR "#include " " /* Definition of " SIG_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P /* Prototype for the underlying system call */ .BI "int syscall(SYS_rt_sigprocmask, int " how , .BI " const kernel_sigset_t *_Nullable " set , .BI " kernel_sigset_t *_Nullable " oldset , .BI " size_t " sigsetsize ); -.PP +.P /* Prototype for the legacy system call */ .BI "[[deprecated]] int syscall(SYS_sigprocmask, int " how , .BI " const old_kernel_sigset_t *_Nullable " set , .BI " old_kernel_sigset_t *_Nullable " oldset ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigprocmask (): .nf _POSIX_C_SOURCE @@ -53,7 +53,7 @@ blocked for the caller (see also .BR signal (7) for more details). -.PP +.P The behavior of the call is dependent on the value of .IR how , as follows. @@ -72,12 +72,12 @@ It is permissible to attempt to unblock a signal which is not blocked. .B SIG_SETMASK The set of blocked signals is set to the argument .IR set . -.PP +.P If .I oldset is non-NULL, the previous value of the signal mask is stored in .IR oldset . -.PP +.P If .I set is NULL, then the signal mask is unchanged (i.e., @@ -86,12 +86,12 @@ is ignored), but the current value of the signal mask is nevertheless returned in .I oldset (if it is not NULL). -.PP +.P A set of functions for modifying and inspecting variables of type .I sigset_t ("signal sets") is described in .BR sigsetops (3). -.PP +.P The use of .BR sigprocmask () is unspecified in a multithreaded process; see @@ -127,7 +127,7 @@ In this manual page, the former is referred to as (it is nevertheless named .I sigset_t in the kernel sources). -.PP +.P The glibc wrapper function for .BR sigprocmask () silently ignores attempts to block the two real-time signals that @@ -135,7 +135,7 @@ are used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P The original Linux system call was named .BR sigprocmask (). However, with the addition of real-time signals in Linux 2.2, @@ -164,7 +164,7 @@ This argument is currently required to have a fixed architecture specific value .IR sizeof(kernel_sigset_t) ). .\" sizeof(kernel_sigset_t) == _NSIG / 8, .\" which equals to 8 on most architectures, but e.g. on MIPS it's 16. -.PP +.P The glibc .BR sigprocmask () wrapper function hides these details from us, transparently calling @@ -179,15 +179,15 @@ POSIX.1-2001. It is not possible to block .BR SIGKILL " or " SIGSTOP . Attempts to do so are silently ignored. -.PP +.P Each of the threads in a process has its own signal mask. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal mask; the signal mask is preserved across .BR execve (2). -.PP +.P If .BR SIGBUS , .BR SIGFPE , @@ -201,11 +201,11 @@ unless the signal was generated by .BR sigqueue (3), or .BR raise (3). -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P Note that it is permissible (although not very useful) to specify both .I set and diff --git a/man2/sigreturn.2 b/man2/sigreturn.2 index 03ce952..dd0935a 100644 --- a/man2/sigreturn.2 +++ b/man2/sigreturn.2 @@ -7,7 +7,7 @@ .\" 2008-06-26, mtk, added some more detail on the work done by sigreturn() .\" 2014-12-05, mtk, rewrote all of the rest of the original page .\" -.TH sigreturn 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigreturn 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigreturn, rt_sigreturn \- return from signal handler and cleanup stack frame .SH LIBRARY @@ -27,14 +27,14 @@ it creates a new frame on the user-space stack where it saves various pieces of process context (processor status word, registers, signal mask, and signal stack settings). .\" See arch/x86/kernel/signal.c::__setup_frame() [in Linux 3.17 source code] -.PP +.P The kernel also arranges that, during the transition back to user mode, the signal handler is called, and that, upon return from the handler, control passes to a piece of user-space code commonly called the "signal trampoline". The signal trampoline code in turn calls .BR sigreturn (). -.PP +.P This .BR sigreturn () call undoes everything that was @@ -82,7 +82,7 @@ vary depending on the architecture. takes no arguments, since all of the information that it requires is available in the stack frame that was previously created by the kernel on the user-space stack.) -.PP +.P Once upon a time, UNIX systems placed the signal trampoline code onto the user stack. Nowadays, pages of the user stack are protected so as to @@ -107,7 +107,7 @@ and sets the flag in the .I sa_flags field. -.PP +.P The saved process context information is placed in a .I ucontext_t structure (see @@ -118,7 +118,7 @@ as the third argument of a handler established via with the .B SA_SIGINFO flag. -.PP +.P On some other UNIX systems, the operation of the signal trampoline differs a little. In particular, on some systems, upon transitioning back to user mode, diff --git a/man2/sigsuspend.2 b/man2/sigsuspend.2 index f89a6ca..9bb39f8 100644 --- a/man2/sigsuspend.2 +++ b/man2/sigsuspend.2 @@ -6,7 +6,7 @@ .\" .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 .\" -.TH sigsuspend 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigsuspend 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigsuspend, rt_sigsuspend \- wait for a signal .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigsuspend(const sigset_t *" mask ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigsuspend (): .nf _POSIX_C_SOURCE @@ -35,7 +35,7 @@ mask given by .I mask and then suspends the thread until delivery of a signal whose action is to invoke a signal handler or to terminate a process. -.PP +.P If the signal terminates the process, then .BR sigsuspend () does not return. @@ -44,7 +44,7 @@ If the signal is caught, then returns after the signal handler returns, and the signal mask is restored to the state before the call to .BR sigsuspend (). -.PP +.P It is not possible to block .B SIGKILL or @@ -115,7 +115,7 @@ with the signal mask that was returned by (in the .I oldset argument). -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 index a5703fc..cf231bc 100644 --- a/man2/sigwaitinfo.2 +++ b/man2/sigwaitinfo.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sigwaitinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sigwaitinfo 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait for queued signals @@ -12,19 +12,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigwaitinfo(const sigset_t *restrict " set , .BI " siginfo_t *_Nullable restrict " info ); .BI "int sigtimedwait(const sigset_t *restrict " set , .BI " siginfo_t *_Nullable restrict " info , .BI " const struct timespec *restrict " timeout ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigwaitinfo (), .BR sigtimedwait (): .nf @@ -40,7 +40,7 @@ is pending is already pending for the calling thread, .BR sigwaitinfo () will return immediately.) -.PP +.P .BR sigwaitinfo () removes the signal from the set of pending signals and returns the signal number as its function result. @@ -52,7 +52,7 @@ then the buffer that it points to is used to return a structure of type (see .BR sigaction (2)) containing information about the signal. -.PP +.P If multiple signals in .I set are pending for the caller, the signal that is retrieved by @@ -60,7 +60,7 @@ are pending for the caller, the signal that is retrieved by is determined according to the usual ordering rules; see .BR signal (7) for further details. -.PP +.P .BR sigtimedwait () operates in exactly the same way as .BR sigwaitinfo () @@ -74,7 +74,7 @@ may overrun by a small amount.) This argument is a .BR timespec (3) structure. -.PP +.P If both fields of this structure are specified as 0, a poll is performed: .BR sigtimedwait () returns immediately, either with information about a signal that @@ -116,7 +116,7 @@ On Linux, .BR sigwaitinfo () is a library function implemented on top of .BR sigtimedwait (). -.PP +.P The glibc wrapper functions for .BR sigwaitinfo () and @@ -126,7 +126,7 @@ are used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P The original Linux system call was named .BR sigtimedwait (). However, with the addition of real-time signals in Linux 2.2, @@ -175,18 +175,18 @@ a thread other than the one calling .BR sigwaitinfo () or .BR sigtimedwait ()). -.PP +.P The set of signals that is pending for a given thread is the union of the set of signals that is pending specifically for that thread and the set of signals that is pending for the process as a whole (see .BR signal (7)). -.PP +.P Attempts to wait for .B SIGKILL and .B SIGSTOP are silently ignored. -.PP +.P If multiple threads of a process are blocked waiting for the same signal(s) in .BR sigwaitinfo () @@ -195,7 +195,7 @@ or then exactly one of the threads will actually receive the signal if it becomes pending for the process as a whole; which of the threads receives the signal is indeterminate. -.PP +.P .BR sigwaitinfo () or .BR sigtimedwait (), @@ -207,7 +207,7 @@ or the .B SIGFPE signal that results from an arithmetic error. Such signals can be caught only via signal handler. -.PP +.P POSIX leaves the meaning of a NULL value for the .I timeout argument of diff --git a/man2/socket.2 b/man2/socket.2 index 2a35f2b..b83bd5b 100644 --- a/man2/socket.2 +++ b/man2/socket.2 @@ -12,7 +12,7 @@ .\" Modified 2002-07-17 by Michael Kerrisk .\" Modified 2004-06-17 by Michael Kerrisk .\" -.TH socket 2 2023-03-30 "Linux man-pages 6.05.01" +.TH socket 2 2024-01-28 "Linux man-pages 6.7" .SH NAME socket \- create an endpoint for communication .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int socket(int " domain ", int " type ", int " protocol ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ creates an endpoint for communication and returns a file descriptor that refers to that endpoint. The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process. -.PP +.P The .I domain argument specifies a communication domain; this selects the protocol @@ -79,7 +79,7 @@ T}:AppleTalk:T{ T} T{ .B AF_X25 -T}:ITU-T X.25 / ISO-8208 protocol:T{ +T}:ITU-T X.25 / ISO/IEC\~8208 protocol:T{ .BR x25 (7) T} T{ @@ -193,11 +193,11 @@ T}:T{ XDP (express data path) interface T} .TE -.PP +.P Further details of the above address families, as well as information on several other address families, can be found in .BR address_families (7). -.PP +.P The socket has the indicated .IR type , which specifies the communication semantics. @@ -227,9 +227,9 @@ Provides a reliable datagram layer that does not guarantee ordering. Obsolete and should not be used in new programs; see .BR packet (7). -.PP +.P Some socket types may not be implemented by all protocol families. -.PP +.P Since Linux 2.6.27, the .I type argument serves a second purpose: @@ -257,7 +257,7 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P The .I protocol specifies a particular protocol to be used with the socket. @@ -273,7 +273,7 @@ in which communication is to take place; see See .BR getprotoent (3) on how to map protocol name strings to protocol numbers. -.PP +.P Sockets of type .B SOCK_STREAM are full-duplex byte streams. @@ -303,7 +303,7 @@ Out-of-band data may also be transmitted as described in .BR send (2) and received as described in .BR recv (2). -.PP +.P The communications protocols which implement a .B SOCK_STREAM ensure that data is not lost or duplicated. @@ -329,7 +329,7 @@ The only difference is that calls will return only the amount of data requested, and any data remaining in the arriving packet will be discarded. Also all message boundaries in incoming datagrams are preserved. -.PP +.P .B SOCK_DGRAM and .B SOCK_RAW @@ -339,14 +339,14 @@ calls. Datagrams are generally received with .BR recvfrom (2), which returns the next datagram along with the address of its sender. -.PP +.P .B SOCK_PACKET is an obsolete socket type to receive raw packets directly from the device driver. Use .BR packet (7) instead. -.PP +.P An .BR fcntl (2) .B F_SETOWN @@ -369,7 +369,7 @@ call with the or .B SIOCSPGRP argument. -.PP +.P When the network signals an error condition to the protocol module (e.g., using an ICMP message for IP) the pending error flag is set for the socket. The next operation on this socket will return the error code of the pending @@ -379,7 +379,7 @@ to retrieve detailed information about the error; see .B IP_RECVERR in .BR ip (7). -.PP +.P The operation of sockets is controlled by socket level .IR options . These options are defined in @@ -425,24 +425,24 @@ created until sufficient resources are freed. .B EPROTONOSUPPORT The protocol type or the specified protocol is not supported within this domain. -.PP +.P Other errors may be generated by the underlying protocol modules. .SH STANDARDS POSIX.1-2008. -.PP +.P .B SOCK_NONBLOCK and .B SOCK_CLOEXEC are Linux-specific. .SH HISTORY POSIX.1-2001, 4.4BSD. -.PP +.P .BR socket () appeared in 4.2BSD. It is generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System\ V variants). -.PP +.P The manifest constants used under 4.x BSD for protocol families are .BR PF_UNIX , @@ -485,7 +485,7 @@ is shown in .BR tcp (7), .BR udp (7), .BR unix (7) -.PP +.P \[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq] and \[lq]BSD Interprocess Communication Tutorial\[rq], diff --git a/man2/socketcall.2 b/man2/socketcall.2 index 24f7f6b..d536966 100644 --- a/man2/socketcall.2 +++ b/man2/socketcall.2 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Tue Oct 22 22:11:53 1996 by Eric S. Raymond -.TH socketcall 2 2023-03-30 "Linux man-pages 6.05.01" +.TH socketcall 2 2023-10-31 "Linux man-pages 6.7" .SH NAME socketcall \- socket system calls .SH LIBRARY @@ -15,10 +15,10 @@ Standard C library .BR "#include " " /* Definition of " SYS_* " constants */" .BR "#include " " /* Definition of " SYS_socketcall " */" .B #include -.PP +.P .BI "int syscall(SYS_socketcall, int " call ", unsigned long *" args ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR socketcall (), @@ -32,11 +32,11 @@ determines which socket function to invoke. .I args points to a block containing the actual arguments, which are passed through to the appropriate call. -.PP +.P User programs should call the appropriate functions by their usual names. Only standard library implementors and kernel hackers need to know about .BR socketcall (). -.PP +.P .TS tab(:); l l. @@ -152,7 +152,7 @@ system call; instead and so on really are implemented as separate system calls. .SH STANDARDS Linux. -.PP +.P On x86-32, .BR socketcall () was historically the only entry point for the sockets API. diff --git a/man2/socketpair.2 b/man2/socketpair.2 index 741596e..ae304e6 100644 --- a/man2/socketpair.2 +++ b/man2/socketpair.2 @@ -11,7 +11,7 @@ .\" Modified 2004-06-17 by Michael Kerrisk .\" 2008-10-11, mtk: Add description of SOCK_NONBLOCK and SOCK_CLOEXEC .\" -.TH socketpair 2 2023-03-30 "Linux man-pages 6.05.01" +.TH socketpair 2 2023-10-31 "Linux man-pages 6.7" .SH NAME socketpair \- create a pair of connected sockets .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int socketpair(int " domain ", int " type ", int " protocol \ ", int " sv [2]); .fi @@ -35,7 +35,7 @@ and using the optionally specified .IR protocol . For further details of these arguments, see .BR socket (2). -.PP +.P The file descriptors used in referencing the new sockets are returned in .I sv[0] and @@ -48,7 +48,7 @@ On error, \-1 is returned, is set to indicate the error, and .I sv is left unchanged -.PP +.P On Linux (and other systems), .BR socketpair () does not modify @@ -90,13 +90,13 @@ and POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.4BSD. -.PP +.P .BR socketpair () first appeared in 4.2BSD. It is generally portable to/from non-BSD systems supporting clones of the BSD socket layer (including System\ V variants). -.PP +.P Since Linux 2.6.27, .BR socketpair () supports the diff --git a/man2/splice.2 b/man2/splice.2 index 88d4160..ff39e03 100644 --- a/man2/splice.2 +++ b/man2/splice.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH splice 2 2023-07-15 "Linux man-pages 6.05.01" +.TH splice 2 2023-10-31 "Linux man-pages 6.7" .SH NAME splice \- splice data to/from a pipe .SH LIBRARY @@ -12,9 +12,9 @@ Standard C library .SH SYNOPSIS .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" -.B "#define _FILE_OFFSET_BITS 64 +.B #define _FILE_OFFSET_BITS 64 .B #include -.PP +.P .BI "ssize_t splice(int " fd_in ", off_t *_Nullable " off_in , .BI " int " fd_out ", off_t *_Nullable " off_out , .BI " size_t " len ", unsigned int " flags ); @@ -31,7 +31,7 @@ bytes of data from the file descriptor to the file descriptor .IR fd_out , where one of the file descriptors must refer to a pipe. -.PP +.P The following semantics apply for .I fd_in and @@ -64,12 +64,12 @@ offset from which bytes will be read from in this case, the file offset of .I fd_in is not changed. -.PP +.P Analogous statements apply for .I fd_out and .IR off_out . -.PP +.P The .I flags argument is a bit mask that is composed by ORing together @@ -121,14 +121,14 @@ Upon successful completion, .BR splice () returns the number of bytes spliced to or from the pipe. -.PP +.P A return value of 0 means end of input. If .I fd_in refers to a pipe, then this means that there was no data to transfer, and it would not make sense to block because there are no writers connected to the write end of the pipe. -.PP +.P On error, .BR splice () returns \-1 and @@ -182,7 +182,7 @@ Linux. .SH HISTORY Linux 2.6.17, glibc 2.5. -.PP +.P In Linux 2.6.30 and earlier, exactly one of .I fd_in @@ -212,7 +212,7 @@ or from one buffer to another. .TP .BR vmsplice (2) "copies" data from user space into the buffer. -.PP +.P Though we talk of copying, actual copies are generally avoided. The kernel does this by implementing a pipe buffer as a set of reference-counted pointers to pages of kernel memory. @@ -243,7 +243,7 @@ only pointers are copied, not the pages of the buffer. .\" the data and choose to forward it to two or more different .\" users - for things like logging etc.). .\" -.PP +.P .B _FILE_OFFSET_BITS should be defined to be 64 in code that uses non-null .I off_in diff --git a/man2/spu_create.2 b/man2/spu_create.2 index 36d1bbd..38efa2c 100644 --- a/man2/spu_create.2 +++ b/man2/spu_create.2 @@ -8,7 +8,7 @@ .\" 2007-07-10, some polishing by mtk .\" 2007-09-28, updates for newer kernels by Jeremy Kerr .\" -.TH spu_create 2 2023-03-30 "Linux man-pages 6.05.01" +.TH spu_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME spu_create \- create a new spu context .SH LIBRARY @@ -19,12 +19,12 @@ Standard C library .BR "#include " " /* Definition of " SPU_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_spu_create, const char *" pathname \ ", unsigned int " flags , .BI " mode_t " mode ", int " neighbor_fd ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR spu_create (), @@ -49,7 +49,7 @@ is successful, a directory is created at .I pathname and it is populated with the files described in .BR spufs (7). -.PP +.P When a context is created, the returned file descriptor can only be passed to .BR spu_run (2), @@ -68,7 +68,7 @@ directory) once the last reference to the context has gone; this usually occurs when the file descriptor returned by .BR spu_create () is closed. -.PP +.P The .I mode argument (minus any bits set in the process's @@ -80,13 +80,13 @@ See for a full list of the possible .I mode values. -.PP +.P The .I neighbor_fd is used only when the .B SPU_CREATE_AFFINITY_SPU flag is specified; see below. -.PP +.P The .I flags argument can be zero or any bitwise OR-ed @@ -248,7 +248,7 @@ By convention, it gets mounted in Linux on PowerPC. .SH HISTORY Linux 2.6.16. -.PP +.P Prior to the addition of the .B SPU_CREATE_AFFINITY_SPU flag in Linux 2.6.23, the diff --git a/man2/spu_run.2 b/man2/spu_run.2 index 0a9d229..5b70753 100644 --- a/man2/spu_run.2 +++ b/man2/spu_run.2 @@ -9,7 +9,7 @@ .\" 2007-09-28, updates for newer kernels, added example .\" by Jeremy Kerr .\" -.TH spu_run 2 2023-05-03 "Linux man-pages 6.05.01" +.TH spu_run 2 2023-10-31 "Linux man-pages 6.7" .SH NAME spu_run \- execute an SPU context .SH LIBRARY @@ -20,11 +20,11 @@ Standard C library .BR "#include " " /* Definition of " SPU_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \ ", uint32_t *" event ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR spu_run (), @@ -44,7 +44,7 @@ that refers to a specific SPU context. When the context gets scheduled to a physical SPU, it starts execution at the instruction pointer passed in .IR npc . -.PP +.P Execution of SPU code happens synchronously, meaning that .BR spu_run () blocks while the SPU is still running. @@ -53,7 +53,7 @@ to execute SPU code in parallel with other code on either the main CPU or other SPUs, a new thread of execution must be created first (e.g., using .BR pthread_create (3)). -.PP +.P When .BR spu_run () returns, the current value of the SPU program counter is written to @@ -63,7 +63,7 @@ so successive calls to can use the same .I npc pointer. -.PP +.P The .I event argument provides a buffer for an extended status code. @@ -73,7 +73,7 @@ context was created with the flag, then this buffer is populated by the Linux kernel before .BR spu_run () returns. -.PP +.P The status code may be one (or more) of the following constants: .TP .B SPE_EVENT_DMA_ALIGNMENT @@ -89,7 +89,7 @@ A DMA storage error occurred. .TP .B SPE_EVENT_SPE_ERROR An illegal instruction was executed. -.PP +.P NULL is a valid value for the .I event @@ -104,7 +104,7 @@ register. On failure, it returns \-1 and sets .I errno is set to indicate the error. -.PP +.P The .I spu_status register value is a bit mask of status codes and @@ -141,7 +141,7 @@ The bits masked with this value contain the code returned from a .B stop-and-signal instruction. These bits are valid only if the 0x02 bit is set. -.PP +.P If .BR spu_run () has not returned an error, one or more bits among the lower eight @@ -198,7 +198,7 @@ The following is an example of running a simple, one-instruction SPU program with the .BR spu_run () system call. -.PP +.P .\" SRC BEGIN (spu_run.c) .EX #include diff --git a/man2/stat.2 b/man2/stat.2 index f41daab..bb813ff 100644 --- a/man2/stat.2 +++ b/man2/stat.2 @@ -16,7 +16,7 @@ .\" 2007-06-08 mtk: Added example program .\" 2007-07-05 mtk: Added details on underlying system call interfaces .\" -.TH stat 2 2023-05-03 "Linux man-pages 6.05.01" +.TH stat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME stat, fstat, lstat, fstatat \- get file status .SH LIBRARY @@ -25,25 +25,25 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int stat(const char *restrict " pathname , .BI " struct stat *restrict " statbuf ); .BI "int fstat(int " fd ", struct stat *" statbuf ); .BI "int lstat(const char *restrict " pathname , .BI " struct stat *restrict " statbuf ); -.PP +.P .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int fstatat(int " dirfd ", const char *restrict " pathname , .BI " struct stat *restrict " statbuf ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR lstat (): .nf /* Since glibc 2.20 */ _DEFAULT_SOURCE @@ -52,7 +52,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L || /* glibc 2.19 and earlier */ _BSD_SOURCE .fi -.PP +.P .BR fstatat (): .nf Since glibc 2.10: @@ -71,7 +71,7 @@ and (search) permission is required on all of the directories in .I pathname that lead to the file. -.PP +.P .BR stat () and .BR fstatat () @@ -80,7 +80,7 @@ retrieve information about the file pointed to by the differences for .BR fstatat () are described below. -.PP +.P .BR lstat () is identical to .BR stat (), @@ -88,7 +88,7 @@ except that if .I pathname is a symbolic link, then it returns information about the link itself, not the file that the link refers to. -.PP +.P .BR fstat () is identical to .BR stat (), @@ -101,7 +101,7 @@ All of these system calls return a .I stat structure (see .BR stat (3type)). -.PP +.P .\" Background: inode attributes are modified with i_mutex held, but .\" read by stat() without taking the mutex. .IR Note : @@ -135,7 +135,7 @@ which can still provide exactly the behavior of each of .BR lstat (), and .BR fstat (). -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -147,7 +147,7 @@ the calling process, as is done by and .BR lstat () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -161,13 +161,13 @@ directory of the calling process (like .BR stat () and .BR lstat ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags can either be 0, or include one or more of the following flags ORed: .TP @@ -214,7 +214,7 @@ instead return information about the link itself, like .BR fstatat () dereferences symbolic links, like .BR stat ().) -.PP +.P See .BR openat (2) for an explanation of the need for @@ -329,7 +329,7 @@ SVr4, 4.3BSD, POSIX.1-2001. POSIX.1-2008. Linux 2.6.16, glibc 2.4. -.PP +.P According to POSIX.1-2001, .BR lstat () on a symbolic link need return valid information only in the @@ -343,7 +343,7 @@ POSIX.1-2008 tightens the specification, requiring .BR lstat () to return valid information in all fields except the mode bits in .IR st_mode . -.PP +.P Use of the .I st_blocks and @@ -377,7 +377,7 @@ Similar remarks apply for .BR fstat () and .BR lstat (). -.PP +.P The kernel-internal versions of the .I stat structure dealt with by the different versions are, respectively: @@ -404,7 +404,7 @@ and various other enlarged fields and further padding in the structure. (Various padding bytes were eventually consumed in Linux 2.6, with the advent of 32-bit device IDs and nanosecond components for the timestamp fields.) -.PP +.P The glibc .BR stat () wrapper function hides these details from applications, @@ -438,13 +438,13 @@ and repacking the returned information if required for old binaries. .\" interface, rather than the libc-kernel interface. .\" .\" (Note that the details depend on gcc being used as c compiler.) -.PP +.P On modern 64-bit systems, life is simpler: there is a single .BR stat () system call and the kernel deals with a .I stat structure that contains fields of a sufficient size. -.PP +.P The underlying system call employed by the glibc .BR fstatat () wrapper function is actually called @@ -458,7 +458,7 @@ The following program calls and displays selected fields in the returned .I stat structure. -.PP +.P .\" SRC BEGIN (stat.c) .EX #include diff --git a/man2/statfs.2 b/man2/statfs.2 index 26dad7c..df633ae 100644 --- a/man2/statfs.2 +++ b/man2/statfs.2 @@ -5,7 +5,7 @@ .\" Modified 2003-08-17 by Walter Harms .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH statfs 2 2023-07-18 "Linux man-pages 6.05.01" +.TH statfs 2 2023-10-31 "Linux man-pages 6.7" .SH NAME statfs, fstatfs \- get filesystem statistics .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .SH SYNOPSIS .nf .BR "#include " "/* or */" -.PP +.P .BI "int statfs(const char *" path ", struct statfs *" buf ); .BI "int fstatfs(int " fd ", struct statfs *" buf ); .fi -.PP +.P Unless you need the .I f_type field, you should use the standard @@ -34,7 +34,7 @@ is the pathname of any file within the mounted filesystem. is a pointer to a .I statfs structure defined approximately as follows: -.PP +.P .in +4n .EX struct statfs { @@ -56,10 +56,10 @@ struct statfs { }; .EE .in -.PP +.P The following filesystem types may appear in .IR f_type : -.PP +.P .in +4n .EX ADFS_SUPER_MAGIC 0xadf5 @@ -150,11 +150,11 @@ XFS_SUPER_MAGIC 0x58465342 _XIAFS_SUPER_MAGIC 0x012fd16d /* Linux 2.0 and earlier */ .EE .in -.PP +.P Most of these MAGIC constants are defined in .IR /usr/include/linux/magic.h , and some are hardcoded in kernel sources. -.PP +.P The .I f_flags field is a bit mask indicating mount options for the filesystem. @@ -201,13 +201,13 @@ in .\" dab741e0e02bd3c4f5e2e97be74b39df2523fc6e Symbolic links are not followed when resolving paths; see .BR mount (2). -.PP +.P Nobody knows what .I f_fsid is supposed to contain (but see below). -.PP +.P Fields that are undefined for a particular filesystem are set to 0. -.PP +.P .BR fstatfs () returns the same information about an open file referenced by descriptor .IR fd . @@ -299,7 +299,7 @@ is defined as .IR "struct { int val[2]; }" . The same holds for FreeBSD, except that it uses the include file .IR . -.PP +.P The general idea is that .I f_fsid contains some random stuff such that the pair @@ -312,7 +312,7 @@ Several operating systems restrict giving out the field to the superuser only (and zero it for unprivileged users), because this field is used in the filehandle of the filesystem when NFS-exported, and giving it out is a security concern. -.PP +.P Under some operating systems, the .I fsid can be used as the second argument to the @@ -325,7 +325,7 @@ The Linux .BR statfs () was inspired by the 4.4BSD one (but they do not use the same structure). -.PP +.P The original Linux .BR statfs () and @@ -347,7 +347,7 @@ The glibc and .BR fstatfs () wrapper functions transparently deal with the kernel differences. -.PP +.P LSB has deprecated the library calls .BR statfs () and @@ -369,7 +369,7 @@ or compare these fields to local variables in a program. Using .I "unsigned\ int" for such variables suffices on most systems. -.PP +.P Some systems have only \fI\fP, other systems also have \fI\fP, where the former includes the latter. So it seems diff --git a/man2/statx.2 b/man2/statx.2 index d7c36b8..ce79da2 100644 --- a/man2/statx.2 +++ b/man2/statx.2 @@ -8,7 +8,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH statx 2 2023-06-01 "Linux man-pages 6.05.01" +.TH statx 2 2023-10-31 "Linux man-pages 6.7" .SH NAME statx \- get file status (extended) .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags , .BI " unsigned int " mask ", struct statx *restrict " statxbuf ); .fi @@ -28,7 +28,7 @@ This function returns information about a file, storing it in the buffer pointed to by .IR statxbuf . The returned buffer is a structure of the following type: -.PP +.P .in +4n .EX struct statx { @@ -71,9 +71,9 @@ struct statx { }; .EE .in -.PP +.P The file timestamps are structures of the following type: -.PP +.P .in +4n .EX struct statx_timestamp { @@ -82,7 +82,7 @@ struct statx_timestamp { }; .EE .in -.PP +.P (Note that reserved space and padding is omitted.) .SS Invoking \fBstatx\fR(): @@ -93,7 +93,7 @@ with a pathname, execute (search) permission is required on all of the directories in .I pathname that lead to the file. -.PP +.P .BR statx () uses .IR pathname , @@ -147,7 +147,7 @@ flag is specified in (see below), then the target file is the one referred to by the file descriptor .IR dirfd . -.PP +.P .I flags can be used to influence a pathname-based lookup. A value for @@ -202,7 +202,7 @@ If is a symbolic link, do not dereference it: instead return information about the link itself, like .BR lstat (2). -.PP +.P .I flags can also be used to control what sort of synchronization the kernel will do when querying a file on a remote filesystem. @@ -225,7 +225,7 @@ the system has cached if possible. This may mean that the information returned is approximate, but, on a network filesystem, it may not involve a round trip to the server - even if no lease is held. -.PP +.P The .I mask argument to @@ -233,7 +233,7 @@ argument to is used to tell the kernel which fields the caller is interested in. .I mask is an ORed combination of the following constants: -.PP +.P .in +4n .TS lB l. @@ -257,7 +257,7 @@ STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align (since Linux 6.1; support varies by filesystem) .TE .in -.PP +.P Note that, in general, the kernel does .I not reject values in @@ -293,7 +293,7 @@ has the same format as the .I mask argument and bits are set in it to indicate which fields have been filled in. -.PP +.P It should be noted that the kernel may return fields that weren't requested and may fail to return fields that were requested, depending on what the backing filesystem supports. @@ -302,7 +302,7 @@ In either case, .I stx_mask will not be equal .IR mask . -.PP +.P If a filesystem does not support a field or if it has an unrepresentable value (for instance, a file with an exotic type), then the mask bit corresponding to that field will be cleared in @@ -310,12 +310,12 @@ then the mask bit corresponding to that field will be cleared in even if the user asked for it and a dummy value will be filled in for compatibility purposes if one is available (e.g., a dummy UID and GID may be specified to mount under some circumstances). -.PP +.P A filesystem may also fill in fields that the caller didn't ask for if it has values for them available and the information is available at no extra cost. If this happens, the corresponding bits will be set in .IR stx_mask . -.PP +.P .\" Background: inode attributes are modified with i_mutex held, but .\" read by stat() without taking the mutex. .IR Note : @@ -340,7 +340,7 @@ or the old .I stx_uid together with the new .IR stx_mode . -.PP +.P Apart from .I stx_mask (which is described above), the fields in the @@ -439,7 +439,7 @@ or 0 if direct I/O is not supported on this file. This will only be nonzero if .I stx_dio_mem_align is nonzero, and vice versa. -.PP +.P For further information on the above fields, see .BR inode (7). .\" @@ -455,7 +455,7 @@ The bits in .I stx_attributes_mask correspond bit-by-bit to .IR stx_attributes . -.PP +.P The flags are as follows: .TP .B STATX_ATTR_COMPRESSED diff --git a/man2/stime.2 b/man2/stime.2 index e4d1a38..1337889 100644 --- a/man2/stime.2 +++ b/man2/stime.2 @@ -7,21 +7,21 @@ .\" Modified 2001-03-16 by Andries Brouwer .\" Modified 2004-05-27 by Michael Kerrisk .\" -.TH stime 2 2023-03-30 "Linux man-pages 6.05.01" +.TH stime 2 2023-10-31 "Linux man-pages 6.7" .SH NAME stime \- set time .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int stime(const time_t *" t ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR stime (): .nf Since glibc 2.19: @@ -35,7 +35,7 @@ This function is deprecated; use .BR clock_settime (2) instead. -.PP +.P .BR stime () sets the system's idea of the time and date. The time, pointed @@ -62,7 +62,7 @@ privilege is required. None. .SH HISTORY SVr4. -.PP +.P Starting with glibc 2.31, this function is no longer available to newly linked applications and is no longer declared in diff --git a/man2/subpage_prot.2 b/man2/subpage_prot.2 index 4309a7d..aaeb883 100644 --- a/man2/subpage_prot.2 +++ b/man2/subpage_prot.2 @@ -7,7 +7,7 @@ .\" in Linux commit fa28237cfcc5827553044cbd6ee52e33692b0faa .\" both written by Paul Mackerras .\" -.TH subpage_prot 2 2023-03-30 "Linux man-pages 6.05.01" +.TH subpage_prot 2 2023-10-31 "Linux man-pages 6.7" .SH NAME subpage_prot \- define a subpage protection for an address range .SH LIBRARY @@ -17,11 +17,11 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_subpage_prot, unsigned long " addr ", unsigned long " len , .BI " uint32_t *" map ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR subpage_prot (), @@ -33,14 +33,14 @@ The PowerPC-specific system call provides the facility to control the access permissions on individual 4\ kB subpages on systems configured with a page size of 64\ kB. -.PP +.P The protection map is applied to the memory pages in the region starting at .I addr and continuing for .I len bytes. Both of these arguments must be aligned to a 64-kB boundary. -.PP +.P The protection map is specified in the buffer pointed to by .IR map . The map has 2 bits per 4\ kB subpage; @@ -80,7 +80,7 @@ Out of memory. Linux. .SH HISTORY Linux 2.6.25 (PowerPC). -.PP +.P The system call is provided only if the kernel is configured with .BR CONFIG_PPC_64K_PAGES . .SH NOTES @@ -113,6 +113,6 @@ hardware pages (on machines with hardware 64-kB page support). .SH SEE ALSO .BR mprotect (2), .BR syscall (2) -.PP +.P .I Documentation/admin\-guide/mm/hugetlbpage.rst in the Linux kernel source tree diff --git a/man2/swapon.2 b/man2/swapon.2 index 400f609..87bd6a0 100644 --- a/man2/swapon.2 +++ b/man2/swapon.2 @@ -22,7 +22,7 @@ .\" Author: Rafael Aquini .\" Date: Wed Jul 3 15:02:46 2013 -0700 .\" -.TH swapon 2 2023-03-30 "Linux man-pages 6.05.01" +.TH swapon 2 2023-12-22 "Linux man-pages 6.7" .SH NAME swapon, swapoff \- start/stop swapping to file/device .SH LIBRARY @@ -31,7 +31,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int swapon(const char *" path ", int " swapflags ); .BI "int swapoff(const char *" path ); .fi @@ -42,7 +42,7 @@ sets the swap area to the file or block device specified by .BR swapoff () stops swapping to the file or block device specified by .IR path . -.PP +.P If the .B SWAP_FLAG_PREFER flag is specified in the @@ -52,13 +52,13 @@ argument, the new swap area will have a higher priority than default. The priority is encoded within .I swapflags as: -.PP +.P .in +4n .EX .I "(prio << SWAP_FLAG_PRIO_SHIFT) & SWAP_FLAG_PRIO_MASK" .EE .in -.PP +.P If the .B SWAP_FLAG_DISCARD flag is specified in the @@ -69,7 +69,7 @@ if the swap device supports the discard or trim operation. (This may improve performance on some Solid State Devices, but often it does not.) See also NOTES. -.PP +.P These functions may be used only by a privileged process (one having the .B CAP_SYS_ADMIN capability). @@ -78,13 +78,13 @@ Each swap area has a priority, either high or low. The default priority is low. Within the low-priority areas, newer areas are even lower priority than older areas. -.PP +.P All priorities set with .I swapflags are high-priority, higher than default. They may have any nonnegative value chosen by the caller. Higher numbers mean higher priority. -.PP +.P Swap pages are allocated from areas in priority order, highest priority first. For areas with different priorities, @@ -92,7 +92,7 @@ a higher-priority area is exhausted before using a lower-priority area. If two or more areas have the same priority, and it is the highest priority available, pages are allocated on a round-robin basis between them. -.PP +.P As of Linux 1.3.6, the kernel usually follows these rules, but there are exceptions. .SH RETURN VALUE @@ -156,7 +156,7 @@ argument was introduced in Linux 1.3.2. .SH NOTES The partition or path must be prepared with .BR mkswap (8). -.PP +.P There is an upper limit on the number of swap files that may be used, defined by the kernel constant .BR MAX_SWAPFILES . @@ -164,7 +164,8 @@ Before Linux 2.4.10, .B MAX_SWAPFILES has the value 8; since Linux 2.4.10, it has the value 32. -Since Linux 2.6.18, the limit is decreased by 2 (thus: 30) +Since Linux 2.6.18, the limit is decreased by 2 (thus 30), +since Linux 5.19, the limit is decreased by 3 (thus: 29) if the kernel is built with the .B CONFIG_MIGRATION option @@ -180,7 +181,11 @@ Since Linux 5.14, the limit is further decreased by 4 if the kernel is built with the .B CONFIG_DEVICE_PRIVATE option. -.PP +Since Linux 5.19, the limit is further decreased by 1 +if the kernel is built with the +.B CONFIG_PTE_MARKER +option. +.P Discard of swap pages was introduced in Linux 2.6.29, then made conditional on the diff --git a/man2/symlink.2 b/man2/symlink.2 index dd87f2d..37db3c8 100644 --- a/man2/symlink.2 +++ b/man2/symlink.2 @@ -10,7 +10,7 @@ .\" Modified 1997-01-31 by Eric S. Raymond .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH symlink 2 2023-03-30 "Linux man-pages 6.05.01" +.TH symlink 2 2023-10-31 "Linux man-pages 6.7" .SH NAME symlink, symlinkat \- make a new name for a file .SH LIBRARY @@ -19,28 +19,28 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int symlink(const char *" target ", const char *" linkpath ); -.PP +.P .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int symlinkat(const char *" target ", int " newdirfd \ ", const char *" linkpath ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR symlink (): .nf _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR symlinkat (): .nf Since glibc 2.10: @@ -54,20 +54,20 @@ creates a symbolic link named .I linkpath which contains the string .IR target . -.PP +.P Symbolic links are interpreted at run time as if the contents of the link had been substituted into the path being followed to find a file or directory. -.PP +.P Symbolic links may contain .I .. path components, which (if used at the start of the link) refer to the parent directories of that in which the link resides. -.PP +.P A symbolic link (also known as a soft link) may point to an existing file or to a nonexistent one; the latter case is known as a dangling link. -.PP +.P The permissions of a symbolic link are irrelevant; the ownership is ignored when following the link (except when the @@ -79,7 +79,7 @@ renaming of the link is requested and the link is in a directory with the sticky bit .RB ( S_ISVTX ) set. -.PP +.P If .I linkpath exists, it will @@ -91,7 +91,7 @@ The system call operates in exactly the same way as .BR symlink (), except for the differences described here. -.PP +.P If the pathname given in .I linkpath is relative, then it is interpreted relative to the directory @@ -101,7 +101,7 @@ referred to by the file descriptor the calling process, as is done by .BR symlink () for a relative pathname). -.PP +.P If .I linkpath is relative and @@ -113,13 +113,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR symlink ()). -.PP +.P If .I linkpath is absolute, then .I newdirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -246,7 +246,7 @@ argument. No checking of .I target is done. -.PP +.P Deleting the name referred to by a symbolic link will actually delete the file (unless it also has other hard links). If this behavior is not desired, use diff --git a/man2/sync.2 b/man2/sync.2 index 21f01d7..a556c8e 100644 --- a/man2/sync.2 +++ b/man2/sync.2 @@ -13,7 +13,7 @@ .\" Modified 2001-10-10 by aeb, following Michael Kerrisk. .\" 2011-09-07, mtk, Added syncfs() documentation, .\" -.TH sync 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sync 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sync, syncfs \- commit filesystem caches to disk .SH LIBRARY @@ -22,17 +22,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B void sync(void); -.PP +.P .BI "int syncfs(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sync (): .nf _XOPEN_SOURCE >= 500 @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR syncfs (): .nf _GNU_SOURCE @@ -49,7 +49,7 @@ Feature Test Macro Requirements for glibc (see .BR sync () causes all pending modifications to filesystem metadata and cached file data to be written to the underlying filesystems. -.PP +.P .BR syncfs () is like .BR sync (), @@ -65,7 +65,7 @@ to indicate the error. .SH ERRORS .BR sync () is always successful. -.PP +.P .BR syncfs () can fail for at least the following reasons: .TP @@ -81,7 +81,9 @@ metadata related to the filesystem itself. .B ENOSPC Disk space was exhausted while synchronizing. .TP -.BR ENOSPC ", " EDQUOT +.B ENOSPC +.TQ +.B EDQUOT Data was written to a file on NFS or another filesystem which does not allocate space at the time of a .BR write (2) @@ -116,7 +118,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .BR syncfs () Linux 2.6.39, glibc 2.14. -.PP +.P Since glibc 2.2.2, the Linux prototype for .BR sync () is as listed above, @@ -125,7 +127,7 @@ In glibc 2.2.1 and earlier, it was "int sync(void)", and .BR sync () always returned 0. -.PP +.P In mainline kernel versions prior to Linux 5.8, .BR syncfs () will fail only when passed a bad file descriptor diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index f324f75..becef29 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -7,7 +7,7 @@ .\" Andrew Morton's comments in fs/sync.c .\" 2010-10-09, mtk, Document sync_file_range2() .\" -.TH sync_file_range 2 2023-07-15 "Linux man-pages 6.05.01" +.TH sync_file_range 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sync_file_range \- sync a file segment with disk .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #define _FILE_OFFSET_BITS 64 .B #include -.PP +.P .BI "int sync_file_range(int " fd ", off_t " offset ", off_t " nbytes , .BI " unsigned int " flags ); .fi @@ -28,7 +28,7 @@ permits fine control when synchronizing the open file referred to by the file descriptor .I fd with disk. -.PP +.P .I offset is the starting byte of the file range to be synchronized. .I nbytes @@ -42,7 +42,7 @@ Synchronization is in units of the system page size: is rounded down to a page boundary; .I (offset+nbytes\-1) is rounded up to a page boundary. -.PP +.P The .I flags bit-mask argument can include any of the following values: @@ -61,7 +61,7 @@ write more than request queue size. .B SYNC_FILE_RANGE_WAIT_AFTER Wait upon write-out of all pages in the range after performing any write. -.PP +.P Specifying .I flags as 0 is permitted, as a no-op. @@ -89,7 +89,7 @@ will detect any I/O errors or .B ENOSPC conditions and will return these to the caller. -.PP +.P Useful combinations of the .I flags bits are: @@ -173,14 +173,14 @@ arguments. for details.) Therefore, these architectures define a different system call that orders the arguments suitably: -.PP +.P .in +4n .EX .BI "int sync_file_range2(int " fd ", unsigned int " flags , .BI " off_t " offset ", off_t " nbytes ); .EE .in -.PP +.P The behavior of this system call is otherwise exactly the same as .BR sync_file_range (). .SH STANDARDS diff --git a/man2/syscall.2 b/man2/syscall.2 index 43f054a..01229e8 100644 --- a/man2/syscall.2 +++ b/man2/syscall.2 @@ -12,7 +12,7 @@ .\" 2015-01-17, Kees Cook .\" Added mips and arm64. .\" -.TH syscall 2 2023-05-03 "Linux man-pages 6.05.01" +.TH syscall 2 2023-10-31 "Linux man-pages 6.7" .SH NAME syscall \- indirect system call .SH LIBRARY @@ -22,15 +22,15 @@ Standard C library .nf .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "long syscall(long " number ", ...);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR syscall (): .nf Since glibc 2.19: @@ -49,13 +49,13 @@ Employing .BR syscall () is useful, for example, when invoking a system call that has no wrapper function in the C library. -.PP +.P .BR syscall () saves CPU registers before making the system call, restores the registers upon return from the system call, and stores any error returned by the system call in .BR errno (3). -.PP +.P Symbolic constants for system call numbers can be found in the header file .IR . .SH RETURN VALUE @@ -68,7 +68,7 @@ and an error number is stored in .TP .B ENOSYS The requested system call number is not implemented. -.PP +.P Other errors are specific to the invoked system call. .SH NOTES .BR syscall () @@ -85,7 +85,7 @@ However, when using to make a system call, the caller might need to handle architecture-dependent details; this requirement is most commonly encountered on certain 32-bit architectures. -.PP +.P For example, on the ARM architecture Embedded ABI (EABI), a 64-bit value (e.g., .IR "long long" ) @@ -97,7 +97,7 @@ the .BR readahead (2) system call would be invoked as follows on the ARM architecture with the EABI in little endian mode: -.PP +.P .in +4n .EX syscall(SYS_readahead, fd, 0, @@ -106,7 +106,7 @@ syscall(SYS_readahead, fd, 0, count); .EE .in -.PP +.P Since the offset argument is 64 bits, and the first argument .RI ( fd ) is passed in @@ -120,16 +120,16 @@ That means inserting a dummy value into (the second argument of 0). Care also must be taken so that the split follows endian conventions (according to the C ABI for the platform). -.PP +.P Similar issues can occur on MIPS with the O32 ABI, on PowerPC and parisc with the 32-bit ABI, and on Xtensa. .\" Mike Frysinger: this issue ends up forcing MIPS .\" O32 to take 7 arguments to syscall() -.PP +.P .\" See arch/parisc/kernel/sys_parisc.c. Note that while the parisc C ABI also uses aligned register pairs, it uses a shim layer to hide the issue from user space. -.PP +.P The affected system calls are .BR fadvise64_64 (2), .BR ftruncate64 (2), @@ -140,7 +140,7 @@ The affected system calls are .BR sync_file_range (2), and .BR truncate64 (2). -.PP +.P .\" You need to look up the syscalls directly in the kernel source to see if .\" they should be in this list. For example, look at fs/read_write.c and .\" the function signatures that do: @@ -159,7 +159,7 @@ Welcome to the wonderful world of historical baggage. Every architecture has its own way of invoking and passing arguments to the kernel. The details for various architectures are listed in the two tables below. -.PP +.P The first table lists the instruction used to transition to kernel mode (which might not be the fastest or best way to transition to the kernel, so you might have to refer to @@ -202,7 +202,7 @@ x86-64 syscall rax rax rdx - 5 x32 syscall rax rax rdx - 5 xtensa syscall a2 a2 - - .TE -.PP +.P Notes: .IP \[bu] 3 On a few architectures, @@ -292,7 +292,7 @@ in the system call interface, even if it is defined in the System V ABI. .in .ft P \} -.PP +.P The second table shows the registers used to pass the system call arguments. .if t \{\ .ft CW @@ -329,7 +329,7 @@ x86-64 rdi rsi rdx r10 r8 r9 - x32 rdi rsi rdx r10 r8 r9 - xtensa a6 a3 a4 a5 a8 a9 - .TE -.PP +.P Notes: .IP \[bu] 3 The mips/o32 system call convention passes @@ -338,7 +338,7 @@ arguments 5 through 8 on the user stack. .in .ft P \} -.PP +.P Note that these tables don't cover the entire calling convention\[em]some architectures may indiscriminately clobber other registers not listed here. .SH EXAMPLES diff --git a/man2/syscalls.2 b/man2/syscalls.2 index 1011c14..09535aa 100644 --- a/man2/syscalls.2 +++ b/man2/syscalls.2 @@ -9,7 +9,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH syscalls 2 2023-07-30 "Linux man-pages 6.05.01" +.TH syscalls 2 2024-02-18 "Linux man-pages 6.7" .SH NAME syscalls \- Linux system calls .SH SYNOPSIS @@ -29,7 +29,7 @@ as the name of the system call that it invokes. For example, glibc contains a function .BR chdir () which invokes the underlying "chdir" system call. -.PP +.P Often the glibc wrapper function is quite thin, doing little work other than copying arguments to the right registers before invoking the system call, @@ -49,7 +49,7 @@ the wrapper function negates the returned error number (to make it positive), copies it to .IR errno , and returns \-1 to the caller of the wrapper. -.PP +.P Sometimes, however, the wrapper function does some extra work before invoking the system call. For example, nowadays there are (for reasons described below) two @@ -76,8 +76,8 @@ the system call appeared in Linux 1.0 or earlier. Where a system call is marked "1.2" this means the system call probably appeared in a Linux 1.1.x kernel version, and first appeared in a stable kernel with 1.2. -(Development of the 1.2 kernel was initiated from a branch of kernel -1.0.6 via the 1.1.x unstable kernel series.) +(Development of the Linux 1.2 kernel was initiated from a branch of +Linux 1.0.6 via the Linux 1.1.x unstable kernel series.) .IP \[bu] Where a system call is marked "2.0" this means the system call probably appeared in a Linux 1.3.x kernel version, @@ -98,7 +98,7 @@ via the Linux 1.3.x unstable kernel series.) Where a system call is marked "2.2" this means the system call probably appeared in a Linux 2.1.x kernel version, and first appeared in a stable kernel with Linux 2.2.0. -(Development of the Linux 2.2 kernel was initiated from a branch of kernel +(Development of the Linux 2.2 kernel was initiated from a branch of Linux 2.0.21 via the Linux 2.1.x unstable kernel series.) .IP \[bu] Where a system call is marked "2.4" @@ -120,7 +120,8 @@ is shown. This convention continues with the Linux 3.x kernel series, which followed on from Linux 2.6.39; and the Linux 4.x kernel series, which followed on from Linux 3.19; and the Linux 5.x kernel series, -which followed on from Linux 4.20. +which followed on from Linux 4.20; and the Linux 6.x kernel series, +which followed on from Linux 5.19. .IP \[bu] In some cases, a system call was added to a stable kernel series after it branched from the previous stable kernel @@ -129,19 +130,19 @@ For example some system calls that appeared in Linux 2.6.x were also backported into a Linux 2.4.x release after Linux 2.4.15. When this is so, the version where the system call appeared in both of the major kernel series is listed. -.PP +.P The list of system calls that are available as at Linux 5.14 (or in a few cases only on older kernels) is as follows: +.P .\" .\" Looking at scripts/checksyscalls.sh in the kernel source is .\" instructive about x86 specifics. .\" .TS -l2 le l ---- -l l l. -\fBSystem call\fP \fBKernel\fP \fBNotes\fP - +Lb Lb Lb +L2 L L. +System call Kernel Notes +_ \fB_llseek\fP(2) 1.2 \fB_newselect\fP(2) 2.0 \fB_sysctl\fP(2) 2.0 Removed in 5.5 @@ -832,13 +833,13 @@ T} .\" 5a0015d62668e64c8b6e02e360fbbea121bfd5e6 \fBxtensa\fP(2) 2.6.13 Xtensa only .TE -.PP +.P On many platforms, including x86-32, socket calls are all multiplexed (via glibc wrapper functions) through .BR socketcall (2) and similarly System\ V IPC calls are multiplexed through .BR ipc (2). -.PP +.P Although slots are reserved for them in the system call table, the following system calls are not implemented in the standard kernel: .BR afs_syscall (2), \" __NR_afs_syscall is 53 on Linux 2.6.22/i386 @@ -883,7 +884,7 @@ and .BR putpmsg (2) calls are for kernels patched to support STREAMS, and may never be in the standard kernel. -.PP +.P There was briefly .BR set_zone_reclaim (2), added in Linux 2.6.13, and removed in Linux 2.6.16; @@ -967,7 +968,7 @@ proprietary operating-system emulation, such as sparc, sparc64, and alpha, there are many additional system calls; mips64 also contains a full set of 32-bit system calls. -.PP +.P Over time, changes to the interfaces of some system calls have been necessary. One reason for such changes was the need to increase the size of @@ -984,7 +985,7 @@ details such as the size of their arguments. the glibc wrapper functions do some work to ensure that the right system call is invoked, and that ABI compatibility is preserved for old binaries.) -Examples of systems calls that exist in multiple versions are +Examples of system calls that exist in multiple versions are the following: .IP \[bu] 3 By now there are three different versions of @@ -1111,7 +1112,7 @@ and similarly .IR __NR_mmap2 . s390x is the only 64-bit architecture that has .IR old_mmap (). -.\" .PP +.\" .P .\" Two system call numbers, .\" .IR __NR__llseek .\" and diff --git a/man2/sysctl.2 b/man2/sysctl.2 index fbe967f..082545e 100644 --- a/man2/sysctl.2 +++ b/man2/sysctl.2 @@ -7,27 +7,27 @@ .\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond .\" Modified Mon Jan 5 20:31:04 1998 by aeb. .\" -.TH sysctl 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sysctl 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sysctl \- read/write system parameters .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .BI "[[deprecated]] int _sysctl(struct __sysctl_args *" args ); .fi .SH DESCRIPTION .B This system call no longer exists on current kernels! See NOTES. -.PP +.P The .BR _sysctl () call reads and/or writes kernel parameters. For example, the hostname, or the maximum number of open files. The argument has the form -.PP +.P .in +4n .EX struct __sysctl_args { @@ -41,7 +41,7 @@ struct __sysctl_args { }; .EE .in -.PP +.P This call does a search in a tree structure, possibly resembling a directory tree under .IR /proc/sys , @@ -56,7 +56,9 @@ Otherwise, a value of \-1 is returned and is set to indicate the error. .SH ERRORS .TP -.BR EACCES ", " EPERM +.B EACCES +.TQ +.B EPERM No search permission for one of the encountered "directories", or no read permission where .I oldval @@ -78,7 +80,7 @@ Linux. .SH HISTORY Linux 1.3.57. Removed in Linux 5.5, glibc 2.32. -.PP +.P It originated in 4.4BSD. Only Linux has the @@ -95,7 +97,7 @@ and in Linux 5.5, the system call was finally removed. Use the .I /proc/sys interface instead. -.PP +.P Note that on older kernels where this system call still exists, it is available only if the kernel was configured with the .B CONFIG_SYSCTL_SYSCALL @@ -106,9 +108,9 @@ necessitating the use of .SH BUGS The object names vary between kernel versions, making this system call worthless for applications. -.PP +.P Not all available objects are properly documented. -.PP +.P It is not yet possible to change operating system by writing to .IR /proc/sys/kernel/ostype . .SH EXAMPLES diff --git a/man2/sysfs.2 b/man2/sysfs.2 index d650a9c..06507fd 100644 --- a/man2/sysfs.2 +++ b/man2/sysfs.2 @@ -4,7 +4,7 @@ .\" .\" Created Wed Aug 9 1995 Thomas K. Dyas .\" -.TH sysfs 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sysfs 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sysfs \- get filesystem type information .SH SYNOPSIS @@ -21,7 +21,7 @@ filesystem that is normally mounted at .IR /sys , see .BR sysfs (5). -.PP +.P The (obsolete) .BR sysfs () system call returns information about the filesystem types @@ -51,7 +51,7 @@ has enough space to accept the string. .B 3 Return the total number of filesystem types currently present in the kernel. -.PP +.P The numbering of the filesystem type indexes begins with zero. .SH RETURN VALUE On success, @@ -82,7 +82,7 @@ is invalid. None. .SH HISTORY SVr4. -.PP +.P This System-V derived system call is obsolete; don't use it. On systems with .IR /proc , diff --git a/man2/sysinfo.2 b/man2/sysinfo.2 index fc44136..5566b4b 100644 --- a/man2/sysinfo.2 +++ b/man2/sysinfo.2 @@ -12,7 +12,7 @@ .\" Modified Tue Oct 22 22:29:51 1996 by Eric S. Raymond .\" Modified Mon Aug 25 16:06:11 1997 by Nicolás Lichtmaier .\" -.TH sysinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.TH sysinfo 2 2023-10-31 "Linux man-pages 6.7" .SH NAME sysinfo \- return system information .SH LIBRARY @@ -21,18 +21,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sysinfo(struct sysinfo *" info ); .fi .SH DESCRIPTION .BR sysinfo () returns certain statistics on memory and swap usage, as well as the load average. -.PP +.P Until Linux 2.3.16, .BR sysinfo () returned information in the following structure: -.PP +.P .in +4n .EX struct sysinfo { @@ -49,13 +49,13 @@ struct sysinfo { }; .EE .in -.PP +.P In the above structure, the sizes of the memory and swap fields are given in bytes. -.PP +.P Since Linux 2.3.23 (i386) and Linux 2.3.48 (all architectures) the structure is: -.PP +.P .in +4n .EX struct sysinfo { @@ -76,7 +76,7 @@ struct sysinfo { }; .EE .in -.PP +.P In the above structure, sizes of the memory and swap fields are given as multiples of .I mem_unit diff --git a/man2/syslog.2 b/man2/syslog.2 index 4e90778..a799c82 100644 --- a/man2/syslog.2 +++ b/man2/syslog.2 @@ -10,7 +10,7 @@ .\" 2008-02-15, Michael Kerrisk .\" Update LOG_BUF_LEN details; update RETURN VALUE section. .\" -.TH syslog 2 2023-03-30 "Linux man-pages 6.05.01" +.TH syslog 2 2023-10-31 "Linux man-pages 6.7" .SH NAME syslog, klogctl \- read and/or clear kernel message ring buffer; set console_loglevel @@ -22,12 +22,12 @@ Standard C library .BR "#include " " /* Definition of " SYSLOG_* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len ); -.PP +.P /* The glibc interface */ .B #include -.PP +.P .BI "int klogctl(int " type ", char *" bufp ", int " len ); .fi .SH DESCRIPTION @@ -39,7 +39,7 @@ which talks to see .BR syslog (3) for details. -.PP +.P This page describes the kernel .BR syslog () system call, which is used to control the kernel @@ -208,7 +208,7 @@ The and .I len arguments are ignored. -.PP +.P All commands except 3 and 10 require privilege. In Linux kernels before Linux 2.6.37, command types 3 and 10 are allowed to unprivileged processes; @@ -300,7 +300,7 @@ T} KERN_INFO 6 Informational KERN_DEBUG 7 Debug-level messages .TE -.sp 1 +.P The kernel .I printk() routine will print a message on the @@ -319,7 +319,7 @@ For \fItype\fP 10, .BR syslog () returns the total size of the kernel log buffer. For other values of \fItype\fP, 0 is returned on success. -.PP +.P In case of error, \-1 is returned, and \fIerrno\fP is set to indicate the error. .SH ERRORS diff --git a/man2/tee.2 b/man2/tee.2 index 7a3a6b1..e9ae11f 100644 --- a/man2/tee.2 +++ b/man2/tee.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tee 2 2023-05-03 "Linux man-pages 6.05.01" +.TH tee 2 2023-10-31 "Linux man-pages 6.7" .SH NAME tee \- duplicating pipe content .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "ssize_t tee(int " fd_in ", int " fd_out ", size_t " len \ ", unsigned int " flags ); .fi @@ -36,7 +36,7 @@ It does not consume the data that is duplicated from .IR fd_in ; therefore, that data can be copied by a subsequent .BR splice (2). -.PP +.P .I flags is a bit mask that is composed by ORing together zero or more of the following values: @@ -72,7 +72,7 @@ A return value of 0 means that there was no data to transfer, and it would not make sense to block, because there are no writers connected to the write end of the pipe referred to by .IR fd_in . -.PP +.P On error, .BR tee () returns \-1 and @@ -121,7 +121,7 @@ program using the .BR tee () system call. Here is an example of its use: -.PP +.P .in +4n .EX $ \fBdate | ./a.out out.log | cat\fP diff --git a/man2/time.2 b/man2/time.2 index f121e9c..5ac0bc4 100644 --- a/man2/time.2 +++ b/man2/time.2 @@ -6,7 +6,7 @@ .\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith .\" Additions by Joseph S. Myers , 970909 .\" -.TH time 2 2023-03-30 "Linux man-pages 6.05.01" +.TH time 2 2023-11-11 "Linux man-pages 6.7" .SH NAME time \- get time in seconds .SH LIBRARY @@ -15,14 +15,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "time_t time(time_t *_Nullable " tloc ); .fi .SH DESCRIPTION .BR time () returns the time as the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P If .I tloc is non-NULL, @@ -35,6 +35,17 @@ On error, \fI((time_t)\ \-1)\fP is returned, and is set to indicate the error. .SH ERRORS .TP +.B EOVERFLOW +The time cannot be represented as a +.I time_t +value. +This can happen if an executable with 32-bit +.I time_t +is run on a 64-bit kernel when the time is 2038-01-19 03:14:08 UTC or later. +However, when the system time is out of +.I time_t +range in other situations, the behavior is undefined. +.TP .B EFAULT .I tloc points outside your accessible address space (but see BUGS). @@ -60,29 +71,15 @@ in which case they are leap years. This value is not the same as the actual number of seconds between the time and the Epoch, because of leap seconds and because system clocks are not required to be synchronized to a standard reference. -The intention is that the interpretation of seconds since the Epoch values be -consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale. -.PP -On Linux, a call to -.BR time () -with -.I tloc -specified as NULL cannot fail with the error -.BR EOVERFLOW , -even on ABIs where -.I time_t -is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds -(2038-01-19 03:14:08 UTC, ignoring leap seconds). -(POSIX.1 permits, but does not require, the -.B EOVERFLOW -error in the case where the seconds since the Epoch will not fit in -.IR time_t .) -Instead, the behavior on Linux is undefined when the system time is out of the -.I time_t -range. +Linux systems normally follow the POSIX requirement +that this value ignore leap seconds, +so that conforming systems interpret it consistently; +see POSIX.1-2018 Rationale A.4.16. +.P Applications intended to run after 2038 should use ABIs with .I time_t -wider than 32 bits. +wider than 32 bits; see +.BR time_t (3type). .SS C library/kernel differences On some architectures, an implementation of .BR time () @@ -101,7 +98,7 @@ successful reports that the time is a few seconds the Epoch, so the C library wrapper function never sets .I errno as a result of this call. -.PP +.P The .I tloc argument is obsolescent and should always be NULL in new code. diff --git a/man2/timer_create.2 b/man2/timer_create.2 index 3265b27..44d505d 100644 --- a/man2/timer_create.2 +++ b/man2/timer_create.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_create 2 2023-05-03 "Linux man-pages 6.05.01" +.TH timer_create 2 2023-11-11 "Linux man-pages 6.7" .SH NAME timer_create \- create a POSIX per-process timer .SH LIBRARY @@ -13,17 +13,17 @@ Real-time library .nf .BR "#include " " /* Definition of " SIGEV_* " constants */" .B #include -.PP +.P .BI "int timer_create(clockid_t " clockid , .BI " struct sigevent *_Nullable restrict " sevp , .BI " timer_t *restrict " timerid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_create (): .nf _POSIX_C_SOURCE >= 199309L @@ -36,7 +36,7 @@ The ID of the new timer is returned in the buffer pointed to by which must be a non-null pointer. This ID is unique within the process, until the timer is deleted. The new timer is initially disarmed. -.PP +.P The .I clockid argument specifies the clock that the new timer uses to measure time. @@ -96,12 +96,12 @@ The caller must have the capability in order to set a timer against this clock. .TP .BR CLOCK_TAI " (since Linux 3.10)" -A system-wide clock derived from wall-clock time but ignoring leap seconds. -.PP +A system-wide clock derived from wall-clock time but counting leap seconds. +.P See .BR clock_getres (2) for some further details on the above clocks. -.PP +.P As well as the above values, .I clockid can be specified as the @@ -110,7 +110,7 @@ returned by a call to .BR clock_getcpuclockid (3) or .BR pthread_getcpuclockid (3). -.PP +.P The .I sevp argument points to a @@ -118,8 +118,8 @@ argument points to a structure that specifies how the caller should be notified when the timer expires. For the definition and general details of this structure, see -.BR sigevent (7). -.PP +.BR sigevent (3type). +.P The .I sevp.sigev_notify field can have the following values: @@ -134,7 +134,7 @@ Upon timer expiration, generate the signal .I sigev_signo for the process. See -.BR sigevent (7) +.BR sigevent (3type) for general details. The .I si_code @@ -152,7 +152,7 @@ Upon timer expiration, invoke .I sigev_notify_function as if it were the start function of a new thread. See -.BR sigevent (7) +.BR sigevent (3type) for details. .TP .BR SIGEV_THREAD_ID " (Linux-specific)" @@ -168,7 +168,7 @@ field specifies a kernel thread ID, that is, the value returned by or .BR gettid (2). This flag is intended only for use by threading libraries. -.PP +.P Specifying .I sevp as NULL is equivalent to specifying a pointer to a @@ -258,7 +258,7 @@ POSIX.1-2008. .SH HISTORY Linux 2.6. POSIX.1-2001. -.PP +.P Prior to Linux 2.6, glibc provided an incomplete user-space implementation .RB ( CLOCK_REALTIME @@ -270,12 +270,12 @@ running kernels older than Linux 2.6. .SH NOTES A program may create multiple interval timers using .BR timer_create (). -.PP +.P Timers are not inherited by the child of a .BR fork (2), and are disarmed and deleted during an .BR execve (2). -.PP +.P The kernel preallocates a "queued real-time signal" for each timer created using .BR timer_create (). @@ -283,7 +283,7 @@ Consequently, the number of timers is limited by the .B RLIMIT_SIGPENDING resource limit (see .BR setrlimit (2)). -.PP +.P The timers created by .BR timer_create () are commonly known as "POSIX (interval) timers". @@ -304,7 +304,7 @@ Return the overrun count for the last timer expiration. .TP .BR timer_delete (2) Disarm and delete a timer. -.PP +.P Since Linux 3.10, the .IR /proc/ pid /timers file can be used to list the POSIX timers for the process with PID @@ -312,7 +312,7 @@ file can be used to list the POSIX timers for the process with PID See .BR proc (5) for further information. -.PP +.P Since Linux 4.10, .\" baa73d9e478ff32d62f3f9422822b59dd9a95a21 support for POSIX timers is a configurable option that is enabled by default. @@ -331,12 +331,12 @@ Assuming that the timer expired at least once while the program slept, the signal handler will be invoked, and the handler displays some information about the timer notification. The program terminates after one invocation of the signal handler. -.PP +.P In the following example run, the program sleeps for 1 second, after creating a timer that has a frequency of 100 nanoseconds. By the time the signal is unblocked and delivered, there have been around ten million overruns. -.PP +.P .in +4n .EX $ \fB./a.out 1 100\fP @@ -482,6 +482,6 @@ main(int argc, char *argv[]) .BR clock_getcpuclockid (3), .BR pthread_getcpuclockid (3), .BR pthreads (7), -.BR sigevent (7), +.BR sigevent (3type), .BR signal (7), .BR time (7) diff --git a/man2/timer_delete.2 b/man2/timer_delete.2 index ee1468e..b08d736 100644 --- a/man2/timer_delete.2 +++ b/man2/timer_delete.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_delete 2 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_delete 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_delete \- delete a POSIX per-process timer .SH LIBRARY @@ -12,15 +12,15 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int timer_delete(timer_t " timerid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_delete (): .nf _POSIX_C_SOURCE >= 199309L diff --git a/man2/timer_getoverrun.2 b/man2/timer_getoverrun.2 index 7521957..0f136b6 100644 --- a/man2/timer_getoverrun.2 +++ b/man2/timer_getoverrun.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_getoverrun 2 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_getoverrun 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_getoverrun \- get overrun count for a POSIX per-process timer .SH LIBRARY @@ -12,15 +12,15 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int timer_getoverrun(timer_t " timerid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_getoverrun (): .nf _POSIX_C_SOURCE >= 199309L @@ -36,7 +36,7 @@ via signals .RB ( SIGEV_SIGNAL ), and via threads .RB ( SIGEV_THREAD ). -.PP +.P When expiration notifications are delivered via a signal, overruns can occur as follows. Regardless of whether or not a real-time signal is used for @@ -56,7 +56,7 @@ In this interval, further timer expirations may occur. The timer overrun count is the number of additional timer expirations that occurred between the time when the signal was generated and when it was delivered or accepted. -.PP +.P Timer overruns can also occur when expiration notifications are delivered via invocation of a thread, since there may be an arbitrary delay between an expiration of the timer @@ -87,7 +87,7 @@ structure (see This allows an application to avoid the overhead of making a system call to obtain the overrun count, but is a nonportable extension to POSIX.1. -.PP +.P POSIX.1 discusses timer overruns only in the context of timer notifications using signals. .\" FIXME . Austin bug filed, 11 Feb 09 diff --git a/man2/timer_settime.2 b/man2/timer_settime.2 index 030bab5..d222fe4 100644 --- a/man2/timer_settime.2 +++ b/man2/timer_settime.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timer_settime 2 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_settime 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_settime, timer_gettime \- arm/disarm and fetch state of POSIX per-process timer @@ -13,18 +13,18 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value ); .BI "int timer_settime(timer_t " timerid ", int " flags , .BI " const struct itimerspec *restrict " new_value , .BI " struct itimerspec *_Nullable restrict " old_value ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timer_settime (), .BR timer_gettime (): .nf @@ -44,7 +44,7 @@ The .I itimerspec structure is described in .BR itimerspec (3type). -.PP +.P Each of the substructures of the .I itimerspec structure is a @@ -54,7 +54,7 @@ in seconds and nanoseconds. These time values are measured according to the clock that was specified when the timer was created by .BR timer_create (2). -.PP +.P If .I new_value\->it_value specifies a nonzero value (i.e., either subfield is nonzero), then @@ -68,7 +68,7 @@ If specifies a zero value (i.e., both subfields are zero), then the timer is disarmed. -.PP +.P The .I new_value\->it_interval field specifies the period of the timer, in seconds and nanoseconds. @@ -80,7 +80,7 @@ If specifies a zero value, then the timer expires just once, at the time specified by .IR it_value . -.PP +.P By default, the initial expiration time specified in .I new_value\->it_value is interpreted relative to the current time on the timer's @@ -101,7 +101,7 @@ and the overrun count (see .BR timer_getoverrun (2)) will be set correctly. .\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME. -.PP +.P If the value of the .B CLOCK_REALTIME clock is adjusted while an absolute timer based on that clock is armed, @@ -111,7 +111,7 @@ Adjustments to the clock have no effect on relative timers based on that clock. .\" Similar remarks might apply with respect to process and thread CPU time .\" clocks, but these clocks are not currently (2.6.28) settable on Linux. -.PP +.P If .I old_value is not NULL, then it points to a buffer @@ -120,7 +120,7 @@ that is used to return the previous interval of the timer (in and the amount of time until the timer would previously have next expired (in .IR old_value\->it_value ). -.PP +.P .BR timer_gettime () returns the time until next expiration, and the interval, for the timer specified by @@ -163,7 +163,7 @@ is not a valid pointer. .I timerid is invalid. .\" FIXME . eventually: invalid value in flags -.PP +.P .BR timer_settime () may fail with the following errors: .TP diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2 index 6ceea56..1d6a0d2 100644 --- a/man2/timerfd_create.2 +++ b/man2/timerfd_create.2 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH timerfd_create 2 2023-05-03 "Linux man-pages 6.05.01" +.TH timerfd_create 2 2023-10-31 "Linux man-pages 6.7" .SH NAME timerfd_create, timerfd_settime, timerfd_gettime \- timers that notify via file descriptors @@ -12,9 +12,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int timerfd_create(int " clockid ", int " flags ); -.PP +.P .BI "int timerfd_settime(int " fd ", int " flags , .BI " const struct itimerspec *" new_value , .BI " struct itimerspec *_Nullable " old_value ); @@ -32,7 +32,7 @@ with the advantage that the file descriptor may be monitored by .BR poll (2), and .BR epoll (7). -.PP +.P The use of these three system calls is analogous to the use of .BR timer_create (2), .BR timer_settime (2), @@ -93,14 +93,14 @@ but will wake the system if it is suspended. The caller must have the .B CAP_WAKE_ALARM capability in order to set a timer against this clock. -.PP +.P See .BR clock_getres (2) for some further details on the above clocks. -.PP +.P The current value of each of these clocks can be retrieved using .BR clock_gettime (2). -.PP +.P Starting with Linux 2.6.27, the following values may be bitwise ORed in .I flags to change the behavior of @@ -125,7 +125,7 @@ See the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P In Linux versions up to and including 2.6.26, .I flags must be specified as zero. @@ -134,7 +134,7 @@ must be specified as zero. arms (starts) or disarms (stops) the timer referred to by the file descriptor .IR fd . -.PP +.P The .I new_value argument specifies the initial expiration and interval for the timer. @@ -142,7 +142,7 @@ The .I itimerspec structure used for this argument is described in .BR itimerspec (3type). -.PP +.P .I new_value.it_value specifies the initial expiration of the timer, in seconds and nanoseconds. @@ -152,7 +152,7 @@ to a nonzero value arms the timer. Setting both fields of .I new_value.it_value to zero disarms the timer. -.PP +.P Setting one or both fields of .I new_value.it_interval to nonzero values specifies the period, in seconds and nanoseconds, @@ -161,7 +161,7 @@ If both fields of .I new_value.it_interval are zero, the timer expires just once, at the time specified by .IR new_value.it_value . -.PP +.P By default, the initial expiration time specified in .I new_value @@ -173,7 +173,7 @@ specifies a time relative to the current value of the clock specified by An absolute timeout can be selected via the .I flags argument. -.PP +.P The .I flags argument is a bit mask that can include the following values: @@ -202,7 +202,7 @@ When such changes occur, a current or future .BR read (2) from the file descriptor will fail with the error .BR ECANCELED . -.PP +.P If the .I old_value argument is not NULL, then the @@ -222,7 +222,7 @@ an structure that contains the current setting of the timer referred to by the file descriptor .IR fd . -.PP +.P The .I it_value field returns the amount of time @@ -232,7 +232,7 @@ then the timer is currently disarmed. This field always contains a relative value, regardless of whether the .B TFD_TIMER_ABSTIME flag was specified when setting the timer. -.PP +.P The .I it_interval field returns the interval of the timer. @@ -317,7 +317,11 @@ but before the .BR read (2) on the file descriptor. .TP -.BR poll "(2), " select "(2) (and similar)" +.BR poll (2) +.TQ +.BR select (2) +.TQ +(and similar) The file descriptor is readable (the .BR select (2) @@ -384,7 +388,7 @@ returns a new file descriptor. On error, \-1 is returned and .I errno is set to indicate the error. -.PP +.P .BR timerfd_settime () and .BR timerfd_gettime () @@ -430,7 +434,7 @@ or but the caller did not have the .B CAP_WAKE_ALARM capability. -.PP +.P .BR timerfd_settime () and .BR timerfd_gettime () @@ -450,7 +454,7 @@ is not a valid pointer. .B EINVAL .I fd is not a valid timerfd file descriptor. -.PP +.P .BR timerfd_settime () can also fail with the following errors: .TP @@ -500,7 +504,7 @@ the caller once more calls to rearm the timer (without first doing a .BR read (2) on the file descriptor). -.PP +.P In this case the following occurs: .IP \[bu] 3 The @@ -534,9 +538,9 @@ The second argument specifies the interval for the timer, in seconds. The third argument specifies the number of times the program should allow the timer to expire before terminating. The second and third command-line arguments are optional. -.PP +.P The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " a.out 3 1 100" diff --git a/man2/times.2 b/man2/times.2 index 1d85010..2dad5b5 100644 --- a/man2/times.2 +++ b/man2/times.2 @@ -15,7 +15,7 @@ .\" Added notes on nonstandard behavior: Linux allows 'buf' to .\" be NULL, but POSIX.1 doesn't specify this and it's nonportable. .\" -.TH times 2 2023-03-30 "Linux man-pages 6.05.01" +.TH times 2 2023-10-31 "Linux man-pages 6.7" .SH NAME times \- get process times .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "clock_t times(struct tms *" buf ); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ The .I struct tms is as defined in .IR : -.PP +.P .in +4n .EX struct tms { @@ -49,7 +49,7 @@ struct tms { }; .EE .in -.PP +.P The .I tms_utime field contains the CPU time spent executing instructions @@ -58,7 +58,7 @@ The .I tms_stime field contains the CPU time spent executing inside the kernel while performing tasks on behalf of the calling process. -.PP +.P The .I tms_cutime field contains the sum of the @@ -73,7 +73,7 @@ field contains the sum of the and .I tms_cstime values for all waited-for terminated children. -.PP +.P Times for terminated children (and their descendants) are added in at the moment .BR wait (2) @@ -83,7 +83,7 @@ returns their process ID. In particular, times of grandchildren that the children did not wait for are never seen. -.PP +.P All times reported are in clock ticks. .SH RETURN VALUE .BR times () @@ -120,12 +120,12 @@ POSIX.1-2008. POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P In POSIX.1-1996 the symbol \fBCLK_TCK\fP (defined in .IR ) is mentioned as obsolescent. It is obsolete now. -.PP +.P Before Linux 2.6.9, if the disposition of .B SIGCHLD @@ -145,7 +145,7 @@ This nonconformance is rectified in Linux 2.6.9 and later. .\" See the description of times() in XSH, which says: .\" The times of a terminated child process are included... when wait() .\" or waitpid() returns the process ID of this terminated child. -.PP +.P On Linux, the \[lq]arbitrary point in the past\[rq] from which the return value of @@ -164,10 +164,10 @@ To measure changes in elapsed time, use .BR clock_gettime (2) instead. -.\" .PP +.\" .P .\" On older systems the number of clock ticks per second is given .\" by the variable HZ. -.PP +.P SVr1-3 returns .I long and the struct members are of type @@ -182,13 +182,13 @@ because it had no type yet. .SH NOTES The number of clock ticks per second can be obtained using: -.PP +.P .in +4n .EX sysconf(_SC_CLK_TCK); .EE .in -.PP +.P Note that .BR clock (3) also returns a value of type diff --git a/man2/tkill.2 b/man2/tkill.2 index 8780e8a..78a1ce5 100644 --- a/man2/tkill.2 +++ b/man2/tkill.2 @@ -6,7 +6,7 @@ .\" 2004-05-31, added tgkill, ahu, aeb .\" 2008-01-15 mtk -- rewrote DESCRIPTION .\" -.TH tkill 2 2023-03-30 "Linux man-pages 6.05.01" +.TH tkill 2 2023-10-31 "Linux man-pages 6.7" .SH NAME tkill, tgkill \- send a signal to a thread .SH LIBRARY @@ -17,14 +17,14 @@ Standard C library .BR "#include " " /* Definition of " SIG* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include -.PP +.P .BI "[[deprecated]] int syscall(SYS_tkill, pid_t " tid ", int " sig ); -.PP +.P .B #include -.PP +.P .BI "int tgkill(pid_t " tgid ", pid_t " tid ", int " sig ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR tkill (), @@ -43,7 +43,7 @@ in the thread group can be used to send a signal only to a process (i.e., thread group) as a whole, and the signal will be delivered to an arbitrary thread within that process.) -.PP +.P .BR tkill () is an obsolete predecessor to .BR tgkill (). @@ -76,7 +76,7 @@ Avoid using this system call. .\" measurable, one could exhaust all but 1-2 available pid values, .\" possibly by lowering the max pid parameter in /proc, forcing .\" the same tid to be reused rapidly. -.PP +.P These are the raw system call interfaces, meant for internal thread library use. .SH RETURN VALUE diff --git a/man2/truncate.2 b/man2/truncate.2 index 02a12e5..13ebec0 100644 --- a/man2/truncate.2 +++ b/man2/truncate.2 @@ -12,7 +12,7 @@ .\" Modified 2002-04-06 by Andries Brouwer .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH truncate 2 2023-03-30 "Linux man-pages 6.05.01" +.TH truncate 2 2023-10-31 "Linux man-pages 6.7" .SH NAME truncate, ftruncate \- truncate a file to a specified length .SH LIBRARY @@ -21,16 +21,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int truncate(const char *" path ", off_t " length ); .BI "int ftruncate(int " fd ", off_t " length ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR truncate (): .nf _XOPEN_SOURCE >= 500 @@ -38,7 +38,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR ftruncate (): .nf _XOPEN_SOURCE >= 500 @@ -58,20 +58,20 @@ or referenced by to be truncated to a size of precisely .I length bytes. -.PP +.P If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes (\[aq]\e0\[aq]). -.PP +.P The file offset is not changed. -.PP +.P If the size changed, then the st_ctime and st_mtime fields (respectively, time of last status change and time of last modification; see .BR inode (7)) for the file are updated, and the set-user-ID and set-group-ID mode bits may be cleared. -.PP +.P With .BR ftruncate (), the file must be open for writing; with @@ -148,7 +148,7 @@ The named file resides on a read-only filesystem. .TP .B ETXTBSY The file is an executable file that is being executed. -.PP +.P For .BR ftruncate () the same errors apply, but instead of things that can be wrong with @@ -197,7 +197,7 @@ and to be used to extend a file beyond its current length: a notable example on Linux is VFAT. .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 -.PP +.P On some 32-bit architectures, the calling signature for these system calls differ, for the reasons described in @@ -212,13 +212,13 @@ POSIX.1-2001, .\" POSIX.1-2001 also has .\" .BR truncate (), .\" as an XSI extension. -.\" .LP +.\" .P .\" SVr4 documents additional .\" .BR truncate () .\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for .\" .BR ftruncate () .\" an additional EAGAIN error condition. -.PP +.P The original Linux .BR truncate () and diff --git a/man2/umask.2 b/man2/umask.2 index c920b55..bfea2e6 100644 --- a/man2/umask.2 +++ b/man2/umask.2 @@ -11,7 +11,7 @@ .\" with Lars Wirzenius suggestion .\" 2006-05-13, mtk, substantial rewrite of description of 'mask' .\" 2008-01-09, mtk, a few rewrites and additions. -.TH umask 2 2023-03-30 "Linux man-pages 6.05.01" +.TH umask 2 2023-10-31 "Linux man-pages 6.7" .SH NAME umask \- set file mode creation mask .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "mode_t umask(mode_t " mask ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ sets the calling process's file mode creation mask (umask) to & 0777 (i.e., only the file permission bits of .I mask are used), and returns the previous value of the mask. -.PP +.P The umask is used by .BR open (2), .BR mkdir (2), @@ -45,7 +45,7 @@ argument to .BR open (2) and .BR mkdir (2). -.PP +.P Alternatively, if the parent directory has a default ACL (see .BR acl (5)), the umask is ignored, the default ACL is inherited, @@ -54,23 +54,23 @@ and permission bits absent in the .I mode argument are turned off. For example, the following default ACL is equivalent to a umask of 022: -.PP +.P .in +4n .EX u::rwx,g::r-x,o::r-x .EE .in -.PP +.P Combining the effect of this default ACL with a .I mode argument of 0666 (rw-rw-rw-), the resulting file permissions would be 0644 (rw-r--r--). -.PP +.P The constants that should be used to specify .I mask are described in .BR inode (7). -.PP +.P The typical default value for the process umask is .BR S_IWGRP " | " S_IWOTH (octal 022). @@ -79,22 +79,22 @@ In the usual case where the argument to .BR open (2) is specified as: -.PP +.P .in +4n .EX .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH .EE .in -.PP +.P (octal 0666) when creating a new file, the permissions on the resulting file will be: -.PP +.P .in +4n .EX .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IROTH .EE .in -.PP +.P (because 0666 & \[ti]022 = 0644; i.e. rw\-r\-\-r\-\-). .SH RETURN VALUE This system call always succeeds and the previous value of the mask @@ -109,7 +109,7 @@ A child process created via inherits its parent's umask. The umask is left unchanged by .BR execve (2). -.PP +.P It is impossible to use .BR umask () to fetch a process's umask without at the same time changing it. @@ -118,7 +118,7 @@ A second call to would then be needed to restore the umask. The nonatomicity of these two steps provides the potential for races in multithreaded programs. -.PP +.P Since Linux 4.7, the umask of any process can be viewed via the .I Umask field of @@ -126,7 +126,7 @@ field of Inspecting this field in .I /proc/self/status allows a process to retrieve its umask without at the same time changing it. -.PP +.P The umask setting also affects the permissions assigned to POSIX IPC objects .RB ( mq_open (3), .BR sem_open (3), diff --git a/man2/umount.2 b/man2/umount.2 index cba0abc..07e3a93 100644 --- a/man2/umount.2 +++ b/man2/umount.2 @@ -7,7 +7,7 @@ .\" 2008-10-06, mtk: Created this as a new page by splitting .\" umount/umount2 material out of mount.2 .\" -.TH umount 2 2023-03-30 "Linux man-pages 6.05.01" +.TH umount 2 2023-10-31 "Linux man-pages 6.7" .SH NAME umount, umount2 \- unmount filesystem .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int umount(const char *" target ); .BI "int umount2(const char *" target ", int " flags ); .fi @@ -29,11 +29,11 @@ remove the attachment of the (topmost) filesystem mounted on .\" Note: the kernel naming differs from the glibc naming .\" umount2 is the glibc name for what the kernel now calls umount .\" and umount is the glibc name for oldumount -.PP +.P Appropriate privilege (Linux: the .B CAP_SYS_ADMIN capability) is required to unmount filesystems. -.PP +.P Linux 2.1.116 added the .BR umount2 () system call, which, like @@ -162,7 +162,7 @@ and .B MNT_EXPIRE .\" http://sourceware.org/bugzilla/show_bug.cgi?id=10092 are available since glibc 2.11. -.PP +.P The original .BR umount () function was called as \fIumount(device)\fP and would return @@ -183,7 +183,7 @@ This means that .BR umount () of any peer in a set of shared mounts will cause all of its peers to be unmounted and all of their slaves to be unmounted as well. -.PP +.P This propagation of unmount activity can be particularly surprising on systems where every mount is shared by default. On such systems, @@ -191,7 +191,7 @@ recursively bind mounting the root directory of the filesystem onto a subdirectory and then later unmounting that subdirectory with .B MNT_DETACH will cause every mount in the mount namespace to be lazily unmounted. -.PP +.P To ensure .BR umount () does not propagate in this fashion, diff --git a/man2/uname.2 b/man2/uname.2 index e84f3e7..e4f449f 100644 --- a/man2/uname.2 +++ b/man2/uname.2 @@ -4,7 +4,7 @@ .\" .\" 2007-07-05 mtk: Added details on underlying system call interfaces .\" -.TH uname 2 2023-03-30 "Linux man-pages 6.05.01" +.TH uname 2 2023-10-31 "Linux man-pages 6.7" .SH NAME uname \- get name and information about current kernel .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int uname(struct utsname *" buf ); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ The .I utsname struct is defined in .IR : -.PP +.P .in +4n .EX struct utsname { @@ -41,7 +41,7 @@ struct utsname { }; .EE .in -.PP +.P The length of the arrays in a .I struct utsname is unspecified (see NOTES); @@ -60,7 +60,7 @@ is not valid. The .I domainname member (the NIS or YP domain name) is a GNU extension. -.PP +.P The length of the fields in the struct varies. Some operating systems or libraries use a hardcoded 9 or 33 or 65 or 257. @@ -120,7 +120,7 @@ Similarly, the .I domainname field is set via .BR setdomainname (2). -.PP +.P Part of the utsname information is also accessible via .IR /proc/sys/kernel/ { ostype , .IR hostname , diff --git a/man2/unimplemented.2 b/man2/unimplemented.2 index 535d3e9..3daa030 100644 --- a/man2/unimplemented.2 +++ b/man2/unimplemented.2 @@ -4,7 +4,7 @@ .\" .\" Updated, aeb, 980612 .\" -.TH UNIMPLEMENTED 2 2022-10-09 "Linux man-pages 6.05.01" +.TH UNIMPLEMENTED 2 2023-10-31 "Linux man-pages 6.7" .SH NAME afs_syscall, break, fattach, fdetach, ftime, getmsg, getpmsg, gtty, isastream, lock, madvise1, mpx, prof, profil, putmsg, putpmsg, security, @@ -27,7 +27,7 @@ Note that and .BR ulimit (3) are implemented as library functions. -.PP +.P Some system calls, like .BR alloc_hugepages (2), .BR free_hugepages (2), @@ -36,7 +36,7 @@ Some system calls, like and .BR vm86 (2) exist only on certain architectures. -.PP +.P Some system calls, like .BR ipc (2), .BR create_module (2), diff --git a/man2/unlink.2 b/man2/unlink.2 index 85cb670..7485a32 100644 --- a/man2/unlink.2 +++ b/man2/unlink.2 @@ -10,7 +10,7 @@ .\" Modified 2001-05-17 by aeb .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH unlink 2 2023-03-30 "Linux man-pages 6.05.01" +.TH unlink 2 2024-02-18 "Linux man-pages 6.7" .SH NAME unlink, unlinkat \- delete a name and possibly the file it refers to .SH LIBRARY @@ -19,20 +19,20 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int unlink(const char *" pathname ); -.PP +.P .BR "#include " "/* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR unlinkat (): .nf Since glibc 2.10: @@ -46,13 +46,13 @@ deletes a name from the filesystem. If that name was the last link to a file and no processes have the file open, the file is deleted and the space it was using is made available for reuse. -.PP +.P If the name was the last link to a file but any processes still have the file open, the file will remain in existence until the last file descriptor referring to it is closed. -.PP +.P If the name referred to a symbolic link, the link is removed. -.PP +.P If the name referred to a socket, FIFO, or device, the name for it is removed but processes which have the object open may continue to use it. @@ -69,7 +69,7 @@ includes the .B AT_REMOVEDIR flag) except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -81,7 +81,7 @@ the calling process, as is done by and .BR rmdir (2) for a relative pathname). -.PP +.P If the pathname given in .I pathname is relative and @@ -95,13 +95,13 @@ directory of the calling process (like .BR unlink () and .BR rmdir (2)). -.PP +.P If the pathname given in .I pathname is absolute, then .I dirfd is ignored. -.PP +.P .I flags is a bit mask that can either be specified as 0, or by ORing together flag values that control the operation of @@ -117,12 +117,12 @@ on .IR pathname . If the .B AT_REMOVEDIR -flag is specified, then +flag is specified, it performs the equivalent of .BR rmdir (2) on .IR pathname . -.PP +.P See .BR openat (2) for an explanation of the need for @@ -218,7 +218,7 @@ The file to be unlinked is marked immutable or append-only. .B EROFS .I pathname refers to a file on a read-only filesystem. -.PP +.P The same errors that occur for .BR unlink () and diff --git a/man2/unshare.2 b/man2/unshare.2 index b12afb5..ce2464d 100644 --- a/man2/unshare.2 +++ b/man2/unshare.2 @@ -15,7 +15,7 @@ .\" by clone, which would require porting and maintaining all commands .\" such as login, and su, that establish a user session. .\" -.TH unshare 2 2023-05-26 "Linux man-pages 6.05.01" +.TH unshare 2 2023-10-31 "Linux man-pages 6.7" .SH NAME unshare \- disassociate parts of the process execution context .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .nf .B #define _GNU_SOURCE .B #include -.PP +.P .BI "int unshare(int " flags ); .fi .SH DESCRIPTION @@ -40,12 +40,12 @@ or while other parts, such as virtual memory, may be shared by explicit request when creating a process or thread using .BR clone (2). -.PP +.P The main use of .BR unshare () is to allow a process to control its shared execution context without creating a new process. -.PP +.P The .I flags argument is a bit mask that specifies which parts of @@ -250,7 +250,7 @@ to the corresponding semaphores, as described in .BR semop (2). .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared .\" (i.e., current->signal->count > 1), force CLONE_THREAD. -.PP +.P In addition, .BR CLONE_THREAD , .BR CLONE_SIGHAND , @@ -277,7 +277,7 @@ automatically implies If the process is multithreaded, then the use of these flags results in an error. .\" See kernel/fork.c::check_unshare_flags() -.PP +.P If .I flags is specified as zero, then @@ -457,7 +457,7 @@ Such functionality may be added in the future, if required. .\"be incrementally added to unshare without affecting legacy .\"applications using unshare. .\" -.PP +.P Creating all kinds of namespace, except user namespaces, requires the .B CAP_SYS_ADMIN capability. @@ -477,7 +477,7 @@ Here's an example of the use of this program, running a shell in a new mount namespace, and verifying that the original shell and the new shell are in separate mount namespaces: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/mnt\fP @@ -487,7 +487,7 @@ $ \fBsudo ./unshare \-m /bin/bash\fP mnt:[4026532325] .EE .in -.PP +.P The differing output of the two .BR readlink (1) commands shows that the two shells are in different mount namespaces. @@ -563,7 +563,7 @@ main(int argc, char *argv[]) .BR setns (2), .BR vfork (2), .BR namespaces (7) -.PP +.P .I Documentation/userspace\-api/unshare.rst in the Linux kernel source tree .\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2 diff --git a/man2/uselib.2 b/man2/uselib.2 index 1d6a072..cdd7fba 100644 --- a/man2/uselib.2 +++ b/man2/uselib.2 @@ -8,13 +8,13 @@ .\" Modified 2004-06-23 by Michael Kerrisk .\" Modified 2005-01-09 by aeb .\" -.TH uselib 2 2023-03-30 "Linux man-pages 6.05.01" +.TH uselib 2 2023-10-31 "Linux man-pages 6.7" .SH NAME uselib \- load shared library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int uselib(const char *" library ); .fi .SH DESCRIPTION @@ -65,13 +65,13 @@ Therefore, in order to employ this system call, it was sufficient to manually declare the interface in your code; alternatively, you could invoke the system call using .BR syscall (2). -.PP +.P In ancient libc versions (before glibc 2.0), .BR uselib () was used to load the shared libraries with names found in an array of names in the binary. -.\" .PP +.\" .P .\" .\" libc 4.3.1f - changelog 1993-03-02 .\" Since libc 4.3.2, startup code tries to prefix these names .\" with "/usr/lib", "/lib" and "" before giving up. @@ -81,14 +81,14 @@ in the binary. .\" .BR LD_LIBRARY_PATH , .\" and if not found there, .\" prefixes "/usr/lib", "/lib" and "/" are tried. -.\" .PP +.\" .P .\" From libc 4.4.4 on only the library "/lib/ld.so" is loaded, .\" so that this dynamic library can load the remaining libraries needed .\" (again using this call). .\" This is also the state of affairs in libc5. -.\" .PP +.\" .P .\" glibc2 does not use this call. -.PP +.P Since Linux 3.15, .\" commit 69369a7003735d0d8ef22097e27a55a8bad9557a this system call is available only when the kernel is configured with the diff --git a/man2/userfaultfd.2 b/man2/userfaultfd.2 index 82903c6..27f4b69 100644 --- a/man2/userfaultfd.2 +++ b/man2/userfaultfd.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH userfaultfd 2 2023-05-03 "Linux man-pages 6.05.01" +.TH userfaultfd 2 2024-02-12 "Linux man-pages 6.7" .SH NAME userfaultfd \- create a file descriptor for handling page faults in user space .SH LIBRARY @@ -16,10 +16,10 @@ Standard C library .BR "#include " " /* Definition of " SYS_* " constants */" .BR "#include " " /* Definition of " UFFD_* " constants */" .B #include -.PP +.P .BI "int syscall(SYS_userfaultfd, int " flags ); .fi -.PP +.P .IR Note : glibc provides no wrapper for .BR userfaultfd (), @@ -32,7 +32,7 @@ handling to a user-space application, and returns a file descriptor that refers to the new object. The new userfaultfd object is configured using .BR ioctl (2). -.PP +.P Once the userfaultfd object is configured, the application can use .BR read (2) to receive userfaultfd notifications. @@ -41,7 +41,7 @@ depending on the value of .I flags used for the creation of the userfaultfd or subsequent calls to .BR fcntl (2). -.PP +.P The following values may be bitwise ORed in .I flags to change the behavior of @@ -69,12 +69,12 @@ When a kernel-originated fault was triggered on the registered range with this userfaultfd, a .B SIGBUS signal will be delivered. -.PP +.P When the last file descriptor referring to a userfaultfd object is closed, all memory ranges that were registered with the object are unregistered and unread events are flushed. .\" -.PP +.P Userfaultfd supports three modes of registration: .TP .BR UFFDIO_REGISTER_MODE_MISSING " (since Linux 4.10)" @@ -111,9 +111,9 @@ The faulted thread will be stopped from execution until user-space write-unprotects the page using an .B UFFDIO_WRITEPROTECT ioctl. -.PP +.P Multiple modes can be enabled at the same time for the same memory range. -.PP +.P Since Linux 4.14, a userfaultfd page-fault notification can selectively embed faulting thread ID information into the notification. One needs to enable this feature explicitly using the @@ -132,7 +132,7 @@ them using the operations described in .BR ioctl_userfaultfd (2). When servicing the page fault events, the fault-handling thread can trigger a wake-up for the sleeping thread. -.PP +.P It is possible for the faulting threads and the fault-handling threads to run in the context of different processes. In this case, these threads may belong to different programs, @@ -142,7 +142,7 @@ In such non-cooperative mode, the process that monitors userfaultfd and handles page faults needs to be aware of the changes in the virtual memory layout of the faulting process to avoid memory corruption. -.PP +.P Since Linux 4.11, userfaultfd can also notify the fault-handling threads about changes in the virtual memory layout of the faulting process. @@ -166,7 +166,7 @@ soon as the userfaultfd manager executes The userfaultfd manager should carefully synchronize calls to .B UFFDIO_COPY with the processing of events. -.PP +.P The current asynchronous model of the event delivery is optimal for single threaded non-cooperative userfaultfd manager implementations. .\" Regarding the preceding sentence, Mike Rapoport says: @@ -174,13 +174,13 @@ single threaded non-cooperative userfaultfd manager implementations. .\" problematic for multi-threaded monitor. I even suspect that it would be .\" impossible to ensure synchronization between page faults and non-page .\" fault events in multi-threaded monitor. -.\" .PP +.\" .P .\" FIXME elaborate about non-cooperating mode, describe its limitations .\" for kernels before Linux 4.11, features added in Linux 4.11 .\" and limitations remaining in Linux 4.11 .\" Maybe it's worth adding a dedicated sub-section... .\" -.PP +.P Since Linux 5.7, userfaultfd is able to do synchronous page dirty tracking using the new write-protect register mode. One should check against the feature bit @@ -200,14 +200,15 @@ the application must enable it using the .B UFFDIO_API .BR ioctl (2) operation. -This operation allows a handshake between the kernel and user space -to determine the API version and supported features. +This operation allows a two-step handshake between the kernel and user space +to determine what API version and features the kernel supports, +and then to enable those features user space wants. This operation must be performed before any of the other .BR ioctl (2) operations described below (or those operations fail with the .B EINVAL error). -.PP +.P After a successful .B UFFDIO_API operation, @@ -221,14 +222,14 @@ operation, a page fault occurring in the requested memory range, and satisfying the mode defined at the registration time, will be forwarded by the kernel to the user-space application. -The application can then use the -.B UFFDIO_COPY , -.B UFFDIO_ZEROPAGE , +The application can then use various (e.g., +.BR UFFDIO_COPY , +.BR UFFDIO_ZEROPAGE , or -.B UFFDIO_CONTINUE +.BR UFFDIO_CONTINUE ) .BR ioctl (2) operations to resolve the page fault. -.PP +.P Since Linux 4.14, if the application sets the .B UFFD_FEATURE_SIGBUS feature bit using the @@ -247,23 +248,23 @@ accesses. For example, this feature can be useful for applications that want to prevent the kernel from automatically allocating pages and filling holes in sparse files when the hole is accessed through a memory mapping. -.PP +.P The .B UFFD_FEATURE_SIGBUS feature is implicitly inherited through .BR fork (2) if used in combination with .BR UFFD_FEATURE_FORK . -.PP +.P Details of the various .BR ioctl (2) operations can be found in .BR ioctl_userfaultfd (2). -.PP +.P Since Linux 4.11, events other than page-fault may enabled during .B UFFDIO_API operation. -.PP +.P Up to Linux 4.11, userfaultfd can be used only with anonymous private memory mappings. Since Linux 4.11, @@ -276,13 +277,13 @@ The user needs to first check availability of this feature using ioctl against the feature bit .B UFFD_FEATURE_PAGEFAULT_FLAG_WP before using this feature. -.PP +.P Since Linux 5.19, the write-protection mode was also supported on shmem and hugetlbfs memory types. It can be detected with the feature bit .BR UFFD_FEATURE_WP_HUGETLBFS_SHMEM . -.PP +.P To register with userfaultfd write-protect mode, the user needs to initiate the .B UFFDIO_REGISTER ioctl with mode @@ -300,7 +301,7 @@ registered, user-space will receive any notification when a missing page is written. Instead, user-space will receive a write-protect page-fault notification only when an existing but write-protected page got written. -.PP +.P After the .B UFFDIO_REGISTER ioctl completed with @@ -312,7 +313,7 @@ where .I uffdio_writeprotect.mode should be set to .BR UFFDIO_WRITEPROTECT_MODE_WP . -.PP +.P When a write-protect event happens, user-space will receive a page-fault notification whose .I uffd_msg.pagefault.flags @@ -325,7 +326,7 @@ write-protect notifications will always have the bit set along with the .B UFFD_PAGEFAULT_FLAG_WP bit. -.PP +.P To resolve a write-protection page fault, the user should initiate another .B UFFDIO_WRITEPROTECT ioctl, whose @@ -351,14 +352,14 @@ since Linux 5.13, or .B UFFD_FEATURE_MINOR_SHMEM since Linux 5.14. -.PP +.P To register with userfaultfd minor fault mode, the user needs to initiate the .B UFFDIO_REGISTER ioctl with mode .B UFFD_REGISTER_MODE_MINOR set. -.PP +.P When a minor fault occurs, user-space will receive a page-fault notification whose @@ -366,7 +367,7 @@ whose will have the .B UFFD_PAGEFAULT_FLAG_MINOR flag set. -.PP +.P To resolve a minor page fault, the handler should decide whether or not the existing page contents need to be modified first. @@ -382,7 +383,7 @@ ioctl, which installs the page table entries and (by default) wakes up the faulting thread(s). -.PP +.P Minor fault mode supports only hugetlbfs-backed (since Linux 5.13) and shmem-backed (since Linux 5.14) memory. .\" @@ -393,7 +394,7 @@ from the userfaultfd file descriptor returns one or more .I uffd_msg structures, each of which describes a page-fault event or an event required for the non-cooperative userfaultfd usage: -.PP +.P .in +4n .EX struct uffd_msg { @@ -430,7 +431,7 @@ struct uffd_msg { } __packed; .EE .in -.PP +.P If multiple events are available and the supplied buffer is large enough, .BR read (2) returns as many events as will fit in the supplied buffer. @@ -442,7 +443,7 @@ structure, the .BR read (2) fails with the error .BR EINVAL . -.PP +.P The fields set in the .I uffd_msg structure are as follows: @@ -532,7 +533,7 @@ If this flag is set, then the fault was a minor fault. .TP .B UFFD_PAGEFAULT_FLAG_WRITE If this flag is set, then the fault was a write fault. -.PP +.P If neither .B UFFD_PAGEFAULT_FLAG_WP nor @@ -569,7 +570,7 @@ or unmapped The end address of the memory range that was freed using .BR madvise (2) or unmapped -.PP +.P A .BR read (2) on a userfaultfd file descriptor can fail with the following errors: @@ -579,7 +580,7 @@ The userfaultfd object has not yet been enabled using the .B UFFDIO_API .BR ioctl (2) operation -.PP +.P If the .B O_NONBLOCK flag is enabled in the associated open file description, @@ -636,7 +637,7 @@ has the value 0. Linux. .SH HISTORY Linux 4.3. -.PP +.P Support for hugetlbfs and shared memory areas and non-page-fault events was added in Linux 4.11 .SH NOTES @@ -666,7 +667,7 @@ The program creates two threads, one of which acts as the page-fault handler for the process, for the pages in a demand-page zero region created using .BR mmap (2). -.PP +.P The program takes one command-line argument, which is the number of pages that will be created in a mapping whose page faults will be handled via userfaultfd. @@ -678,13 +679,13 @@ and registers the address range of that mapping using the operation. The program then creates a second thread that will perform the task of handling page faults. -.PP +.P The main thread then walks through the pages of the mapping fetching bytes from successive pages. Because the pages have not yet been accessed, the first access of a byte in each page will trigger a page-fault event on the userfaultfd file descriptor. -.PP +.P Each of the page-fault events is handled by the second thread, which sits in a loop processing input from the userfaultfd file descriptor. In each loop iteration, the second thread first calls @@ -699,9 +700,9 @@ the faulting region using the .B UFFDIO_COPY .BR ioctl (2) operation. -.PP +.P The following is an example of what we see when running the program: -.PP +.P .in +4n .EX $ \fB./userfaultfd_demo 3\fP @@ -879,6 +880,13 @@ main(int argc, char *argv[]) if (uffd == \-1) err(EXIT_FAILURE, "userfaultfd"); \& + /* NOTE: Two-step feature handshake is not needed here, since this + example doesn't require any specific features. +\& + Programs that *do* should call UFFDIO_API twice: once with + `features = 0` to detect features supported by this kernel, and + again with the subset of features the program actually wants to + enable. */ uffdio_api.api = UFFD_API; uffdio_api.features = 0; if (ioctl(uffd, UFFDIO_API, &uffdio_api) == \-1) @@ -938,6 +946,6 @@ main(int argc, char *argv[]) .BR ioctl_userfaultfd (2), .BR madvise (2), .BR mmap (2) -.PP +.P .I Documentation/admin\-guide/mm/userfaultfd.rst in the Linux kernel source tree diff --git a/man2/ustat.2 b/man2/ustat.2 index a894b13..6a682d7 100644 --- a/man2/ustat.2 +++ b/man2/ustat.2 @@ -7,7 +7,7 @@ .\" Modified 2001-03-22 by aeb .\" Modified 2003-08-04 by aeb .\" -.TH ustat 2 2023-03-30 "Linux man-pages 6.05.01" +.TH ustat 2 2023-10-31 "Linux man-pages 6.7" .SH NAME ustat \- get filesystem statistics .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .B #include .BR "#include " " /* libc[45] */" .BR "#include " " /* glibc2 */" -.PP +.P .BI "[[deprecated]] int ustat(dev_t " dev ", struct ustat *" ubuf ); .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ is a pointer to a .I ustat structure that contains the following members: -.PP +.P .in +4n .EX daddr_t f_tfree; /* Total free blocks */ @@ -41,7 +41,7 @@ char f_fname[6]; /* Filsys name */ char f_fpack[6]; /* Filsys pack name */ .EE .in -.PP +.P The last two fields, .I f_fname and @@ -79,7 +79,7 @@ SVr4. Removed in glibc 2.28. .\" SVr4 documents additional error conditions ENOLINK, ECOMM, and EINTR .\" but has no ENOSYS condition. -.PP +.P .BR ustat () is deprecated and has been provided only for compatibility. All new programs should use diff --git a/man2/utime.2 b/man2/utime.2 index 86760ab..51073d0 100644 --- a/man2/utime.2 +++ b/man2/utime.2 @@ -8,7 +8,7 @@ .\" Modified 2004-06-23 by Michael Kerrisk .\" Modified 2004-10-10 by Andries Brouwer .\" -.TH utime 2 2023-03-30 "Linux man-pages 6.05.01" +.TH utime 2 2023-10-31 "Linux man-pages 6.7" .SH NAME utime, utimes \- change file last access and modification times .SH LIBRARY @@ -17,12 +17,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int utime(const char *" filename , .BI " const struct utimbuf *_Nullable " times ); -.PP +.P .B #include -.PP +.P .BI "int utimes(const char *" filename , .BI " const struct timeval " times "[_Nullable 2]);" .fi @@ -30,7 +30,7 @@ Standard C library .B Note: modern applications may prefer to use the interfaces described in .BR utimensat (2). -.PP +.P The .BR utime () system call @@ -43,23 +43,23 @@ fields of respectively. The status change time (ctime) will be set to the current time, even if the other time stamps don't actually change. -.PP +.P If .I times is NULL, then the access and modification times of the file are set to the current time. -.PP +.P Changing timestamps is permitted when: either the process has appropriate privileges, or the effective user ID equals the user ID of the file, or .I times is NULL and the process has write permission for the file. -.PP +.P The .I utimbuf structure is: -.PP +.P .in +4n .EX struct utimbuf { @@ -68,12 +68,12 @@ struct utimbuf { }; .EE .in -.PP +.P The .BR utime () system call allows specification of timestamps with a resolution of 1 second. -.PP +.P The .BR utimes () system call @@ -86,7 +86,7 @@ structures, which allow a precision of 1 microsecond for specifying timestamps. The .I timeval structure is: -.PP +.P .in +4n .EX struct timeval { @@ -95,7 +95,7 @@ struct timeval { }; .EE .in -.PP +.P .I times[0] specifies the new access time, and .I times[1] diff --git a/man2/utimensat.2 b/man2/utimensat.2 index 77456fc..d69539d 100644 --- a/man2/utimensat.2 +++ b/man2/utimensat.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH utimensat 2 2023-07-20 "Linux man-pages 6.05.01" +.TH utimensat 2 2024-01-01 "Linux man-pages 6.7" .SH NAME utimensat, futimens \- change file timestamps with nanosecond precision .SH LIBRARY @@ -14,17 +14,17 @@ Standard C library .nf .BR "#include " " /* Definition of " AT_* " constants */" .B #include -.PP +.P .BI "int utimensat(int " dirfd ", const char *" pathname , .BI " const struct timespec " times "[_Nullable 2], int " flags ); .BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR utimensat (): .nf Since glibc 2.10: @@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.10: _ATFILE_SOURCE .fi -.PP +.P .BR futimens (): .nf Since glibc 2.10: @@ -51,7 +51,7 @@ and .BR utimes (2), which permit only second and microsecond precision, respectively, when setting file timestamps. -.PP +.P With .BR utimensat () the file is specified via the pathname given in @@ -61,7 +61,7 @@ With the file whose timestamps are to be updated is specified via an open file descriptor, .IR fd . -.PP +.P For both calls, the new file timestamps are specified in the array .IR times : .I times[0] @@ -75,10 +75,10 @@ since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). This information is conveyed in a .BR timespec (3) structure. -.PP +.P Updated file timestamps are set to the greatest value supported by the filesystem that is not greater than the specified time. -.PP +.P If the .I tv_nsec field of one of the @@ -97,12 +97,12 @@ In both of these cases, the value of the corresponding .I tv_sec .\" 2.6.22 was broken: it is not ignored field is ignored. -.PP +.P If .I times is NULL, then both timestamps are set to the current time. .\" -.PP +.P The status change time (ctime) will be set to the current time, even if the other time stamps don't actually change. .SS Permissions requirements @@ -123,7 +123,7 @@ the caller must have write access to the file; the caller's effective user ID must match the owner of the file; or .IP \[bu] the caller must have appropriate privileges. -.PP +.P To make any change other than setting both timestamps to the current time (i.e., .I times @@ -138,7 +138,7 @@ and neither field is .BR UTIME_OMIT ), either condition 2 or 3 above must apply. -.PP +.P If both .I tv_nsec fields are specified as @@ -161,7 +161,7 @@ for a relative pathname). See .BR openat (2) for an explanation of why this can be useful. -.PP +.P If .I pathname is relative and @@ -173,19 +173,40 @@ then is interpreted relative to the current working directory of the calling process (like .BR utimes (2)). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P The .I flags -field is a bit mask that may be 0, or include the following constant, -defined in +argument is a bit mask created by ORing together zero or more of +the following values defined in .IR : .TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP .B AT_SYMLINK_NOFOLLOW If .I pathname @@ -383,7 +404,6 @@ T{ .BR futimens () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel ABI differences On Linux, @@ -402,13 +422,13 @@ the file referred to by the file descriptor Using this feature, the call .I "futimens(fd,\ times)" is implemented as: -.PP +.P .in +4n .EX utimensat(fd, NULL, times, 0); .EE .in -.PP +.P Note, however, that the glibc wrapper for .BR utimensat () disallows passing NULL as the value for @@ -432,7 +452,7 @@ POSIX.1-2008. .BR utimensat () obsoletes .BR futimesat (2). -.PP +.P On Linux, timestamps cannot be changed for a file marked immutable, and the only change permitted for files marked append-only is to set the timestamps to the current time. @@ -441,7 +461,7 @@ set the timestamps to the current time. and .BR utimes (2) on Linux.) -.PP +.P If both .I tv_nsec fields are specified as @@ -504,7 +524,7 @@ c) the wrong value is returned in case of an error. .\" Below, the long description of the errors from the previous bullet .\" point (abridged because it's too much detail for a man page). -.\" .IP * +.\" .IP \[bu] .\" If one of the .\" .I tv_nsec .\" fields is @@ -516,7 +536,7 @@ value is returned in case of an error. .\" should occur if the process's effective user ID does not match .\" the file owner and the process is not privileged. .\" Instead, the call successfully changes one of the timestamps. -.\" .IP * +.\" .IP \[bu] .\" If file is not writable by the effective user ID of the process and .\" the process's effective user ID does not match the file owner and .\" the process is not privileged, @@ -532,7 +552,7 @@ value is returned in case of an error. .\" fields are .\" .BR UTIME_NOW . .\" Instead the call succeeds. -.\" .IP * +.\" .IP \[bu] .\" If a file is marked as append-only (see .\" .BR chattr (1)), .\" then Linux traditionally @@ -554,7 +574,7 @@ value is returned in case of an error. .\" .BR UTIME_NOW . .\" Instead, the call fails with the error .\" .BR EPERM . -.\" .IP * +.\" .IP \[bu] .\" If a file is marked as immutable (see .\" .BR chattr (1)), .\" then Linux traditionally diff --git a/man2/vfork.2 b/man2/vfork.2 index 85c04d3..5d523ad 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -6,7 +6,7 @@ .\" 1999-11-10: Merged text taken from the page contributed by .\" Reed H. Petty (rhp@draper.net) .\" -.TH vfork 2 2023-07-28 "Linux man-pages 6.05.01" +.TH vfork 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vfork \- create a child process and block parent .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B pid_t vfork(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vfork (): .nf Since glibc 2.12: @@ -61,7 +61,7 @@ just like creates a child process of the calling process. For details and return value and errors, see .BR fork (2). -.PP +.P .BR vfork () is a special case of .BR clone (2). @@ -70,7 +70,7 @@ the parent process. It may be useful in performance-sensitive applications where a child is created which then immediately issues an .BR execve (2). -.PP +.P .BR vfork () differs from .BR fork (2) @@ -90,7 +90,7 @@ established by the parent process and flushing the parent's .BR stdio (3) buffers), but may call .BR _exit (2). -.PP +.P As with .BR fork (2), the child process created by @@ -101,7 +101,7 @@ the .BR vfork () call differs only in the treatment of the virtual address space, as described above. -.PP +.P Signals sent to the parent arrive after the child releases the parent's memory (i.e., after the child terminates @@ -145,7 +145,7 @@ remaining blocked until the child either terminates or calls .BR execve (2), and cannot rely on any specific behavior with respect to shared memory. .\" In AIXv3.1 vfork is equivalent to fork. -.PP +.P Some consider the semantics of .BR vfork () to be an architectural blemish, and the 4.2BSD man page stated: @@ -211,7 +211,7 @@ LinuxThreads threading library. (See .BR pthreads (7) for a description of Linux threading libraries.) -.PP +.P A call to .BR vfork () is equivalent to calling @@ -219,7 +219,7 @@ is equivalent to calling with .I flags specified as: -.PP +.P .in +4n .EX CLONE_VM | CLONE_VFORK | SIGCHLD @@ -231,7 +231,7 @@ None. 4.3BSD; POSIX.1-2001 (but marked OBSOLETE). POSIX.1-2008 removes the specification of .BR vfork (). -.PP +.P The .BR vfork () system call appeared in 3.0BSD. @@ -261,7 +261,7 @@ changes memory, those changes may result in an inconsistent process state from the perspective of the parent process (e.g., memory changes would be visible in the parent, but changes to the state of open file descriptors would not be visible). -.PP +.P When .BR vfork () is called in a multithreaded process, diff --git a/man2/vhangup.2 b/man2/vhangup.2 index af9853b..ed422b6 100644 --- a/man2/vhangup.2 +++ b/man2/vhangup.2 @@ -5,7 +5,7 @@ .\" Modified, 27 May 2004, Michael Kerrisk .\" Added notes on capability requirements .\" -.TH vhangup 2 2023-03-30 "Linux man-pages 6.05.01" +.TH vhangup 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vhangup \- virtually hangup the current terminal .SH LIBRARY @@ -14,15 +14,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int vhangup(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vhangup (): .nf Since glibc 2.21: diff --git a/man2/vm86.2 b/man2/vm86.2 index 97595e8..fba1167 100644 --- a/man2/vm86.2 +++ b/man2/vm86.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vm86 2 2023-03-30 "Linux man-pages 6.05.01" +.TH vm86 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vm86old, vm86 \- enter virtual 8086 mode .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int vm86old(struct vm86_struct *" info ); .BI "int vm86(unsigned long " fn ", struct vm86plus_struct *" v86 ); .fi @@ -29,11 +29,11 @@ The definition of .I struct vm86_struct was changed in 1.1.8 and 1.1.9. -.PP +.P These calls cause the process to enter VM86 mode (virtual-8086 in Intel literature), and are used by .BR dosemu . -.PP +.P VM86 mode is an emulation of real mode within a protected mode task. .SH RETURN VALUE On success, zero is returned. diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 index 4520b8a..ccbf2c6 100644 --- a/man2/vmsplice.2 +++ b/man2/vmsplice.2 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vmsplice 2 2023-03-30 "Linux man-pages 6.05.01" +.TH vmsplice 2 2023-10-31 "Linux man-pages 6.7" .SH NAME vmsplice \- splice user pages to/from a pipe .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "ssize_t vmsplice(int " fd ", const struct iovec *" iov , .BI " size_t " nr_segs ", unsigned int " flags ); .fi @@ -50,14 +50,14 @@ from a pipe. The file descriptor .I fd must refer to a pipe. -.PP +.P The pointer .I iov points to an array of .I iovec structures as described in .BR iovec (3type). -.PP +.P The .I flags argument is a bit mask that is composed by ORing together @@ -148,7 +148,7 @@ as defined in Currently, .\" UIO_MAXIOV in kernel source this limit is 1024. -.PP +.P .\" commit 6a14b90bb6bc7cd83e2a444bf457a2ea645cbfe7 .BR vmsplice () really supports true splicing only from user memory to a pipe. diff --git a/man2/wait.2 b/man2/wait.2 index cbd851e..e15ca87 100644 --- a/man2/wait.2 +++ b/man2/wait.2 @@ -26,7 +26,7 @@ .\" 2005-05-10, mtk, __W* flags can't be used with waitid() .\" 2008-07-04, mtk, removed erroneous text about SA_NOCLDSTOP .\" -.TH wait 2 2023-05-03 "Linux man-pages 6.05.01" +.TH wait 2 2023-10-31 "Linux man-pages 6.7" .SH NAME wait, waitpid, waitid \- wait for process to change state .SH LIBRARY @@ -35,21 +35,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "pid_t wait(int *_Nullable " "wstatus" ); .BI "pid_t waitpid(pid_t " pid ", int *_Nullable " wstatus ", int " options ); -.PP +.P .BI "int waitid(idtype_t " idtype ", id_t " id \ ", siginfo_t *" infop ", int " options ); /* This is the glibc and POSIX interface; see NOTES for information on the raw system call. */ .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR waitid (): .nf Since glibc 2.26: @@ -70,7 +70,7 @@ In the case of a terminated child, performing a wait allows the system to release the resources associated with the child; if a wait is not performed, then the terminated child remains in a "zombie" state (see NOTES below). -.PP +.P If a child has already changed state, then these calls return immediately. Otherwise, they block until either a child changes state or a signal handler interrupts the call (assuming that system calls @@ -90,13 +90,13 @@ children terminates. The call .I wait(&wstatus) is equivalent to: -.PP +.P .in +4n .EX waitpid(\-1, &wstatus, 0); .EE .in -.PP +.P The .BR waitpid () system call suspends execution of the calling thread until a @@ -109,7 +109,7 @@ waits only for terminated children, but this behavior is modifiable via the .I options argument, as described below. -.PP +.P The value of .I pid can be: @@ -131,7 +131,7 @@ equal to that of the calling process at the time of the call to meaning wait for the child whose process ID is equal to the value of .IR pid . -.PP +.P The value of .I options is an OR of zero or more of the following constants: @@ -151,9 +151,9 @@ even if this option is not specified. .BR WCONTINUED " (since Linux 2.6.10)" also return if a stopped child has been resumed by delivery of .BR SIGCONT . -.PP +.P (For Linux-only options, see below.) -.PP +.P If .I wstatus is not NULL, @@ -233,7 +233,7 @@ The .BR waitid () system call (available since Linux 2.6.9) provides more precise control over which child state changes to wait for. -.PP +.P The .I idtype and @@ -266,7 +266,7 @@ as the caller's process group at the time of the call. Wait for any child; .I id is ignored. -.PP +.P The child state changes to wait for are specified by ORing one or more of the following flags in .IR options : @@ -281,7 +281,7 @@ Wait for children that have been stopped by delivery of a signal. Wait for (previously stopped) children that have been resumed by delivery of .BR SIGCONT . -.PP +.P The following flags may additionally be ORed in .IR options : .TP @@ -292,7 +292,7 @@ As for .B WNOWAIT Leave the child in a waitable state; a later wait call can be used to again retrieve the child status information. -.PP +.P Upon successful return, .BR waitid () fills in the following fields of the @@ -337,7 +337,7 @@ Set to one of: .B CLD_CONTINUED (child continued by .BR SIGCONT ). -.PP +.P If .B WNOHANG was specified in @@ -355,7 +355,7 @@ waitable state, zero out the .I si_pid field before the call and check for a nonzero value in this field after the call returns. -.PP +.P POSIX.1-2008 Technical Corrigendum 1 (2013) adds the requirement that when .B WNOHANG is specified in @@ -382,7 +382,7 @@ not all implementations follow the POSIX.1 specification on this point. .BR wait (): on success, returns the process ID of the terminated child; on failure, \-1 is returned. -.PP +.P .BR waitpid (): on success, returns the process ID of the child whose state has changed; if @@ -391,7 +391,7 @@ was specified and one or more child(ren) specified by .I pid exist, but have not yet changed state, then 0 is returned. On failure, \-1 is returned. -.PP +.P .BR waitid (): returns 0 on success or if @@ -404,7 +404,7 @@ on failure, \-1 is returned. .\" returns the PID of the child. Either this is a bug, or it is intended .\" behavior that needs to be documented. See my Jan 2009 LKML mail .\" "waitid() return value strangeness when infop is NULL". -.PP +.P On failure, each of these calls sets .I errno to indicate the error. @@ -465,7 +465,7 @@ is equal to .BR wait () is actually a library function that (in glibc) is implemented as a call to .BR wait4 (2). -.PP +.P On some architectures, there is no .BR waitpid () system call; @@ -473,7 +473,7 @@ system call; instead, this interface is implemented via a C library wrapper function that calls .BR wait4 (2). -.PP +.P The raw .BR waitid () system call takes a fifth argument, of type @@ -507,7 +507,7 @@ are adopted by operation); .BR init (1) automatically performs a wait to remove the zombies. -.PP +.P POSIX.1-2001 specifies that if the disposition of .B SIGCHLD is set to @@ -536,7 +536,7 @@ Note that even though the default disposition of is "ignore", explicitly setting the disposition to .B SIG_IGN results in different treatment of zombie process children.) -.PP +.P Linux 2.6 conforms to the POSIX requirements. However, Linux 2.4 (and earlier) does not: if a @@ -565,7 +565,7 @@ of another thread, even when the latter belongs to the same thread group. However, POSIX prescribes such functionality, and since Linux 2.4 a thread can, and by default will, wait on children of other threads in the same thread group. -.PP +.P The following Linux-specific .I options are for use with children created using @@ -596,7 +596,7 @@ type ("clone" or "non-clone"). Do not wait for children of other threads in the same thread group. This was the default before Linux 2.4. -.PP +.P Since Linux 4.7, .\" commit bf959931ddb88c4e4366e96dd22e68fa0db9527c .\" prevents cases where an unreapable zombie is created if @@ -636,9 +636,9 @@ using the integer supplied on the command line as the exit status. The parent process executes a loop that monitors the child using .BR waitpid (), and uses the W*() macros described above to analyze the wait status value. -.PP +.P The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out &" diff --git a/man2/wait4.2 b/man2/wait4.2 index 7136d70..8e0798a 100644 --- a/man2/wait4.2 +++ b/man2/wait4.2 @@ -10,7 +10,7 @@ .\" Rewrote much of this page, and removed much duplicated text, .\" replacing with pointers to wait.2 .\" -.TH wait4 2 2023-03-30 "Linux man-pages 6.05.01" +.TH wait4 2 2023-10-31 "Linux man-pages 6.7" .SH NAME wait3, wait4 \- wait for process to change state, BSD style .SH LIBRARY @@ -19,18 +19,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "pid_t wait3(int *_Nullable " "wstatus" ", int " options , .BI " struct rusage *_Nullable " rusage ); .BI "pid_t wait4(pid_t " pid ", int *_Nullable " wstatus ", int " options , .BI " struct rusage *_Nullable " rusage ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wait3 (): .nf Since glibc 2.26: @@ -44,7 +44,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE >= 500 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED .fi -.PP +.P .BR wait4 (): .nf Since glibc 2.19: @@ -58,7 +58,7 @@ These functions are nonstandard; in new programs, the use of or .BR waitid (2) is preferable. -.PP +.P The .BR wait3 () and @@ -68,45 +68,45 @@ system calls are similar to but additionally return resource usage information about the child in the structure pointed to by .IR rusage . -.PP +.P Other than the use of the .I rusage argument, the following .BR wait3 () call: -.PP +.P .in +4n .EX wait3(wstatus, options, rusage); .EE .in -.PP +.P is equivalent to: -.PP +.P .in +4n .EX waitpid(\-1, wstatus, options); .EE .in -.PP +.P Similarly, the following .BR wait4 () call: -.PP +.P .in +4n .EX wait4(pid, wstatus, options, rusage); .EE .in -.PP +.P is equivalent to: -.PP +.P .in +4n .EX waitpid(pid, wstatus, options); .EE .in -.PP +.P In other words, .BR wait3 () waits of any child, while @@ -115,7 +115,7 @@ can be used to select a specific child, or children, on which to wait. See .BR wait (2) for further details. -.PP +.P If .I rusage is not NULL, the @@ -135,14 +135,14 @@ As for None. .SH HISTORY 4.3BSD. -.PP +.P SUSv1 included a specification of .BR wait3 (); SUSv2 included .BR wait3 (), but marked it LEGACY; SUSv3 removed it. -.PP +.P Including .I is not required these days, but increases portability. diff --git a/man2/write.2 b/man2/write.2 index d1dc273..fc22ae3 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -16,7 +16,7 @@ .\" gave some examples of why this might occur. .\" Noted what happens if write() is interrupted by a signal. .\" -.TH write 2 2023-04-03 "Linux man-pages 6.05.01" +.TH write 2 2023-10-31 "Linux man-pages 6.7" .SH NAME write \- write to a file descriptor .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t write(int " fd ", const void " buf [. count "], size_t " count ); .fi .SH DESCRIPTION @@ -36,7 +36,7 @@ bytes from the buffer starting at .I buf to the file referred to by the file descriptor .IR fd . -.PP +.P The number of bytes written may be less than .I count if, for example, @@ -50,7 +50,7 @@ handler after having written less than bytes. (See also .BR pipe (7).) -.PP +.P For a seekable file (i.e., one to which .BR lseek (2) may be applied, for example, a regular file) @@ -64,14 +64,14 @@ with the file offset is first set to the end of the file before writing. The adjustment of the file offset and the write operation are performed as an atomic step. -.PP +.P POSIX requires that a .BR read (2) that can be proved to occur after a .BR write () has returned will return the new data. Note that not all filesystems are POSIX conforming. -.PP +.P According to POSIX.1, if .I count is greater than @@ -82,7 +82,7 @@ see NOTES for the upper limit on Linux. On success, the number of bytes written is returned. On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. -.PP +.P Note that a successful .BR write () may transfer fewer than @@ -100,7 +100,7 @@ In the event of a partial write, the caller can make another call to transfer the remaining bytes. The subsequent call will either transfer further bytes or may result in an error (e.g., if the disk is now full). -.PP +.P If \fIcount\fP is zero and .I fd refers to a regular file, then @@ -222,7 +222,7 @@ When this happens the writing process will also receive a signal. (Thus, the write return value is seen only if the program catches, blocks or ignores this signal.) -.PP +.P Other errors may occur, depending on the object connected to .IR fd . .SH STANDARDS @@ -231,7 +231,7 @@ POSIX.1-2008. SVr4, 4.3BSD, POSIX.1-2001. .\" SVr4 documents additional error .\" conditions EDEADLK, ENOLCK, ENOLNK, ENOSR, ENXIO, or ERANGE. -.PP +.P Under SVr4 a write may be interrupted and return .B EINTR at any point, @@ -251,7 +251,7 @@ or even The only way to be sure is to call .BR fsync (2) after you are done writing all your data. -.PP +.P If a .BR write () is interrupted by a signal handler before any bytes are written, @@ -259,7 +259,7 @@ then the call fails with the error .BR EINTR ; if it is interrupted after at least one byte has been written, the call succeeds, and returns the number of bytes written. -.PP +.P On Linux, .BR write () (and similar system calls) will transfer at most @@ -267,7 +267,7 @@ On Linux, returning the number of bytes actually transferred. .\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69 (This is true on both 32-bit and 64-bit systems.) -.PP +.P An error return value while performing .BR write () using direct I/O does not mean the @@ -279,13 +279,13 @@ was attempted should be considered inconsistent. .SH BUGS According to POSIX.1-2008/SUSv4 Section XSI 2.9.7 ("Thread Interactions with Regular File Operations"): -.PP +.P .RS 4 All of the following functions shall be atomic with respect to each other in the effects specified in POSIX.1-2008 when they operate on regular files or symbolic links: ... .RE -.PP +.P Among the APIs subsequently listed are .BR write () and diff --git a/man2type/open_how.2type b/man2type/open_how.2type index 38445a7..869f18a 100644 --- a/man2type/open_how.2type +++ b/man2type/open_how.2type @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH open_how 2type 2023-03-30 "Linux man-pages 6.05.01" +.TH open_how 2type 2023-10-31 "Linux man-pages 6.7" .SH NAME open_how \- how to open a pathname .SH LIBRARY @@ -11,7 +11,7 @@ Linux kernel headers .SH SYNOPSIS .EX .B #include -.PP +.P .B struct open_how { .BR " u64 flags;" " /* " O_ "* flags */" .BR " u64 mode;" " /* Mode for " O_ { CREAT , TMPFILE "} */" @@ -21,7 +21,7 @@ Linux kernel headers .EE .SH DESCRIPTION Specifies how a pathname should be opened. -.PP +.P The fields are as follows: .TP .I flags diff --git a/man3/CPU_SET.3 b/man3/CPU_SET.3 index aa5d71d..6c13a62 100644 --- a/man3/CPU_SET.3 +++ b/man3/CPU_SET.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH CPU_SET 3 2023-05-03 "Linux man-pages 6.05.01" +.TH CPU_SET 3 2023-10-31 "Linux man-pages 6.7" .SH NAME CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL, @@ -19,43 +19,43 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void CPU_ZERO(cpu_set_t *" set ); -.PP +.P .BI "void CPU_SET(int " cpu ", cpu_set_t *" set ); .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set ); .BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set ); -.PP +.P .BI "int CPU_COUNT(cpu_set_t *" set ); -.PP +.P .BI "void CPU_AND(cpu_set_t *" destset , .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); .BI "void CPU_OR(cpu_set_t *" destset , .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); .BI "void CPU_XOR(cpu_set_t *" destset , .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); -.PP +.P .BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 ); -.PP +.P .BI "cpu_set_t *CPU_ALLOC(int " num_cpus ); .BI "void CPU_FREE(cpu_set_t *" set ); .BI "size_t CPU_ALLOC_SIZE(int " num_cpus ); -.PP +.P .BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set ); -.PP +.P .BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); .BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); .BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set ); -.PP +.P .BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set ); -.PP +.P .BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset , .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); .BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset , .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); .BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset , .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); -.PP +.P .BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \ ", cpu_set_t *" set2 ); .fi @@ -66,14 +66,14 @@ data structure represents a set of CPUs. CPU sets are used by .BR sched_setaffinity (2) and similar interfaces. -.PP +.P The .I cpu_set_t data type is implemented as a bit mask. However, the data structure should be treated as opaque: all manipulation of CPU sets should be done via the macros described in this page. -.PP +.P The following macros are provided to operate on the CPU set .IR set : .TP @@ -103,12 +103,12 @@ is a member of .BR CPU_COUNT () Return the number of CPUs in .IR set . -.PP +.P Where a .I cpu argument is specified, it should not produce side effects, since the above macros may evaluate the argument more than once. -.PP +.P The first CPU on the system corresponds to a .I cpu value of 0, the next CPU corresponds to a @@ -122,7 +122,7 @@ The constant (currently 1024) specifies a value one greater than the maximum CPU number that can be stored in .IR cpu_set_t . -.PP +.P The following macros perform logical operations on CPU sets: .TP .BR CPU_AND () @@ -165,7 +165,7 @@ size CPU sets (e.g., to allocate sets larger than that defined by the standard .I cpu_set_t data type), glibc nowadays provides a set of macros to support this. -.PP +.P The following macros are used to allocate and deallocate CPU sets: .TP .BR CPU_ALLOC () @@ -186,7 +186,7 @@ macros described below. .BR CPU_FREE () Free a CPU set previously allocated by .BR CPU_ALLOC (). -.PP +.P The macros whose names end with "_S" are the analogs of the similarly named macros without the suffix. These macros perform the same tasks as their analogs, @@ -202,27 +202,27 @@ return nonzero if is in .IR set ; otherwise, it returns 0. -.PP +.P .BR CPU_COUNT () and .BR CPU_COUNT_S () return the number of CPUs in .IR set . -.PP +.P .BR CPU_EQUAL () and .BR CPU_EQUAL_S () return nonzero if the two CPU sets are equal; otherwise they return 0. -.PP +.P .BR CPU_ALLOC () returns a pointer on success, or NULL on failure. (Errors are as for .BR malloc (3).) -.PP +.P .BR CPU_ALLOC_SIZE () returns the number of bytes required to store a CPU set of the specified cardinality. -.PP +.P The other functions do not return a value. .SH STANDARDS Linux. @@ -234,10 +234,10 @@ The and .BR CPU_ISSET () macros were added in glibc 2.3.3. -.PP +.P .BR CPU_COUNT () first appeared in glibc 2.6. -.PP +.P .BR CPU_AND (), .BR CPU_OR (), .BR CPU_XOR (), @@ -258,14 +258,14 @@ first appeared in glibc 2.7. .SH NOTES To duplicate a CPU set, use .BR memcpy (3). -.PP +.P Since CPU sets are bit masks allocated in units of long words, the actual number of CPUs in a dynamically allocated CPU set will be rounded up to the next multiple of .IR "sizeof(unsigned long)" . An application should consider the contents of these extra bits to be undefined. -.PP +.P Notwithstanding the similarity in the names, note that the constant .B CPU_SETSIZE @@ -277,7 +277,7 @@ while the argument of the .BR CPU_*_S () macros is a size in bytes. -.PP +.P The data types for arguments and return values shown in the SYNOPSIS are hints what about is expected in each case. However, since these interfaces are implemented as macros, @@ -298,7 +298,7 @@ These bugs are fixed in glibc 2.9. .SH EXAMPLES The following program demonstrates the use of some of the macros used for dynamically allocated CPU sets. -.PP +.P .\" SRC BEGIN (CPU_SET.c) .EX #define _GNU_SOURCE diff --git a/man3/INFINITY.3 b/man3/INFINITY.3 index aa7ea0c..0f8eab0 100644 --- a/man3/INFINITY.3 +++ b/man3/INFINITY.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH INFINITY 3 2023-03-30 "Linux man-pages 6.05.01" +.TH INFINITY 3 2023-10-31 "Linux man-pages 6.7" .SH NAME INFINITY, NAN, HUGE_VAL, HUGE_VALF, HUGE_VALL \- floating-point constants .SH LIBRARY @@ -12,11 +12,11 @@ Math library .nf .BR "#define _ISOC99_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .B INFINITY -.PP +.P .B NAN -.PP +.P .B HUGE_VAL .B HUGE_VALF .B HUGE_VALL @@ -27,7 +27,7 @@ The macro expands to a .I float constant representing positive infinity. -.PP +.P The macro .B NAN expands to a @@ -42,7 +42,7 @@ The opposite is a .I signaling NaN. See IEC 60559:1989. -.PP +.P The macros .BR HUGE_VAL , .BR HUGE_VALF , @@ -58,7 +58,7 @@ that represent a large positive value, possibly positive infinity. C11. .SH HISTORY C99. -.PP +.P On a glibc system, the macro .B HUGE_VAL is always available. diff --git a/man3/MAX.3 b/man3/MAX.3 index fddf220..de46614 100644 --- a/man3/MAX.3 +++ b/man3/MAX.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH MAX 3 2023-05-03 "Linux man-pages 6.05.01" +.TH MAX 3 2023-10-31 "Linux man-pages 6.7" .SH NAME MAX, MIN \- maximum or minimum of two values .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI MAX( a ", " b ); .BI MIN( a ", " b ); .fi @@ -35,9 +35,9 @@ you might prefer to use or .BR fmin (3), which can handle NaN. -.PP +.P The arguments may be evaluated more than once, or not at all. -.PP +.P Some UNIX systems might provide these macros in a different header, or not at all. .SH BUGS diff --git a/man3/MB_CUR_MAX.3 b/man3/MB_CUR_MAX.3 index c74d563..9aa2089 100644 --- a/man3/MB_CUR_MAX.3 +++ b/man3/MB_CUR_MAX.3 @@ -9,7 +9,7 @@ .\" .\" Modified, aeb, 990824 .\" -.TH MB_CUR_MAX 3 2023-03-30 "Linux man-pages 6.05.01" +.TH MB_CUR_MAX 3 2023-03-30 "Linux man-pages 6.7" .SH NAME MB_CUR_MAX \- maximum length of a multibyte character in the current locale .SH LIBRARY diff --git a/man3/MB_LEN_MAX.3 b/man3/MB_LEN_MAX.3 index b58bdd5..3c56b44 100644 --- a/man3/MB_LEN_MAX.3 +++ b/man3/MB_LEN_MAX.3 @@ -9,7 +9,7 @@ .\" .\" Modified, aeb, 990824 .\" -.TH MB_LEN_MAX 3 2023-03-30 "Linux man-pages 6.05.01" +.TH MB_LEN_MAX 3 2023-03-30 "Linux man-pages 6.7" .SH NAME MB_LEN_MAX \- maximum multibyte length of a character across all locales .SH LIBRARY diff --git a/man3/TIMESPEC_TO_TIMEVAL.3 b/man3/TIMESPEC_TO_TIMEVAL.3 new file mode 100644 index 0000000..30ab755 --- /dev/null +++ b/man3/TIMESPEC_TO_TIMEVAL.3 @@ -0,0 +1 @@ +.so man3/TIMEVAL_TO_TIMESPEC.3 diff --git a/man3/TIMEVAL_TO_TIMESPEC.3 b/man3/TIMEVAL_TO_TIMESPEC.3 new file mode 100644 index 0000000..9559a52 --- /dev/null +++ b/man3/TIMEVAL_TO_TIMESPEC.3 @@ -0,0 +1,32 @@ +.\" Copyright (C) 2024 Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH TIMEVAL_TO_TIMESPEC 3 2024-03-12 "Linux man-pages 6.7" +.SH NAME +TIMEVAL_TO_TIMESPEC, +TIMESPEC_TO_TIMEVAL +\- +convert between time structures +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.P +.BI "void TIMEVAL_TO_TIMESPEC(const struct timeval *" tv ", struct timespec *" ts ); +.BI "void TIMESPEC_TO_TIMEVAL(struct timeval *" tv ", const struct timespec *" ts ); +.fi +.SH DESCRIPTION +These macros convert from a +.BR timeval (3type) +to a +.BR timespec (3type) +structure, +and vice versa, +respectively. +.P +This is especially useful for writing interfaces that receive a type, +but are implemented with calls to functions that receive the other one. +.SH STANDARDS +GNU, +BSD. diff --git a/man3/_Generic.3 b/man3/_Generic.3 index ef1e2a6..b9bb026 100644 --- a/man3/_Generic.3 +++ b/man3/_Generic.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH _Generic 3 2023-05-03 "Linux man-pages 6.05.01" +.TH _Generic 3 2023-10-31 "Linux man-pages 6.7" .SH NAME _Generic \- type-generic selection .SH SYNOPSIS @@ -18,10 +18,10 @@ that is compatible with the type of the controlling or .B default: if no type is compatible. -.PP +.P .I expression is not evaluated. -.PP +.P This is especially useful for writing type-generic macros, that will behave differently depending on the type of the argument. .SH STANDARDS @@ -44,7 +44,7 @@ seamlessly upgrading to the widest available type. #define my_imaxabs _Generic(INTMAX_C(0), \e long: labs, \e long long: llabs \e - /* long long long: lllabs */ \e +/* long long long: lllabs */ \e ) \& int diff --git a/man3/__ppc_get_timebase.3 b/man3/__ppc_get_timebase.3 index 7ec1e5a..2933787 100644 --- a/man3/__ppc_get_timebase.3 +++ b/man3/__ppc_get_timebase.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH __ppc_get_timebase 3 2023-05-03 "Linux man-pages 6.05.01" +.TH __ppc_get_timebase 3 2023-10-31 "Linux man-pages 6.7" .SH NAME __ppc_get_timebase, __ppc_get_timebase_freq \- get the current value of the Time Base Register on Power architecture and its frequency. @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B uint64_t __ppc_get_timebase(void); .B uint64_t __ppc_get_timebase_freq(void); .fi @@ -22,7 +22,7 @@ reads the current value of the Time Base Register and returns its value, while .BR __ppc_get_timebase_freq () returns the frequency in which the Time Base Register is updated. -.PP +.P The Time Base Register is a 64-bit register provided by Power Architecture processors. It stores a monotonically incremented value that is updated at a @@ -32,7 +32,7 @@ frequency. .BR __ppc_get_timebase () returns a 64-bit unsigned integer that represents the current value of the Time Base Register. -.PP +.P .BR __ppc_get_timebase_freq () returns a 64-bit unsigned integer that represents the frequency at which the Time Base Register is updated. diff --git a/man3/__ppc_set_ppr_med.3 b/man3/__ppc_set_ppr_med.3 index b3effad..6c2e692 100644 --- a/man3/__ppc_set_ppr_med.3 +++ b/man3/__ppc_set_ppr_med.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH __ppc_set_ppr_med 3 2023-07-20 "Linux man-pages 6.05.01" +.TH __ppc_set_ppr_med 3 2023-10-31 "Linux man-pages 6.7" Programmer's Manual" .SH NAME __ppc_set_ppr_med, __ppc_set_ppr_very_low, __ppc_set_ppr_low, @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B void __ppc_set_ppr_med(void); .B void __ppc_set_ppr_very_low(void); .B void __ppc_set_ppr_low(void); @@ -26,7 +26,7 @@ Standard C library These functions provide access to the .I Program Priority Register (PPR) on the Power architecture. -.PP +.P The PPR is a 64-bit register that controls the program's priority. By adjusting the PPR value the programmer may improve system throughput by causing system resources to be used more @@ -49,7 +49,7 @@ sets the Program Priority Register value to .BR __ppc_set_ppr_med_low () sets the Program Priority Register value to .IR "medium low" . -.PP +.P The privileged state .I medium high may also be set during certain time intervals by problem-state (unprivileged) @@ -58,7 +58,7 @@ programs, with the following function: .BR __ppc_set_ppr_med_high () sets the Program Priority to .IR "medium high" . -.PP +.P If the program priority is medium high when the time interval expires or if an attempt is made to set the priority to medium high when it is not allowed, the priority is set to medium. @@ -80,7 +80,6 @@ T{ .BR __ppc_set_ppr_med_high () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -110,5 +109,5 @@ Availability of these functions can be tested using .BR "#ifdef _ARCH_PWR8" . .SH SEE ALSO .BR __ppc_yield (3) -.PP +.P .I Power ISA, Book\~II - Section\ 3.1 (Program Priority Registers) diff --git a/man3/__ppc_yield.3 b/man3/__ppc_yield.3 index 465dd29..c98a74f 100644 --- a/man3/__ppc_yield.3 +++ b/man3/__ppc_yield.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH __ppc_yield 3 2023-07-20 "Linux man-pages 6.05.01" +.TH __ppc_yield 3 2023-10-31 "Linux man-pages 6.7" .SH NAME __ppc_yield, __ppc_mdoio, __ppc_mdoom \- Hint the processor to release shared resources @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B void __ppc_yield(void); .B void __ppc_mdoio(void); .B void __ppc_mdoom(void); @@ -24,18 +24,18 @@ provide hints about the usage of resources that are shared with other processors on the Power architecture. They can be used, for example, if a program waiting on a lock intends to divert the shared resources to be used by other processors. -.PP +.P .BR __ppc_yield () provides a hint that performance will probably be improved if shared resources dedicated to the executing processor are released for use by other processors. -.PP +.P .BR __ppc_mdoio () provides a hint that performance will probably be improved if shared resources dedicated to the executing processor are released until all outstanding storage accesses to caching-inhibited storage have been completed. -.PP +.P .BR __ppc_mdoom () provides a hint that performance will probably be improved if shared resources dedicated to the executing processor are released until all @@ -57,12 +57,11 @@ T{ .BR __ppc_mdoom () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY glibc 2.18. .SH SEE ALSO .BR __ppc_set_ppr_med (3) -.PP +.P .I Power ISA, Book\~II - Section\~3.2 ("or" architecture) diff --git a/man3/__setfpucw.3 b/man3/__setfpucw.3 index 161bbf9..2296268 100644 --- a/man3/__setfpucw.3 +++ b/man3/__setfpucw.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH __setfpucw 3 2023-03-30 "Linux man-pages 6.05.01" +.TH __setfpucw 3 2023-10-31 "Linux man-pages 6.7" .SH NAME __setfpucw \- set FPU control word on i386 architecture (obsolete) .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] void __setfpucw(unsigned short " control_word ); .fi .SH DESCRIPTION @@ -44,7 +44,7 @@ and FPU exception handling, like .BR fesetexceptflag (3), and .BR fetestexcept (3). -.PP +.P If direct access to the FPU control word is still needed, the .B _FPU_GETCW and @@ -54,7 +54,7 @@ macros from can be used. .SH EXAMPLES .B __setfpucw(0x1372) -.PP +.P Set FPU control word on the i386 architecture to .RS .PD 0 @@ -68,5 +68,5 @@ exceptions on overflow, zero divide and NaN .RE .SH SEE ALSO .BR feclearexcept (3) -.PP +.P .I diff --git a/man3/a64l.3 b/man3/a64l.3 index eec0f70..228c259 100644 --- a/man3/a64l.3 +++ b/man3/a64l.3 @@ -6,7 +6,7 @@ .\" .\" Corrected, aeb, 2002-05-30 .\" -.TH a64l 3 2023-07-20 "Linux man-pages 6.05.01" +.TH a64l 3 2023-10-31 "Linux man-pages 6.7" .SH NAME a64l, l64a \- convert between long and base-64 .SH LIBRARY @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long a64l(const char *" str64 ); .BI "char *l64a(long " value ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR a64l (), .BR l64a (): .nf @@ -48,9 +48,9 @@ uses only the low order 32 bits of and .BR a64l () sign-extends its 32-bit result. -.PP +.P The 64 digits in the base-64 system are: -.PP +.P .RS .nf \&\[aq].\[aq] represents a 0 @@ -60,7 +60,7 @@ A-Z represent 12-37 a-z represent 38-63 .fi .RE -.PP +.P So 123 = 59*64\[ha]0 + 1*64\[ha]1 = "v/". .SH ATTRIBUTES For an explanation of the terms used in this section, see @@ -81,7 +81,6 @@ T{ .BR a64l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -91,7 +90,7 @@ The value returned by .BR l64a () may be a pointer to a static buffer, possibly overwritten by later calls. -.PP +.P The behavior of .BR l64a () is undefined when @@ -100,10 +99,10 @@ is negative. If .I value is zero, it returns an empty string. -.PP +.P These functions are broken before glibc 2.2.5 (puts most significant digit first). -.PP +.P This is not the encoding used by .BR uuencode (1). .SH SEE ALSO diff --git a/man3/abort.3 b/man3/abort.3 index 952fd13..75f47bd 100644 --- a/man3/abort.3 +++ b/man3/abort.3 @@ -12,7 +12,7 @@ .\" Modified Fri Aug 4 10:51:53 2000 - patch from Joseph S. Myers .\" 2007-12-15, mtk, Mostly rewritten .\" -.TH abort 3 2023-07-28 "Linux man-pages 6.05.01" +.TH abort 3 2023-10-31 "Linux man-pages 6.7" .SH NAME abort \- cause abnormal process termination .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B [[noreturn]] void abort(void); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ This results in the abnormal termination of the process unless the signal is caught and the signal handler does not return (see .BR longjmp (3)). -.PP +.P If the .B SIGABRT signal is ignored, or caught by a handler that returns, the @@ -47,7 +47,7 @@ function will still terminate the process. It does this by restoring the default disposition for .B SIGABRT and then raising the signal for a second time. -.PP +.P As with other cases of abnormal termination the functions registered with .BR atexit (3) and @@ -71,12 +71,11 @@ T{ .BR abort () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY SVr4, POSIX.1-2001, 4.3BSD, C89. -.PP +.P Up until glibc 2.26, if the .BR abort () diff --git a/man3/abs.3 b/man3/abs.3 index 1d70ba5..6492c6b 100644 --- a/man3/abs.3 +++ b/man3/abs.3 @@ -12,7 +12,7 @@ .\" Modified Sat Jul 24 21:45:37 1993, Rik Faith (faith@cs.unc.edu) .\" Modified Sat Dec 16 15:02:59 2000, Joseph S. Myers .\" -.TH abs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH abs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME abs, labs, llabs, imaxabs \- compute the absolute value of an integer .SH LIBRARY @@ -21,21 +21,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int abs(int " j ); .BI "long labs(long " j ); .BI "long long llabs(long long " j ); -.PP +.P .B #include -.PP +.P .BI "intmax_t imaxabs(intmax_t " j ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR llabs (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -72,7 +72,6 @@ T{ .BR imaxabs () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -80,7 +79,7 @@ POSIX.1-2001, C99, SVr4, 4.3BSD. .\" POSIX.1 (1996 edition) requires only the .\" .BR abs () .\" function. -.PP +.P C89 only includes the .BR abs () @@ -94,20 +93,20 @@ were added in C99. .SH NOTES Trying to take the absolute value of the most negative integer is not defined. -.PP +.P The .BR llabs () function is included since glibc 2.0. The .BR imaxabs () function is included since glibc 2.1.1. -.PP +.P For .BR llabs () to be declared, it may be necessary to define \fB_ISOC99_SOURCE\fP or \fB_ISOC9X_SOURCE\fP (depending on the version of glibc) before including any standard headers. -.PP +.P By default, GCC handles .BR abs (), diff --git a/man3/acos.3 b/man3/acos.3 index a81b4ef..b67d1cd 100644 --- a/man3/acos.3 +++ b/man3/acos.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-25 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH acos 3 2023-07-20 "Linux man-pages 6.05.01" +.TH acos 3 2023-10-31 "Linux man-pages 6.7" .SH NAME acos, acosf, acosl \- arc cosine function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double acos(double " x ); .BI "float acosf(float " x ); .BI "long double acosl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR acosf (), .BR acosl (): .nf @@ -50,22 +50,22 @@ the value whose cosine is On success, these functions return the arc cosine of .I x in radians; the return value is in the range [0,\ pi]. -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +1, +0 is returned. -.PP +.P If .I x is positive infinity or negative infinity, a domain error occurs, and a NaN is returned. -.PP +.P If .I x is outside the range [\-1,\ 1], @@ -76,7 +76,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is outside the range [\-1,\ 1] @@ -102,12 +102,11 @@ T{ .BR acosl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/acosh.3 b/man3/acosh.3 index b846807..0c8963d 100644 --- a/man3/acosh.3 +++ b/man3/acosh.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-25 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH acosh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH acosh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME acosh, acoshf, acoshl \- inverse hyperbolic cosine function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double acosh(double " x ); .BI "float acoshf(float " x ); .BI "long double acoshl(long double " x ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR acosh (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -41,7 +41,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR acoshf (), .BR acoshl (): .nf @@ -57,19 +57,19 @@ that is the value whose hyperbolic cosine is .SH RETURN VALUE On success, these functions return the inverse hyperbolic cosine of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +1, +0 is returned. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is less than 1, @@ -80,7 +80,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is less than 1 @@ -106,12 +106,11 @@ T{ .BR acoshl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/addseverity.3 b/man3/addseverity.3 index 447725c..9f430e6 100644 --- a/man3/addseverity.3 +++ b/man3/addseverity.3 @@ -5,7 +5,7 @@ .\" adapted glibc info page .\" .\" polished a little, aeb -.TH addseverity 3 2023-07-20 "Linux man-pages 6.05.01" +.TH addseverity 3 2023-10-31 "Linux man-pages 6.7" .SH NAME addseverity \- introduce new severity classes .SH LIBRARY @@ -13,17 +13,17 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .B #include -.PP +.P .BI "int addseverity(int " severity ", const char *" s ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR addseverity (): .nf Since glibc 2.19: @@ -75,7 +75,6 @@ T{ .BR addseverity () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY diff --git a/man3/adjtime.3 b/man3/adjtime.3 index 1d9da6e..a6fcce5 100644 --- a/man3/adjtime.3 +++ b/man3/adjtime.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH adjtime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH adjtime 3 2024-01-28 "Linux man-pages 6.7" .SH NAME adjtime \- correct the time to synchronize the system clock .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int adjtime(const struct timeval *" delta ", struct timeval *" olddelta ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR adjtime (): .nf Since glibc 2.19: @@ -37,7 +37,7 @@ The amount of time by which the clock is to be adjusted is specified in the structure pointed to by .IR delta . This structure has the following form: -.PP +.P .in +4n .EX struct timeval { @@ -46,7 +46,7 @@ struct timeval { }; .EE .in -.PP +.P If the adjustment in .I delta is positive, then the system clock is speeded up by some @@ -56,7 +56,7 @@ has been completed. If the adjustment in .I delta is negative, then the clock is slowed down in a similar fashion. -.PP +.P If a clock adjustment from an earlier .BR adjtime () call is already in progress @@ -66,7 +66,7 @@ call, and .I delta is not NULL for the later call, then the earlier adjustment is stopped, but any already completed part of that adjustment is not undone. -.PP +.P If .I olddelta is not NULL, then the buffer that it points to is used to return @@ -105,7 +105,6 @@ T{ .BR adjtime () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -117,11 +116,11 @@ makes to the clock is carried out in such a manner that the clock is always monotonically increasing. Using .BR adjtime () -to adjust the time prevents the problems that can be caused for certain +to adjust the time prevents the problems that could be caused for certain applications (e.g., .BR make (1)) by abrupt positive or negative jumps in the system time. -.PP +.P .BR adjtime () is intended to be used to make small adjustments to the system time. Most systems impose a limit on the adjustment that can be specified in diff --git a/man3/aio_cancel.3 b/man3/aio_cancel.3 index e8ef7d5..1125669 100644 --- a/man3/aio_cancel.3 +++ b/man3/aio_cancel.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_cancel 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_cancel 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_cancel \- cancel an outstanding asynchronous I/O request .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int aio_cancel(int " fd ", struct aiocb *" aiocbp ); .fi .SH DESCRIPTION @@ -33,11 +33,11 @@ is canceled. for a description of the .I aiocb structure.) -.PP +.P Normal asynchronous notification occurs for canceled requests (see .BR aio (7) and -.BR sigevent (7)). +.BR sigevent (3type)). The request return status .RB ( aio_return (3)) is set to \-1, and the request error status @@ -45,21 +45,21 @@ is set to \-1, and the request error status is set to .BR ECANCELED . The control block of requests that cannot be canceled is not changed. -.PP +.P If the request could not be canceled, then it will terminate in the usual way after performing the I/O operation. (In this case, .BR aio_error (3) will return the status .BR EINPROGRESSS .) -.PP +.P If .I aiocbp is not NULL, and .I fd differs from the file descriptor with which the asynchronous operation was initiated, unspecified results occur. -.PP +.P Which operations are cancelable is implementation-defined. .\" FreeBSD: not those on raw disk devices. .SH RETURN VALUE @@ -106,7 +106,6 @@ T{ .BR aio_cancel () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/aio_error.3 b/man3/aio_error.3 index 77d33e0..9f8bf8c 100644 --- a/man3/aio_error.3 +++ b/man3/aio_error.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_error 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_error 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_error \- get error status of asynchronous I/O operation .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int aio_error(const struct aiocb *" aiocbp ); .fi .SH DESCRIPTION @@ -76,7 +76,6 @@ T{ .BR aio_error () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/aio_fsync.3 b/man3/aio_fsync.3 index 1dea3d8..4246c56 100644 --- a/man3/aio_fsync.3 +++ b/man3/aio_fsync.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_fsync 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_fsync 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_fsync \- asynchronous file synchronization .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int aio_fsync(int " op ", struct aiocb *" aiocbp ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ associated with for a description of the .I aiocb structure.) -.PP +.P More precisely, if .I op is @@ -40,9 +40,9 @@ is .BR O_DSYNC , this call is the asynchronous analog of .BR fdatasync (2). -.PP +.P Note that this is a request only; it does not wait for I/O completion. -.PP +.P Apart from .IR aio_fildes , the only field in the structure pointed to by @@ -52,7 +52,7 @@ that is used by this call is the field (a .I sigevent structure, described in -.BR sigevent (7)), +.BR sigevent (3type)), which indicates the desired type of asynchronous notification at completion. All other fields are ignored. .SH RETURN VALUE @@ -95,7 +95,6 @@ T{ .BR aio_fsync () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -110,4 +109,4 @@ POSIX.1-2001. .BR aio_write (3), .BR lio_listio (3), .BR aio (7), -.BR sigevent (7) +.BR sigevent (3type) diff --git a/man3/aio_init.3 b/man3/aio_init.3 index 4b97839..2e43d03 100644 --- a/man3/aio_init.3 +++ b/man3/aio_init.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH aio_init 3 2023-03-30 "Linux man-pages 6.05.01" +.TH aio_init 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_init \- asynchronous I/O initialization .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B "#include " -.PP +.P .BI "void aio_init(const struct aioinit *" init ); .fi .SH DESCRIPTION @@ -22,11 +22,11 @@ function allows the caller to provide tuning hints to the glibc POSIX AIO implementation. Use of this function is optional, but to be effective, it must be called before employing any other functions in the POSIX AIO API. -.PP +.P The tuning information is provided in the buffer pointed to by the argument .IR init . This buffer is a structure of the following form: -.PP +.P .in +4n .EX struct aioinit { @@ -43,7 +43,7 @@ struct aioinit { }; .EE .in -.PP +.P The following fields are used in the .I aioinit structure: diff --git a/man3/aio_read.3 b/man3/aio_read.3 index 909d444..49de8f8 100644 --- a/man3/aio_read.3 +++ b/man3/aio_read.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_read 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_read 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_read \- asynchronous read .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int aio_read(struct aiocb *" aiocbp ); .fi .SH DESCRIPTION @@ -23,13 +23,13 @@ function queues the I/O request described by the buffer pointed to by This function is the asynchronous analog of .BR read (2). The arguments of the call -.PP +.P .in +4n .EX read(fd, buf, count) .EE .in -.PP +.P correspond (in order) to the fields .IR aio_fildes , .IR aio_buf , @@ -42,13 +42,13 @@ of the structure pointed to by for a description of the .I aiocb structure.) -.PP +.P The data is read starting at the absolute position .IR aiocbp\->aio_offset , regardless of the file offset. After the call, the value of the file offset is unspecified. -.PP +.P The "asynchronous" means that this call returns as soon as the request has been enqueued; the read may or may not have completed when the call returns. @@ -59,20 +59,20 @@ The return status of a completed I/O operation can be obtained by Asynchronous notification of I/O completion can be obtained by setting .I aiocbp\->aio_sigevent appropriately; see -.BR sigevent (7) +.BR sigevent (3type) for details. -.PP +.P If .B _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the asynchronous operation is submitted at a priority equal to that of the calling process minus .IR aiocbp\->aio_reqprio . -.PP +.P The field .I aiocbp\->aio_lio_opcode is ignored. -.PP +.P No data is read from a regular file beyond its maximum offset. .SH RETURN VALUE On success, 0 is returned. @@ -128,7 +128,6 @@ T{ .BR aio_read () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -142,7 +141,7 @@ The buffer area being read into .\" or the control block of the operation must not be accessed during the operation or undefined results may occur. The memory areas involved must remain valid. -.PP +.P Simultaneous I/O operations specifying the same .I aiocb structure produce undefined results. diff --git a/man3/aio_return.3 b/man3/aio_return.3 index c0d14a6..1993d04 100644 --- a/man3/aio_return.3 +++ b/man3/aio_return.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_return 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_return 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_return \- get return status of asynchronous I/O operation .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "ssize_t aio_return(struct aiocb *" aiocbp ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ with control block pointed to by for a description of the .I aiocb structure.) -.PP +.P This function should be called only once for any given request, after .BR aio_error (3) returns something other than @@ -41,7 +41,7 @@ or .BR fdatasync (2), call. On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. -.PP +.P If the asynchronous I/O operation has not yet completed, the return value and effect of .BR aio_return () @@ -70,7 +70,6 @@ T{ .BR aio_return () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/aio_suspend.3 b/man3/aio_suspend.3 index b532568..c8f606e 100644 --- a/man3/aio_suspend.3 +++ b/man3/aio_suspend.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_suspend 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_suspend 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_suspend \- wait for asynchronous I/O operation or timeout .SH LIBRARY @@ -12,9 +12,9 @@ Real-time library .RI ( librt ", " \-lrt ) .SH SYNOPSIS .nf -.PP +.P .B "#include " -.PP +.P .BI "int aio_suspend(const struct aiocb *const " aiocb_list "[], int " nitems , .BI " const struct timespec *restrict " timeout ); .fi @@ -35,7 +35,7 @@ is not NULL and the specified time interval has passed. .I timespec structure, see .BR nanosleep (2).) -.PP +.P The .I nitems argument specifies the number of items in @@ -53,7 +53,7 @@ or for a description of the .I aiocb structure.) -.PP +.P If .B CLOCK_MONOTONIC is supported, this clock is used to measure @@ -96,13 +96,12 @@ T{ .BR aio_suspend () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.1. POSIX.1-2001. -.PP +.P POSIX doesn't specify the parameters to be .IR restrict ; that is specific to glibc. @@ -110,13 +109,13 @@ that is specific to glibc. One can achieve polling by using a non-NULL .I timeout that specifies a zero time interval. -.PP +.P If one or more of the asynchronous I/O operations specified in .I aiocb_list has already completed at the time of the call to .BR aio_suspend (), then the call returns immediately. -.PP +.P To determine which I/O operations have completed after a successful return from .BR aio_suspend (), diff --git a/man3/aio_write.3 b/man3/aio_write.3 index 20b0349..eaba457 100644 --- a/man3/aio_write.3 +++ b/man3/aio_write.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH aio_write 3 2023-07-20 "Linux man-pages 6.05.01" +.TH aio_write 3 2023-10-31 "Linux man-pages 6.7" .SH NAME aio_write \- asynchronous write .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int aio_write(struct aiocb *" aiocbp ); .fi .SH DESCRIPTION @@ -23,13 +23,13 @@ function queues the I/O request described by the buffer pointed to by This function is the asynchronous analog of .BR write (2). The arguments of the call -.PP +.P .in +4n .EX write(fd, buf, count) .EE .in -.PP +.P correspond (in order) to the fields .IR aio_fildes , .IR aio_buf , @@ -42,7 +42,7 @@ of the structure pointed to by for a description of the .I aiocb structure.) -.PP +.P If .B O_APPEND is not set, the data is written starting at the @@ -55,7 +55,7 @@ is set, data is written at the end of the file in the same order as .BR aio_write () calls are made. After the call, the value of the file offset is unspecified. -.PP +.P The "asynchronous" means that this call returns as soon as the request has been enqueued; the write may or may not have completed when the call returns. @@ -66,20 +66,20 @@ The return status of a completed I/O operation can be obtained Asynchronous notification of I/O completion can be obtained by setting .I aiocbp\->aio_sigevent appropriately; see -.BR sigevent (7) +.BR sigevent (3type) for details. -.PP +.P If .B _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the asynchronous operation is submitted at a priority equal to that of the calling process minus .IR aiocbp\->aio_reqprio . -.PP +.P The field .I aiocbp\->aio_lio_opcode is ignored. -.PP +.P No data is written to a regular file beyond its maximum offset. .SH RETURN VALUE On success, 0 is returned. @@ -133,7 +133,6 @@ T{ .BR aio_write () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -147,7 +146,7 @@ The buffer area being written out .\" or the control block of the operation must not be accessed during the operation or undefined results may occur. The memory areas involved must remain valid. -.PP +.P Simultaneous I/O operations specifying the same .I aiocb structure produce undefined results. diff --git a/man3/alloca.3 b/man3/alloca.3 index 6bf1791..7fa61bc 100644 --- a/man3/alloca.3 +++ b/man3/alloca.3 @@ -13,7 +13,7 @@ .\" Various rewrites and additions (notes on longjmp() and SIGSEGV). .\" Weaken warning against use of alloca() (as per Debian bug 461100). .\" -.TH alloca 3 2023-07-20 "Linux man-pages 6.05.01" +.TH alloca 3 2023-10-31 "Linux man-pages 6.7" .SH NAME alloca \- allocate memory that is automatically freed .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *alloca(size_t " size ); .fi .SH DESCRIPTION @@ -54,7 +54,6 @@ T{ .BR alloca () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -73,7 +72,7 @@ it can also simplify memory deallocation in applications that use or .BR siglongjmp (3). Otherwise, its use is discouraged. -.PP +.P Because the space allocated by .BR alloca () is allocated within the stack frame, @@ -82,19 +81,19 @@ is jumped over by a call to .BR longjmp (3) or .BR siglongjmp (3). -.PP +.P The space allocated by .BR alloca () is .I not automatically deallocated if the pointer that refers to it simply goes out of scope. -.PP +.P Do not attempt to .BR free (3) space allocated by .BR alloca ()! -.PP +.P By necessity, .BR alloca () is a compiler built-in, also known as @@ -107,12 +106,12 @@ into the built-in, but this is forbidden if standards conformance is requested in which case .I is required, lest a symbol dependency be emitted. -.PP +.P The fact that .BR alloca () is a built-in means it is impossible to take its address or to change its behavior by linking with a different library. -.PP +.P Variable length arrays (VLAs) are part of the C99 standard, optional since C11, and can be used for a similar purpose. However, they do not port to standard C++, and, being variables, @@ -125,7 +124,7 @@ would overflow the space available, and, hence, neither is indicating an error. (However, the program is likely to receive a .B SIGSEGV signal if it attempts to access unavailable space.) -.PP +.P On many systems .BR alloca () cannot be used inside the list of arguments of a function call, because diff --git a/man3/arc4random.3 b/man3/arc4random.3 index b7e1f4d..b205ca9 100644 --- a/man3/arc4random.3 +++ b/man3/arc4random.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH arc4random 3 2023-07-20 "Linux man-pages 6.05.01" +.TH arc4random 3 2023-10-31 "Linux man-pages 6.7" .SH NAME arc4random, arc4random_uniform, arc4random_buf \- cryptographically-secure pseudorandom number generator @@ -13,29 +13,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B uint32_t arc4random(void); .BI "uint32_t arc4random_uniform(uint32_t " upper_bound ); .BI "void arc4random_buf(void " buf [. n "], size_t " n ); .fi .SH DESCRIPTION These functions give cryptographically-secure pseudorandom numbers. -.PP +.P .BR arc4random () returns a uniformly-distributed value. -.PP +.P .BR arc4random_uniform () returns a uniformly-distributed value less than .I upper_bound (see BUGS). -.PP +.P .BR arc4random_buf () fills the memory pointed to by .IR buf , with .I n bytes of pseudorandom data. -.PP +.P The .BR rand (3) and @@ -51,7 +51,7 @@ functions. .SH RETURN VALUE .BR arc4random () returns a pseudorandom number. -.PP +.P .BR arc4random_uniform () returns a pseudorandom number less than .I upper_bound @@ -76,7 +76,6 @@ T{ .BR arc4random_buf () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY diff --git a/man3/argz_add.3 b/man3/argz_add.3 index 3654e7b..c61705a 100644 --- a/man3/argz_add.3 +++ b/man3/argz_add.3 @@ -6,7 +6,7 @@ .\" based on the description in glibc source and infopages .\" .\" Corrections and additions, aeb -.TH argz_add 3 2023-07-20 "Linux man-pages 6.05.01" +.TH argz_add 3 2023-10-31 "Linux man-pages 6.7" .SH NAME argz_add, argz_add_sep, argz_append, argz_count, argz_create, argz_create_sep, argz_delete, argz_extract, argz_insert, @@ -17,52 +17,52 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "error_t argz_add(char **restrict " argz ", size_t *restrict " argz_len , .BI " const char *restrict " str ); -.PP +.P .BI "error_t argz_add_sep(char **restrict " argz \ ", size_t *restrict " argz_len , .BI " const char *restrict " str ", int " delim ); -.PP +.P .BI "error_t argz_append(char **restrict " argz ", size_t *restrict " argz_len , .BI " const char *restrict " buf ", size_t " buf_len ); -.PP +.P .BI "size_t argz_count(const char *" argz ", size_t " argz_len ); -.PP +.P .BI "error_t argz_create(char *const " argv "[], char **restrict " argz , .BI " size_t *restrict " argz_len ); -.PP +.P .BI "error_t argz_create_sep(const char *restrict " str ", int " sep , .BI " char **restrict " argz ", size_t *restrict " argz_len ); -.PP +.P .BI "void argz_delete(char **restrict " argz ", size_t *restrict " argz_len , .BI " char *restrict " entry ); -.PP +.P .BI "void argz_extract(const char *restrict " argz ", size_t " argz_len , .BI " char **restrict " argv ); -.PP +.P .BI "error_t argz_insert(char **restrict " argz ", size_t *restrict " argz_len , .BI " char *restrict " before ", const char *restrict " entry ); -.PP +.P .BI "char *argz_next(const char *restrict " argz ", size_t " argz_len , .BI " const char *restrict " entry ); -.PP +.P .BI "error_t argz_replace(char **restrict " argz \ ", size_t *restrict " argz_len , .BI " const char *restrict " str ", const char *restrict " with , .BI " unsigned int *restrict " replace_count ); -.PP +.P .BI "void argz_stringify(char *" argz ", size_t " len ", int " sep ); .fi .SH DESCRIPTION These functions are glibc-specific. -.PP +.P An argz vector is a pointer to a character buffer together with a length. The intended interpretation of the character buffer is an array of strings, where the strings are separated by null bytes (\[aq]\e0\[aq]). If the length is nonzero, the last byte of the buffer must be a null byte. -.PP +.P These functions are for handling argz vectors. The pair (NULL,0) is an argz vector, and, conversely, argz vectors of length 0 must have null pointer. @@ -71,7 +71,7 @@ Allocation of nonempty argz vectors is done using so that .BR free (3) can be used to dispose of them again. -.PP +.P .BR argz_add () adds the string .I str @@ -81,7 +81,7 @@ and updates .I *argz and .IR *argz_len . -.PP +.P .BR argz_add_sep () is similar, but splits the string .I str @@ -89,7 +89,7 @@ into substrings separated by the delimiter .IR delim . For example, one might use this on a UNIX search path with delimiter \[aq]:\[aq]. -.PP +.P .BR argz_append () appends the argz vector .RI ( buf ,\ buf_len ) @@ -103,12 +103,12 @@ and .I *argz_len will be increased by .IR buf_len .) -.PP +.P .BR argz_count () counts the number of strings, that is, the number of null bytes (\[aq]\e0\[aq]), in .RI ( argz ,\ argz_len ). -.PP +.P .BR argz_create () converts a UNIX-style argument vector .IR argv , @@ -116,7 +116,7 @@ terminated by .IR "(char\ *)\ 0" , into an argz vector .RI ( *argz ,\ *argz_len ). -.PP +.P .BR argz_create_sep () converts the null-terminated string .I str @@ -124,7 +124,7 @@ into an argz vector .RI ( *argz ,\ *argz_len ) by breaking it up at every occurrence of the separator .IR sep . -.PP +.P .BR argz_delete () removes the substring pointed to by .I entry @@ -134,7 +134,7 @@ and updates .I *argz and .IR *argz_len . -.PP +.P .BR argz_extract () is the opposite of .BR argz_create (). @@ -149,7 +149,7 @@ The array must have room for .IR argz_count ( argz ", " argz_len ") + 1" pointers. -.PP +.P .BR argz_insert () is the opposite of .BR argz_delete (). @@ -168,7 +168,7 @@ If is NULL, then .I entry will inserted at the end. -.PP +.P .BR argz_next () is a function to step through the argz vector. If @@ -177,7 +177,7 @@ is NULL, the first entry is returned. Otherwise, the entry following is returned. It returns NULL if there is no following entry. -.PP +.P .BR argz_replace () replaces each occurrence of .I str @@ -189,7 +189,7 @@ If is non-NULL, .I *replace_count will be incremented by the number of replacements. -.PP +.P .BR argz_stringify () is the opposite of .BR argz_create_sep (). @@ -228,7 +228,6 @@ T{ .BR argz_stringify () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH BUGS diff --git a/man3/asin.3 b/man3/asin.3 index 74ac283..3545d5c 100644 --- a/man3/asin.3 +++ b/man3/asin.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-25 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH asin 3 2023-07-20 "Linux man-pages 6.05.01" +.TH asin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME asin, asinf, asinl \- arc sine function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double asin(double " x ); .BI "float asinf(float " x ); .BI "long double asinl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR asinf (), .BR asinl (): .nf @@ -49,16 +49,16 @@ that is the value whose sine is On success, these functions return the principal value of the arc sine of .I x in radians; the return value is in the range [\-pi/2,\ pi/2]. -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is outside the range [\-1,\ 1], @@ -72,7 +72,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is outside the range [\-1,\ 1] @@ -98,12 +98,11 @@ T{ .BR asinl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/asinh.3 b/man3/asinh.3 index 3197390..dd0ada0 100644 --- a/man3/asinh.3 +++ b/man3/asinh.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH asinh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH asinh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME asinh, asinhf, asinhl \- inverse hyperbolic sine function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double asinh(double " x ); .BI "float asinhf(float " x ); .BI "long double asinhl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR asinh (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -41,7 +41,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR asinhf (), .BR asinhl (): .nf @@ -57,15 +57,15 @@ that is the value whose hyperbolic sine is .SH RETURN VALUE On success, these functions return the inverse hyperbolic sine of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity (negative infinity), @@ -91,12 +91,11 @@ T{ .BR asinhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/asprintf.3 b/man3/asprintf.3 index adc3e5b..40b687b 100644 --- a/man3/asprintf.3 +++ b/man3/asprintf.3 @@ -5,7 +5,7 @@ .\" .\" Text fragments inspired by Martin Schulze . .\" -.TH asprintf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH asprintf 3 2023-10-31 "Linux man-pages 6.7" .SH NAME asprintf, vasprintf \- print to allocated string .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int asprintf(char **restrict " strp ", const char *restrict " fmt ", ...);" .BI "int vasprintf(char **restrict " strp ", const char *restrict " fmt , .BI " va_list " ap ); @@ -58,7 +58,6 @@ T{ .BR vasprintf () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS The FreeBSD implementation sets .I strp diff --git a/man3/assert.3 b/man3/assert.3 index b1e8a9d..6f5a242 100644 --- a/man3/assert.3 +++ b/man3/assert.3 @@ -6,7 +6,7 @@ .\" Modified Sat Jul 24 21:42:42 1993 by Rik Faith .\" Modified Tue Oct 22 23:44:11 1996 by Eric S. Raymond .\" Modified Thu Jun 2 23:44:11 2016 by Nikos Mavrogiannopoulos -.TH assert 3 2023-07-20 "Linux man-pages 6.05.01" +.TH assert 3 2023-10-31 "Linux man-pages 6.7" .SH NAME assert \- abort the program if assertion is false .SH LIBRARY @@ -15,14 +15,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void assert(scalar " expression ); .fi .SH DESCRIPTION This macro can help programmers find bugs in their programs, or handle exceptional cases via a crash that will produce limited debugging output. -.PP +.P If .I expression is false (i.e., compares equal to zero), @@ -34,13 +34,13 @@ The error message includes the name of the file and function containing the .BR assert () call, the source code line number of the call, and the text of the argument; something like: -.PP +.P .in +4n .EX prog: some_file.c:16: some_func: Assertion \`val == 0\[aq] failed. .EE .in -.PP +.P If the macro .B NDEBUG is defined at the moment @@ -70,12 +70,11 @@ T{ .BR assert () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C89, C99, POSIX.1-2001. -.PP +.P In C89, .I expression is required to be of type diff --git a/man3/assert_perror.3 b/man3/assert_perror.3 index 77d70f1..cde8024 100644 --- a/man3/assert_perror.3 +++ b/man3/assert_perror.3 @@ -6,7 +6,7 @@ .\" This replaces an earlier man page written by Walter Harms .\" . .\" -.TH assert_perror 3 2023-07-20 "Linux man-pages 6.05.01" +.TH assert_perror 3 2023-10-31 "Linux man-pages 6.7" .SH NAME assert_perror \- test errnum and abort .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void assert_perror(int " errnum ); .fi .SH DESCRIPTION @@ -54,7 +54,6 @@ T{ .BR assert_perror () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH BUGS diff --git a/man3/atan.3 b/man3/atan.3 index 5c89c62..8e86698 100644 --- a/man3/atan.3 +++ b/man3/atan.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH atan 3 2023-07-20 "Linux man-pages 6.05.01" +.TH atan 3 2023-10-31 "Linux man-pages 6.7" .SH NAME atan, atanf, atanl \- arc tangent function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double atan(double " x ); .BI "float atanf(float " x ); .BI "long double atanl(long double " x ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR atanf (), .BR atanl (): .nf @@ -49,16 +49,16 @@ that is the value whose tangent is On success, these functions return the principal value of the arc tangent of .I x in radians; the return value is in the range [\-pi/2,\ pi/2]. -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity (negative infinity), +pi/2 (\-pi/2) is returned. @@ -83,12 +83,11 @@ T{ .BR atanl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/atan2.3 b/man3/atan2.3 index 0532b47..9ac661b 100644 --- a/man3/atan2.3 +++ b/man3/atan2.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH atan2 3 2023-07-20 "Linux man-pages 6.05.01" +.TH atan2 3 2023-10-31 "Linux man-pages 6.7" .SH NAME atan2, atan2f, atan2l \- arc tangent function of two variables .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double atan2(double " y ", double " x ); .BI "float atan2f(float " y ", float " x ); .BI "long double atan2l(long double " y ", long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR atan2f (), .BR atan2l (): .nf @@ -49,31 +49,31 @@ the quadrant of the result. On success, these functions return the principal value of the arc tangent of .I y/x in radians; the return value is in the range [\-pi,\ pi]. -.PP +.P If .I y is +0 (\-0) and .I x is less than 0, +pi (\-pi) is returned. -.PP +.P If .I y is +0 (\-0) and .I x is greater than 0, +0 (\-0) is returned. -.PP +.P If .I y is less than 0 and .I x is +0 or \-0, \-pi/2 is returned. -.PP +.P If .I y is greater than 0 and .I x is +0 or \-0, pi/2 is returned. -.PP +.P .\" POSIX.1 says: .\" If .\" .I x @@ -84,7 +84,7 @@ If either or .I y is NaN, a NaN is returned. -.PP +.P .\" POSIX.1 says: .\" If the result underflows, a range error may occur and .\" .I y/x @@ -95,38 +95,38 @@ If is +0 (\-0) and .I x is \-0, +pi (\-pi) is returned. -.PP +.P If .I y is +0 (\-0) and .I x is +0, +0 (\-0) is returned. -.PP +.P If .I y is a finite value greater (less) than 0, and .I x is negative infinity, +pi (\-pi) is returned. -.PP +.P If .I y is a finite value greater (less) than 0, and .I x is positive infinity, +0 (\-0) is returned. -.PP +.P If .I y is positive infinity (negative infinity), and .I x is finite, pi/2 (\-pi/2) is returned. -.PP +.P If .I y is positive infinity (negative infinity) and .I x is negative infinity, +3*pi/4 (\-3*pi/4) is returned. -.PP +.P If .I y is positive infinity (negative infinity) and @@ -155,12 +155,11 @@ T{ .BR atan2l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/atanh.3 b/man3/atanh.3 index f3a9b2e..0220493 100644 --- a/man3/atanh.3 +++ b/man3/atanh.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH atanh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH atanh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME atanh, atanhf, atanhl \- inverse hyperbolic tangent function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double atanh(double " x ); .BI "float atanhf(float " x ); .BI "long double atanhl(long double " x ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR atanh (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -41,7 +41,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR atanhf (), .BR atanhl (): .nf @@ -57,15 +57,15 @@ that is the value whose hyperbolic tangent is .SH RETURN VALUE On success, these functions return the inverse hyperbolic tangent of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is +1 or \-1, @@ -76,7 +76,7 @@ and the functions return or .BR HUGE_VALL , respectively, with the mathematically correct sign. -.PP +.P If the absolute value of .I x is greater than 1, @@ -90,7 +90,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP less than \-1 or greater than +1 @@ -125,12 +125,11 @@ T{ .BR atanhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/atexit.3 b/man3/atexit.3 index 4a57ac5..4a9842b 100644 --- a/man3/atexit.3 +++ b/man3/atexit.3 @@ -11,7 +11,7 @@ .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) .\" Modified 2003-10-25, Walter Harms .\" -.TH atexit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH atexit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME atexit \- register a function to be called at normal process termination .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int atexit(void (*" function )(void)); .fi .SH DESCRIPTION @@ -35,17 +35,17 @@ or via return from the program's .IR main (). Functions so registered are called in the reverse order of their registration; no arguments are passed. -.PP +.P The same function may be registered multiple times: it is called once for each registration. -.PP +.P POSIX.1 requires that an implementation allow at least .\" POSIX.1-2001, POSIX.1-2008 .B ATEXIT_MAX (32) such functions to be registered. The actual limit supported by an implementation can be obtained using .BR sysconf (3). -.PP +.P When a child process is created via .BR fork (2), it inherits copies of its parent's registrations. @@ -72,7 +72,6 @@ T{ .BR atexit () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS POSIX.1 says that the result of calling .\" POSIX.1-2001, POSIX.1-2008 @@ -102,14 +101,14 @@ Functions registered using .BR on_exit (3)) are not called if a process terminates abnormally because of the delivery of a signal. -.PP +.P If one of the registered functions calls .BR _exit (2), then any remaining functions are not invoked, and the other process termination steps performed by .BR exit (3) are not performed. -.PP +.P The .BR atexit () and @@ -118,7 +117,7 @@ functions register functions on the same list: at normal process termination, the registered functions are invoked in reverse order of their registration by these two functions. -.PP +.P According to POSIX.1, the result is undefined if .BR longjmp (3) is used to terminate execution of one of the functions registered using diff --git a/man3/atof.3 b/man3/atof.3 index bb1398a..acb75ae 100644 --- a/man3/atof.3 +++ b/man3/atof.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Mon Mar 29 22:39:24 1993, David Metcalfe .\" Modified Sat Jul 24 21:39:22 1993, Rik Faith (faith@cs.unc.edu) -.TH atof 3 2023-07-20 "Linux man-pages 6.05.01" +.TH atof 3 2023-10-31 "Linux man-pages 6.7" .SH NAME atof \- convert a string to a double .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double atof(const char *" nptr ); .fi .SH DESCRIPTION @@ -28,13 +28,13 @@ function converts the initial portion of the string pointed to by \fInptr\fP to .IR double . The behavior is the same as -.PP +.P .in +4n .EX strtod(nptr, NULL); .EE .in -.PP +.P except that .BR atof () does not detect errors. @@ -54,7 +54,6 @@ T{ .BR atof () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/atoi.3 b/man3/atoi.3 index d1d32f5..ebe67f3 100644 --- a/man3/atoi.3 +++ b/man3/atoi.3 @@ -11,7 +11,7 @@ .\" Modified Sat Jul 24 21:38:42 1993, Rik Faith (faith@cs.unc.edu) .\" Modified Sun Dec 17 18:35:06 2000, Joseph S. Myers .\" -.TH atoi 3 2023-07-20 "Linux man-pages 6.05.01" +.TH atoi 3 2023-10-31 "Linux man-pages 6.7" .SH NAME atoi, atol, atoll \- convert a string to an integer .SH LIBRARY @@ -20,17 +20,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int atoi(const char *" nptr ); .BI "long atol(const char *" nptr ); .BI "long long atoll(const char *" nptr ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR atoll (): .nf _ISOC99_SOURCE @@ -43,17 +43,17 @@ function converts the initial portion of the string pointed to by \fInptr\fP to .IR int . The behavior is the same as -.PP +.P .in +4n .EX strtol(nptr, NULL, 10); .EE .in -.PP +.P except that .BR atoi () does not detect errors. -.PP +.P The .BR atol () and @@ -80,7 +80,6 @@ T{ .BR atoll () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS POSIX.1 leaves the return value of .BR atoi () @@ -90,7 +89,7 @@ On glibc, musl libc, and uClibc, 0 is returned on error. C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P C89 and POSIX.1-1996 include the functions .BR atoi () diff --git a/man3/backtrace.3 b/man3/backtrace.3 index ae970ff..399b180 100644 --- a/man3/backtrace.3 +++ b/man3/backtrace.3 @@ -25,7 +25,7 @@ .\" .\" References: .\" glibc manual and source -.TH backtrace 3 2023-07-20 "Linux man-pages 6.05.01" +.TH backtrace 3 2023-10-31 "Linux man-pages 6.7" .SH NAME backtrace, backtrace_symbols, backtrace_symbols_fd \- support for application self-debugging @@ -35,9 +35,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int backtrace(void *" buffer [. size "], int " size ); -.PP +.P .BI "char **backtrace_symbols(void *const " buffer [. size "], int " size ); .BI "void backtrace_symbols_fd(void *const " buffer [. size "], int " size ", \ int " fd ); @@ -70,7 +70,7 @@ to obtain the complete backtrace, make sure that and .I size are large enough. -.PP +.P Given the set of addresses returned by .BR backtrace () in @@ -95,7 +95,7 @@ by and must be freed by the caller. (The strings pointed to by the array of pointers need not and should not be freed.) -.PP +.P .BR backtrace_symbols_fd () takes the same .I buffer @@ -123,7 +123,7 @@ then the full backtrace was stored; if it is equal to .IR size , then it may have been truncated, in which case the addresses of the oldest stack frames are not returned. -.PP +.P On success, .BR backtrace_symbols () returns a pointer to the array @@ -146,7 +146,6 @@ T{ .BR backtrace_symbols_fd () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -180,7 +179,7 @@ If you need certain calls to these two functions to not allocate memory (in signal handlers, for example), you need to make sure .I libgcc is loaded beforehand. -.PP +.P The symbol names may be unavailable without the use of special linker options. For systems using the GNU linker, it is necessary to use the @@ -195,7 +194,7 @@ and .BR backtrace_symbols (). The following shell session shows what we might see when running the program: -.PP +.P .in +4n .EX .RB "$" " cc \-rdynamic prog.c \-o prog" diff --git a/man3/basename.3 b/man3/basename.3 index 266c49a..a3dc075 100644 --- a/man3/basename.3 +++ b/man3/basename.3 @@ -5,7 +5,7 @@ .\" .\" Created, 14 Dec 2000 by Michael Kerrisk .\" -.TH basename 3 2023-07-20 "Linux man-pages 6.05.01" +.TH basename 3 2023-10-31 "Linux man-pages 6.7" .SH NAME basename, dirname \- parse pathname components .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *dirname(char *" path ); .BI "char *basename(char *" path ); .fi @@ -22,7 +22,7 @@ Standard C library Warning: there are two different functions .BR basename (); see below. -.PP +.P The functions .BR dirname () and @@ -35,7 +35,7 @@ returns the string up to, but not including, the final \[aq]/\[aq], and .BR basename () returns the component following the final \[aq]/\[aq]. Trailing \[aq]/\[aq] characters are not counted as part of the pathname. -.PP +.P If .I path does not contain a slash, @@ -58,13 +58,13 @@ is a null pointer or points to an empty string, then both and .BR basename () return the string ".". -.PP +.P Concatenating the string returned by .BR dirname (), a "/", and the string returned by .BR basename () yields a complete pathname. -.PP +.P Both .BR dirname () and @@ -73,7 +73,7 @@ may modify the contents of .IR path , so it may be desirable to pass a copy when calling one of these functions. -.PP +.P These functions may return pointers to statically allocated memory which may be overwritten by subsequent calls. Alternatively, they may return a pointer to some part of @@ -82,7 +82,7 @@ so that the string referred to by .I path should not be modified or freed until the pointer returned by the function is no longer required. -.PP +.P The following list of examples (taken from SUSv2) shows the strings returned by .BR dirname () @@ -125,27 +125,26 @@ T{ .BR dirname () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS There are two different versions of .BR basename () - the POSIX version described above, and the GNU version, which one gets after -.PP +.P .in +4n .EX .BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B " #include " .EE .in -.PP +.P The GNU version never modifies its argument, and returns the empty string when .I path has a trailing slash, and in particular also when it is "/". There is no GNU version of .BR dirname (). -.PP +.P With glibc, one gets the POSIX version of .BR basename () when @@ -161,7 +160,7 @@ the POSIX versions of these functions modify the .I path argument, and segfault when called with a static string such as "/usr/". -.PP +.P Before glibc 2.2.1, the glibc version of .BR dirname () did not correctly handle pathnames with trailing \[aq]/\[aq] characters, diff --git a/man3/bcmp.3 b/man3/bcmp.3 index d3cc49d..ef96d9c 100644 --- a/man3/bcmp.3 +++ b/man3/bcmp.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH bcmp 3 2023-03-30 "Linux man-pages 6.05.01" +.TH bcmp 3 2023-11-02 "Linux man-pages 6.7" .SH NAME bcmp \- compare byte sequences .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int bcmp(const void " s1 [. n "], const void " s2 [. n "], \ size_t " n ); .fi @@ -19,7 +19,7 @@ size_t " n ); .BR bcmp () is identical to .BR memcmp (3); -use it instead. +use the latter instead. .SH STANDARDS None. .SH HISTORY diff --git a/man3/bcopy.3 b/man3/bcopy.3 index b8892e9..7f76812 100644 --- a/man3/bcopy.3 +++ b/man3/bcopy.3 @@ -11,7 +11,7 @@ .\" Modified Sun Feb 26 14:52:00 1995 by Rik Faith .\" Modified Tue Oct 22 23:48:10 1996 by Eric S. Raymond .\" " -.TH bcopy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH bcopy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bcopy \- copy byte sequence .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] void bcopy(const void " src [. n "], void " dest [. n "], \ size_t " n ); .fi @@ -50,12 +50,11 @@ T{ .BR bcopy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY 4.3BSD. -.PP +.P Marked as LEGACY in POSIX.1-2001: use .BR memcpy (3) or diff --git a/man3/bindresvport.3 b/man3/bindresvport.3 index d14e580..89cd5d0 100644 --- a/man3/bindresvport.3 +++ b/man3/bindresvport.3 @@ -8,7 +8,7 @@ .\" 2007-05-31, mtk: Rewrite and substantial additional text. .\" 2008-12-03, mtk: Rewrote some pieces and fixed some errors .\" -.TH bindresvport 3 2023-07-20 "Linux man-pages 6.05.01" +.TH bindresvport 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bindresvport \- bind a socket to a privileged IP port .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int bindresvport(int " sockfd ", struct sockaddr_in *" sin ); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ file descriptor to a privileged anonymous IP port, that is, a port number arbitrarily selected from the range 512 to 1023. .\" glibc actually starts searching with a port # in the range 600 to 1023 -.PP +.P If the .BR bind (2) performed by @@ -39,7 +39,7 @@ is successful, and is not NULL, then .I sin\->sin_port returns the port number actually allocated. -.PP +.P .I sin can be NULL, in which case .I sin\->sin_family @@ -96,8 +96,7 @@ glibc\ >=\ 2.17: MT-Safe; glibc\ <\ 2.17: MT-Unsafe T} .TE -.sp 1 -.PP +.P The .BR bindresvport () function uses a static variable that was not protected by a lock diff --git a/man3/bsd_signal.3 b/man3/bsd_signal.3 index 3294c5c..19c2147 100644 --- a/man3/bsd_signal.3 +++ b/man3/bsd_signal.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH bsd_signal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH bsd_signal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bsd_signal \- signal handling with BSD semantics .SH LIBRARY @@ -12,17 +12,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B typedef void (*sighandler_t)(int); -.PP +.P .BI "sighandler_t bsd_signal(int " signum ", sighandler_t " handler ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR bsd_signal (): .nf Since glibc 2.26: @@ -37,7 +37,7 @@ The .BR bsd_signal () function takes the same arguments, and performs the same task, as .BR signal (2). -.PP +.P The difference between the two is that .BR bsd_signal () is guaranteed to provide reliable signal semantics, that is: @@ -73,14 +73,13 @@ T{ .BR bsd_signal () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Use of .BR bsd_signal () should be avoided; use .BR sigaction (2) instead. -.PP +.P On modern Linux systems, .BR bsd_signal () and @@ -91,7 +90,7 @@ But on older systems, provided unreliable signal semantics; see .BR signal (2) for details. -.PP +.P The use of .I sighandler_t is a GNU extension; diff --git a/man3/bsearch.3 b/man3/bsearch.3 index f73b939..38a4ac3 100644 --- a/man3/bsearch.3 +++ b/man3/bsearch.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe .\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu) -.TH bsearch 3 2023-07-20 "Linux man-pages 6.05.01" +.TH bsearch 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bsearch \- binary search of a sorted array .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *bsearch(const void " key [. size "], \ const void " base [. size " * ." nmemb ], .BI " size_t " nmemb ", size_t " size , @@ -39,7 +39,7 @@ that matches the object pointed to by The size of each member of the array is specified by .IR size . -.PP +.P The contents of the array should be in ascending sorted order according to the comparison function referenced by .IR compar . @@ -74,7 +74,6 @@ T{ .BR bsearch () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -84,7 +83,7 @@ The example below first sorts an array of structures using .BR qsort (3), then retrieves desired elements using .BR bsearch (). -.PP +.P .\" SRC BEGIN (bsearch.c) .EX #include diff --git a/man3/bstring.3 b/man3/bstring.3 index 87b133a..68e8ae7 100644 --- a/man3/bstring.3 +++ b/man3/bstring.3 @@ -9,7 +9,7 @@ .\" Modified 1993-04-12, David Metcalfe .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) .\" Modified 2002-01-20, Walter Harms -.TH bstring 3 2023-01-07 "Linux man-pages 6.05.01" +.TH bstring 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bcmp, bcopy, bzero, memccpy, memchr, memcmp, memcpy, memfrob, memmem, memmove, memset \- byte string operations @@ -19,29 +19,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int bcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); -.PP +.P .BI "void bcopy(const void " src [. n "], void " dest [. n "], size_t " n ); -.PP +.P .BI "void bzero(void " s [. n "], size_t " n ); -.PP +.P .BI "void *memccpy(void " dest [. n "], const void " src [. n "], int " c ", \ size_t " n ); -.PP +.P .BI "void *memchr(const void " s [. n "], int " c ", size_t " n ); -.PP +.P .BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); -.PP +.P .BI "void *memcpy(void " dest [. n "], const void " src [. n "], size_t " n ); -.PP +.P .BI "void *memfrob(void " s [. n "], size_t " n ); -.PP +.P .BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen , .BI " const void " needle [. needlelen "], size_t " needlelen ); -.PP +.P .BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n ); -.PP +.P .BI "void *memset(void " s [. n "], int " c ", size_t " n ); .fi .SH DESCRIPTION diff --git a/man3/bswap.3 b/man3/bswap.3 index 1810e9f..53d8c51 100644 --- a/man3/bswap.3 +++ b/man3/bswap.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH bswap 3 2023-05-03 "Linux man-pages 6.05.01" +.TH bswap 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bswap_16, bswap_32, bswap_64 \- reverse order of bytes .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "uint16_t bswap_16(uint16_t " x ); .BI "uint32_t bswap_32(uint32_t " x ); .BI "uint64_t bswap_64(uint64_t " x ); @@ -29,7 +29,7 @@ GNU. The program below swaps the bytes of the 8-byte integer supplied as its command-line argument. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX $ \fB./a.out 0x0123456789abcdef\fP diff --git a/man3/btowc.3 b/man3/btowc.3 index 67e0d25..a980864 100644 --- a/man3/btowc.3 +++ b/man3/btowc.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH btowc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH btowc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME btowc \- convert single byte to wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wint_t btowc(int " c ); .fi .SH DESCRIPTION @@ -59,7 +59,6 @@ T{ .BR btowc () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -71,7 +70,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P This function should never be used. It does not work for encodings which have state, and unnecessarily treats single bytes differently from multibyte diff --git a/man3/btree.3 b/man3/btree.3 index dfa8f4e..e93e25b 100644 --- a/man3/btree.3 +++ b/man3/btree.3 @@ -5,7 +5,7 @@ .\" .\" @(#)btree.3 8.4 (Berkeley) 8/18/94 .\" -.TH btree 3 2022-12-04 "Linux man-pages 6.05.01" +.TH btree 3 2023-10-31 "Linux man-pages 6.7" .\".UC 7 .SH NAME btree \- btree database access method @@ -26,7 +26,7 @@ Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the .I libdb library instead. -.PP +.P The routine .BR dbopen (3) is the library interface to database files. @@ -34,16 +34,16 @@ One of the supported file formats is btree files. The general description of the database access methods is in .BR dbopen (3), this manual page describes only the btree-specific information. -.PP +.P The btree data structure is a sorted, balanced tree structure storing associated key/data pairs. -.PP +.P The btree access-method-specific data structure provided to .BR dbopen (3) is defined in the .I include file as follows: -.PP +.P .in +4n .EX typedef struct { @@ -58,7 +58,7 @@ typedef struct { } BTREEINFO; .EE .in -.PP +.P The elements of this structure are as follows: .TP .I flags @@ -178,7 +178,7 @@ big endian order would be the number 4,321. If .I lorder is 0 (no order is specified), the current host order is used. -.PP +.P If the file already exists (and the .B O_TRUNC flag is not specified), the @@ -189,15 +189,15 @@ and .I psize are ignored in favor of the values used when the tree was created. -.PP +.P Forward sequential scans of a tree are from the least key to the greatest. -.PP +.P Space freed up by deleting key/data pairs from the tree is never reclaimed, although it is normally made available for reuse. This means that the btree storage structure is grow-only. The only solutions are to avoid excessive deletions, or to create a fresh tree periodically from a scan of an existing one. -.PP +.P Searches, insertions, and deletions in a btree will all complete in O lg base N where base is the average fill factor. Often, inserting ordered data into btrees results in a low fill factor. @@ -217,13 +217,13 @@ Only big and little endian byte order is supported. .BR hash (3), .BR mpool (3), .BR recno (3) -.PP +.P .IR "The Ubiquitous B-tree" , Douglas Comer, ACM Comput. Surv. 11, 2 (June 1979), 121-138. -.PP +.P .IR "Prefix B-trees" , Bayer and Unterauer, ACM Transactions on Database Systems, Vol. 2, 1 (March 1977), 11-26. -.PP +.P .IR "The Art of Computer Programming Vol. 3: Sorting and Searching" , D.E. Knuth, 1968, pp 471-480. diff --git a/man3/byteorder.3 b/man3/byteorder.3 index 7040f63..e8a1439 100644 --- a/man3/byteorder.3 +++ b/man3/byteorder.3 @@ -10,7 +10,7 @@ .\" Modified Sat Jul 24 21:29:05 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Thu Jul 26 14:06:20 2001 by Andries Brouwer (aeb@cwi.nl) .\" -.TH BYTEORDER 3 2023-07-20 "Linux man-pages 6.05.01" +.TH BYTEORDER 3 2023-10-31 "Linux man-pages 6.7" .SH NAME htonl, htons, ntohl, ntohs \- convert values between host and network byte order @@ -20,10 +20,10 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "uint32_t htonl(uint32_t " hostlong ); .BI "uint16_t htons(uint16_t " hostshort ); -.PP +.P .BI "uint32_t ntohl(uint32_t " netlong ); .BI "uint16_t ntohs(uint16_t " netshort ); .fi @@ -33,25 +33,25 @@ The function converts the unsigned integer .I hostlong from host byte order to network byte order. -.PP +.P The .BR htons () function converts the unsigned short integer .I hostshort from host byte order to network byte order. -.PP +.P The .BR ntohl () function converts the unsigned integer .I netlong from network byte order to host byte order. -.PP +.P The .BR ntohs () function converts the unsigned short integer .I netshort from network byte order to host byte order. -.PP +.P On the i386 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the Internet, is Most Significant Byte first. @@ -72,7 +72,6 @@ T{ .BR ntohs () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/bzero.3 b/man3/bzero.3 index 35abb18..59b30ab 100644 --- a/man3/bzero.3 +++ b/man3/bzero.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH bzero 3 2023-07-20 "Linux man-pages 6.05.01" +.TH bzero 3 2023-10-31 "Linux man-pages 6.7" .SH NAME bzero, explicit_bzero \- zero a byte string .SH LIBRARY @@ -12,11 +12,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void bzero(void " s [. n "], size_t " n ); -.PP +.P .B #include -.PP +.P .BI "void explicit_bzero(void " s [. n "], size_t " n ); .fi .SH DESCRIPTION @@ -27,7 +27,7 @@ function erases the data in the bytes of the memory starting at the location pointed to by .IR s , by writing zeros (bytes containing \[aq]\e0\[aq]) to that area. -.PP +.P The .BR explicit_bzero () function performs the same task as @@ -53,7 +53,6 @@ T{ .BR explicit_bzero () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -94,7 +93,7 @@ by an incorrect or compromised program. Calls to .BR explicit_bzero () are never optimized away by the compiler. -.PP +.P The .BR explicit_bzero () function does not solve all problems associated with erasing sensitive data: @@ -133,7 +132,7 @@ by a bug than data in a register, and thus the call creates a brief time window where the sensitive data is more vulnerable than it would otherwise have been if no attempt had been made to erase the data. -.PP +.P Note that declaring the sensitive variable with the .B volatile qualifier does @@ -143,7 +142,7 @@ Indeed, it will make them worse, since, for example, it may force a variable that would otherwise have been optimized into a register to instead be maintained in (more vulnerable) RAM for its entire lifetime. -.PP +.P Notwithstanding the above details, for security-conscious applications, using .BR explicit_bzero () is generally preferable to not using it. diff --git a/man3/cabs.3 b/man3/cabs.3 index f0c7569..d331ce7 100644 --- a/man3/cabs.3 +++ b/man3/cabs.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cabs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cabs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cabs, cabsf, cabsl \- absolute value of a complex number .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double cabs(double complex " z ); .BI "float cabsf(float complex " z ); .BI "long double cabsl(long double complex " z ); @@ -37,7 +37,6 @@ T{ .BR cabsl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/cacos.3 b/man3/cacos.3 index aebff0f..3c66ff8 100644 --- a/man3/cacos.3 +++ b/man3/cacos.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cacos 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cacos 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cacos, cacosf, cacosl \- complex arc cosine .SH LIBRARY @@ -13,7 +13,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex cacos(double complex " z ); .BI "float complex cacosf(float complex " z ); .BI "long double complex cacosl(long double complex " z ); @@ -25,9 +25,9 @@ If \fIy\ =\ cacos(z)\fP, then \fIz\ =\ ccos(y)\fP. The real part of .I y is chosen in the interval [0,pi]. -.PP +.P One has: -.PP +.P .nf cacos(z) = \-i * clog(z + i * csqrt(1 \- z * z)) .fi @@ -47,7 +47,6 @@ T{ .BR cacosl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/cacosh.3 b/man3/cacosh.3 index 55d1d47..941b375 100644 --- a/man3/cacosh.3 +++ b/man3/cacosh.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cacosh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cacosh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cacosh, cacoshf, cacoshl \- complex arc hyperbolic cosine .SH LIBRARY @@ -13,7 +13,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex cacosh(double complex " z ); .BI "float complex cacoshf(float complex " z ); .BI "long double complex cacoshl(long double complex " z ); @@ -28,9 +28,9 @@ is chosen in the interval [\-pi,pi]. The real part of .I y is chosen nonnegative. -.PP +.P One has: -.PP +.P .nf cacosh(z) = 2 * clog(csqrt((z + 1) / 2) + csqrt((z \- 1) / 2)) .fi @@ -50,7 +50,6 @@ T{ .BR cacoshl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/canonicalize_file_name.3 b/man3/canonicalize_file_name.3 index 5d9e466..6304835 100644 --- a/man3/canonicalize_file_name.3 +++ b/man3/canonicalize_file_name.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH canonicalize_file_name 3 2023-07-20 "Linux man-pages 6.05.01" +.TH canonicalize_file_name 3 2023-10-31 "Linux man-pages 6.7" .SH NAME canonicalize_file_name \- return the canonicalized absolute pathname .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "char *canonicalize_file_name(const char *" path ");" .fi .SH DESCRIPTION @@ -31,17 +31,17 @@ pathname components. Consecutive slash .RI ( / ) characters are replaced by a single slash. -.PP +.P The returned string is dynamically allocated by .BR canonicalize_file_name () and the caller should deallocate it with .BR free (3) when it is no longer required. -.PP +.P The call .I canonicalize_file_name(path) is equivalent to the call: -.PP +.P .in +4n .EX realpath(path, NULL); @@ -73,7 +73,6 @@ T{ .BR canonicalize_file_name () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH SEE ALSO diff --git a/man3/carg.3 b/man3/carg.3 index a7e3daa..bf5003f 100644 --- a/man3/carg.3 +++ b/man3/carg.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH carg 3 2023-07-20 "Linux man-pages 6.05.01" +.TH carg 3 2023-10-31 "Linux man-pages 6.7" .SH NAME carg, cargf, cargl \- calculate the complex argument .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double carg(double complex " z ");" .BI "float cargf(float complex " z ");" .BI "long double cargl(long double complex " z ");" @@ -21,29 +21,29 @@ Math library These functions calculate the complex argument (also called phase angle) of .IR z , with a branch cut along the negative real axis. -.PP +.P A complex number can be described by two real coordinates. One may use rectangular coordinates and gets -.PP +.P .in +4n .EX z = x + I * y .EE .in -.PP +.P where .I x\~=\~creal(z) and .IR y\~=\~cimag(z) . -.PP +.P Or one may use polar coordinates and gets -.PP +.P .in +4n .EX z = r * cexp(I * a) .EE .in -.PP +.P where .I r\~=\~cabs(z) is the "radius", the "modulus", the absolute value of @@ -52,9 +52,9 @@ and .I a\~=\~carg(z) is the "phase angle", the argument of .IR z . -.PP +.P One has: -.PP +.P .in +4n .EX tan(carg(z)) = cimag(z) / creal(z) @@ -78,7 +78,6 @@ T{ .BR cargl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/casin.3 b/man3/casin.3 index 5cce6a4..edc0935 100644 --- a/man3/casin.3 +++ b/man3/casin.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH casin 3 2023-07-20 "Linux man-pages 6.05.01" +.TH casin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME casin, casinf, casinl \- complex arc sine .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex casin(double complex " z ); .BI "float complex casinf(float complex " z ); .BI "long double complex casinl(long double complex " z ); @@ -24,9 +24,9 @@ If \fIy\ =\ casin(z)\fP, then \fIz\ =\ csin(y)\fP. The real part of .I y is chosen in the interval [\-pi/2,pi/2]. -.PP +.P One has: -.PP +.P .nf casin(z) = \-i clog(iz + csqrt(1 \- z * z)) .fi @@ -46,7 +46,6 @@ T{ .BR casinl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/casinh.3 b/man3/casinh.3 index 64cc89e..39afc1e 100644 --- a/man3/casinh.3 +++ b/man3/casinh.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH casinh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH casinh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME casinh, casinhf, casinhl \- complex arc sine hyperbolic .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex casinh(double complex " z ); .BI "float complex casinhf(float complex " z ); .BI "long double complex casinhl(long double complex " z ); @@ -24,9 +24,9 @@ If \fIy\~=\~casinh(z)\fP, then \fIz\~=\~csinh(y)\fP. The imaginary part of .I y is chosen in the interval [\-pi/2,pi/2]. -.PP +.P One has: -.PP +.P .in +4n .EX casinh(z) = clog(z + csqrt(z * z + 1)) @@ -48,7 +48,6 @@ T{ .BR casinhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/catan.3 b/man3/catan.3 index ea79b40..4bba036 100644 --- a/man3/catan.3 +++ b/man3/catan.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH catan 3 2023-07-20 "Linux man-pages 6.05.01" +.TH catan 3 2023-11-01 "Linux man-pages 6.7" .SH NAME catan, catanf, catanl \- complex arc tangents .SH LIBRARY @@ -13,7 +13,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex catan(double complex " z ); .BI "float complex catanf(float complex " z ); .BI "long double complex catanl(long double complex " z ); @@ -22,10 +22,12 @@ Math library These functions calculate the complex arc tangent of .IR z . If \fIy\~=\~catan(z)\fP, then \fIz\~=\~ctan(y)\fP. -The real part of y is chosen in the interval [\-pi/2,pi/2]. -.PP +The real part of +.I y +is chosen in the interval [\-pi/2, pi/2]. +.P One has: -.PP +.P .in +4n .EX catan(z) = (clog(1 + i * z) \- clog(1 \- i * z)) / (2 * i) @@ -47,7 +49,6 @@ T{ .BR catanl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/catanh.3 b/man3/catanh.3 index 0cd8c2b..48abbaa 100644 --- a/man3/catanh.3 +++ b/man3/catanh.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH catanh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH catanh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME catanh, catanhf, catanhl \- complex arc tangents hyperbolic .SH LIBRARY @@ -13,7 +13,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex catanh(double complex " z ); .BI "float complex catanhf(float complex " z ); .BI "long double complex catanhl(long double complex " z ); @@ -25,9 +25,9 @@ If \fIy\~=\~catanh(z)\fP, then \fIz\~=\~ctanh(y)\fP. The imaginary part of .I y is chosen in the interval [\-pi/2,pi/2]. -.PP +.P One has: -.PP +.P .in +4n .EX catanh(z) = 0.5 * (clog(1 + z) \- clog(1 \- z)) @@ -49,7 +49,6 @@ T{ .BR catanhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/catgets.3 b/man3/catgets.3 index 2083bb3..2132dcc 100644 --- a/man3/catgets.3 +++ b/man3/catgets.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Updated, aeb, 980809 -.TH catgets 3 2023-07-20 "Linux man-pages 6.05.01" +.TH catgets 3 2023-10-31 "Linux man-pages 6.7" .SH NAME catgets \- get message from a message catalog .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *catgets(nl_catd " catalog ", int " set_number \ ", int " message_number , .BI " const char *" message ); @@ -63,16 +63,15 @@ T{ .BR catgets () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P The .BR catgets () function is available only in libc.so.4.4.4c and above. -.PP +.P The Jan 1987 X/Open Portability Guide specifies a more subtle error return: .I message diff --git a/man3/catopen.3 b/man3/catopen.3 index b65b1f3..03edefe 100644 --- a/man3/catopen.3 +++ b/man3/catopen.3 @@ -6,7 +6,7 @@ .\" Modified Thu Dec 13 22:51:19 2001 by Martin Schulze .\" Modified 2001-12-14 aeb .\" -.TH catopen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH catopen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME catopen, catclose \- open/close a message catalog .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "nl_catd catopen(const char *" name ", int " flag ); .BI "int catclose(nl_catd " catalog ); .fi @@ -31,7 +31,7 @@ If a file descriptor is used to implement catalog descriptors, then the .B FD_CLOEXEC flag will be set. -.PP +.P The argument .I name specifies the name of the message catalog to be opened. @@ -73,7 +73,7 @@ Changing the .B LC_MESSAGES part of the locale may invalidate open catalog descriptors. -.PP +.P The .I flag argument to @@ -86,7 +86,7 @@ then it will use the current locale setting for Otherwise, it will use the .B LANG environment variable. -.PP +.P The function .BR catclose () closes the message catalog identified by @@ -109,7 +109,7 @@ The possible error values include all possible values for the .BR open (2) call. -.PP +.P The function .BR catclose () returns 0 on success, or \-1 on failure. @@ -147,7 +147,6 @@ T{ .BR catclose () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The above is the POSIX.1 description. The glibc value for diff --git a/man3/cbrt.3 b/man3/cbrt.3 index 106e951..373cd8f 100644 --- a/man3/cbrt.3 +++ b/man3/cbrt.3 @@ -8,7 +8,7 @@ .\" Modified 2002-07-27 Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH cbrt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cbrt 3 2024-03-12 "Linux man-pages 6.7" .SH NAME cbrt, cbrtf, cbrtl \- cube root function .SH LIBRARY @@ -17,17 +17,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double cbrt(double " x ); .BI "float cbrtf(float " x ); .BI "long double cbrtl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR cbrt (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR cbrtf (), .BR cbrtl (): .nf @@ -47,12 +47,15 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION These functions return the (real) cube root of .IR x . -This function cannot fail; every representable real value has a -representable real cube root. +This function cannot fail; +every representable real value +has a real cube root, +and rounding it to a representable value +never causes overflow nor underflow. .SH RETURN VALUE These functions return the cube root of .IR x . -.PP +.P If .I x is +0, \-0, positive infinity, negative infinity, or NaN, @@ -76,7 +79,6 @@ T{ .BR cbrtl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/ccos.3 b/man3/ccos.3 index 2e6ceab..2d992e7 100644 --- a/man3/ccos.3 +++ b/man3/ccos.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ccos 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ccos 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ccos, ccosf, ccosl \- complex cosine function .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex ccos(double complex " z ); .BI "float complex ccosf(float complex " z ); .BI "long double complex ccosl(long double complex " z ); @@ -20,9 +20,9 @@ Math library .SH DESCRIPTION These functions calculate the complex cosine of .IR z . -.PP +.P The complex cosine function is defined as: -.PP +.P .in +4n .EX ccos(z) = (exp(i * z) + exp(\-i * z)) / 2 @@ -44,7 +44,6 @@ T{ .BR ccosl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/ccosh.3 b/man3/ccosh.3 index ee0c384..b61c5f3 100644 --- a/man3/ccosh.3 +++ b/man3/ccosh.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ccosh 3 2023-03-30 "Linux man-pages 6.05.01" +.TH ccosh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ccosh, ccoshf, ccoshl \- complex hyperbolic cosine .SH LIBRARY @@ -11,7 +11,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex ccosh(double complex " z ); .BI "float complex ccoshf(float complex " z ); .BI "long double complex ccoshl(long double complex " z ); @@ -19,9 +19,9 @@ Math library .SH DESCRIPTION These functions calculate the complex hyperbolic cosine of .IR z . -.PP +.P The complex hyperbolic cosine function is defined as: -.PP +.P .in +4n .EX ccosh(z) = (exp(z)+exp(\-z))/2 diff --git a/man3/ceil.3 b/man3/ceil.3 index d72711f..60a86c0 100644 --- a/man3/ceil.3 +++ b/man3/ceil.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH ceil 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ceil 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ceil, ceilf, ceill \- ceiling function: smallest integral value not less than argument @@ -15,17 +15,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double ceil(double " x ); .BI "float ceilf(float " x ); .BI "long double ceill(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ceilf (), .BR ceill (): .nf @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION These functions return the smallest integral value that is not less than .IR x . -.PP +.P For example, .I ceil(0.5) is 1.0, and @@ -45,7 +45,7 @@ is 0.0. .SH RETURN VALUE These functions return the ceiling of .IR x . -.PP +.P If .I x is integral, +0, \-0, NaN, or infinite, @@ -70,12 +70,11 @@ T{ .BR ceill () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to @@ -98,7 +97,7 @@ the maximum value of the exponent is 127 (respectively, 1023), and the number of mantissa bits including the implicit bit is 24 (respectively, 53).) -.PP +.P The integral value returned by these functions may be too large to store in an integer type .RI ( int , diff --git a/man3/cexp.3 b/man3/cexp.3 index 30ba13f..5954913 100644 --- a/man3/cexp.3 +++ b/man3/cexp.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cexp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cexp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cexp, cexpf, cexpl \- complex exponential function .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex cexp(double complex " z ); .BI "float complex cexpf(float complex " z ); .BI "long double complex cexpl(long double complex " z ); @@ -21,9 +21,9 @@ Math library These functions calculate e (2.71828..., the base of natural logarithms) raised to the power of .IR z . -.PP +.P One has: -.PP +.P .in +4n .EX cexp(I * z) = ccos(z) + I * csin(z) @@ -45,7 +45,6 @@ T{ .BR cexpl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/cexp2.3 b/man3/cexp2.3 index e19f1f6..b8d2504 100644 --- a/man3/cexp2.3 +++ b/man3/cexp2.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cexp2 3 2022-12-04 "Linux man-pages 6.05.01" +.TH cexp2 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cexp2, cexp2f, cexp2l \- base-2 exponent of a complex number .SH LIBRARY @@ -11,7 +11,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex cexp2(double complex " z ); .BI "float complex cexp2f(float complex " z ); .BI "long double complex cexp2l(long double complex " z ); @@ -21,7 +21,7 @@ The function returns 2 raised to the power of .IR z . .SH STANDARDS These function names are reserved for future use in C99. -.PP +.P As at glibc 2.31, these functions are not provided in glibc. .\" But reserved in NAMESPACE. .SH SEE ALSO diff --git a/man3/cfree.3 b/man3/cfree.3 index ef97717..97d30b6 100644 --- a/man3/cfree.3 +++ b/man3/cfree.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cfree 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cfree 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cfree \- free allocated memory .SH LIBRARY @@ -11,29 +11,29 @@ Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf -.PP +.P .B "#include " -.PP +.P /* In SunOS 4 */ .BI "int cfree(void *" ptr ); -.PP +.P /* In glibc or FreeBSD libcompat */ .BI "void cfree(void *" ptr ); -.PP +.P /* In SCO OpenServer */ .BI "void cfree(char " ptr [. size " * ." num "], unsigned int " num ", \ unsigned int " size ); -.PP +.P /* In Solaris watchmalloc.so.1 */ .BI "void cfree(void " ptr [. elsize " * ." nelem "], size_t " nelem ", \ size_t " elsize ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR cfree (): .nf Since glibc 2.19: @@ -53,7 +53,7 @@ In glibc, the function is a synonym for .BR free (3), "added for compatibility with SunOS". -.PP +.P Other systems have other functions with this name. The declaration is sometimes in .I @@ -64,17 +64,17 @@ Some SCO and Solaris versions have malloc libraries with a 3-argument .BR cfree (), apparently as an analog to .BR calloc (3). -.PP +.P If you need it while porting something, add -.PP +.P .in +4n .EX #define cfree(p, n, s) free((p)) .EE .in -.PP +.P to your file. -.PP +.P A frequently asked question is "Can I use .BR free (3) to free memory allocated with @@ -83,7 +83,7 @@ or do I need .BR cfree ()?" Answer: use .BR free (3). -.PP +.P An SCO manual writes: "The cfree routine is provided for compliance to the iBCSe2 standard and simply calls free. The num and size @@ -118,7 +118,6 @@ T{ .BR cfree () T} Thread safety MT-Safe /* In glibc */ .TE -.sp 1 .SH VERSIONS The 3-argument version of .BR cfree () diff --git a/man3/cimag.3 b/man3/cimag.3 index 4a9293e..d369cf8 100644 --- a/man3/cimag.3 +++ b/man3/cimag.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cimag 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cimag 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cimag, cimagf, cimagl \- get imaginary part of a complex number .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double cimag(double complex " z ); .BI "float cimagf(float complex " z ); .BI "long double cimagl(long double complex " z ); @@ -20,9 +20,9 @@ Math library .SH DESCRIPTION These functions return the imaginary part of the complex number .IR z . -.PP +.P One has: -.PP +.P .in +4n .EX z = creal(z) + I * cimag(z) @@ -44,7 +44,6 @@ T{ .BR cimagl () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS GCC also supports __imag__. That is a GNU extension. diff --git a/man3/circleq.3 b/man3/circleq.3 index c03ab16..47b8213 100644 --- a/man3/circleq.3 +++ b/man3/circleq.3 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH CIRCLEQ 3 2023-05-03 "Linux man-pages 6.05.01" +.TH CIRCLEQ 3 2023-10-31 "Linux man-pages 6.7" .SH NAME CIRCLEQ_EMPTY, CIRCLEQ_ENTRY, @@ -32,15 +32,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B CIRCLEQ_ENTRY(TYPE); -.PP +.P .B CIRCLEQ_HEAD(HEADNAME, TYPE); .BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ); .BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ); -.PP +.P .BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ); -.PP +.P .BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head , .BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); .BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head , @@ -49,7 +49,7 @@ Standard C library .BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); .BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm , .BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); -.PP +.P .BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ); .BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ); .BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); @@ -58,18 +58,18 @@ Standard C library .BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); .BI "struct TYPE *CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head , .BI " struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ); -.PP +.P .BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head , .BI " CIRCLEQ_ENTRY " NAME ); .BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head , .BI " CIRCLEQ_ENTRY " NAME ); -.PP +.P .BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm , .BI " CIRCLEQ_ENTRY " NAME ); .fi .SH DESCRIPTION These macros define and operate on doubly linked circular queues. -.PP +.P In the macro definitions, .I TYPE is the name of a user-defined structure, @@ -99,43 +99,43 @@ or at the end of the queue. A .I CIRCLEQ_HEAD structure is declared as follows: -.PP +.P .in +4 .EX CIRCLEQ_HEAD(HEADNAME, TYPE) head; .EE .in -.PP +.P where .I struct HEADNAME is the structure to be defined, and .I struct TYPE is the type of the elements to be linked into the queue. A pointer to the head of the queue can later be declared as: -.PP +.P .in +4 .EX struct HEADNAME *headp; .EE .in -.PP +.P (The names .I head and .I headp are user selectable.) -.PP +.P .BR CIRCLEQ_ENTRY () declares a structure that connects the elements in the queue. -.PP +.P .BR CIRCLEQ_HEAD_INITIALIZER () evaluates to an initializer for the queue .IR head . -.PP +.P .BR CIRCLEQ_INIT () initializes the queue referenced by .IR head . -.PP +.P .BR CIRCLEQ_EMPTY () evaluates to true if there are no items on the queue. .SS Insertion @@ -143,18 +143,18 @@ evaluates to true if there are no items on the queue. inserts the new element .I elm at the head of the queue. -.PP +.P .BR CIRCLEQ_INSERT_TAIL () inserts the new element .I elm at the end of the queue. -.PP +.P .BR CIRCLEQ_INSERT_BEFORE () inserts the new element .I elm before the element .IR listelm . -.PP +.P .BR CIRCLEQ_INSERT_AFTER () inserts the new element .I elm @@ -163,32 +163,32 @@ after the element .SS Traversal .BR CIRCLEQ_FIRST () returns the first item on the queue. -.PP +.P .BR CIRCLEQ_LAST () returns the last item on the queue. -.PP +.P .BR CIRCLEQ_PREV () returns the previous item on the queue, or .I &head if this item is the first one. -.PP +.P .BR CIRCLEQ_NEXT () returns the next item on the queue, or .I &head if this item is the last one. -.PP +.P .BR CIRCLEQ_LOOP_PREV () returns the previous item on the queue. If .I elm is the first element on the queue, the last element is returned. -.PP +.P .BR CIRCLEQ_LOOP_NEXT () returns the next item on the queue. If .I elm is the last element on the queue, the first element is returned. -.PP +.P .BR CIRCLEQ_FOREACH () traverses the queue referenced by .I head @@ -198,7 +198,7 @@ in the forward direction, assigning each element in turn to is set to .I &head if the loop completes normally, or if there were no elements. -.PP +.P .BR CIRCLEQ_FOREACH_REVERSE () traverses the queue referenced by .I head @@ -214,7 +214,7 @@ from the queue. .BR CIRCLEQ_EMPTY () returns nonzero if the queue is empty, and zero if the queue contains at least one entry. -.PP +.P .BR CIRCLEQ_FIRST (), .BR CIRCLEQ_LAST (), .BR CIRCLEQ_LOOP_PREV (), @@ -223,7 +223,7 @@ and return a pointer to the first, last, previous, or next .I TYPE structure, respectively. -.PP +.P .BR CIRCLEQ_PREV (), and .BR CIRCLEQ_NEXT () @@ -233,7 +233,7 @@ counterparts, except that if the argument is the first or last element, respectively, they return .IR &head . -.PP +.P .BR CIRCLEQ_HEAD_INITIALIZER () returns an initializer that can be assigned to the queue .IR head . diff --git a/man3/clearenv.3 b/man3/clearenv.3 index 1c91402..3ffd761 100644 --- a/man3/clearenv.3 +++ b/man3/clearenv.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Additions, aeb, 2001-10-17. -.TH clearenv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH clearenv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clearenv \- clear the environment .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "int clearenv(void);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR clearenv (): .nf /* glibc >= 2.19: */ _DEFAULT_SOURCE @@ -59,7 +59,6 @@ T{ .BR clearenv () T} Thread safety MT-Unsafe const:env .TE -.sp 1 .SH STANDARDS .TP .BR putenv () @@ -75,7 +74,7 @@ POSIX.1-2001. .TP .BR clearenv () glibc 2.0. -.PP +.P Various UNIX variants (DG/UX, HP-UX, QNX, ...). POSIX.9 (bindings for FORTRAN77). POSIX.1-1996 did not accept @@ -93,15 +92,15 @@ and rejected On systems where .BR clearenv () is unavailable, the assignment -.PP +.P .in +4n .EX environ = NULL; .EE .in -.PP +.P will probably do. -.PP +.P The .BR clearenv () function may be useful in security-conscious applications that want to @@ -110,14 +109,14 @@ executed using .BR exec (3). The application would do this by first clearing the environment and then adding select environment variables. -.PP +.P Note that the main effect of .BR clearenv () is to adjust the value of the pointer .BR environ (7); this function does not erase the contents of the buffers containing the environment definitions. -.PP +.P The DG/UX and Tru64 man pages write: If .I environ has been modified by anything other than the @@ -128,7 +127,7 @@ or functions, then .BR clearenv () will return an error and the process environment will remain unchanged. -.\" .LP +.\" .P .\" HP-UX has a ENOMEM error return. .SH SEE ALSO .BR getenv (3), diff --git a/man3/clock.3 b/man3/clock.3 index 588209b..53231aa 100644 --- a/man3/clock.3 +++ b/man3/clock.3 @@ -7,7 +7,7 @@ .\" Modified 14 Jun 2002, Michael Kerrisk .\" Added notes on differences from other UNIX systems with respect to .\" waited-for children. -.TH clock 3 2023-07-20 "Linux man-pages 6.05.01" +.TH clock 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clock \- determine processor time .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B clock_t clock(void); .fi .SH DESCRIPTION @@ -45,13 +45,12 @@ T{ .BR clock () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS XSI requires that .B CLOCKS_PER_SEC equals 1000000 independent of the actual resolution. -.PP +.P On several other implementations, the value returned by .BR clock () @@ -74,7 +73,7 @@ caller and its children, may be preferable. C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C89. -.PP +.P In glibc 2.17 and earlier, .BR clock () was implemented on top of @@ -90,7 +89,7 @@ The C standard allows for arbitrary values at the start of the program; subtract the value returned from a call to .BR clock () at the start of the program to get maximum portability. -.PP +.P Note that the time can wrap around. On a 32-bit system where .B CLOCKS_PER_SEC diff --git a/man3/clock_getcpuclockid.3 b/man3/clock_getcpuclockid.3 index 749fdbe..541c46a 100644 --- a/man3/clock_getcpuclockid.3 +++ b/man3/clock_getcpuclockid.3 @@ -4,30 +4,30 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH clock_getcpuclockid 3 2023-07-20 "Linux man-pages 6.05.01" +.TH clock_getcpuclockid 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clock_getcpuclockid \- obtain ID of a process CPU-time clock .SH LIBRARY Standard C library .RI ( libc ", " \-lc ), since glibc 2.17 -.PP +.P Before glibc 2.17, Real-time library .RI ( librt ", " \-lrt ) .SH SYNOPSIS .B #include .nf -.PP +.P .BI "int clock_getcpuclockid(pid_t " pid ", clockid_t *" clockid ); .fi -.PP +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR clock_getcpuclockid (): .nf _POSIX_C_SOURCE >= 200112L @@ -81,7 +81,6 @@ T{ .BR clock_getcpuclockid () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -104,7 +103,7 @@ and then uses .BR clock_gettime (2) to obtain the time on that clock. An example run is the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out 1" " # Show CPU clock of init process" diff --git a/man3/clog.3 b/man3/clog.3 index 5a75d36..9ada276 100644 --- a/man3/clog.3 +++ b/man3/clog.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH clog 3 2023-07-20 "Linux man-pages 6.05.01" +.TH clog 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clog, clogf, clogl \- natural logarithm of a complex number .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex clog(double complex " z ); .BI "float complex clogf(float complex " z ); .BI "long double complex clogl(long double complex " z ); @@ -21,7 +21,7 @@ Math library These functions calculate the complex natural logarithm of .IR z , with a branch cut along the negative real axis. -.PP +.P The logarithm .BR clog () is the inverse function of the exponential @@ -30,15 +30,15 @@ Thus, if \fIy\ =\ clog(z)\fP, then \fIz\ =\ cexp(y)\fP. The imaginary part of .I y is chosen in the interval [\-pi,pi]. -.PP +.P One has: -.PP +.P .in +4n .EX clog(z) = log(cabs(z)) + I * carg(z) .EE .in -.PP +.P Note that .I z close to zero will cause an overflow. @@ -58,7 +58,6 @@ T{ .BR clogl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/clog10.3 b/man3/clog10.3 index 716d6e7..6ad20a4 100644 --- a/man3/clog10.3 +++ b/man3/clog10.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH clog10 3 2023-07-20 "Linux man-pages 6.05.01" +.TH clog10 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clog10, clog10f, clog10l \- base-10 logarithm of a complex number .SH LIBRARY @@ -13,7 +13,7 @@ Math library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "double complex clog10(double complex " z ); .BI "float complex clog10f(float complex " z ); .BI "long double complex clog10l(long double complex " z ); @@ -22,26 +22,26 @@ Math library The call .I clog10(z) is equivalent to: -.PP +.P .in +4n .EX clog(z)/log(10) .EE .in -.PP +.P or equally: -.PP +.P .in +4n .EX log10(cabs(c)) + I * carg(c) / log(10) .EE .in -.PP +.P The other functions perform the same task for .I float and .IR "long double" . -.PP +.P Note that .I z close to zero will cause an overflow. @@ -61,12 +61,11 @@ T{ .BR clog10l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY glibc 2.1. -.PP +.P The identifiers are reserved for future use in C99 and C11. .SH SEE ALSO .BR cabs (3), diff --git a/man3/clog2.3 b/man3/clog2.3 index 06a04a9..d1f3b4a 100644 --- a/man3/clog2.3 +++ b/man3/clog2.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH clog2 3 2023-03-30 "Linux man-pages 6.05.01" +.TH clog2 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clog2, clog2f, clog2l \- base-2 logarithm of a complex number .SH LIBRARY @@ -11,7 +11,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex clog2(double complex " z ); .BI "float complex clog2f(float complex " z ); .BI "long double complex clog2l(long double complex " z ); @@ -21,12 +21,12 @@ The call .I clog2(z) is equivalent to .IR clog(z)/log(2) . -.PP +.P The other functions perform the same task for .I float and .IR "long double" . -.PP +.P Note that .I z close to zero will cause an overflow. @@ -34,7 +34,7 @@ close to zero will cause an overflow. None. .SH HISTORY These function names are reserved for future use in C99. -.PP +.P Not yet in glibc, as at glibc 2.19. .\" But reserved in NAMESPACE. .SH SEE ALSO diff --git a/man3/closedir.3 b/man3/closedir.3 index e10ae9e..5fc9737 100644 --- a/man3/closedir.3 +++ b/man3/closedir.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sat Jul 24 21:25:52 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) -.TH closedir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH closedir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME closedir \- close a directory .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int closedir(DIR *" dirp ); .fi .SH DESCRIPTION @@ -61,7 +61,6 @@ T{ .BR closedir () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/cmsg.3 b/man3/cmsg.3 index 3ca7d1d..2d0a70e 100644 --- a/man3/cmsg.3 +++ b/man3/cmsg.3 @@ -3,7 +3,7 @@ .\" This man page is Copyright (C) 1999 Andi Kleen . .\" .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ -.TH CMSG 3 2023-07-15 "Linux man-pages 6.05.01" +.TH CMSG 3 2023-10-31 "Linux man-pages 6.7" .SH NAME CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- access ancillary data .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ); .BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh , .BR " struct cmsghdr *" cmsg ); @@ -35,7 +35,7 @@ Ancillary data is sent by calling and received by calling .BR recvmsg (2). See their manual pages for more information. -.PP +.P Ancillary data is a sequence of .I cmsghdr structures with appended data. @@ -44,11 +44,11 @@ The maximum ancillary buffer size allowed per socket can be set using .IR /proc/sys/net/core/optmem_max ; see .BR socket (7). -.PP +.P The .I cmsghdr structure is defined as follows: -.PP +.P .in +4n .EX struct cmsghdr { @@ -61,7 +61,7 @@ struct cmsghdr { }; .EE .in -.PP +.P The sequence of .I cmsghdr structures should never be accessed directly. @@ -122,7 +122,7 @@ alignment. It takes the data length as an argument. This is a constant expression. -.PP +.P To create ancillary data, first initialize the .I msg_controllen member of the @@ -158,7 +158,7 @@ see .SH VERSIONS For portability, ancillary data should be accessed using only the macros described here. -.PP +.P In Linux, .BR CMSG_LEN (), .BR CMSG_DATA (), @@ -185,7 +185,7 @@ Linux. .SH HISTORY This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, the IPv6 advanced API described in RFC\ 2292 and SUSv2. -.PP +.P .BR CMSG_SPACE () and .BR CMSG_LEN () @@ -195,7 +195,7 @@ will be included in the next POSIX release (Issue 8). This code looks for the .B IP_TTL option in a received ancillary buffer: -.PP +.P .in +4n .EX struct msghdr msgh; @@ -218,11 +218,11 @@ if (cmsg == NULL) { } .EE .in -.PP +.P The code below passes an array of file descriptors over a UNIX domain socket using .BR SCM_RIGHTS : -.PP +.P .in +4n .EX struct msghdr msg = { 0 }; @@ -250,12 +250,12 @@ cmsg\->cmsg_len = CMSG_LEN(sizeof(myfds)); memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds)); .EE .in -.PP +.P For a complete code example that shows passing of file descriptors over a UNIX domain socket, see .BR seccomp_unotify (2). .SH SEE ALSO .BR recvmsg (2), .BR sendmsg (2) -.PP +.P RFC\ 2292 diff --git a/man3/confstr.3 b/man3/confstr.3 index 5efd862..4a04a25 100644 --- a/man3/confstr.3 +++ b/man3/confstr.3 @@ -11,7 +11,7 @@ .\" These should all be added to this page. .\" See also the POSIX.1-2001 specification of confstr() .\" -.TH confstr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH confstr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME confstr \- get configuration dependent string variables .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t confstr(int " "name" ", char " buf [. size "], size_t " size ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR confstr (): .nf _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION .BR confstr () gets the value of configuration-dependent string variables. -.PP +.P The .I name argument is the system variable to be queried. @@ -55,7 +55,7 @@ A value for the .B PATH variable which indicates where all the POSIX.2 standard utilities can be found. -.PP +.P If .I buf is not NULL and @@ -71,7 +71,7 @@ This can be detected by comparing the return value of .BR confstr () against .IR size . -.PP +.P If .I size is zero and @@ -91,7 +91,7 @@ This value may be greater than which means that the value in .I buf is truncated. -.PP +.P If .I name is a valid configuration variable, @@ -126,7 +126,6 @@ T{ .BR confstr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -134,7 +133,7 @@ POSIX.1-2001. .SH EXAMPLES The following code fragment determines the path where to find the POSIX.2 system utilities: -.PP +.P .in +4n .EX char *pathbuf; diff --git a/man3/conj.3 b/man3/conj.3 index 760f079..4f0bef3 100644 --- a/man3/conj.3 +++ b/man3/conj.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH conj 3 2023-07-20 "Linux man-pages 6.05.01" +.TH conj 3 2023-10-31 "Linux man-pages 6.7" .SH NAME conj, conjf, conjl \- calculate the complex conjugate .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex conj(double complex " z ); .BI "float complex conjf(float complex " z ); .BI "long double complex conjl(long double complex " z ); @@ -21,9 +21,9 @@ Math library These functions return the complex conjugate value of .IR z . That is the value obtained by changing the sign of the imaginary part. -.PP +.P One has: -.PP +.P .in +4n .EX cabs(z) = csqrt(z * conj(z)) @@ -45,7 +45,6 @@ T{ .BR conjl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/copysign.3 b/man3/copysign.3 index 9bd7932..8f7e7ab 100644 --- a/man3/copysign.3 +++ b/man3/copysign.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2002-08-10 by Walter Harms (walter.harms@informatik.uni-oldenburg.de) -.TH copysign 3 2023-07-20 "Linux man-pages 6.05.01" +.TH copysign 3 2023-10-31 "Linux man-pages 6.7" .SH NAME copysign, copysignf, copysignl \- copy sign of a number .SH LIBRARY @@ -18,17 +18,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double copysign(double " x ", double " y ); .BI "float copysignf(float " x ", float " y ); .BI "long double copysignl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR copysign (), .BR copysignf (), .BR copysignl (): @@ -42,7 +42,7 @@ These functions return a value whose absolute value matches that of .IR x , but whose sign bit matches that of .IR y . -.PP +.P For example, .I "copysign(42.0,\ \-1.0)" and @@ -53,7 +53,7 @@ On success, these functions return a value whose magnitude is taken from .I x and whose sign is taken from .IR y . -.PP +.P If .I x is a NaN, @@ -78,13 +78,12 @@ T{ .BR copysignl () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On architectures where the floating-point formats are not IEEE 754 compliant, these functions may treat a negative zero as positive. .SH STANDARDS C11, POSIX.1-2008. -.PP +.P This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854). .SH HISTORY diff --git a/man3/cos.3 b/man3/cos.3 index 44e3444..9b8e1f4 100644 --- a/man3/cos.3 +++ b/man3/cos.3 @@ -12,7 +12,7 @@ .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) -.TH cos 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cos 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cos, cosf, cosl \- cosine function .SH LIBRARY @@ -21,17 +21,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double cos(double " x ); .BI "float cosf(float " x ); .BI "long double cosl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR cosf (), .BR cosl (): .nf @@ -49,11 +49,11 @@ given in radians. .SH RETURN VALUE On success, these functions return the cosine of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity or negative infinity, @@ -64,7 +64,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity @@ -91,12 +91,11 @@ T{ .BR cosl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/cosh.3 b/man3/cosh.3 index 358cb1f..5177cce 100644 --- a/man3/cosh.3 +++ b/man3/cosh.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH cosh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cosh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cosh, coshf, coshl \- hyperbolic cosine function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double cosh(double " x ); .BI "float coshf(float " x ); .BI "long double coshl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR coshf (), .BR coshl (): .nf @@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see These functions return the hyperbolic cosine of .IR x , which is defined mathematically as: -.PP +.P .in +4n .EX cosh(x) = (exp(x) + exp(\-x)) / 2 @@ -54,20 +54,20 @@ cosh(x) = (exp(x) + exp(\-x)) / 2 .SH RETURN VALUE On success, these functions return the hyperbolic cosine of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 or \-0, 1 is returned. -.PP +.P If .I x is positive infinity or negative infinity, positive infinity is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -81,7 +81,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result overflow @@ -107,12 +107,11 @@ T{ .BR coshl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/cpow.3 b/man3/cpow.3 index 92dd971..788f5aa 100644 --- a/man3/cpow.3 +++ b/man3/cpow.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cpow 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cpow 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cpow, cpowf, cpowl \- complex power function .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex cpow(double complex " x ", double complex " z ); .BI "float complex cpowf(float complex " x ", float complex " z ); .BI "long double complex cpowl(long double complex " x , @@ -42,7 +42,6 @@ T{ .BR cpowl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/cproj.3 b/man3/cproj.3 index 159998a..2d32c1e 100644 --- a/man3/cproj.3 +++ b/man3/cproj.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH cproj 3 2023-07-20 "Linux man-pages 6.05.01" +.TH cproj 3 2023-10-31 "Linux man-pages 6.7" .SH NAME cproj, cprojf, cprojl \- project into Riemann Sphere .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex cproj(double complex " z ");" .BI "float complex cprojf(float complex " z ");" .BI "long double complex cprojl(long double complex " z ");" @@ -43,13 +43,12 @@ T{ .BR cprojl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY glibc 2.1. C99, POSIX.1-2001. -.PP +.P In glibc 2.11 and earlier, the implementation does something different (a .I stereographic diff --git a/man3/creal.3 b/man3/creal.3 index 718dc5b..ded56e6 100644 --- a/man3/creal.3 +++ b/man3/creal.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH creal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH creal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME creal, crealf, creall \- get real part of a complex number .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double creal(double complex " z ); .BI "float crealf(float complex " z ); .BI "long double creall(long double complex " z ); @@ -20,9 +20,9 @@ Math library .SH DESCRIPTION These functions return the real part of the complex number .IR z . -.PP +.P One has: -.PP +.P .nf z = creal(z) + I * cimag(z) .fi @@ -42,7 +42,6 @@ T{ .BR creall () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS GCC supports also __real__. That is a GNU extension. diff --git a/man3/crypt.3 b/man3/crypt.3 index c6873a5..d3531f0 100644 --- a/man3/crypt.3 +++ b/man3/crypt.3 @@ -15,7 +15,7 @@ .\" added _XOPEN_SOURCE, aeb, 970705 .\" added GNU MD5 stuff, aeb, 011223 .\" -.TH crypt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH crypt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME crypt, crypt_r \- password hashing .SH LIBRARY @@ -24,20 +24,20 @@ Password hashing library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *crypt(const char *" key ", const char *" salt ); -.PP +.P .B #include -.PP +.P .BI "char *crypt_r(const char *" key ", const char *" salt , .BI " struct crypt_data *restrict " data ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR crypt (): .nf Since glibc 2.28: @@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see glibc 2.27 and earlier: _XOPEN_SOURCE .fi -.PP +.P .BR crypt_r (): .nf _GNU_SOURCE @@ -56,16 +56,16 @@ is the password hashing function. It is based on the Data Encryption Standard algorithm with variations intended (among other things) to discourage use of hardware implementations of a key search. -.PP +.P .I key is a user's typed password. -.PP +.P .I salt is a two-character string chosen from the set [\fBa\-zA\-Z0\-9./\fP]. This string is used to perturb the algorithm in one of 4096 different ways. -.PP +.P By taking the lowest 7 bits of each of the first eight characters of the .IR key , a 56-bit key is obtained. @@ -76,7 +76,7 @@ value points to the hashed password, a series of 13 printable ASCII characters (the first two characters represent the salt itself). The return value points to static data whose content is overwritten by each call. -.PP +.P Warning: the key space consists of .if t 2\s-2\u56\s0\d .if n 2**56 @@ -93,7 +93,7 @@ The use of a .BR passwd (1) program that checks for crackable passwords during the selection process is recommended. -.PP +.P The DES algorithm itself has a few quirks which make the use of the .BR crypt () interface a very poor choice for anything other than password @@ -102,7 +102,7 @@ If you are planning on using the .BR crypt () interface for a cryptography project, don't do it: get a good book on encryption and one of the widely available DES libraries. -.PP +.P .BR crypt_r () is a reentrant version of .BR crypt (). @@ -128,22 +128,22 @@ The .BR crypt () function was not implemented, probably because of U.S.A. export restrictions. .\" This level of detail is not necessary in this man page. . . -.\" .PP +.\" .P .\" When encrypting a plain text P using DES with the key K results in the .\" encrypted text C, then the complementary plain text P' being encrypted .\" using the complementary key K' will result in the complementary encrypted .\" text C'. -.\" .PP +.\" .P .\" Weak keys are keys which stay invariant under the DES key transformation. .\" The four known weak keys 0101010101010101, fefefefefefefefe, .\" 1f1f1f1f0e0e0e0e and e0e0e0e0f1f1f1f1 must be avoided. -.\" .PP +.\" .P .\" There are six known half weak key pairs, which keys lead to the same .\" encrypted data. Keys which are part of such key clusters should be .\" avoided. .\" Sorry, I could not find out what they are. .\"" -.\" .PP +.\" .P .\" Heavily redundant data causes trouble with DES encryption, when used in the .\" .I codebook .\" mode that @@ -152,13 +152,13 @@ function was not implemented, probably because of U.S.A. export restrictions. .\" .BR crypt () .\" interface should be used only for its intended purpose of password .\" verification, and should not be used as part of a data encryption tool. -.\" .PP +.\" .P .\" The first and last three output bits of the fourth S-box can be .\" represented as function of their input bits. Empiric studies have .\" shown that S-boxes partially compute the same output for similar input. .\" It is suspected that this may contain a back door which could allow the .\" NSA to decrypt DES encrypted data. -.\" .PP +.\" .P .\" Making encrypted data computed using crypt() publicly available has .\" to be considered insecure for the given reasons. .TP @@ -185,7 +185,6 @@ T{ .BR crypt_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR crypt () @@ -226,17 +225,17 @@ is an ABI-compatible drop-in replacement. .SS Features in glibc The glibc version of this function supports additional hashing algorithms. -.PP +.P If .I salt is a character string starting with the characters "$\fIid\fP$" followed by a string optionally terminated by "$", then the result has the form: .RS -.PP +.P $\fIid\fP$\fIsalt\fP$\fIhashed\fP .RE -.PP +.P .I id identifies the hashing method used instead of DES and this then determines how the rest of the password string is interpreted. @@ -264,11 +263,11 @@ T} 6 SHA-512 (since glibc 2.7) .TE .RE -.PP +.P Thus, $5$\fIsalt\fP$\fIhashed\fP and $6$\fIsalt\fP$\fIhashed\fP contain the password hashed with, respectively, functions based on SHA-256 and SHA-512. -.PP +.P "\fIsalt\fP" stands for the up to 16 characters following "$\fIid\fP$" in the salt. The "\fIhashed\fP" @@ -282,14 +281,14 @@ SHA-256 43 characters SHA-512 86 characters .TE .RE -.PP +.P The characters in "\fIsalt\fP" and "\fIhashed\fP" are drawn from the set [\fBa\-zA\-Z0\-9./\fP]. In the MD5 and SHA implementations the entire .I key is significant (instead of only the first 8 bytes in DES). -.PP +.P Since glibc 2.7, .\" glibc commit 9425cb9eea6a62fc21d99aafe8a60f752b934b05 the SHA-256 and SHA-512 implementations support a user-supplied number of @@ -298,10 +297,10 @@ If the "$\fIid\fP$" characters in the salt are followed by "rounds=\fIxxx\fP$", where \fIxxx\fP is an integer, then the result has the form .RS -.PP +.P $\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIhashed\fP .RE -.PP +.P where \fIyyy\fP is the number of hashing rounds actually used. The number of rounds actually used is 1000 if .I xxx diff --git a/man3/csin.3 b/man3/csin.3 index bc10951..1bf04a1 100644 --- a/man3/csin.3 +++ b/man3/csin.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH csin 3 2023-07-20 "Linux man-pages 6.05.01" +.TH csin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME csin, csinf, csinl \- complex sine function .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex csin(double complex " z ); .BI "float complex csinf(float complex " z ); .BI "long double complex csinl(long double complex " z ); @@ -20,9 +20,9 @@ Math library .SH DESCRIPTION These functions calculate the complex sine of .IR z . -.PP +.P The complex sine function is defined as: -.PP +.P .in +4n .EX csin(z) = (exp(i * z) \- exp(\-i * z)) / (2 * i) @@ -44,7 +44,6 @@ T{ .BR csinl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/csinh.3 b/man3/csinh.3 index b7a7350..263e2d0 100644 --- a/man3/csinh.3 +++ b/man3/csinh.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH csinh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH csinh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME csinh, csinhf, csinhl \- complex hyperbolic sine .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex csinh(double complex " z ); .BI "float complex csinhf(float complex " z ); .BI "long double complex csinhl(long double complex " z ); @@ -20,9 +20,9 @@ Math library .SH DESCRIPTION These functions calculate the complex hyperbolic sine of .IR z . -.PP +.P The complex hyperbolic sine function is defined as: -.PP +.P .in +4n .EX csinh(z) = (exp(z)\-exp(\-z))/2 @@ -44,7 +44,6 @@ T{ .BR csinhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/csqrt.3 b/man3/csqrt.3 index 319bbd1..9fdf80b 100644 --- a/man3/csqrt.3 +++ b/man3/csqrt.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH csqrt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH csqrt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME csqrt, csqrtf, csqrtl \- complex square root .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex csqrt(double complex " z ); .BI "float complex csqrtf(float complex " z ); .BI "long double complex csqrtl(long double complex " z ); @@ -40,7 +40,6 @@ T{ .BR csqrtl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/ctan.3 b/man3/ctan.3 index e47f11d..3daf68b 100644 --- a/man3/ctan.3 +++ b/man3/ctan.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ctan 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ctan 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ctan, ctanf, ctanl \- complex tangent function .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex ctan(double complex " z ); .BI "float complex ctanf(float complex " z ); .BI "long double complex ctanl(long double complex " z ); @@ -20,9 +20,9 @@ Math library .SH DESCRIPTION These functions calculate the complex tangent of .IR z . -.PP +.P The complex tangent function is defined as: -.PP +.P .in +4n .EX ctan(z) = csin(z) / ccos(z) @@ -44,7 +44,6 @@ T{ .BR ctanl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/ctanh.3 b/man3/ctanh.3 index a9b7b34..f2178b9 100644 --- a/man3/ctanh.3 +++ b/man3/ctanh.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH ctanh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ctanh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ctanh, ctanhf, ctanhl \- complex hyperbolic tangent .SH LIBRARY @@ -12,7 +12,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double complex ctanh(double complex " z ); .BI "float complex ctanhf(float complex " z ); .BI "long double complex ctanhl(long double complex " z ); @@ -20,10 +20,10 @@ Math library .SH DESCRIPTION These functions calculate the complex hyperbolic tangent of .IR z . -.PP +.P The complex hyperbolic tangent function is defined mathematically as: -.PP +.P .in +4n .EX ctanh(z) = csinh(z) / ccosh(z) @@ -45,7 +45,6 @@ T{ .BR ctanhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/ctermid.3 b/man3/ctermid.3 index 0a2ab66..987637f 100644 --- a/man3/ctermid.3 +++ b/man3/ctermid.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Sat Jul 24 19:51:06 1993 by Rik Faith (faith@cs.unc.edu) -.TH ctermid 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ctermid 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ctermid \- get controlling terminal name .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .B #include .\" POSIX also requires this function to be declared in , .\" and glibc does so if suitable feature test macros are defined. -.PP +.P .BI "char *ctermid(char *" "s" ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ctermid (): .nf _POSIX_C_SOURCE @@ -57,7 +57,6 @@ T{ .BR ctermid () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -66,7 +65,7 @@ POSIX.1-2001, Svr4. The returned pathname may not uniquely identify the controlling terminal; it may, for example, be .IR /dev/tty . -.PP +.P It is not assured that the program can open the terminal. .\" in glibc 2.3.x, x >= 4, the glibc headers threw an error .\" if ctermid() was given an argument; fixed in glibc 2.4. diff --git a/man3/ctime.3 b/man3/ctime.3 index 4dc72f2..817e964 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -13,7 +13,7 @@ .\" Modified 2001-12-13, joey, aeb .\" Modified 2004-11-16, mtk .\" -.TH ctime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ctime 3 2023-10-31 "Linux man-pages 6.7" .SH NAME asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r, localtime_r \- transform date and time to broken-down time or ASCII @@ -23,31 +23,31 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *asctime(const struct tm *" tm ); .BI "char *asctime_r(const struct tm *restrict " tm , .BI " char " buf "[restrict 26]);" -.PP +.P .BI "char *ctime(const time_t *" timep ); .BI "char *ctime_r(const time_t *restrict " timep , .BI " char " buf "[restrict 26]);" -.PP +.P .BI "struct tm *gmtime(const time_t *" timep ); .BI "struct tm *gmtime_r(const time_t *restrict " timep , .BI " struct tm *restrict " result ); -.PP +.P .BI "struct tm *localtime(const time_t *" timep ); .BI "struct tm *localtime_r(const time_t *restrict " timep , .BI " struct tm *restrict " result ); -.PP +.P .BI "time_t mktime(struct tm *" tm ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR asctime_r (), .BR ctime_r (), .BR gmtime_r (), @@ -66,7 +66,7 @@ functions all take an argument of data type \fItime_t\fP, which represents calendar time. When interpreted as an absolute time value, it represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P The .BR asctime () and @@ -74,25 +74,25 @@ and functions both take an argument representing broken-down time, which is a representation separated into year, month, day, and so on. -.PP +.P Broken-down time is stored in the structure .IR tm , described in .BR tm (3type). -.PP +.P The call .BI ctime( t ) is equivalent to .BI asctime(localtime( t )) \fR. It converts the calendar time \fIt\fP into a null-terminated string of the form -.PP +.P .in +4n .EX "Wed Jun 30 21:49:08 1993\en" .EE .in -.PP +.P The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", and "Sat". The abbreviations for the months are "Jan", @@ -112,7 +112,7 @@ string in a user-supplied buffer which should have room for at least 26 bytes. It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. -.PP +.P The .BR gmtime () function converts the calendar time \fItimep\fP to @@ -125,7 +125,7 @@ The .BR gmtime_r () function does the same, but stores the data in a user-supplied struct. -.PP +.P The .BR localtime () function converts the calendar time \fItimep\fP to @@ -145,7 +145,7 @@ The function does the same, but stores the data in a user-supplied struct. It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP. -.PP +.P The .BR asctime () function converts the broken-down time value @@ -157,7 +157,7 @@ The .BR asctime_r () function does the same, but stores the string in a user-supplied buffer which should have room for at least 26 bytes. -.PP +.P The .BR mktime () function converts a broken-down time structure, expressed @@ -182,7 +182,7 @@ and a negative value means that .BR mktime () should (use timezone information and system databases to) attempt to determine whether DST is in effect at the specified time. -.PP +.P The .BR mktime () function modifies the fields of the @@ -202,7 +202,7 @@ Calling .BR mktime () also sets the external variable \fItzname\fP with information about the current timezone. -.PP +.P If the specified broken-down time cannot be represented as calendar time (seconds since the Epoch), .BR mktime () @@ -217,33 +217,33 @@ and .BR localtime () return a pointer to a .IR "struct\ tm" . -.PP +.P On success, .BR gmtime_r () and .BR localtime_r () return the address of the structure pointed to by .IR result . -.PP +.P On success, .BR asctime () and .BR ctime () return a pointer to a string. -.PP +.P On success, .BR asctime_r () and .BR ctime_r () return a pointer to the string pointed to by .IR buf . -.PP +.P On success, .BR mktime () returns the calendar time (seconds since the Epoch), expressed as a value of type .IR time_t . -.PP +.P On error, .BR mktime () returns the value @@ -315,18 +315,17 @@ T} Thread safety T{ MT-Unsafe race:tmbuf env locale T} .TE -.sp 1 .SH VERSIONS POSIX doesn't specify the parameters of .BR ctime_r () to be .IR restrict ; that is specific to glibc. -.PP +.P In many implementations, including glibc, a 0 in .I tm_mday is interpreted as meaning the last day of the preceding month. -.PP +.P According to POSIX.1-2001, .BR localtime () is required to behave as though @@ -402,7 +401,7 @@ The thread-safe versions, and .BR localtime_r (), are specified by SUSv2. -.PP +.P POSIX.1-2001 says: "The .BR asctime (), diff --git a/man3/daemon.3 b/man3/daemon.3 index a44263c..9ee1587 100644 --- a/man3/daemon.3 +++ b/man3/daemon.3 @@ -6,7 +6,7 @@ .\" .\" @(#)daemon.3 8.1 (Berkeley) 6/9/93 .\" Added mentioning of glibc weirdness wrt unistd.h. 5/11/98, Al Viro -.TH daemon 3 2023-07-20 "Linux man-pages 6.05.01" +.TH daemon 3 2023-10-31 "Linux man-pages 6.7" .SH NAME daemon \- run in the background .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int daemon(int " nochdir ", int " noclose ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR daemon (): .nf Since glibc 2.21: @@ -39,7 +39,7 @@ The .BR daemon () function is for programs wishing to detach themselves from the controlling terminal and run in the background as system daemons. -.PP +.P If .I nochdir is zero, @@ -47,7 +47,7 @@ is zero, changes the process's current working directory to the root directory ("/"); otherwise, the current working directory is left unchanged. -.PP +.P If .I noclose is zero, @@ -88,10 +88,9 @@ T{ .BR daemon () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS A similar function appears on the BSDs. -.PP +.P The glibc implementation can also return \-1 when .I /dev/null exists but is not a character device with the expected diff --git a/man3/dbopen.3 b/man3/dbopen.3 index a6d418a..516768b 100644 --- a/man3/dbopen.3 +++ b/man3/dbopen.3 @@ -5,7 +5,7 @@ .\" .\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 .\" -.TH dbopen 3 2022-12-04 "Linux man-pages 6.05.01" +.TH dbopen 3 2023-10-31 "Linux man-pages 6.7" .UC 7 .SH NAME dbopen \- database access methods @@ -18,7 +18,7 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ ", DBTYPE " type , .BI " const void *" openinfo ); @@ -30,7 +30,7 @@ Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the .I libdb library instead. -.PP +.P .BR dbopen () is the library interface to database files. The supported file formats are btree, hashed, and UNIX file oriented. @@ -44,7 +44,7 @@ in their respective manual pages .BR hash (3), and .BR recno (3). -.PP +.P .BR dbopen () opens .I file @@ -53,7 +53,7 @@ Files never intended to be preserved on disk may be created by setting the .I file argument to NULL. -.PP +.P The .I flags and @@ -93,7 +93,7 @@ is not possible.) .\"DB_TXN .\"Support transactions in the database. .\"The DB_LOCK and DB_SHMEM flags must be set as well. -.PP +.P The .I type argument is of type @@ -106,7 +106,7 @@ may be set to .BR DB_HASH , or .BR DB_RECNO . -.PP +.P The .I openinfo argument is a pointer to an access-method-specific structure described @@ -115,7 +115,7 @@ If .I openinfo is NULL, each access method will use defaults appropriate for the system and the access method. -.PP +.P .BR dbopen () returns a pointer to a .I DB @@ -126,7 +126,7 @@ structure is defined in the .I include file, and contains at least the following fields: -.PP +.P .in +4n .EX typedef struct { @@ -144,7 +144,7 @@ typedef struct { } DB; .EE .in -.PP +.P These elements describe a database type and a set of functions performing various actions. These functions take a pointer to a structure as returned by @@ -428,7 +428,7 @@ and 0 on success. .SS Key/data pairs Access to all file types is based on key/data pairs. Both keys and data are represented by the following data structure: -.PP +.P .in +4n .EX typedef struct { @@ -437,7 +437,7 @@ typedef struct { } DBT; .EE .in -.PP +.P The elements of the .I DBT structure are defined as follows: @@ -447,7 +447,7 @@ A pointer to a byte string. .TP .I size The length of the byte string. -.PP +.P Key and data byte strings may reference strings of essentially unlimited length although any two of them must fit into available memory at the same time. @@ -473,7 +473,7 @@ incompatible with the current file specification or which is not meaningful for the function (for example, use of the cursor without prior initialization) or there is a mismatch between the version number of file and the software. -.PP +.P The .I close routines may fail and set @@ -485,7 +485,7 @@ for any of the errors specified for the library routines .BR free (3), or .BR fsync (2). -.PP +.P The .IR del , .IR get , @@ -500,7 +500,7 @@ for any of the errors specified for the library routines .BR free (3), or .BR malloc (3). -.PP +.P The .I fd routines will fail and set @@ -508,7 +508,7 @@ routines will fail and set to .B ENOENT for in memory databases. -.PP +.P The .I sync routines may fail and set @@ -520,10 +520,10 @@ The typedef .I DBT is a mnemonic for "data base thang", and was used because no one could think of a reasonable name that wasn't already used. -.PP +.P The file descriptor interface is a kludge and will be deleted in a future version of the interface. -.PP +.P None of the access methods provide any form of concurrent access, locking, or transactions. .SH SEE ALSO @@ -531,6 +531,6 @@ locking, or transactions. .BR hash (3), .BR mpool (3), .BR recno (3) -.PP +.P .IR "LIBTP: Portable, Modular Transactions for UNIX" , Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. diff --git a/man3/des_crypt.3 b/man3/des_crypt.3 index 41afe04..8a1228d 100644 --- a/man3/des_crypt.3 +++ b/man3/des_crypt.3 @@ -10,7 +10,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH des_crypt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH des_crypt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME des_crypt, ecb_crypt, cbc_crypt, des_setparity, DES_FAILED \- fast DES encryption @@ -22,7 +22,7 @@ Standard C library .\" Sun version .\" .B #include .B #include -.PP +.P .BI "[[deprecated]] int ecb_crypt(char *" key ", char " data [. datalen ], .BI " unsigned int " datalen ", \ unsigned int " mode ); @@ -30,9 +30,9 @@ unsigned int " mode ); .BI " unsigned int " datalen ", \ unsigned int " mode , .BI " char *" ivec ); -.PP +.P .BI "[[deprecated]] void des_setparity(char *" key ); -.PP +.P .BI "[[deprecated]] int DES_FAILED(int " status ); .fi .SH DESCRIPTION @@ -64,7 +64,7 @@ mode protects against insertions, deletions, and substitutions of blocks. Also, regularities in the clear text will not appear in the cipher text. -.PP +.P Here is how to use these routines. The first argument, .IR key , @@ -120,7 +120,7 @@ An error occurred in the hardware or driver. .TP .B DESERR_BADPARAM Bad argument to routine. -.PP +.P Given a result status .IR stat , the macro @@ -146,14 +146,13 @@ T{ .BR des_setparity () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY 4.3BSD. glibc 2.1. Removed in glibc 2.28. -.PP +.P Because they employ the DES block cipher, which is no longer considered secure, these functions were removed. diff --git a/man3/difftime.3 b/man3/difftime.3 index e1cd34f..d1e392e 100644 --- a/man3/difftime.3 +++ b/man3/difftime.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:48:17 1993 by Rik Faith (faith@cs.unc.edu) -.TH difftime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH difftime 3 2023-11-11 "Linux man-pages 6.7" .SH NAME difftime \- calculate time difference .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double difftime(time_t " time1 ", time_t " time0 ); .fi .SH DESCRIPTION @@ -26,9 +26,13 @@ The function returns the number of seconds elapsed between time \fItime1\fP and time \fItime0\fP, represented as a .IR double . -Each of the times is specified in calendar time, which means its -value is a measurement (in seconds) relative to the -Epoch, 1970-01-01 00:00:00 +0000 (UTC). +Each time is a count of seconds. +.P +.I difftime(b,\~a) +acts like +.I (b\-a) +except that the result does not overflow and is rounded to +.IR double . .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7). @@ -43,24 +47,10 @@ T{ .BR difftime () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C89, SVr4, 4.3BSD. -.SH NOTES -On a POSIX system, -.I time_t -is an arithmetic type, and one could just -define -.PP -.in +4n -.EX -#define my_difftime(t1,t0) (double)(t1 \- t0) -.EE -.in -.PP -when the possible overflow in the subtraction is not a concern. .SH SEE ALSO .BR date (1), .BR gettimeofday (2), diff --git a/man3/dirfd.3 b/man3/dirfd.3 index 4fa622c..fa296ec 100644 --- a/man3/dirfd.3 +++ b/man3/dirfd.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH dirfd 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dirfd 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dirfd \- get directory stream file descriptor .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int dirfd(DIR *" dirp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR dirfd (): .nf /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L @@ -32,7 +32,7 @@ The function .BR dirfd () returns the file descriptor associated with the directory stream .IR dirp . -.PP +.P This file descriptor is the one used internally by the directory stream. As a result, it is useful only for functions which do not depend on or alter the file position, such as @@ -76,7 +76,6 @@ T{ .BR dirfd () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/div.3 b/man3/div.3 index fa2e538..bbe2aeb 100644 --- a/man3/div.3 +++ b/man3/div.3 @@ -12,7 +12,7 @@ .\" Modified 1993-07-24, Rik Faith (faith@cs.unc.edu) .\" Modified 2002-08-10, 2003-11-01 Walter Harms, aeb .\" -.TH div 3 2023-07-20 "Linux man-pages 6.05.01" +.TH div 3 2023-10-31 "Linux man-pages 6.7" .SH NAME div, ldiv, lldiv, imaxdiv \- compute quotient and remainder of an integer division @@ -22,21 +22,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "div_t div(int " numerator ", int " denominator ); .BI "ldiv_t ldiv(long " numerator ", long " denominator ); .BI "lldiv_t lldiv(long long " numerator ", long long " denominator ); -.PP +.P .B #include -.PP +.P .BI "imaxdiv_t imaxdiv(intmax_t " numerator ", intmax_t " denominator ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR lldiv (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -51,7 +51,7 @@ named \fIdiv_t\fP that contains two integer members (in unspecified order) named \fIquot\fP and \fIrem\fP. The quotient is rounded toward zero. The result satisfies \fIquot\fP*\fIdenominator\fP+\fIrem\fP = \fInumerator\fP. -.PP +.P The .BR ldiv (), .BR lldiv (), @@ -81,25 +81,24 @@ T{ .BR imaxdiv () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C89, C99, SVr4, 4.3BSD. -.PP +.P .BR lldiv () and .BR imaxdiv () were added in C99. .SH EXAMPLES After -.PP +.P .in +4n .EX div_t q = div(\-5, 3); .EE .in -.PP +.P the values \fIq.quot\fP and \fIq.rem\fP are \-1 and \-2, respectively. .SH SEE ALSO .BR abs (3), diff --git a/man3/dl_iterate_phdr.3 b/man3/dl_iterate_phdr.3 index dc15758..b5cbb86 100644 --- a/man3/dl_iterate_phdr.3 +++ b/man3/dl_iterate_phdr.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH dl_iterate_phdr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dl_iterate_phdr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dl_iterate_phdr \- walk through list of shared objects .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .B int dl_iterate_phdr( .BI " int (*" callback ")(struct dl_phdr_info *" info , .BI " size_t " size ", void *" data ), @@ -25,7 +25,7 @@ The function allows an application to inquire at run time to find out which shared objects it has loaded, and the order in which they were loaded. -.PP +.P The .BR dl_iterate_phdr () function walks through the list of an @@ -35,7 +35,7 @@ once for each object, until either all shared objects have been processed or .I callback returns a nonzero value. -.PP +.P Each call to .I callback receives three arguments: @@ -52,11 +52,11 @@ program as the second argument (also named .IR data ) in the call to .BR dl_iterate_phdr (). -.PP +.P The .I info argument is a structure of the following type: -.PP +.P .in +4n .EX struct dl_phdr_info { @@ -90,7 +90,7 @@ struct dl_phdr_info { }; .EE .in -.PP +.P (The .IR ElfW () macro definition turns its argument into the name of an ELF data @@ -102,7 +102,7 @@ yields the data type name Further information on these types can be found in the .IR " and " header files.) -.PP +.P The .I dlpi_addr field indicates the base address of the shared object @@ -113,7 +113,7 @@ The .I dlpi_name field is a null-terminated string giving the pathname from which the shared object was loaded. -.PP +.P To understand the meaning of the .I dlpi_phdr and @@ -128,9 +128,9 @@ shared object. The .I dlpi_phnum field indicates the size of this array. -.PP +.P These program headers are structures of the following form: -.PP +.P .in +4n .EX typedef struct { @@ -145,23 +145,23 @@ typedef struct { } Elf32_Phdr; .EE .in -.PP +.P Note that we can calculate the location of a particular program header, .IR x , in virtual memory using the formula: -.PP +.P .in +4n .EX addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr; .EE .in -.PP +.P Possible values for .I p_type include the following (see .I for further details): -.PP +.P .in +4n .EX #define PT_LOAD 1 /* Loadable program segment */ @@ -196,7 +196,6 @@ T{ .BR dl_iterate_phdr () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Various other systems provide a version of this function, although details of the returned @@ -209,7 +208,7 @@ On the BSDs and Solaris, the structure includes the fields and .I dlpi_phnum in addition to other implementation-specific fields. -.PP +.P Future versions of the C library may add further fields to the .I dl_phdr_info structure; in that event, the @@ -233,13 +232,13 @@ shared objects it has loaded. For each shared object, the program lists some information (virtual address, size, flags, and type) for each of the objects ELF segments. -.PP +.P The following shell session demonstrates the output produced by the program on an x86-64 system. The first shared object for which output is displayed (where the name is an empty string) is the main program. -.PP +.P .in +4n .EX $ \fB./a.out\fP @@ -341,6 +340,6 @@ main(void) .BR dlopen (3), .BR elf (5), .BR ld.so (8) -.PP +.P .IR "Executable and Linking Format Specification" , available at various locations online. diff --git a/man3/dladdr.3 b/man3/dladdr.3 index 4571e67..6929b01 100644 --- a/man3/dladdr.3 +++ b/man3/dladdr.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH dladdr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dladdr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dladdr, dladdr1 \- translate address to symbolic information .SH LIBRARY @@ -14,7 +14,7 @@ Dynamic linking library .nf .B #define _GNU_SOURCE .B #include -.PP +.P .BI "int dladdr(const void *" addr ", Dl_info *" info ); .BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info , .BI " int " flags ); @@ -32,7 +32,7 @@ returns information about the shared object and symbol that overlaps This information is returned in a .I Dl_info structure: -.PP +.P .in +4n .EX typedef struct { @@ -47,7 +47,7 @@ typedef struct { } Dl_info; .EE .in -.PP +.P If no symbol matching .I addr could be found, then @@ -55,7 +55,7 @@ could be found, then and .I dli_saddr are set to NULL. -.PP +.P The function .BR dladdr1 () is like @@ -203,7 +203,7 @@ but not to a symbol in the shared object, then the and .I info\->dli_saddr fields are set to NULL. -.PP +.P If the address specified in .I addr could not be matched to a shared object, then these functions return 0. @@ -228,7 +228,6 @@ T{ .BR dladdr1 () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -238,7 +237,7 @@ glibc 2.0. .TP .BR dladdr1 () glibc 2.3.3. -.PP +.P Solaris. .SH BUGS Sometimes, the function pointers you pass to @@ -252,7 +251,7 @@ may end up pointing back at the object from which you called .BR dladdr (), even if the function used as an argument should come from a dynamically linked library. -.PP +.P The problem is that the function pointer will still be resolved at compile time, but merely point to the .I plt diff --git a/man3/dlerror.3 b/man3/dlerror.3 index 14baeea..06718ee 100644 --- a/man3/dlerror.3 +++ b/man3/dlerror.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH dlerror 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dlerror 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dlerror \- obtain error diagnostic for functions in the dlopen API .SH LIBRARY @@ -13,7 +13,7 @@ Dynamic linking library .SH SYNOPSIS .nf .B #include -.PP +.P .B "char *dlerror(void);" .fi .SH DESCRIPTION @@ -27,7 +27,7 @@ since the last call to The returned string does .I not include a trailing newline. -.PP +.P .BR dlerror () returns NULL if no errors have occurred since initialization or since it was last called. @@ -45,13 +45,12 @@ T{ .BR dlerror () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.0. POSIX.1-2001. -.PP +.P SunOS. .SH NOTES The message returned by @@ -60,7 +59,7 @@ may reside in a statically allocated buffer that is overwritten by subsequent .BR dlerror () calls. -.\" .LP +.\" .P .\" The string returned by .\" .BR dlerror () .\" should not be modified. diff --git a/man3/dlinfo.3 b/man3/dlinfo.3 index 586663d..8fd42fc 100644 --- a/man3/dlinfo.3 +++ b/man3/dlinfo.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH dlinfo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dlinfo 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dlinfo \- obtain information about a dynamically loaded object .SH LIBRARY @@ -14,7 +14,7 @@ Dynamic linking library .B #define _GNU_SOURCE .B #include .B #include -.PP +.P .BR "int dlinfo(void *restrict " handle ", int " request \ ", void *restrict " info ); .fi @@ -36,7 +36,7 @@ The argument is a pointer to a buffer used to store information returned by the call; the type of this argument depends on .IR request . -.PP +.P The following values are supported for .I request (with the corresponding type for @@ -214,7 +214,6 @@ T{ .BR dlinfo () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The sets of requests supported by the various implementations overlaps only partially. @@ -232,7 +231,7 @@ and .B RTLD_DI_SERINFO requests to obtain the library search path list for the library. Here is an example of what we might see when running the program: -.PP +.P .in +4n .EX $ \fB./a.out /lib64/libm.so.6\fP diff --git a/man3/dlopen.3 b/man3/dlopen.3 index 3774e9e..9e31e0f 100644 --- a/man3/dlopen.3 +++ b/man3/dlopen.3 @@ -14,7 +14,7 @@ .\" Modified by Walter Harms: dladdr, dlvsym .\" Modified by Petr Baudis , 2008-12-04: dladdr caveat .\" -.TH dlopen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dlopen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dlclose, dlopen, dlmopen \- open and close a shared object @@ -24,14 +24,14 @@ Dynamic linking library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *dlopen(const char *" filename ", int " flags ); .BI "int dlclose(void *" handle ); -.PP +.P .B #define _GNU_SOURCE .br .B #include -.PP +.P .BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags ); .fi .SH DESCRIPTION @@ -49,7 +49,7 @@ This handle is employed with other functions in the dlopen API, such as .BR dlinfo (3), and .BR dlclose (). -.PP +.P If .I filename .\" FIXME On Solaris, when handle is NULL, we seem to get back @@ -99,7 +99,7 @@ The directories and .I /usr/lib are searched (in that order). -.PP +.P If the object specified by .I filename has dependencies on other shared objects, @@ -107,7 +107,7 @@ then these are also automatically loaded by the dynamic linker using the same rules. (This process may occur recursively, if those objects in turn have dependencies, and so on.) -.PP +.P One of the following two values must be included in .IR flags : .TP @@ -132,7 +132,7 @@ all undefined symbols in the shared object are resolved before .BR dlopen () returns. If this cannot be done, an error is returned. -.PP +.P Zero or more of the following values may also be ORed in .IR flags : .TP @@ -176,7 +176,7 @@ shared object ahead of the global scope. This means that a self-contained object will use its own symbols in preference to global symbols with the same name contained in objects that have already been loaded. -.PP +.P If .I filename is NULL, then the returned handle is for the main program. @@ -188,7 +188,7 @@ and then all shared objects loaded by .BR dlopen () with the flag .BR RTLD_GLOBAL . -.PP +.P Symbol references in the shared object are resolved using (in order): symbols in the link map of objects loaded for the main program and its dependencies; @@ -200,7 +200,7 @@ using the flag; and definitions in the shared object itself (and any dependencies that were loaded for that object). -.PP +.P Any global symbols in the executable that were placed into its dynamic symbol table by .BR ld (1) @@ -212,7 +212,7 @@ the executable's global symbols to be placed in the dynamic symbol table, or because .BR ld (1) noted a dependency on a symbol in another object during static linking. -.PP +.P If the same shared object is opened again with .BR dlopen (), the same object handle is returned. @@ -225,7 +225,7 @@ has been called on it as many times as has succeeded on it. Constructors (see below) are called only when the object is actually loaded into memory (i.e., when the reference count increases to 1). -.PP +.P A subsequent .BR dlopen () call that loads the same shared object with @@ -238,7 +238,7 @@ can be promoted to .B RTLD_GLOBAL in a subsequent .BR dlopen (). -.PP +.P If .BR dlopen () fails for any reason, it returns NULL. @@ -251,7 +251,7 @@ and .I flags arguments, as well as the return value, are the same, except for the differences noted below. -.PP +.P The .BR dlmopen () function differs from @@ -270,7 +270,7 @@ call is made.) The .I Lmid_t type is an opaque handle that refers to a namespace. -.PP +.P The .I lmid argument is either the ID of an existing namespace @@ -289,7 +289,7 @@ Create a new namespace and load the shared object in that namespace. The object must have been correctly linked to reference all of the other shared objects that it requires, since the new namespace is initially empty. -.PP +.P If .I filename is NULL, then the only permitted value for @@ -302,7 +302,7 @@ The function decrements the reference count on the dynamically loaded shared object referred to by .IR handle . -.PP +.P If the object's reference count drops to zero and no symbols in this object are required by other objects, then the object is unloaded @@ -311,13 +311,13 @@ after first calling any destructors defined for the object. because this object was opened with the .B RTLD_GLOBAL flag and one of its symbols satisfied a relocation in another object.) -.PP +.P All shared objects that were automatically loaded when .BR dlopen () was invoked on the object referred to by .I handle are recursively closed in the same manner. -.PP +.P A successful return from .BR dlclose () does not guarantee that the symbols associated with @@ -339,11 +339,11 @@ On error (file could not be found, was not readable, had the wrong format, or caused errors during loading), these functions return NULL. -.PP +.P On success, .BR dlclose () returns 0; on error, it returns a nonzero value. -.PP +.P Errors from these functions can be diagnosed using .BR dlerror (3). .SH ATTRIBUTES @@ -362,7 +362,6 @@ T{ .BR dlclose () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR dlopen () @@ -398,7 +397,7 @@ dependent shared objects are implicitly loaded according to the usual rules, and symbol references are likewise resolved according to the usual rules, but such resolution is confined to the definitions provided by the objects that have been (explicitly and implicitly) loaded into the namespace. -.PP +.P The .BR dlmopen () function permits object-load isolation\[em]the ability @@ -418,7 +417,7 @@ without exposing those symbols to the entire application. This can be achieved by using a separate namespace and the .B RTLD_GLOBAL flag. -.PP +.P The .BR dlmopen () function also can be used to provide better isolation than the @@ -434,7 +433,7 @@ Thus, .B RTLD_LOCAL is insufficient to isolate a loaded shared object except in the (uncommon) case where one has explicit control over all shared object dependencies. -.PP +.P Possible uses of .BR dlmopen () are plugins where the author of the plugin-loading framework @@ -449,7 +448,7 @@ Using .BR dlmopen (), this can be achieved by loading the same shared object file into different namespaces. -.PP +.P The glibc implementation supports a maximum of .\" DL_NNS 16 namespaces. @@ -473,7 +472,7 @@ See the info pages (under "Function attributes") .\" info gcc "C Extensions" "Function attributes" for further information. -.PP +.P An older method of (partially) achieving the same result is via the use of two special symbols recognized by the linker: .B _init @@ -493,7 +492,7 @@ this can be done by using the .BR gcc (1) .I \-nostartfiles command-line option. -.PP +.P Use of .B _init and @@ -514,7 +513,7 @@ permit multiple initialization and finalization functions to be defined. .\" .\" void _init(void) __attribute__((constructor)); .\" .\" void _fini(void) __attribute__((destructor)); .\" -.PP +.P Since glibc 2.2.3, .BR atexit (3) can be used to register an exit handler that is automatically @@ -543,7 +542,7 @@ looks up the address of the .BR cos (3) function, and prints the cosine of 2.0. The following is an example of building and running the program: -.PP +.P .in +4n .EX $ \fBcc dlopen_demo.c \-ldl\fP @@ -621,5 +620,5 @@ main(void) .BR rtld\-audit (7), .BR ld.so (8), .BR ldconfig (8) -.PP +.P gcc info pages, ld info pages diff --git a/man3/dlsym.3 b/man3/dlsym.3 index 499e29c..18ba953 100644 --- a/man3/dlsym.3 +++ b/man3/dlsym.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH dlsym 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dlsym 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dlsym, dlvsym \- obtain address of a symbol in a shared object or executable .SH LIBRARY @@ -13,12 +13,12 @@ Dynamic linking library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *dlsym(void *restrict " handle ", const char *restrict " symbol ); -.PP +.P .B #define _GNU_SOURCE .B #include -.PP +.P .BI "void *dlvsym(void *restrict " handle ", const char *restrict " symbol , .BI " const char *restrict " version ); .fi @@ -39,7 +39,7 @@ returns NULL. (The search performed by .BR dlsym () is breadth first through the dependency tree of these shared objects.) -.PP +.P In unusual cases (see NOTES) the value of the symbol could actually be NULL. Therefore, a NULL return from .BR dlsym () @@ -53,7 +53,7 @@ and then call .BR dlerror (3) again, saving its return value into a variable, and check whether this saved value is not NULL. -.PP +.P There are two special pseudo-handles that may be specified in .IR handle : .TP @@ -79,7 +79,7 @@ in can find and invoke the "real" function provided in another shared object (or for that matter, the "next" definition of the function in cases where there are multiple layers of preloading). -.PP +.P The .B _GNU_SOURCE feature test macro must be defined in order to obtain the @@ -89,7 +89,7 @@ and .B RTLD_NEXT from .IR . -.PP +.P The function .BR dlvsym () does the same as @@ -117,7 +117,6 @@ T{ .BR dlvsym () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR dlsym () diff --git a/man3/drand48.3 b/man3/drand48.3 index b768d0d..18123b0 100644 --- a/man3/drand48.3 +++ b/man3/drand48.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:46:03 1993 by Rik Faith (faith@cs.unc.edu) -.TH drand48 3 2023-07-20 "Linux man-pages 6.05.01" +.TH drand48 3 2023-10-31 "Linux man-pages 6.7" .SH NAME drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, lcong48 \- generate uniformly distributed pseudo-random numbers @@ -18,26 +18,26 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B double drand48(void); .BI "double erand48(unsigned short " xsubi [3]); -.PP +.P .B long lrand48(void); .BI "long nrand48(unsigned short " xsubi [3]); -.PP +.P .B long mrand48(void); .BI "long jrand48(unsigned short " xsubi [3]); -.PP +.P .BI "void srand48(long " seedval ); .BI "unsigned short *seed48(unsigned short " seed16v [3]); .BI "void lcong48(unsigned short " param [7]); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .\" .BR drand48 (), .\" .BR erand48 (), @@ -56,7 +56,7 @@ All functions shown above: .SH DESCRIPTION These functions generate pseudo-random numbers using the linear congruential algorithm and 48-bit integer arithmetic. -.PP +.P The .BR drand48 () and @@ -64,21 +64,21 @@ and functions return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,\ 1.0). -.PP +.P The .BR lrand48 () and .BR nrand48 () functions return nonnegative long integers uniformly distributed over the interval [0,\ 2\[ha]31). -.PP +.P The .BR mrand48 () and .BR jrand48 () functions return signed long integers uniformly distributed over the interval [\-2\[ha]31,\ 2\[ha]31). -.PP +.P The .BR srand48 (), .BR seed48 (), @@ -97,17 +97,17 @@ and .BR jrand48 () do not require an initialization function to be called first. -.PP +.P All the functions work by generating a sequence of 48-bit integers, .IR Xi , according to the linear congruential formula: -.PP +.P .in +4n .EX .B Xn+1 = (aXn + c) mod m, where n >= 0 .EE .in -.PP +.P The parameter .I m = 2\[ha]48, hence 48-bit integer arithmetic is performed. @@ -118,14 +118,14 @@ is called, and .I c are given by: -.PP +.P .in +4n .EX .B a = 0x5DEECE66D .B c = 0xB .EE .in -.PP +.P The value returned by any of the functions .BR drand48 (), .BR erand48 (), @@ -143,7 +143,7 @@ be returned, is copied from the high-order bits of .I Xi and transformed into the returned value. -.PP +.P The functions .BR drand48 (), .BR lrand48 (), @@ -169,7 +169,7 @@ value of .I Xi into the array before calling the function for the first time. -.PP +.P The initializer function .BR srand48 () sets the high order 32-bits of @@ -178,7 +178,7 @@ to the argument .IR seedval . The low order 16-bits are set to the arbitrary value 0x330E. -.PP +.P The initializer function .BR seed48 () sets the value of @@ -192,7 +192,7 @@ previous value of is copied into an internal buffer and a pointer to this buffer is returned by .BR seed48 (). -.PP +.P The initialization function .BR lcong48 () allows the user to specify @@ -249,8 +249,7 @@ T} Thread safety T{ MT-Unsafe race:drand48 T} .TE -.sp 1 -.PP +.P The above functions record global state information for the random number generator, so they are not thread-safe. diff --git a/man3/drand48_r.3 b/man3/drand48_r.3 index 146fed4..19618d7 100644 --- a/man3/drand48_r.3 +++ b/man3/drand48_r.3 @@ -5,7 +5,7 @@ .\" .\" Created 2004-10-31. Text taken from a page by Walter Harms, 2003-09-08 .\" -.TH drand48_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH drand48_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME drand48_r, erand48_r, lrand48_r, nrand48_r, mrand48_r, jrand48_r, srand48_r, seed48_r, lcong48_r @@ -16,35 +16,35 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int drand48_r(struct drand48_data *restrict " buffer , .BI " double *restrict " result ); .BI "int erand48_r(unsigned short " xsubi [3] "," .BI " struct drand48_data *restrict "buffer , .BI " double *restrict " result ");" -.PP +.P .BI "int lrand48_r(struct drand48_data *restrict " buffer , .BI " long *restrict " result ); .BI "int nrand48_r(unsigned short " xsubi[3] "," .BI " struct drand48_data *restrict "buffer , .BI " long *restrict " result ");" -.PP +.P .BI "int mrand48_r(struct drand48_data *restrict " buffer , .BI " long *restrict " result ");" .BI "int jrand48_r(unsigned short " xsubi[3] "," .BI " struct drand48_data *restrict " buffer , .BI " long *restrict " result ");" -.PP +.P .BI "int srand48_r(long int " seedval ", struct drand48_data *" buffer ");" .BI "int seed48_r(unsigned short " seed16v[3] ", struct drand48_data *" buffer ); .BI "int lcong48_r(unsigned short " param[7] ", struct drand48_data *" buffer ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .\" .BR drand48_r (), .\" .BR erand48_r (), @@ -65,7 +65,7 @@ These functions are the reentrant analogs of the functions described in Instead of modifying the global random generator state, they use the supplied data .IR buffer . -.PP +.P Before the first use, this struct must be initialized, for example, by filling it with zeros, or by calling one of the functions .BR srand48_r (), @@ -96,7 +96,6 @@ T{ .BR lcong48_r () T} Thread safety MT-Safe race:buffer .TE -.sp 1 .SH STANDARDS GNU. .SH SEE ALSO diff --git a/man3/duplocale.3 b/man3/duplocale.3 index 7b1bff8..0f75472 100644 --- a/man3/duplocale.3 +++ b/man3/duplocale.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH duplocale 3 2023-05-03 "Linux man-pages 6.05.01" +.TH duplocale 3 2023-10-31 "Linux man-pages 6.7" .SH NAME duplocale \- duplicate a locale object .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "locale_t duplocale(locale_t " locobj ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR duplocale (): .nf Since glibc 2.10: @@ -32,7 +32,7 @@ The .BR duplocale () function creates a duplicate of the locale object referred to by .IR locobj . -.PP +.P If .I locobj is @@ -90,7 +90,7 @@ can be used to ensure that the .B LC_GLOBAL_LOCALE value is converted into a usable locale object. See EXAMPLES, below. -.PP +.P Each locale object created by .BR duplocale () should be deallocated using @@ -106,7 +106,7 @@ The program takes one command-line argument, a string of characters that is converted to uppercase and displayed on standard output. An example of its use is the following: -.PP +.P .in +4n .EX $ \fB./a.out abc\fP diff --git a/man3/dysize.3 b/man3/dysize.3 index 7e2d328..d345076 100644 --- a/man3/dysize.3 +++ b/man3/dysize.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" aeb: some corrections -.TH dysize 3 2023-07-20 "Linux man-pages 6.05.01" +.TH dysize 3 2023-10-31 "Linux man-pages 6.7" .SH NAME dysize \- get number of days for a given year .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int dysize(int " year ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR dysize (): .nf Since glibc 2.19: @@ -32,13 +32,13 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION The function returns 365 for a normal year and 366 for a leap year. The calculation for leap year is based on: -.PP +.P .in +4n .EX (year) %4 == 0 && ((year) %100 != 0 || (year) %400 == 0) .EE .in -.PP +.P The formula is defined in the macro .I __isleap(year) also found in @@ -57,12 +57,11 @@ T{ .BR dysize () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY SunOS 4.x. -.PP +.P This is a compatibility function only. Don't use it in new programs. .\" The SCO version of this function had a year-2000 problem. diff --git a/man3/ecvt.3 b/man3/ecvt.3 index f207948..2e773f4 100644 --- a/man3/ecvt.3 +++ b/man3/ecvt.3 @@ -10,7 +10,7 @@ .\" Modified Sat Jul 24 19:40:39 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Fri Jun 25 12:10:47 1999 by Andries Brouwer (aeb@cwi.nl) .\" -.TH ecvt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ecvt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ecvt, fcvt \- convert a floating-point number to a string .SH LIBRARY @@ -19,18 +19,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] char *ecvt(double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign ); .BI "[[deprecated]] char *fcvt(double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ecvt (), .BR fcvt (): .nf @@ -68,7 +68,7 @@ otherwise it is set to 0. If .I number is zero, it is unspecified whether \fI*decpt\fP is 0 or 1. -.PP +.P The .BR fcvt () function is identical to @@ -105,7 +105,6 @@ T{ .BR fcvt () T} Thread safety MT-Unsafe race:fcvt .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/ecvt_r.3 b/man3/ecvt_r.3 index 39eafa9..30c1fc6 100644 --- a/man3/ecvt_r.3 +++ b/man3/ecvt_r.3 @@ -8,7 +8,7 @@ .\" .\" Corrected return types; from Fabian; 2004-10-05 .\" -.TH ecvt_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ecvt_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ecvt_r, fcvt_r, qecvt_r, qfcvt_r \- convert a floating-point number to a string .SH LIBRARY @@ -17,14 +17,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int ecvt_r(double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign , .BI " char *restrict " buf ", size_t " len ); .BI "[[deprecated]] int fcvt_r(double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign , .BI " char *restrict " buf ", size_t " len ); -.PP +.P .BI "[[deprecated]] int qecvt_r(long double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign , .BI " char *restrict " buf ", size_t " len ); @@ -32,12 +32,12 @@ Standard C library .BI " int *restrict " decpt ", int *restrict " sign , .BI " char *restrict " buf ", size_t " len ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ecvt_r (), .BR fcvt_r (), .BR qecvt_r (), @@ -87,7 +87,6 @@ T{ .BR qfcvt_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH NOTES diff --git a/man3/encrypt.3 b/man3/encrypt.3 index a3fae2f..58c61b3 100644 --- a/man3/encrypt.3 +++ b/man3/encrypt.3 @@ -9,7 +9,7 @@ .\" .\" Modified 2003-04-04, aeb .\" -.TH encrypt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH encrypt 3 2024-02-26 "Linux man-pages 6.7" .SH NAME encrypt, setkey, encrypt_r, setkey_r \- encrypt 64-bit messages .SH LIBRARY @@ -19,17 +19,17 @@ Password hashing library .nf .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "[[deprecated]] void encrypt(char " block "[64], int " edflag ); -.PP +.P .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "[[deprecated]] void setkey(const char *" key ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "[[deprecated]] void setkey_r(const char *" key ", struct crypt_data *" data ); .BI "[[deprecated]] void encrypt_r(char *" block ", int " edflag , .BI " struct crypt_data *" data ); @@ -46,7 +46,7 @@ argument used here is an array of 64 bytes, each of which has numerical value 1 or 0. The bytes key[n] where n=8*i-1 are ignored, so that the effective key length is 56 bits. -.PP +.P The .BR encrypt () function modifies the passed buffer, encoding if @@ -58,7 +58,7 @@ argument, also .I block is a bit vector representation of the actual value that is encoded. The result is returned in that same vector. -.PP +.P These two functions are not reentrant, that is, the key data is kept in static storage. The functions @@ -68,7 +68,7 @@ and are the reentrant versions. They use the following structure to hold the key data: -.PP +.P .in +4n .EX struct crypt_data { @@ -85,7 +85,7 @@ struct crypt_data { }; .EE .in -.PP +.P Before calling .BR setkey_r () set @@ -125,7 +125,6 @@ T{ .BR setkey_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR encrypt () @@ -139,7 +138,7 @@ POSIX.1-2008. None. .SH HISTORY Removed in glibc 2.28. -.PP +.P Because they employ the DES block cipher, which is no longer considered secure, these functions were removed from glibc. @@ -156,7 +155,7 @@ See .SS Features in glibc In glibc 2.2, these functions use the DES algorithm. .SH EXAMPLES -.\" [[deprecated]] SRC BEGIN (encrypt.c) +.\" SRC BEGIN (encrypt.c) .EX #define _XOPEN_SOURCE #include diff --git a/man3/end.3 b/man3/end.3 index a0691d6..1eb07fd 100644 --- a/man3/end.3 +++ b/man3/end.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH end 3 2023-05-03 "Linux man-pages 6.05.01" +.TH end 3 2023-10-31 "Linux man-pages 6.7" .SH NAME etext, edata, end \- end of program segments .SH SYNOPSIS @@ -35,7 +35,7 @@ they are not standardized; use with caution. .SH NOTES The program must explicitly declare these symbols; they are not defined in any header file. -.PP +.P On some systems the names of these symbols are preceded by underscores, thus: .IR _etext , @@ -43,7 +43,7 @@ thus: and .IR _end . These symbols are also defined for programs compiled on Linux. -.PP +.P At the start of program execution, the program break will be somewhere near .I &end @@ -57,7 +57,7 @@ Use with an argument of zero to find the current value of the program break. .SH EXAMPLES When run, the program below produces output such as the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man3/endian.3 b/man3/endian.3 index fa7b9fd..8de4974 100644 --- a/man3/endian.3 +++ b/man3/endian.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH endian 3 2023-05-03 "Linux man-pages 6.05.01" +.TH endian 3 2023-10-31 "Linux man-pages 6.7" .SH NAME htobe16, htole16, be16toh, le16toh, htobe32, htole32, be32toh, le32toh, htobe64, htole64, be64toh, le64toh \- @@ -16,29 +16,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "uint16_t htobe16(uint16_t " host_16bits ); .BI "uint16_t htole16(uint16_t " host_16bits ); .BI "uint16_t be16toh(uint16_t " big_endian_16bits ); .BI "uint16_t le16toh(uint16_t " little_endian_16bits ); -.PP +.P .BI "uint32_t htobe32(uint32_t " host_32bits ); .BI "uint32_t htole32(uint32_t " host_32bits ); .BI "uint32_t be32toh(uint32_t " big_endian_32bits ); .BI "uint32_t le32toh(uint32_t " little_endian_32bits ); -.PP +.P .BI "uint64_t htobe64(uint64_t " host_64bits ); .BI "uint64_t htole64(uint64_t " host_64bits ); .BI "uint64_t be64toh(uint64_t " big_endian_64bits ); .BI "uint64_t le64toh(uint64_t " little_endian_64bits ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE .ad l -.PP +.P .BR htobe16 (), .BR htole16 (), .BR be16toh (), @@ -62,21 +62,21 @@ Feature Test Macro Requirements for glibc (see These functions convert the byte encoding of integer values from the byte order that the current CPU (the "host") uses, to and from little-endian and big-endian byte order. -.PP +.P The number, .IR nn , in the name of each function indicates the size of integer handled by the function, either 16, 32, or 64 bits. -.PP +.P The functions with names of the form "htobe\fInn\fP" convert from host byte order to big-endian order. -.PP +.P The functions with names of the form "htole\fInn\fP" convert from host byte order to little-endian order. -.PP +.P The functions with names of the form "be\fInn\fPtoh" convert from big-endian order to host byte order. -.PP +.P The functions with names of the form "le\fInn\fPtoh" convert from little-endian order to host byte order. .SH VERSIONS @@ -97,7 +97,7 @@ the equivalent of OpenBSDs "betoh32" is "be32toh"). None. .SH HISTORY glibc 2.9. -.PP +.P These functions are similar to the older .BR byteorder (3) family of functions. @@ -105,7 +105,7 @@ For example, .BR be32toh () is identical to .BR ntohl (). -.PP +.P The advantage of the .BR byteorder (3) functions is that they are standard functions available @@ -120,7 +120,7 @@ Since host byte order is either little-endian or big-endian, only one of these conversions will have an effect. When we run this program on a little-endian system such as x86-32, we see the following: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man3/envz_add.3 b/man3/envz_add.3 index fcb5ca3..ec2f658 100644 --- a/man3/envz_add.3 +++ b/man3/envz_add.3 @@ -6,7 +6,7 @@ .\" based on the description in glibc source and infopages .\" .\" Corrections and additions, aeb -.TH envz_add 3 2023-07-20 "Linux man-pages 6.05.01" +.TH envz_add 3 2023-10-31 "Linux man-pages 6.7" .SH NAME envz_add, envz_entry, envz_get, envz_merge, envz_remove, envz_strip \- environment string support @@ -16,29 +16,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "error_t envz_add(char **restrict " envz ", size_t *restrict " envz_len , .BI " const char *restrict " name \ ", const char *restrict " value ); -.PP +.P .BI "char *envz_entry(const char *restrict " envz ", size_t " envz_len , .BI " const char *restrict " name ); -.PP +.P .BI "char *envz_get(const char *restrict " envz ", size_t " envz_len , .BI " const char *restrict " name ); -.PP +.P .BI "error_t envz_merge(char **restrict " envz ", size_t *restrict " envz_len , .BI " const char *restrict " envz2 ", size_t " envz2_len , .BI " int " override ); -.PP +.P .BI "void envz_remove(char **restrict " envz ", size_t *restrict " envz_len , .BI " const char *restrict " name ); -.PP +.P .BI "void envz_strip(char **restrict " envz ", size_t *restrict " envz_len ); .fi .SH DESCRIPTION These functions are glibc-specific. -.PP +.P An argz vector is a pointer to a character buffer together with a length, see .BR argz_add (3). @@ -48,9 +48,9 @@ Everything after the first \[aq]=\[aq] is considered to be the value. If there is no \[aq]=\[aq], the value is taken to be NULL. (While the value in case of a trailing \[aq]=\[aq] is the empty string "".) -.PP +.P These functions are for handling envz vectors. -.PP +.P .BR envz_add () adds the string .RI \&" name = value \&" @@ -69,14 +69,14 @@ and If an entry with the same .I name existed, it is removed. -.PP +.P .BR envz_entry () looks for .I name in the envz vector .RI ( envz ,\ envz_len ) and returns the entry if found, or NULL if not. -.PP +.P .BR envz_get () looks for .I name @@ -87,7 +87,7 @@ and returns the value if found, or NULL if not. an entry for .I name without \[aq]=\[aq] sign.) -.PP +.P .BR envz_merge () adds each entry in .I envz2 @@ -102,14 +102,14 @@ is true, then values in will supersede those with the same name in .IR *envz , otherwise not. -.PP +.P .BR envz_remove () removes the entry for .I name from .RI ( *envz ,\ *envz_len ) if there was one. -.PP +.P .BR envz_strip () removes all entries with value NULL. .SH RETURN VALUE @@ -138,7 +138,6 @@ T{ .BR envz_strip () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH EXAMPLES diff --git a/man3/erf.3 b/man3/erf.3 index ed7f7f0..1e12bba 100644 --- a/man3/erf.3 +++ b/man3/erf.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH erf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH erf 3 2023-10-31 "Linux man-pages 6.7" .SH NAME erf, erff, erfl \- error function .SH LIBRARY @@ -22,24 +22,24 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double erf(double " x ); .BI "float erff(float " x ); .BI "long double erfl(long double " x ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR erf (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR erff (), .BR erfl (): .nf @@ -51,7 +51,7 @@ Feature Test Macro Requirements for glibc (see These functions return the error function of .IR x , defined as -.PP +.P .in +4n .EX erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt @@ -61,20 +61,20 @@ erf(x) = 2/sqrt(pi) * integral from 0 to x of exp(\-t*t) dt On success, these functions return the value of the error function of .IR x , a value in the range [\-1,\ 1]. -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity (negative infinity), +1 (\-1) is returned. -.PP +.P If .I x is subnormal, @@ -85,7 +85,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result underflow (\fIx\fP is subnormal) @@ -95,7 +95,7 @@ Range error: result underflow (\fIx\fP is subnormal) An underflow floating-point exception .RB ( FE_UNDERFLOW ) is raised. -.PP +.P These functions do not set .IR errno . .\" It is intentional that these functions do not set errno for this case @@ -116,12 +116,11 @@ T{ .BR erfl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/erfc.3 b/man3/erfc.3 index 92d6293..658e1bb 100644 --- a/man3/erfc.3 +++ b/man3/erfc.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH erfc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH erfc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME erfc, erfcf, erfcl \- complementary error function .SH LIBRARY @@ -13,24 +13,24 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double erfc(double " x ); .BI "float erfcf(float " x ); .BI "long double erfcl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR erfc (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR erfcf (), .BR erfcl (): .nf @@ -46,28 +46,28 @@ that is, 1.0 \- erf(x). On success, these functions return the complementary error function of .IR x , a value in the range [0,2]. -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 or \-0, 1 is returned. -.PP +.P If .I x is positive infinity, +0 is returned. -.PP +.P If .I x is negative infinity, +2 is returned. -.PP +.P If the function result underflows and produces an unrepresentable value, the return value is 0.0. -.PP +.P If the function result underflows but produces a representable (i.e., subnormal) value, .\" e.g., erfc(27) on x86-32 @@ -78,7 +78,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result underflow (result is subnormal) @@ -88,7 +88,7 @@ Range error: result underflow (result is subnormal) An underflow floating-point exception .RB ( FE_UNDERFLOW ) is raised. -.PP +.P These functions do not set .IR errno . .\" It is intentional that these functions do not set errno for this case @@ -109,12 +109,11 @@ T{ .BR erfcl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/err.3 b/man3/err.3 index 87f45a3..01a88ec 100644 --- a/man3/err.3 +++ b/man3/err.3 @@ -9,7 +9,7 @@ .\" .\" 2011-09-10, mtk, Converted from mdoc to man macros .\" -.TH err 3 2023-07-20 "Linux man-pages 6.05.01" +.TH err 3 2023-10-31 "Linux man-pages 6.7" .SH NAME err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages .SH LIBRARY @@ -18,18 +18,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[noreturn]] void err(int " eval ", const char *" fmt ", ...);" .BI "[[noreturn]] void errx(int " eval ", const char *" fmt ", ...);" -.PP +.P .BI "void warn(const char *" fmt ", ...);" .BI "void warnx(const char *" fmt ", ...);" -.PP +.P .B #include -.PP +.P .BI "[[noreturn]] void verr(int " eval ", const char *" fmt ", va_list " args ); .BI "[[noreturn]] void verrx(int " eval ", const char *" fmt ", va_list " args ); -.PP +.P .BI "void vwarn(const char *" fmt ", va_list " args ); .BI "void vwarnx(const char *" fmt ", va_list " args ); .fi @@ -48,7 +48,7 @@ argument is not NULL, the .BR printf (3)-like formatted error message is output. The output is terminated by a newline character. -.PP +.P The .BR err (), .BR verr (), @@ -63,13 +63,13 @@ preceded by another colon and space unless the .I fmt argument is NULL. -.PP +.P The .BR errx () and .BR warnx () functions do not append an error message. -.PP +.P The .BR err (), .BR verr (), @@ -99,7 +99,6 @@ T{ .BR vwarnx () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY @@ -112,7 +111,7 @@ BSD. Display the current .I errno information string and exit: -.PP +.P .in +4n .EX p = malloc(size); @@ -123,9 +122,9 @@ if (fd == \-1) err(EXIT_FAILURE, "%s", file_name); .EE .in -.PP +.P Display an error message and exit: -.PP +.P .in +4n .EX if (tm.tm_hour < START_TIME) @@ -133,9 +132,9 @@ if (tm.tm_hour < START_TIME) start_time_string); .EE .in -.PP +.P Warn of an error: -.PP +.P .in +4n .EX fd = open(raw_device, O_RDONLY, 0); diff --git a/man3/errno.3 b/man3/errno.3 index f3ffee5..335bb9c 100644 --- a/man3/errno.3 +++ b/man3/errno.3 @@ -9,7 +9,7 @@ .\" 2006-02-09 Kurt Wall, mtk .\" Added non-POSIX errors .\" -.TH errno 3 2022-12-04 "Linux man-pages 6.05.01" +.TH errno 3 2023-10-31 "Linux man-pages 6.7" .SH NAME errno \- number of last error .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.\".PP +.\".P .\".BI "extern int " errno ; .fi .SH DESCRIPTION @@ -43,7 +43,7 @@ allowed to change The value of .I errno is never set to zero by any system call or library function. -.PP +.P For some system calls and library functions (e.g., .BR getpriority (2)), \-1 is a valid return on success. @@ -55,7 +55,7 @@ if the call returns a status that indicates that an error may have occurred, checking to see if .I errno has a nonzero value. -.PP +.P .I errno is defined by the ISO C standard to be a modifiable lvalue of type @@ -74,7 +74,7 @@ The header file defines symbolic names for each of the possible error numbers that may appear in .IR errno . -.PP +.P All the error names specified by POSIX.1 must have distinct values, with the exception of .B EAGAIN @@ -82,7 +82,7 @@ and .BR EWOULDBLOCK , which may be the same. On Linux, these two have the same value on all architectures. -.PP +.P The error numbers that correspond to each symbolic name vary across UNIX systems, and even across different architectures on Linux. @@ -94,7 +94,7 @@ and .BR strerror (3) functions can be used to convert these names to corresponding textual error messages. -.PP +.P On any particular Linux system, one can obtain a list of all symbolic error names and the corresponding error numbers using the @@ -102,7 +102,7 @@ the corresponding error numbers using the command (part of the .I moreutils package): -.PP +.P .in +4n .EX $ \fBerrno \-l\fP @@ -114,13 +114,13 @@ EIO 5 Input/output error \&... .EE .in -.PP +.P The .BR errno (1) command can also be used to look up individual error numbers and names, and to search for errors using strings from the error description, as in the following examples: -.PP +.P .in +4n .EX $ \fBerrno 2\fP @@ -131,7 +131,7 @@ $ \fBerrno \-s permission\fP EACCES 13 Permission denied .EE .in -.\".PP +.\".P .\" POSIX.1 (2001 edition) lists the following symbolic error names. Of .\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard. ISO C .\" Amendment 1 defines the additional error number \fBEILSEQ\fP for @@ -151,7 +151,7 @@ but was not present in earlier POSIX.1 standards. .TP .I C99 The name is defined by C99. -.PP +.P Below is a list of the symbolic error names that are defined on Linux: .TP 16 .B E2BIG @@ -595,7 +595,7 @@ Invalid cross-device link (POSIX.1-2001). Exchange full. .SH NOTES A common mistake is to do -.PP +.P .in +4n .EX if (somecall() == \-1) { @@ -604,7 +604,7 @@ if (somecall() == \-1) { } .EE .in -.PP +.P where .I errno no longer needs to have the value it had upon return from @@ -614,7 +614,7 @@ no longer needs to have the value it had upon return from If the value of .I errno should be preserved across a library call, it must be saved: -.PP +.P .in +4n .EX if (somecall() == \-1) { @@ -624,7 +624,7 @@ if (somecall() == \-1) { } .EE .in -.PP +.P Note that the POSIX threads APIs do .I not set @@ -634,7 +634,7 @@ Instead, on failure they return an error number as the function result. These error numbers have the same meanings as the error numbers returned in .I errno by other APIs. -.PP +.P On some ancient systems, .I was not present or did not declare diff --git a/man3/error.3 b/man3/error.3 index 1b12a60..fce50fa 100644 --- a/man3/error.3 +++ b/man3/error.3 @@ -25,7 +25,7 @@ .\" .\" References: .\" glibc manual and source -.TH error 3 2023-07-20 "Linux man-pages 6.05.01" +.TH error 3 2023-10-31 "Linux man-pages 6.7" .SH NAME error, error_at_line, error_message_count, error_one_per_line, error_print_progname \- glibc error reporting functions @@ -35,14 +35,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void error(int " status ", int " errnum ", const char *" format ", ...);" .BI "void error_at_line(int " status ", int " errnum ", const char *" filename , .BI " unsigned int " linenum ", const char *" format ", ...);" -.PP +.P .BI "extern unsigned int " error_message_count ; .BI "extern int " error_one_per_line ; -.PP +.P .BI "extern void (*" error_print_progname ")(void);" .fi .SH DESCRIPTION @@ -63,7 +63,7 @@ should follow .I format in the argument list. The output is terminated by a newline character. -.PP +.P The program name printed by .BR error () is the value of the global variable @@ -74,14 +74,14 @@ initially has the same value as .IR argv[0] . The value of this variable can be modified to change the output of .BR error (). -.PP +.P If \fIstatus\fP has a nonzero value, then .BR error () calls .BR exit (3) to terminate the program using the given value as the exit status; otherwise it returns after printing the error message. -.PP +.P The .BR error_at_line () function is exactly the same as @@ -101,20 +101,20 @@ The preprocessor values \fB__LINE__\fP and .BR error_at_line (), but other values can also be used. For example, these arguments could refer to a location in an input file. -.PP +.P If the global variable \fIerror_one_per_line\fP is set nonzero, a sequence of .BR error_at_line () calls with the same value of \fIfilename\fP and \fIlinenum\fP will result in only one message (the first) being output. -.PP +.P The global variable \fIerror_message_count\fP counts the number of messages that have been output by .BR error () and .BR error_at_line (). -.PP +.P If the global variable \fIerror_print_progname\fP is assigned the address of a function (i.e., is not NULL), then that function is called @@ -144,8 +144,7 @@ T} Thread safety T{ MT-Unsafe\ race: error_at_line/\:error_one_per_line locale T} .TE -.sp 1 -.PP +.P The internal .I error_one_per_line variable is accessed (without any form of synchronization, but since it's an diff --git a/man3/ether_aton.3 b/man3/ether_aton.3 index 973566b..8181dd5 100644 --- a/man3/ether_aton.3 +++ b/man3/ether_aton.3 @@ -9,7 +9,7 @@ .\" .\" Minor additions, aeb, 2013-06-21 .\" -.TH ether_aton 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ether_aton 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line, ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines @@ -19,19 +19,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *ether_ntoa(const struct ether_addr *" addr ); .BI "struct ether_addr *ether_aton(const char *" asc ); -.PP +.P .BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr ); .BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr ); -.PP +.P .BI "int ether_line(const char *" line ", struct ether_addr *" addr , .BI " char *" hostname ); -.PP +.P /* GNU extensions */ .BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf ); -.PP +.P .BI "struct ether_addr *ether_aton_r(const char *" asc , .BI " struct ether_addr *" addr ); .fi @@ -45,7 +45,7 @@ allocated buffer, which subsequent calls will overwrite. .BR ether_aton () returns NULL if the address is invalid. -.PP +.P The .BR ether_ntoa () function converts the Ethernet host address @@ -54,21 +54,21 @@ given in network byte order to a string in standard hex-digits-and-colons notation, omitting leading zeros. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. -.PP +.P The .BR ether_ntohost () function maps an Ethernet address to the corresponding hostname in .I /etc/ethers and returns nonzero if it cannot be found. -.PP +.P The .BR ether_hostton () function maps a hostname to the corresponding Ethernet address in .I /etc/ethers and returns nonzero if it cannot be found. -.PP +.P The .BR ether_line () function parses a line in @@ -80,7 +80,7 @@ The buffer pointed to by .I hostname must be sufficiently long, for example, have the same length as .IR line . -.PP +.P The functions .BR ether_ntoa_r () and @@ -91,13 +91,13 @@ thread-safe versions of and .BR ether_aton () respectively, and do not use static buffers. -.PP +.P The structure .I ether_addr is defined in .I as: -.PP +.P .in +4n .EX struct ether_addr { @@ -129,7 +129,6 @@ T{ .BR ether_aton_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/euidaccess.3 b/man3/euidaccess.3 index a8d1218..c4fcc0e 100644 --- a/man3/euidaccess.3 +++ b/man3/euidaccess.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH euidaccess 3 2023-07-20 "Linux man-pages 6.05.01" +.TH euidaccess 3 2023-10-31 "Linux man-pages 6.7" .SH NAME euidaccess, eaccess \- check effective user's permissions for a file .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int euidaccess(const char *" pathname ", int " mode ); .BI "int eaccess(const char *" pathname ", int " mode ); .fi @@ -28,13 +28,13 @@ However, whereas performs checks using the real user and group identifiers of the process, .BR euidaccess () uses the effective identifiers. -.PP +.P .I mode is a mask consisting of one or more of .BR R_OK ", " W_OK ", " X_OK ", and " F_OK , with the same meanings as for .BR access (2). -.PP +.P .BR eaccess () is a synonym for .BR euidaccess (), @@ -65,7 +65,6 @@ T{ .BR eaccess () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Some other systems have an .\" e.g., FreeBSD 6.1. @@ -84,7 +83,7 @@ performing some operation based on that information leads to race conditions: the file permissions may change between the two steps. Generally, it is safer just to attempt the desired operation and handle any permission error that occurs. -.PP +.P This function always dereferences symbolic links. If you need to check the permissions on a symbolic link, use .BR faccessat (2) diff --git a/man3/exec.3 b/man3/exec.3 index 0f60f57..caf6d6a 100644 --- a/man3/exec.3 +++ b/man3/exec.3 @@ -11,7 +11,7 @@ .\" Modified, 24 Jun 2004, Michael Kerrisk .\" Added note on casting NULL .\" -.TH exec 3 2023-07-20 "Linux man-pages 6.05.01" +.TH exec 3 2023-10-31 "Linux man-pages 6.7" .SH NAME execl, execlp, execle, execv, execvp, execvpe \- execute a file .SH LIBRARY @@ -20,9 +20,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B extern char **environ; -.PP +.P .BI "int execl(const char *" pathname ", const char *" arg ", ..." .B " /*, (char *) NULL */);" .BI "int execlp(const char *" file ", const char *" arg ", ..." @@ -34,12 +34,12 @@ Standard C library .BI "int execvpe(const char *" file ", char *const " argv \ "[], char *const " envp "[]);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR execvpe (): .nf _GNU_SOURCE @@ -54,10 +54,10 @@ The functions described in this manual page are layered on top of (See the manual page for .BR execve (2) for further details about the replacement of the current process image.) -.PP +.P The initial argument for these functions is the name of a file that is to be executed. -.PP +.P The functions can be grouped based on the letters following the "exec" prefix. .\" .SS l - execl(), execlp(), execle() @@ -77,7 +77,7 @@ The list of arguments be terminated by a null pointer, and, since these are variadic functions, this pointer must be cast .IR "(char\ *) NULL" . -.PP +.P By contrast with the 'l' functions, the 'v' functions (below) specify the command-line arguments of the executed program as a vector. .\" @@ -99,7 +99,7 @@ The argument is an array of pointers to null-terminated strings and .I must be terminated by a null pointer. -.PP +.P All other .BR exec () functions (which do not include 'e' in the suffix) @@ -121,20 +121,20 @@ a list that includes the directories returned by (which typically returns the value "/bin:/usr/bin") and possibly also the current working directory; see NOTES for further details. -.PP +.P .BR execvpe () searches for the program using the value of .B PATH from the caller's environment, not from the .I envp argument. -.PP +.P If the specified filename includes a slash character, then .B PATH is ignored, and the file at the specified pathname is executed. -.PP +.P In addition, certain errors are treated specially. -.PP +.P If permission is denied for a file (the attempted .BR execve (2) failed with the error @@ -145,7 +145,7 @@ they will return with .I errno set to .BR EACCES . -.PP +.P If the header of a file isn't recognized (the attempted .BR execve (2) failed with the error @@ -154,7 +154,7 @@ these functions will execute the shell .RI ( /bin/sh ) with the path of the file as its first argument. (If this attempt fails, no further searching is done.) -.PP +.P All other .BR exec () functions (which do not include 'p' in the suffix) @@ -195,7 +195,6 @@ T{ .BR execvpe () T} Thread safety MT-Safe env .TE -.sp 1 .SH VERSIONS The default search path (used when the environment does not contain the variable \fBPATH\fR) @@ -218,7 +217,7 @@ caused the current working directory to be dropped altogether from the default search path. This accidental behavior change is considered mildly beneficial, and won't be reverted. -.PP +.P The behavior of .BR execlp () and @@ -232,7 +231,7 @@ sleep and retry if is encountered. Linux treats it as a hard error and returns immediately. -.PP +.P Traditionally, the functions .BR execlp () and diff --git a/man3/exit.3 b/man3/exit.3 index f51c557..0b8bab2 100644 --- a/man3/exit.3 +++ b/man3/exit.3 @@ -7,7 +7,7 @@ .\" could be listed on this page. See, for example, the list in the .\" POSIX exit(3p) page. .\" -.TH exit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH exit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME exit \- cause normal process termination .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[noreturn]] void exit(int " status ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ function causes normal process termination and the least significant byte of .I status (i.e., \fIstatus & 0xFF\fP) is returned to the parent (see .BR wait (2)). -.PP +.P All functions registered with .BR atexit (3) and @@ -53,14 +53,14 @@ If a function has been registered multiple times using or .BR on_exit (3), then it is called as many times as it was registered. -.PP +.P All open .BR stdio (3) streams are flushed and closed. Files created by .BR tmpfile (3) are removed. -.PP +.P The C standard specifies two constants, \fBEXIT_SUCCESS\fP and \fBEXIT_FAILURE\fP, that may be passed to @@ -85,8 +85,7 @@ T{ .BR exit () T} Thread safety MT-Unsafe race:exit .TE -.sp 1 -.PP +.P The .BR exit () function uses a global variable that is not protected, @@ -110,7 +109,7 @@ removes registrations created using .BR atexit (3) and .BR on_exit (3). -.PP +.P The use of .B EXIT_SUCCESS and @@ -119,12 +118,12 @@ is slightly more portable (to non-UNIX environments) than the use of 0 and some nonzero value like 1 or \-1. In particular, VMS uses a different convention. -.PP +.P BSD has attempted to standardize exit codes (which some C libraries such as the GNU C library have also adopted); see the file .IR . -.PP +.P After .BR exit (), the exit status must be transmitted to the @@ -151,7 +150,7 @@ This allows the parent to subsequently use .BR waitpid (2) (or similar) to learn the termination status of the child; at that point the zombie process slot is released. -.PP +.P If the implementation supports the .B SIGCHLD signal, this signal @@ -171,7 +170,7 @@ is sent a signal, and the terminal is disassociated from this session, allowing it to be acquired by a new controlling process. -.PP +.P If the exit of the process causes a process group to become orphaned, and if any member of the newly orphaned process group is stopped, then a @@ -183,7 +182,7 @@ sent to each process in this process group. See .BR setpgid (2) for an explanation of orphaned process groups. -.PP +.P Except in the above cases, where the signalled processes may be children of the terminating process, termination of a process does diff --git a/man3/exp.3 b/man3/exp.3 index 8736d12..bdfd95b 100644 --- a/man3/exp.3 +++ b/man3/exp.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH exp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH exp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME exp, expf, expl \- base-e exponential function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double exp(double " x ); .BI "float expf(float " x ); .BI "long double expl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR expf (), .BR expl (): .nf @@ -48,26 +48,26 @@ logarithms) raised to the power of .SH RETURN VALUE On success, these functions return the exponential value of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is negative infinity, +0 is returned. -.PP +.P If the result underflows, a range error occurs, and zero is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -81,7 +81,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error, overflow @@ -115,12 +115,11 @@ T{ .BR expl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/exp10.3 b/man3/exp10.3 index 88b0ea6..1d85871 100644 --- a/man3/exp10.3 +++ b/man3/exp10.3 @@ -13,7 +13,7 @@ .\" Modified 1995-08-14 by Arnt Gulbrandsen .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) -.TH exp10 3 2023-07-20 "Linux man-pages 6.05.01" +.TH exp10 3 2023-10-31 "Linux man-pages 6.7" .SH NAME exp10, exp10f, exp10l \- base-10 exponential function .SH LIBRARY @@ -23,7 +23,7 @@ Math library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "double exp10(double " x ); .BI "float exp10f(float " x ); .BI "long double exp10l(long double " x ); @@ -35,7 +35,7 @@ raised to the power of .SH RETURN VALUE On success, these functions return the base-10 exponential value of .IR x . -.PP +.P For various special cases, including the handling of infinity and NaN, as well as overflows and underflows, see .BR exp (3). @@ -44,7 +44,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P For a discussion of the errors that can occur for these functions, see .BR exp (3). .SH ATTRIBUTES @@ -63,7 +63,6 @@ T{ .BR exp10l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY diff --git a/man3/exp2.3 b/man3/exp2.3 index 9b3d99c..1cf5ead 100644 --- a/man3/exp2.3 +++ b/man3/exp2.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH exp2 3 2023-07-20 "Linux man-pages 6.05.01" +.TH exp2 3 2023-10-31 "Linux man-pages 6.7" .SH NAME exp2, exp2f, exp2l \- base-2 exponential function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double exp2(double " x ); .BI "float exp2f(float " x ); .BI "long double exp2l(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR exp2 (), .BR exp2f (), .BR exp2l (): @@ -46,7 +46,7 @@ These functions return the value of 2 raised to the power of .SH RETURN VALUE On success, these functions return the base-2 exponential value of .IR x . -.PP +.P For various special cases, including the handling of infinity and NaN, as well as overflows and underflows, see .BR exp (3). @@ -55,7 +55,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P For a discussion of the errors that can occur for these functions, see .BR exp (3). .SH ATTRIBUTES @@ -74,13 +74,12 @@ T{ .BR exp2l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY glibc 2.1. C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/expm1.3 b/man3/expm1.3 index dd99ac1..32b9767 100644 --- a/man3/expm1.3 +++ b/man3/expm1.3 @@ -8,7 +8,7 @@ .\" Modified 2002-07-27 Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH expm1 3 2023-07-20 "Linux man-pages 6.05.01" +.TH expm1 3 2023-10-31 "Linux man-pages 6.7" .SH NAME expm1, expm1f, expm1l \- exponential minus 1 .SH LIBRARY @@ -17,17 +17,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double expm1(double " x ); .BI "float expm1f(float " x ); .BI "long double expm1l(long double " x ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR expm1 (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR expm1f (), .BR expm1l (): .nf @@ -46,11 +46,11 @@ Feature Test Macro Requirements for glibc (see .fi .SH DESCRIPTION These functions return a value equivalent to -.PP +.P .nf exp(x) \- 1 .fi -.PP +.P The result is computed in a way that is accurate even if the value of .I x is near @@ -61,25 +61,25 @@ subtraction of two numbers that are nearly equal. .SH RETURN VALUE On success, these functions return .IR "exp(x)\ \-\ 1" . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is negative infinity, \-1 is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return .RB \- HUGE_VAL , @@ -92,7 +92,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error, overflow @@ -122,7 +122,6 @@ T{ .BR expm1l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -137,7 +136,7 @@ raised a bogus underflow floating-point exception for some large negative .I x values (where the function result approaches \-1). -.PP +.P Before approximately glibc 2.11, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6814 .\" e.g., expm1(1e5) through expm1(1.00199970127e5), @@ -148,7 +147,7 @@ overflow exception, and returned a NaN instead of positive infinity, for some large positive .I x values. -.PP +.P Before glibc 2.11, .\" It looks like the fix was in glibc 2.11, or possibly glibc 2.12. .\" I have no test system for glibc 2.11, but glibc 2.12 passes. diff --git a/man3/fabs.3 b/man3/fabs.3 index 37097d1..ed1c83d 100644 --- a/man3/fabs.3 +++ b/man3/fabs.3 @@ -10,7 +10,7 @@ .\" Modified Sat Jul 24 19:42:04 1993 by Rik Faith (faith@cs.unc.edu) .\" Added fabsl, fabsf, aeb, 2001-06-07 .\" -.TH fabs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fabs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fabs, fabsf, fabsl \- absolute value of floating-point number .SH LIBRARY @@ -19,17 +19,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double fabs(double " x ); .BI "float fabsf(float " x ); .BI "long double fabsl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fabsf (), .BR fabsl (): .nf @@ -44,15 +44,15 @@ number .SH RETURN VALUE These functions return the absolute value of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is \-0, +0 is returned. -.PP +.P If .I x is negative infinity or positive infinity, positive infinity is returned. @@ -74,12 +74,11 @@ T{ .BR fabsl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/fclose.3 b/man3/fclose.3 index 3694d54..651850a 100644 --- a/man3/fclose.3 +++ b/man3/fclose.3 @@ -14,7 +14,7 @@ .\" .\" Modified 2000-07-22 by Nicolás Lichtmaier .\" -.TH fclose 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fclose 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fclose \- close a stream .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fclose(FILE *" stream ); .fi .SH DESCRIPTION @@ -55,7 +55,7 @@ is not valid. .\" low-level file operations on the same stream. If you do get this error, .\" you must have closed the stream's low-level file descriptor using .\" something like close(fileno(stream)). -.PP +.P The .BR fclose () function may also fail and set @@ -79,7 +79,6 @@ T{ .BR fclose () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fcloseall.3 b/man3/fcloseall.3 index 7fc02c0..d56f4cb 100644 --- a/man3/fcloseall.3 +++ b/man3/fcloseall.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH fcloseall 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fcloseall 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fcloseall \- close all open streams .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .B int fcloseall(void); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ Buffered output for each stream is written before it is closed (as for .BR fflush (3)); buffered input is discarded. -.PP +.P The standard streams, .IR stdin , .IR stdout , @@ -50,8 +50,7 @@ T{ .BR fcloseall () T} Thread safety MT-Unsafe race:streams .TE -.sp 1 -.PP +.P The .BR fcloseall () function does not lock the streams, so it is not thread-safe. diff --git a/man3/fdim.3 b/man3/fdim.3 index 98c3961..37ad621 100644 --- a/man3/fdim.3 +++ b/man3/fdim.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH fdim 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fdim 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fdim, fdimf, fdiml \- positive difference .SH LIBRARY @@ -14,17 +14,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double fdim(double " x ", double " y ); .BI "float fdimf(float " x ", float " y ); .BI "long double fdiml(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fdimf (), .BR fdiml (): .nf @@ -35,13 +35,13 @@ These functions return the positive difference, max(\fIx\fP-\fIy\fP,0), between their arguments. .SH RETURN VALUE On success, these functions return the positive difference. -.PP +.P If .I x or .I y is a NaN, a NaN is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -55,7 +55,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result overflow @@ -81,7 +81,6 @@ T{ .BR fdiml () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fenv.3 b/man3/fenv.3 index 653ba03..6e2bf45 100644 --- a/man3/fenv.3 +++ b/man3/fenv.3 @@ -6,7 +6,7 @@ .\" 2000-08-14 added GNU additions from Andreas Jaeger .\" 2000-12-05 some changes inspired by acahalan's remarks .\" -.TH fenv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fenv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, @@ -18,16 +18,16 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int feclearexcept(int " excepts ); .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts ); .BI "int feraiseexcept(int " excepts ); .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts ); .BI "int fetestexcept(int " excepts ); -.PP +.P .B "int fegetround(void);" .BI "int fesetround(int " rounding_mode ); -.PP +.P .BI "int fegetenv(fenv_t *" envp ); .BI "int feholdexcept(fenv_t *" envp ); .BI "int fesetenv(const fenv_t *" envp ); @@ -41,20 +41,20 @@ The .I divide-by-zero exception occurs when an operation on finite numbers produces infinity as exact answer. -.PP +.P The .I overflow exception occurs when a result has to be represented as a floating-point number, but has (much) larger absolute value than the largest (finite) floating-point number that is representable. -.PP +.P The .I underflow exception occurs when a result has to be represented as a floating-point number, but has smaller absolute value than the smallest positive normalized floating-point number (and would lose much accuracy when represented as a denormalized number). -.PP +.P The .I inexact exception occurs when the rounded result of an operation @@ -64,7 +64,7 @@ It may occur whenever or .I underflow occurs. -.PP +.P The .I invalid exception occurs when there is no well-defined result @@ -75,7 +75,7 @@ Exceptions are represented in two ways: as a single bit implementation-defined way with bit positions in an integer, and also as an opaque structure that may contain more information about the exception (perhaps the code address where it occurred). -.PP +.P Each of the macros .BR FE_DIVBYZERO , .BR FE_INEXACT , @@ -91,12 +91,12 @@ Other exceptions may be supported. The macro .B FE_ALL_EXCEPT is the bitwise OR of all bits corresponding to supported exceptions. -.PP +.P The .BR feclearexcept () function clears the supported exceptions represented by the bits in its argument. -.PP +.P The .BR fegetexceptflag () function stores a representation of the state of the exception flags @@ -104,12 +104,12 @@ represented by the argument .I excepts in the opaque object .IR *flagp . -.PP +.P The .BR feraiseexcept () function raises the supported exceptions represented by the bits in .IR excepts . -.PP +.P The .BR fesetexceptflag () function sets the complete status for the exceptions represented by @@ -120,7 +120,7 @@ This value must have been obtained by an earlier call of .BR fegetexceptflag () with a last argument that contained all bits in .IR excepts . -.PP +.P The .BR fetestexcept () function returns a word in which the bits are set that were @@ -135,7 +135,7 @@ round to nearest (the default), round up (toward positive infinity), round down (toward negative infinity), and round toward zero. -.PP +.P Each of the macros .BR FE_TONEAREST , .BR FE_UPWARD , @@ -144,17 +144,17 @@ and .B FE_TOWARDZERO is defined when the implementation supports getting and setting the corresponding rounding direction. -.PP +.P The .BR fegetround () function returns the macro corresponding to the current rounding mode. -.PP +.P The .BR fesetround () function sets the rounding mode as specified by its argument and returns zero when it was successful. -.PP +.P C99 and POSIX.1-2008 specify an identifier, .BR FLT_ROUNDS , defined in @@ -177,9 +177,9 @@ Rounding is toward positive infinity. .TP .B 3 Rounding is toward negative infinity. -.PP +.P Other values represent machine-dependent, nonstandard rounding modes. -.PP +.P The value of .B FLT_ROUNDS should reflect the current rounding mode as set by @@ -197,19 +197,19 @@ The default environment is denoted by This is the environment setup at program start and it is defined by ISO C to have round to nearest, all exceptions cleared and a nonstop (continue on exceptions) mode. -.PP +.P The .BR fegetenv () function saves the current floating-point environment in the object .IR *envp . -.PP +.P The .BR feholdexcept () function does the same, then clears all exception flags, and sets a nonstop (continue on exceptions) mode, if available. It returns zero when successful. -.PP +.P The .BR fesetenv () function restores the floating-point environment from @@ -222,7 +222,7 @@ or or equal to .BR FE_DFL_ENV . This call does not raise exceptions. -.PP +.P The .BR feupdateenv () function installs the floating-point environment represented by @@ -272,7 +272,6 @@ T} Thread safety T{ MT-Safe T} .TE -.sp 1 .hy .SH STANDARDS C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854. @@ -299,16 +298,16 @@ and to set individual floating-point traps, and .BR fegetexcept () to query the state. -.PP +.P .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B "#include " -.PP +.P .BI "int feenableexcept(int " excepts ); .BI "int fedisableexcept(int " excepts ); .B "int fegetexcept(void);" .fi -.PP +.P The .BR feenableexcept () and diff --git a/man3/ferror.3 b/man3/ferror.3 index 68791f1..3bb3390 100644 --- a/man3/ferror.3 +++ b/man3/ferror.3 @@ -14,7 +14,7 @@ .\" .\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu .\" -.TH ferror 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ferror 3 2023-10-31 "Linux man-pages 6.7" .SH NAME clearerr, feof, ferror \- check and reset stream status .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void clearerr(FILE *" stream ); .BI "int feof(FILE *" stream ); .BI "int ferror(FILE *" stream ); @@ -33,7 +33,7 @@ The function .BR clearerr () clears the end-of-file and error indicators for the stream pointed to by .IR stream . -.PP +.P The function .BR feof () tests the end-of-file indicator for the stream pointed to by @@ -41,7 +41,7 @@ tests the end-of-file indicator for the stream pointed to by returning nonzero if it is set. The end-of-file indicator can be cleared only by the function .BR clearerr (). -.PP +.P The function .BR ferror () tests the error indicator for the stream pointed to by @@ -50,7 +50,7 @@ returning nonzero if it is set. The error indicator can be reset only by the .BR clearerr () function. -.PP +.P For nonlocking counterparts, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -59,7 +59,7 @@ The function returns nonzero if the end-of-file indicator is set for .IR stream ; otherwise, it returns zero. -.PP +.P The .BR ferror () function returns nonzero if the error indicator is set for @@ -84,7 +84,6 @@ T{ .BR ferror () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fexecve.3 b/man3/fexecve.3 index 2ffe5c3..51d3d0f 100644 --- a/man3/fexecve.3 +++ b/man3/fexecve.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH fexecve 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fexecve 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fexecve \- execute program specified via file descriptor .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fexecve(int " fd ", char *const " argv "[], char *const " envp []); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fexecve (): .nf Since glibc 2.10: @@ -92,12 +92,11 @@ T{ .BR fexecve () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.3.2. -.PP +.P On Linux with glibc versions 2.26 and earlier, .BR fexecve () is implemented using the @@ -131,7 +130,7 @@ of a file could be changed between the checksumming and the call to .BR fexecve (); for that, the solution is to ensure that the permissions on the file prevent it from being modified by malicious users. -.PP +.P The natural idiom when using .BR fexecve () is to set the close-on-exec flag on diff --git a/man3/fflush.3 b/man3/fflush.3 index a26c3e8..25aa47c 100644 --- a/man3/fflush.3 +++ b/man3/fflush.3 @@ -15,7 +15,7 @@ .\" Modified 2000-07-22 by Nicolás Lichtmaier .\" Modified 2001-10-16 by John Levon .\" -.TH fflush 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fflush 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fflush \- flush a stream .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fflush(FILE *_Nullable " stream ); .fi .SH DESCRIPTION @@ -33,15 +33,15 @@ For output streams, forces a write of all user-space buffered data for the given output or update .I stream via the stream's underlying write function. -.PP +.P For input streams associated with seekable files (e.g., disk files, but not pipes or terminals), .BR fflush () discards any buffered data that has been fetched from the underlying file, but has not been consumed by the application. -.PP +.P The open status of the stream is unaffected. -.PP +.P If the .I stream argument is NULL, @@ -51,7 +51,7 @@ flushes open output streams. .\" mtk: POSIX specifies that only output streams are flushed for this case. .\" Also verified for glibc by experiment. -.PP +.P For a nonlocking counterpart, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -66,7 +66,7 @@ is set to indicate the error. .B EBADF .I stream is not an open stream, or is not open for writing. -.PP +.P The function .BR fflush () may also fail and set @@ -87,12 +87,11 @@ T{ .BR fflush () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001, POSIX.1-2008. -.PP +.P POSIX.1-2001 did not specify the behavior for flushing of input streams, but the behavior is specified in POSIX.1-2008. .SH NOTES diff --git a/man3/ffs.3 b/man3/ffs.3 index b092438..00c8aad 100644 --- a/man3/ffs.3 +++ b/man3/ffs.3 @@ -11,7 +11,7 @@ .\" .\" Modified 2003 Walter Harms (walter.harms@informatik.uni-oldenburg.de) .\" -.TH ffs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ffs 3 2023-11-19 "Linux man-pages 6.7" .SH NAME ffs, ffsl, ffsll \- find first bit set in a word .SH LIBRARY @@ -20,20 +20,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int ffs(int " i ); -.PP -.B #include -.PP .BI "int ffsl(long " i ); .BI "int ffsll(long long " i ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ffs (): .nf Since glibc 2.12: @@ -44,7 +41,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.12: none .fi -.PP +.P .BR ffsl (), .BR ffsll (): .nf @@ -87,10 +84,6 @@ T{ .BR ffsll () T} Thread safety MT-Safe .TE -.sp 1 -.SH VERSIONS -BSD systems have a prototype in -.IR . .SH STANDARDS .TP .BR ffs () diff --git a/man3/fgetc.3 b/man3/fgetc.3 index 1b13d61..1f820f8 100644 --- a/man3/fgetc.3 +++ b/man3/fgetc.3 @@ -5,7 +5,7 @@ .\" .\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) -.TH fgetc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fgetc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fgetc, fgets, getc, getchar, ungetc \- input of characters and strings .SH LIBRARY @@ -14,14 +14,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fgetc(FILE *" stream ); .BI "int getc(FILE *" stream ); .B "int getchar(void);" -.PP +.P .BI "char *fgets(char " s "[restrict ." size "], int " size ", \ FILE *restrict " stream ); -.PP +.P .BI "int ungetc(int " c ", FILE *" stream ); .fi .SH DESCRIPTION @@ -35,18 +35,18 @@ cast to an or .B EOF on end of file or error. -.PP +.P .BR getc () is equivalent to .BR fgetc () except that it may be implemented as a macro which evaluates .I stream more than once. -.PP +.P .BR getchar () is equivalent to .BI "getc(" stdin ) \fR. -.PP +.P .BR fgets () reads in at most one less than .I size @@ -60,7 +60,7 @@ or a newline. If a newline is read, it is stored into the buffer. A terminating null byte (\[aq]\e0\[aq]) is stored after the last character in the buffer. -.PP +.P .BR ungetc () pushes .I c @@ -71,12 +71,12 @@ cast to where it is available for subsequent read operations. Pushed-back characters will be returned in reverse order; only one pushback is guaranteed. -.PP +.P Calls to the functions described here can be mixed with each other and with calls to other input functions from the .I stdio library for the same input stream. -.PP +.P For nonlocking counterparts, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -91,13 +91,13 @@ cast to an or .B EOF on end of file or error. -.PP +.P .BR fgets () returns .I s on success, and NULL on error or when end of file occurs while no characters have been read. -.PP +.P .BR ungetc () returns .I c @@ -122,7 +122,6 @@ T{ .BR ungetc () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fgetgrent.3 b/man3/fgetgrent.3 index 71926a1..cba26b2 100644 --- a/man3/fgetgrent.3 +++ b/man3/fgetgrent.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:38:44 1993 by Rik Faith (faith@cs.unc.edu) -.TH fgetgrent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fgetgrent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fgetgrent \- get group file entry .SH LIBRARY @@ -19,15 +19,15 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "struct group *fgetgrent(FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fgetgrent (): .nf Since glibc 2.19: @@ -49,9 +49,9 @@ must have the same format as .I /etc/group (see .BR group (5)). -.PP +.P The \fIgroup\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct group { @@ -93,7 +93,6 @@ T{ .BR fgetgrent () T} Thread safety MT-Unsafe race:fgetgrent .TE -.sp 1 .\" FIXME The marking is different from that in the glibc manual, .\" which has: .\" diff --git a/man3/fgetpwent.3 b/man3/fgetpwent.3 index 676fe26..b27f616 100644 --- a/man3/fgetpwent.3 +++ b/man3/fgetpwent.3 @@ -11,7 +11,7 @@ .\" Modified Sat Jul 24 19:37:37 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Mon May 27 22:40:48 1996 by Martin Schulze (joey@linux.de) .\" -.TH fgetpwent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fgetpwent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fgetpwent \- get password file entry .SH LIBRARY @@ -22,15 +22,15 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "struct passwd *fgetpwent(FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fgetpwent (): .nf Since glibc 2.19: @@ -51,9 +51,9 @@ must have the same format as .I /etc/passwd (see .BR passwd (5)). -.PP +.P The \fIpasswd\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct passwd { @@ -101,7 +101,6 @@ T{ .BR fgetpwent () T} Thread safety MT-Unsafe race:fgetpwent .TE -.sp 1 .\" FIXME: The marking is different from that in the glibc manual, .\" which has: .\" diff --git a/man3/fgetwc.3 b/man3/fgetwc.3 index b66b018..2873754 100644 --- a/man3/fgetwc.3 +++ b/man3/fgetwc.3 @@ -11,7 +11,7 @@ .\" ISO/IEC 9899:1999 .\" .\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon -.TH fgetwc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fgetwc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fgetwc, getwc \- read a wide character from a FILE stream .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "wint_t fgetwc(FILE *" stream ); .BI "wint_t getwc(FILE *" stream ); .fi @@ -39,7 +39,7 @@ it returns If a wide-character conversion error occurs, it sets \fIerrno\fP to \fBEILSEQ\fP and returns .BR WEOF . -.PP +.P The .BR getwc () function or macro functions identically to @@ -47,7 +47,7 @@ function or macro functions identically to It may be implemented as a macro, and may evaluate its argument more than once. There is no reason ever to use it. -.PP +.P For nonlocking counterparts, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -80,7 +80,6 @@ T{ .BR getwc () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -92,7 +91,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P In the absence of additional information passed to the .BR fopen (3) call, it is diff --git a/man3/fgetws.3 b/man3/fgetws.3 index fa2a208..a9fdfca 100644 --- a/man3/fgetws.3 +++ b/man3/fgetws.3 @@ -11,7 +11,7 @@ .\" ISO/IEC 9899:1999 .\" .\" Modified Tue Oct 16 23:18:40 BST 2001 by John Levon -.TH fgetws 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fgetws 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fgetws \- read a wide-character string from a FILE stream .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *fgetws(wchar_t " ws "[restrict ." n "], int " n \ ", FILE *restrict " stream ); .fi @@ -37,10 +37,10 @@ and adds a terminating null wide character (L\[aq]\e0\[aq]). It stops reading wide characters after it has encountered and stored a newline wide character. It also stops when end of stream is reached. -.PP +.P The programmer must ensure that there is room for at least \fIn\fP wide characters at \fIws\fP. -.PP +.P For a nonlocking counterpart, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -63,7 +63,6 @@ T{ .BR fgetws () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -75,7 +74,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P In the absence of additional information passed to the .BR fopen (3) call, it is @@ -83,7 +82,7 @@ reasonable to expect that .BR fgetws () will actually read a multibyte string from the stream and then convert it to a wide-character string. -.PP +.P This function is unreliable, because it does not permit to deal properly with null wide characters that may be present in the input. diff --git a/man3/fileno.3 b/man3/fileno.3 index 642948b..5c5a717 100644 --- a/man3/fileno.3 +++ b/man3/fileno.3 @@ -12,7 +12,7 @@ .\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu .\" Added remark on EBADF for fileno, aeb, 2001-03-22 .\" -.TH fileno 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fileno 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fileno \- obtain file descriptor of a stdio stream .SH LIBRARY @@ -21,15 +21,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fileno(FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fileno (): .nf _POSIX_C_SOURCE @@ -48,7 +48,7 @@ is called. Duplicate the file descriptor with .BR dup (2) before passing it to code that might close it. -.PP +.P For the nonlocking counterpart, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -78,7 +78,6 @@ T{ .BR fileno () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/finite.3 b/man3/finite.3 index 11a1581..bad355f 100644 --- a/man3/finite.3 +++ b/man3/finite.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH finite 3 2023-07-20 "Linux man-pages 6.05.01" +.TH finite 3 2023-10-31 "Linux man-pages 6.7" .SH NAME finite, finitef, finitel, isinf, isinff, isinfl, isnan, isnanf, isnanl \- BSD floating-point classification functions @@ -13,52 +13,52 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int finite(double " x ); .BI "int finitef(float " x ); .BI "int finitel(long double " x ); -.PP +.P .BI "int isinf(double " x ); .BI "int isinff(float " x ); .BI "int isinfl(long double " x ); -.PP +.P .BI "int isnan(double " x ); .BI "int isnanf(float " x ); .BI "int isnanl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR finite (), .BR finitef (), .BR finitel (): .nf /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE -.PP +.P .BR isinf (): _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE || /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR isinff (), .BR isinfl (): .nf /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR isnan (): .nf _XOPEN_SOURCE || _ISOC99_SOURCE || /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR isnanf (), .BR isnanl (): .nf @@ -76,7 +76,7 @@ functions return a nonzero value if .I x is neither infinite nor a "not-a-number" (NaN) value, and 0 otherwise. -.PP +.P The .BR isnan (), .BR isnanf (), @@ -86,7 +86,7 @@ functions return a nonzero value if .I x is a NaN value, and 0 otherwise. -.PP +.P The .BR isinf (), .BR isinff (), @@ -119,7 +119,6 @@ T{ .BR isnanl () T} Thread safety MT-Safe .TE -.sp 1 .SH NOTES Note that these functions are obsolete. C99 defines macros diff --git a/man3/flockfile.3 b/man3/flockfile.3 index c2a18a4..911f8de 100644 --- a/man3/flockfile.3 +++ b/man3/flockfile.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH flockfile 3 2023-07-20 "Linux man-pages 6.05.01" +.TH flockfile 3 2023-10-31 "Linux man-pages 6.7" .SH NAME flockfile, ftrylockfile, funlockfile \- lock FILE for stdio .SH LIBRARY @@ -12,17 +12,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void flockfile(FILE *" filehandle ); .BI "int ftrylockfile(FILE *" filehandle ); .BI "void funlockfile(FILE *" filehandle ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .nf /* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L @@ -41,13 +41,13 @@ For each library call, these functions wait until the object is no longer locked by a different thread, then lock it, do the requested I/O, and unlock the object again. -.PP +.P (Note: this locking has nothing to do with the file locking done by functions like .BR flock (2) and .BR lockf (3).) -.PP +.P All this is invisible to the C-programmer, but there may be two reasons to wish for more detailed control. On the one hand, maybe @@ -55,7 +55,7 @@ a series of I/O actions by one thread belongs together, and should not be interrupted by the I/O of some other thread. On the other hand, maybe the locking overhead should be avoided for greater efficiency. -.PP +.P To this end, a thread can explicitly lock the .I FILE object, @@ -72,7 +72,7 @@ instead of .BR getc (3) and .BR putc (3). -.PP +.P The .BR flockfile () function waits for @@ -83,11 +83,11 @@ current thread owner of .IR *filehandle , and increments the lockcount. -.PP +.P The .BR funlockfile () function decrements the lock count. -.PP +.P The .BR ftrylockfile () function is a nonblocking version @@ -121,12 +121,11 @@ T{ .BR funlockfile () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P These functions are available when .B _POSIX_THREAD_SAFE_FUNCTIONS is defined. diff --git a/man3/floor.3 b/man3/floor.3 index 6040607..0f2731c 100644 --- a/man3/floor.3 +++ b/man3/floor.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH floor 3 2023-07-20 "Linux man-pages 6.05.01" +.TH floor 3 2023-10-31 "Linux man-pages 6.7" .SH NAME floor, floorf, floorl \- largest integral value not greater than argument .SH LIBRARY @@ -14,17 +14,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double floor(double " x ); .BI "float floorf(float " x ); .BI "long double floorl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR floorf (), .BR floorl (): .nf @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION These functions return the largest integral value that is not greater than .IR x . -.PP +.P For example, .I floor(0.5) is 0.0, and @@ -44,7 +44,7 @@ is \-1.0. .SH RETURN VALUE These functions return the floor of .IR x . -.PP +.P If .I x is integral, +0, \-0, NaN, or an infinity, @@ -69,17 +69,16 @@ T{ .BR floorl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to SVr4, 4.3BSD, C89. -.PP +.P SUSv2 and POSIX.1-2001 contain text about overflow (which might set .I errno to diff --git a/man3/fma.3 b/man3/fma.3 index e9a3313..a93042b 100644 --- a/man3/fma.3 +++ b/man3/fma.3 @@ -8,7 +8,7 @@ .\" Modified 2004-11-15, Added further text on FLT_ROUNDS .\" as suggested by AEB and Fabian Kreutz .\" -.TH fma 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fma 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fma, fmaf, fmal \- floating-point multiply and add .SH LIBRARY @@ -17,17 +17,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double fma(double " x ", double " y ", double " z ); .BI "float fmaf(float " x ", float " y ", float " z ); .BI "long double fmal(long double " x ", long double " y ", long double " z ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fma (), .BR fmaf (), .BR fmal (): @@ -44,13 +44,13 @@ current rounding mode (see These functions return the value of .IR x " * " y " + " z , rounded as one ternary operation. -.PP +.P If .I x or .I y is a NaN, a NaN is returned. -.PP +.P If .I x times @@ -60,7 +60,7 @@ is an exact infinity, and is an infinity with the opposite sign, a domain error occurs, and a NaN is returned. -.PP +.P .\" POSIX.1-2008 allows some possible differences for the following two .\" domain error cases, but on Linux they are treated the same (AFAICS). .\" Nevertheless, we'll mirror POSIX.1 and describe the two cases @@ -76,7 +76,7 @@ a domain error occurs, and a NaN is returned. .\" POSIX.1 says that a NaN or an implementation-defined value shall .\" be returned for this case. -.PP +.P If one of .I x or @@ -87,7 +87,7 @@ is a NaN, .\" POSIX.1 makes the domain error optional for this case. a domain error occurs, and a NaN is returned. -.PP +.P If .I x times @@ -96,11 +96,11 @@ is not an infinity times zero (or vice versa), and .I z is a NaN, a NaN is returned. -.PP +.P If the result overflows, a range error occurs, and an infinity with the correct sign is returned. -.PP +.P If the result underflows, a range error occurs, and a signed 0 is returned. @@ -109,7 +109,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP * \fIy\fP + \fIz\fP, \ @@ -136,7 +136,7 @@ Range error: result underflow An underflow floating-point exception .RB ( FE_UNDERFLOW ) is raised. -.PP +.P These functions do not set .IR errno . .\" FIXME . Is it intentional that these functions do not set errno? @@ -157,7 +157,6 @@ T{ .BR fmal () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fmax.3 b/man3/fmax.3 index 1133432..8f502dd 100644 --- a/man3/fmax.3 +++ b/man3/fmax.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH fmax 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fmax 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fmax, fmaxf, fmaxl \- determine maximum of two floating-point numbers .SH LIBRARY @@ -14,17 +14,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double fmax(double " x ", double " y ); .BI "float fmaxf(float " x ", float " y ); .BI "long double fmaxl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fmax (), .BR fmaxf (), .BR fmaxl (): @@ -41,9 +41,9 @@ These functions return the maximum of .I x and .IR y . -.PP +.P If one argument is a NaN, the other argument is returned. -.PP +.P If both arguments are NaN, a NaN is returned. .SH ERRORS No errors occur. @@ -63,7 +63,6 @@ T{ .BR fmaxl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fmemopen.3 b/man3/fmemopen.3 index 081a33f..93f3a12 100644 --- a/man3/fmemopen.3 +++ b/man3/fmemopen.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH fmemopen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fmemopen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fmemopen \- open memory as stream .SH LIBRARY @@ -12,16 +12,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "FILE *fmemopen(void " buf [. size "], size_t " size ", \ const char *" mode ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fmemopen (): .nf Since glibc 2.10: @@ -37,7 +37,7 @@ function opens a stream that permits the access specified by The stream allows I/O to be performed on the string or memory buffer pointed to by .IR buf . -.PP +.P The .I mode argument specifies the semantics of I/O on the stream, @@ -64,7 +64,7 @@ The buffer contents are truncated .I a+ Append; open the stream for reading and writing, with the initial buffer position set to the first null byte. -.PP +.P The stream maintains the notion of a current position, the location where the next I/O operation will be performed. The current position is implicitly updated by I/O operations. @@ -77,7 +77,7 @@ the initial position is set to the start of the buffer. In append mode, if no null byte is found within the buffer, then the initial position is .IR size+1 . -.PP +.P If .I buf is specified as NULL, then @@ -92,13 +92,13 @@ The buffer is automatically freed when the stream is closed. Note that the caller has no way to obtain a pointer to the temporary buffer allocated by this call (but see .BR open_memstream (3)). -.PP +.P If .I buf is not NULL, then it should point to a buffer of at least .I size bytes allocated by the caller. -.PP +.P When a stream that has been opened for writing is flushed .RB ( fflush (3)) or closed @@ -110,7 +110,7 @@ buffer .I size counts that byte) to allow for this. -.PP +.P In a stream opened for reading, null bytes (\[aq]\e0\[aq]) in the buffer do not cause read operations to return an end-of-file indication. @@ -118,11 +118,11 @@ A read from the buffer will indicate end-of-file only when the current buffer position advances .I size bytes past the start of the buffer. -.PP +.P Write operations take place either at the current position (for modes other than append), or at the current size of the stream (for append modes). -.PP +.P Attempts to write more than .I size bytes to the buffer result in an error. @@ -132,7 +132,7 @@ By default, such errors will be visible buffer is flushed. Disabling buffering with the following call may be useful to detect errors at the time of an output operation: -.PP +.P .in +4n .EX setbuf(stream, NULL); @@ -161,13 +161,12 @@ T{ .BR fmemopen (), T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 1.0.x. POSIX.1-2008. -.PP +.P POSIX.1-2008 specifies that \[aq]b\[aq] in .I mode shall be ignored. @@ -175,7 +174,7 @@ However, Technical Corrigendum 1 .\" http://austingroupbugs.net/view.php?id=396 adjusts the standard to allow implementation-specific treatment for this case, thus permitting the glibc treatment of \[aq]b\[aq]. -.PP +.P With glibc 2.22, binary mode (see below) was removed, many longstanding bugs in the implementation of .BR fmemopen () @@ -194,7 +193,7 @@ writes don't implicitly add a terminating null byte, and is relative to the end of the buffer (i.e., the value specified by the .I size argument), rather than the current string length. -.PP +.P An API bug afflicted the implementation of binary mode: to specify binary mode, the \[aq]b\[aq] must be the .I second @@ -206,7 +205,7 @@ This is inconsistent with the treatment of .I mode by .BR fopen (3). -.PP +.P Binary mode was removed in glibc 2.22; a \[aq]b\[aq] specified in .I mode has no effect. @@ -227,7 +226,7 @@ fails with the error It would be more consistent if this case successfully created a stream that then returned end-of-file on the first attempt at reading; since glibc 2.22, the glibc implementation provides that behavior. -.PP +.P Before glibc 2.22, specifying append mode ("a" or "a+") for .BR fmemopen () @@ -237,7 +236,7 @@ sets the initial buffer position to the first null byte, but the end of the stream) does not force subsequent writes to append at the end of the stream. This bug is fixed in glibc 2.22. -.PP +.P Before glibc 2.22, if the .I mode argument to @@ -254,7 +253,7 @@ However, in this case the glibc .BR fmemopen () sets the buffer position to \-1. This bug is fixed in glibc 2.22. -.PP +.P Before glibc 2.22, .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292 when a call to @@ -271,7 +270,7 @@ was .I subtracted from the end-of-stream position, instead of being added. This bug is fixed in glibc 2.22. -.PP +.P The glibc 2.9 addition of "binary" mode for .BR fmemopen () .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544 @@ -289,7 +288,7 @@ The program scans its input string (taken from the program's first command-line argument) reading integers, and writes the squares of these integers to the output buffer. An example of the output produced by this program is the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out \[aq]1 23 43\[aq]" diff --git a/man3/fmin.3 b/man3/fmin.3 index c6fbb9d..c601195 100644 --- a/man3/fmin.3 +++ b/man3/fmin.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH fmin 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fmin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fmin, fminf, fminl \- determine minimum of two floating-point numbers .SH LIBRARY @@ -14,17 +14,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double fmin(double " x ", double " y ); .BI "float fminf(float " x ", float " y ); .BI "long double fminl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fmin (), .BR fminf (), .BR fminl (): @@ -41,9 +41,9 @@ These functions return the minimum of .I x and .IR y . -.PP +.P If one argument is a NaN, the other argument is returned. -.PP +.P If both arguments are NaN, a NaN is returned. .SH ERRORS No errors occur. @@ -63,7 +63,6 @@ T{ .BR fminl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fmod.3 b/man3/fmod.3 index e524514..dfca42e 100644 --- a/man3/fmod.3 +++ b/man3/fmod.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH fmod 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fmod 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fmod, fmodf, fmodl \- floating-point remainder function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double fmod(double " x ", double " y ); .BI "float fmodf(float " x ", float " y ); .BI "long double fmodl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fmodf (), .BR fmodl (): .nf @@ -58,6 +58,23 @@ is the quotient of / .IR y , rounded toward zero to an integer. +.P +To obtain the modulus, more specifically, the Least Positive Residue, +you will need to adjust the result from fmod like so: +.P +.in +4n +.nf +z = fmod(x, y); +if (z < 0) + z += y; +.fi +.in +.P +An alternate way to express this is with +.IR "fmod(fmod(x, y) + y, y)" , +but the second +.BR fmod () +usually costs way more than the one branch. .SH RETURN VALUE On success, these functions return the value \fIx\fP\ \-\ \fIn\fP*\fIy\fP, @@ -67,25 +84,25 @@ such that the returned value has the same sign as .I x and a magnitude less than the magnitude of .IR y . -.PP +.P If .I x or .I y is a NaN, a NaN is returned. -.PP +.P If .I x is an infinity, a domain error occurs, and a NaN is returned. -.PP +.P If .I y is zero, a domain error occurs, and a NaN is returned. -.PP +.P If .I x is +0 (\-0), and @@ -96,7 +113,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity @@ -133,12 +150,11 @@ T{ .BR fmodl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to @@ -151,5 +167,17 @@ to .B EDOM when a domain error occurred for an infinite .IR x . +.SH EXAMPLES +The call +.I fmod(372, 360) +returns 348. +.P +The call +.I fmod(-372, 360) +returns -12. +.P +The call +.I fmod(-372, -360) +also returns -12. .SH SEE ALSO .BR remainder (3) diff --git a/man3/fmtmsg.3 b/man3/fmtmsg.3 index 1ed9824..ca21108 100644 --- a/man3/fmtmsg.3 +++ b/man3/fmtmsg.3 @@ -9,7 +9,7 @@ .\" The function is quite complex and deserves an example .\" .\" Polished, aeb, 2003-11-01 -.TH fmtmsg 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fmtmsg 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fmtmsg \- print formatted error messages .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fmtmsg(long " classification ", const char *" label , .BI " int " severity ", const char *" text , .BI " const char *" action ", const char *" tag ); @@ -33,23 +33,23 @@ For messages written to the format depends on the .B MSGVERB environment variable. -.PP +.P The .I label argument identifies the source of the message. The string must consist of two colon separated parts where the first part has not more than 10 and the second part not more than 14 characters. -.PP +.P The .I text argument describes the condition of the error. -.PP +.P The .I action argument describes possible steps to recover from the error. If it is printed, it is prefixed by "TO FIX: ". -.PP +.P The .I tag argument is a reference to the online documentation where more @@ -80,7 +80,7 @@ is a synonym for The .I classification argument is the sum of values describing 4 types of information. -.PP +.P The first value defines the output channel. .TP 12n .B MM_PRINT @@ -92,7 +92,7 @@ Output to the system console. .TP .B "MM_PRINT | MM_CONSOLE" Output to both. -.PP +.P The second value is the source of the error: .TP 12n .B MM_HARD @@ -103,7 +103,7 @@ A firmware error occurred. .TP .B MM_SOFT A software error occurred. -.PP +.P The third value encodes the detector of the problem: .TP 12n .B MM_APPL @@ -114,7 +114,7 @@ It is detected by a utility. .TP .B MM_OPSYS It is detected by the operating system. -.PP +.P The fourth value shows the severity of the incident: .TP 12n .B MM_RECOVER @@ -141,7 +141,7 @@ This value is printed as WARNING. .TP .B MM_INFO This value is printed as INFO. -.PP +.P The numeric values are between 0 and 4. Using .BR addseverity (3) @@ -174,7 +174,7 @@ When this variable is defined, is non-NULL, and is a colon-separated list of valid keywords, then only the parts of the message corresponding to these keywords is printed. Valid keywords are "label", "severity", "text", "action", and "tag". -.PP +.P The environment variable .B SEV_LEVEL can be used to introduce new severity levels. @@ -186,25 +186,25 @@ print nothing. If the user puts .B SEV_LEVEL with a format like -.PP +.P .RS SEV_LEVEL=[description[:description[:...]]] .RE -.PP +.P in the environment of the process before the first call to .BR fmtmsg (), where each description is of the form -.PP +.P .RS severity-keyword,level,printstring .RE -.PP +.P then .BR fmtmsg () will also accept the indicated values for the level (in addition to the standard levels 0\[en]4), and use the indicated printstring when such a level occurs. -.PP +.P The severity-keyword part is not used by .BR fmtmsg () but it has to be present. @@ -237,13 +237,12 @@ glibc\ >=\ 2.16: MT-Safe; glibc\ <\ 2.16: MT-Unsafe T} .TE -.sp 1 -.PP +.P Before glibc 2.16, the .BR fmtmsg () function uses a static variable that is not protected, so it is not thread-safe. -.PP +.P Since glibc 2.16, .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94 the @@ -268,7 +267,7 @@ POSIX.1-2001 and POSIX.1-2008. .TP .B SEV_LEVEL System V. -.PP +.P System V and UnixWare man pages tell us that these functions have been replaced by "pfmt() and addsev()" or by "pfmt(), vpfmt(), lfmt(), and vlfmt()", and will be removed later. @@ -307,26 +306,26 @@ main(void) } .EE .\" SRC END -.PP +.P The output should be: -.PP +.P .in +4n .EX util\-linux:mount: ERROR: unknown mount option TO FIX: See mount(8). util\-linux:mount:017 .EE .in -.PP +.P and after -.PP +.P .in +4n .EX MSGVERB=text:action; export MSGVERB .EE .in -.PP +.P the output becomes: -.PP +.P .in +4n .EX unknown mount option diff --git a/man3/fnmatch.3 b/man3/fnmatch.3 index 3de8117..c834ac9 100644 --- a/man3/fnmatch.3 +++ b/man3/fnmatch.3 @@ -6,7 +6,7 @@ .\" Modified Sat Jul 24 19:35:54 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Mon Oct 16 00:16:29 2000 following Joseph S. Myers .\" -.TH fnmatch 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fnmatch 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fnmatch \- match filename or pathname .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fnmatch(const char *" "pattern" ", const char *" string ", int " flags ); .fi .SH DESCRIPTION @@ -27,7 +27,7 @@ argument matches the .I pattern argument, which is a shell wildcard pattern (see .BR glob (7)). -.PP +.P The .I flags argument modifies the behavior; it is the bitwise OR of zero or more @@ -118,7 +118,6 @@ T{ .BR fnmatch () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS .TP .BR fnmatch () diff --git a/man3/fopen.3 b/man3/fopen.3 index e96303c..654c697 100644 --- a/man3/fopen.3 +++ b/man3/fopen.3 @@ -14,7 +14,7 @@ .\" Modified, aeb, 960421, 970806 .\" Modified, joey, aeb, 2002-01-03 .\" -.TH fopen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fopen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fopen, fdopen, freopen \- stream open functions .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "FILE *fopen(const char *restrict " pathname \ ", const char *restrict " mode ); .BI "FILE *fdopen(int " fd ", const char *" mode ); @@ -31,12 +31,12 @@ Standard C library ", const char *restrict " mode , .BI " FILE *restrict " stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fdopen (): .nf _POSIX_C_SOURCE @@ -47,7 +47,7 @@ The function opens the file whose name is the string pointed to by .I pathname and associates a stream with it. -.PP +.P The argument .I mode points to a string beginning with one of the following sequences @@ -84,7 +84,7 @@ POSIX is silent on what the initial read position is when using this mode. For glibc, the initial file position for reading is at the beginning of the file, but for Android/BSD/MacOS, the initial file position for reading is at the end of the file. -.PP +.P The .I mode string can also include the letter \[aq]b\[aq] either as a last character or as @@ -97,15 +97,15 @@ conforming systems, including Linux. and adding the \[aq]b\[aq] may be a good idea if you do I/O to a binary file and expect that your program may be ported to non-UNIX environments.) -.PP +.P See NOTES below for details of glibc extensions for .IR mode . -.PP +.P Any created file will have the mode .BR S_IRUSR " | " S_IWUSR " | " S_IRGRP " | " S_IWGRP " | " S_IROTH " | " S_IWOTH (0666), as modified by the process's umask value (see .BR umask (2)). -.PP +.P Reads and writes may be intermixed on read/write streams in any order. Note that ANSI C requires that a file positioning function intervene between output and input, unless an input operation encounters end-of-file. @@ -120,18 +120,18 @@ operation between write and read operations on such a stream. This operation may be an apparent no-op (as in \fIfseek(..., 0L, SEEK_CUR)\fP called for its synchronizing side effect). -.PP +.P Opening a file in append mode (\fBa\fP as the first character of .IR mode ) causes all subsequent write operations to this stream to occur at end-of-file, as if preceded by the call: -.PP +.P .in +4n .EX fseek(stream, 0, SEEK_END); .EE .in -.PP +.P The file descriptor associated with the stream is opened as if by a call to .BR open (2) with the following flags: @@ -186,7 +186,7 @@ The argument is used just as in the .BR fopen () function. -.PP +.P If the .I pathname argument is a null pointer, @@ -197,7 +197,7 @@ that is, .BR freopen () reopens the pathname that is associated with the stream. The specification for this behavior was added in the C99 standard, which says: -.PP +.P .RS In this case, the file descriptor associated with the stream need not be closed @@ -207,7 +207,7 @@ succeeds. It is implementation-defined which changes of mode are permitted (if any), and under what circumstances. .RE -.PP +.P The primary use of the .BR freopen () function is to change the file associated with a standard text stream @@ -235,7 +235,7 @@ provided to or .BR freopen () was invalid. -.PP +.P The .BR fopen (), .BR fdopen (), @@ -245,21 +245,21 @@ functions may also fail and set .I errno for any of the errors specified for the routine .BR malloc (3). -.PP +.P The .BR fopen () function may also fail and set .I errno for any of the errors specified for the routine .BR open (2). -.PP +.P The .BR fdopen () function may also fail and set .I errno for any of the errors specified for the routine .BR fcntl (2). -.PP +.P The .BR freopen () function may also fail and set @@ -285,7 +285,6 @@ T{ .BR freopen () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR fopen () @@ -354,7 +353,7 @@ to .BR EEXIST . This flag is ignored for .BR fdopen (). -.PP +.P In addition to the above characters, .BR fopen () and @@ -362,9 +361,9 @@ and support the following syntax in .IR mode : -.PP +.P .BI " ,ccs=" string -.PP +.P The given .I string is taken as the name of a coded character set and diff --git a/man3/fopencookie.3 b/man3/fopencookie.3 index 61f77bc..5d5d1d3 100644 --- a/man3/fopencookie.3 +++ b/man3/fopencookie.3 @@ -4,9 +4,9 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH fopencookie 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fopencookie 3 2023-12-29 "Linux man-pages 6.7" .SH NAME -fopencookie \- opening a custom stream +fopencookie \- open a custom stream .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) @@ -15,7 +15,7 @@ Standard C library .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #define _FILE_OFFSET_BITS 64 .B #include -.PP +.P .BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict " mode , .BI " cookie_io_functions_t " io_funcs ); .fi @@ -31,7 +31,7 @@ is used to implement .BR fmemopen (3), which provides a stream interface to data that is stored in a buffer in memory. -.PP +.P In order to create a custom stream the programmer must: .IP \[bu] 3 Implement four "hook" functions that are used internally by the @@ -52,7 +52,7 @@ Call .BR fopencookie () to open a new stream and associate the cookie and hook functions with that stream. -.PP +.P The .BR fopencookie () function serves a purpose similar to @@ -60,14 +60,14 @@ function serves a purpose similar to it opens a new stream and returns a pointer to a .I FILE object that is used to operate on that stream. -.PP +.P The .I cookie argument is a pointer to the caller's cookie structure that is to be associated with the new stream. This pointer is supplied as the first argument when the standard I/O library invokes any of the hook functions described below. -.PP +.P The .I mode argument serves the same purpose as for @@ -83,13 +83,13 @@ and See .BR fopen (3) for details. -.PP +.P The .I io_funcs argument is a structure that contains four fields pointing to the programmer-defined hook functions that are used to implement this stream. The structure is defined as follows -.PP +.P .in +4n .EX typedef struct { @@ -100,7 +100,7 @@ typedef struct { } cookie_io_functions_t; .EE .in -.PP +.P The four fields are as follows: .TP .I cookie_read_function_t *read @@ -257,7 +257,6 @@ T{ .BR fopencookie () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH EXAMPLES @@ -269,7 +268,7 @@ The program writes its command-line arguments to the stream, and then seeks through the stream reading two out of every five characters and writing them to standard output. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out \[aq]hello world\[aq]" @@ -279,7 +278,7 @@ The following shell session demonstrates the use of the program: Reached end of file .EE .in -.PP +.P Note that a more general version of the program below could be improved to more robustly handle various error situations (e.g., opening a stream with a cookie that already has an open stream; diff --git a/man3/fpathconf.3 b/man3/fpathconf.3 index 6195197..af993ed 100644 --- a/man3/fpathconf.3 +++ b/man3/fpathconf.3 @@ -20,7 +20,7 @@ .\" _PC_SYMLINK_MAX, .\" _PC_2_SYMLINKS .\" -.TH fpathconf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fpathconf 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fpathconf, pathconf \- get configuration values for files .SH LIBRARY @@ -29,7 +29,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long fpathconf(int " fd ", int " name ); .BI "long pathconf(const char *" path ", int " name ); .fi @@ -39,13 +39,13 @@ gets a value for the configuration option .I name for the open file descriptor .IR fd . -.PP +.P .BR pathconf () gets a value for configuration option .I name for the filename .IR path . -.PP +.P The corresponding macros defined in .I are minimum values; if an application wants to take advantage of values @@ -54,7 +54,7 @@ which may change, a call to or .BR pathconf () can be made, which may yield more liberal results. -.PP +.P Setting .I name equal to one of the following constants returns the following @@ -252,7 +252,6 @@ T{ .BR pathconf () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -263,7 +262,7 @@ Files with name lengths longer than the value returned for equal to .B _PC_NAME_MAX may exist in the given directory. -.PP +.P Some returned values may be huge; they are not suitable for allocating memory. .SH SEE ALSO diff --git a/man3/fpclassify.3 b/man3/fpclassify.3 index cfb16be..8e72dd3 100644 --- a/man3/fpclassify.3 +++ b/man3/fpclassify.3 @@ -6,7 +6,7 @@ .\" This was done with the help of the glibc manual. .\" .\" 2004-10-31, aeb, corrected -.TH fpclassify 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fpclassify 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fpclassify, isfinite, isnormal, isnan, isinf \- floating-point classification macros @@ -16,19 +16,19 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fpclassify(" x ); .BI "int isfinite(" x ); .BI "int isnormal(" x ); .BI "int isnan(" x ); .BI "int isinf(" x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .\" I haven't fully grokked the source to determine the FTM requirements; .\" in part, the following has been tested by experiment. .BR fpclassify (), @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L .fi -.PP +.P .BR isnan (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR isinf (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -82,7 +82,7 @@ is too small to be represented in normalized format. .B FP_NORMAL if nothing of the above is correct then it must be a normal floating-point number. -.PP +.P The other macros provide a short answer to some standard questions. .TP 14 .BI isfinite( x ) @@ -122,12 +122,11 @@ T{ .BR isinf () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C99. -.PP +.P In glibc 2.01 and earlier, .BR isinf () returns a nonzero value (actually: 1) if diff --git a/man3/fpurge.3 b/man3/fpurge.3 index 545af20..c3fbdb9 100644 --- a/man3/fpurge.3 +++ b/man3/fpurge.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH fpurge 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fpurge 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fpurge, __fpurge \- purge a stream .SH LIBRARY @@ -13,13 +13,13 @@ Standard C library .nf /* unsupported */ .B #include -.PP +.P .BI "int fpurge(FILE *" stream ); -.PP +.P /* supported */ .B #include .B #include -.PP +.P .BI "void __fpurge(FILE *" stream ); .fi .SH DESCRIPTION @@ -34,7 +34,7 @@ this includes any text pushed back via .BR ungetc (3). See also .BR fflush (3). -.PP +.P The function .BR __fpurge () does precisely the same, but without returning a value. @@ -64,7 +64,6 @@ T{ .BR __fpurge () T} Thread safety MT-Safe race:stream .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/fputwc.3 b/man3/fputwc.3 index ce5ad42..3fe0b2e 100644 --- a/man3/fputwc.3 +++ b/man3/fputwc.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH fputwc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fputwc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fputwc, putwc \- write a wide character to a FILE stream .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "wint_t fputwc(wchar_t " wc ", FILE *" stream ); .BI "wint_t putwc(wchar_t " wc ", FILE *" stream ); .fi @@ -38,7 +38,7 @@ If a wide-character conversion error occurs, it sets \fIerrno\fP to \fBEILSEQ\fP and returns .BR WEOF . Otherwise, it returns \fIwc\fP. -.PP +.P The .BR putwc () function or macro functions identically to @@ -46,7 +46,7 @@ function or macro functions identically to It may be implemented as a macro, and may evaluate its argument more than once. There is no reason ever to use it. -.PP +.P For nonlocking counterparts, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -79,7 +79,6 @@ T{ .BR putwc () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -91,7 +90,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P In the absence of additional information passed to the .BR fopen (3) call, it is diff --git a/man3/fputws.3 b/man3/fputws.3 index dd54932..431ab5d 100644 --- a/man3/fputws.3 +++ b/man3/fputws.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH fputws 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fputws 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fputws \- write a wide-character string to a FILE stream .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fputws(const wchar_t *restrict " ws ", FILE *restrict " stream ); .fi .SH DESCRIPTION @@ -31,7 +31,7 @@ function. It writes the wide-character string starting at \fIws\fP, up to but not including the terminating null wide character (L\[aq]\e0\[aq]), to \fIstream\fP. -.PP +.P For a nonlocking counterpart, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -54,7 +54,6 @@ T{ .BR fputws () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -66,7 +65,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P In the absence of additional information passed to the .BR fopen (3) call, it is diff --git a/man3/fread.3 b/man3/fread.3 index 2874d43..34b11b3 100644 --- a/man3/fread.3 +++ b/man3/fread.3 @@ -16,7 +16,7 @@ .\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt .\" Modified Fri May 17 10:21:51 1996 by Martin Schulze .\" -.TH fread 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fread 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fread, fwrite \- binary stream input/output .SH LIBRARY @@ -25,7 +25,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t fread(void " ptr "[restrict ." size " * ." nmemb ], .BI " size_t " size ", size_t " nmemb , .BI " FILE *restrict " stream ); @@ -44,7 +44,7 @@ bytes long, from the stream pointed to by .IR stream , storing them at the location given by .IR ptr . -.PP +.P The function .BR fwrite () writes @@ -55,7 +55,7 @@ bytes long, to the stream pointed to by .IR stream , obtaining them from the location given by .IR ptr . -.PP +.P For nonlocking counterparts, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -69,10 +69,10 @@ This number equals the number of bytes transferred only when is 1. If an error occurs, or the end of the file is reached, the return value is a short item count (or zero). -.PP +.P The file position indicator for the stream is advanced by the number of bytes successfully read or written. -.PP +.P .BR fread () does not distinguish between end-of-file and error, and callers must use .BR feof (3) @@ -94,7 +94,6 @@ T{ .BR fwrite () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -104,7 +103,7 @@ The program below demonstrates the use of .BR fread () by parsing /bin/sh ELF executable in binary mode and printing its magic and class: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man3/frexp.3 b/man3/frexp.3 index c3c838a..9a5ab0d 100644 --- a/man3/frexp.3 +++ b/man3/frexp.3 @@ -11,7 +11,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH frexp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH frexp 3 2024-01-29 "Linux man-pages 6.7" .SH NAME frexp, frexpf, frexpl \- convert floating-point number to fractional and integral components @@ -21,17 +21,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double frexp(double " x ", int *" exp ); .BI "float frexpf(float " x ", int *" exp ); .BI "long double frexpl(long double " x ", int *" exp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR frexpf (), .BR frexpl (): .nf @@ -55,20 +55,20 @@ the normalized fraction is times a power of two, and its absolute value is always in the range 1/2 (inclusive) to 1 (exclusive), that is, [0.5,1). -.PP +.P If .I x is zero, then the normalized fraction is zero and zero is stored in .IR exp . -.PP +.P If .I x is a NaN, a NaN is returned, and the value of .I *exp is unspecified. -.PP +.P If .I x is positive infinity (negative infinity), @@ -93,19 +93,18 @@ T{ .BR frexpl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to SVr4, 4.3BSD, C89. .SH EXAMPLES The program below produces results such as the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out 2560" @@ -132,8 +131,7 @@ main(int argc, char *argv[]) x = strtod(argv[1], NULL); r = frexp(x, &exp); \& - printf("frexp(%g, &e) = %g: %g * %d\[ha]%d = %g\en", - x, r, r, FLT_RADIX, exp, x); + printf("frexp(%g, &e) = %g: %g * %d\[ha]%d = %g\en", x, r, r, 2, exp, x); exit(EXIT_SUCCESS); } .EE diff --git a/man3/fseek.3 b/man3/fseek.3 index 4b7a9af..c97c4d7 100644 --- a/man3/fseek.3 +++ b/man3/fseek.3 @@ -12,7 +12,7 @@ .\" .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu .\" -.TH fseek 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fseek 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream .SH LIBRARY @@ -21,12 +21,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fseek(FILE *" stream ", long " offset ", int " whence ); .BI "long ftell(FILE *" stream ); -.PP +.P .BI "void rewind(FILE *" stream ); -.PP +.P .BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos ); .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos ); .fi @@ -54,27 +54,27 @@ function clears the end-of-file indicator for the stream and undoes any effects of the .BR ungetc (3) function on the same stream. -.PP +.P The .BR ftell () function obtains the current value of the file position indicator for the stream pointed to by .IR stream . -.PP +.P The .BR rewind () function sets the file position indicator for the stream pointed to by .I stream to the beginning of the file. It is equivalent to: -.PP +.P .RS (void) fseek(stream, 0L, SEEK_SET) .RE -.PP +.P except that the error indicator for the stream is also cleared (see .BR clearerr (3)). -.PP +.P The .BR fgetpos () and @@ -94,7 +94,7 @@ On some non-UNIX systems, an .I fpos_t object may be a complex object and these routines may be the only way to portably reposition a text stream. -.PP +.P If the stream refers to a regular file and the resulting stream offset is beyond the size of the file, subsequent writes will extend the file with a hole, up to the offset, @@ -135,7 +135,7 @@ Or: the resulting file offset would be negative. The file descriptor underlying .I stream is not seekable (e.g., it refers to a pipe, FIFO, or socket). -.PP +.P The functions .BR fgetpos (), .BR fseek (), @@ -168,7 +168,6 @@ T{ .BR fsetpos () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/fseeko.3 b/man3/fseeko.3 index 3625fe2..fe35c97 100644 --- a/man3/fseeko.3 +++ b/man3/fseeko.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH fseeko 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fseeko 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fseeko, ftello \- seek to or report file position .SH LIBRARY @@ -12,16 +12,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fseeko(FILE *" stream ", off_t " offset ", int " whence ); .BI "off_t ftello(FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fseeko (), .BR ftello (): .nf @@ -48,7 +48,7 @@ is of type .I off_t instead of .IR long . -.PP +.P On some architectures, both .I off_t and @@ -88,7 +88,6 @@ T{ .BR ftello () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/ftime.3 b/man3/ftime.3 index cfa6ad9..a810b36 100644 --- a/man3/ftime.3 +++ b/man3/ftime.3 @@ -9,7 +9,7 @@ .\" Modified Sun Oct 18 17:31:43 1998 by Andries Brouwer (aeb@cwi.nl) .\" 2008-06-23, mtk, minor rewrites, added some details .\" -.TH ftime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ftime 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ftime \- return date and time .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int ftime(struct timeb *" tp ); .fi .SH DESCRIPTION @@ -27,13 +27,13 @@ This function is no longer provided by the GNU C library. Use .BR clock_gettime (2) instead. -.PP +.P This function returns the current time as seconds and milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). The time is returned in .IR tp , which is declared as follows: -.PP +.P .in +4n .EX struct timeb { @@ -44,7 +44,7 @@ struct timeb { }; .EE .in -.PP +.P Here \fItime\fP is the number of seconds since the Epoch, and \fImillitm\fP is the number of milliseconds since \fItime\fP seconds since the Epoch. @@ -54,7 +54,7 @@ east of Greenwich). The \fIdstflag\fP field is a flag that, if nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. -.PP +.P POSIX.1-2001 says that the contents of the \fItimezone\fP and \fIdstflag\fP fields are unspecified; avoid relying on them. .SH RETURN VALUE @@ -74,14 +74,13 @@ T{ .BR ftime () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY Removed in glibc 2.33. 4.2BSD, POSIX.1-2001. Removed in POSIX.1-2008. -.PP +.P This function is obsolete. Don't use it. If the time in seconds diff --git a/man3/ftok.3 b/man3/ftok.3 index 3b7d8ec..258276c 100644 --- a/man3/ftok.3 +++ b/man3/ftok.3 @@ -7,7 +7,7 @@ .\" Changed data type of proj_id; minor fixes .\" aeb: further fixes; added notes. .\" -.TH ftok 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ftok 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ftok \- convert a pathname and a project identifier to a System V IPC key .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .nf .B #include .fi -.PP +.P .BI "key_t ftok(const char *" pathname ", int " proj_id ); .SH DESCRIPTION The @@ -34,7 +34,7 @@ type System V IPC key, suitable for use with .BR semget (2), or .BR shmget (2). -.PP +.P The resulting value is the same for all pathnames that name the same file, when the same value of .I proj_id @@ -64,20 +64,19 @@ T{ .BR ftok () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. .SH NOTES On some ancient systems, the prototype was: -.PP +.P .in +4n .EX .BI "key_t ftok(char *" pathname ", char " proj_id ); .EE .in -.PP +.P Today, .I proj_id is an @@ -88,7 +87,7 @@ Typical usage has an ASCII character that is why the behavior is said to be undefined when .I proj_id is zero. -.PP +.P Of course, no guarantee can be given that the resulting .I key_t is unique. diff --git a/man3/fts.3 b/man3/fts.3 index 2a2745c..fa33766 100644 --- a/man3/fts.3 +++ b/man3/fts.3 @@ -10,7 +10,7 @@ .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH fts 3 2023-07-20 "Linux man-pages 6.05.01" +.TH fts 3 2024-01-16 "Linux man-pages 6.7" .SH NAME fts, fts_open, fts_read, fts_children, fts_set, fts_close \- \ traverse a file hierarchy @@ -22,16 +22,16 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "FTS *fts_open(char *const *" path_argv ", int " options , .BI " int (*_Nullable " compar ")(const FTSENT **, const FTSENT **));" -.PP +.P .BI "FTSENT *fts_read(FTS *" ftsp ); -.PP +.P .BI "FTSENT *fts_children(FTS *" ftsp ", int " instr ); -.PP +.P .BI "int fts_set(FTS *" ftsp ", FTSENT *" f ", int " instr ); -.PP +.P .BI "int fts_close(FTS *" ftsp ); .fi .SH DESCRIPTION @@ -53,7 +53,7 @@ The function .BR fts_children () returns a pointer to a linked list of structures, each of which describes one of the files contained in a directory in the hierarchy. -.PP +.P In general, directories are visited two distinguishable times; in preorder (before any of their descendants are visited) and in postorder (after all of their descendants have been visited). @@ -63,7 +63,7 @@ symbolic links point to) or physically (visiting the symbolic links themselves), order the walk of the hierarchy or prune and/or revisit portions of the hierarchy. -.PP +.P Two structures (and associated types) are defined in the include file .IR . The first type is @@ -80,14 +80,14 @@ hierarchy. In this manual page, "file" and "FTSENT structure" are generally interchangeable. -.PP +.P The .I FTSENT structure contains fields describing a file. The structure contains at least the following fields (there are additional fields that should be considered private to the implementation): -.PP +.P .in +4n .EX typedef struct _ftsent { @@ -115,7 +115,7 @@ typedef struct _ftsent { } FTSENT; .EE .in -.PP +.P These fields are defined as follows: .\" .Bl -tag -width "fts_namelen" .TP @@ -187,7 +187,8 @@ A regular file. .TP .B FTS_NS A file for which no -.RB [ l ] stat (2) +.RB [ l ]\c +.BR stat (2) information was available. The contents of the .I fts_statp @@ -198,7 +199,8 @@ field will be set to indicate what caused the error. .TP .B FTS_NSOK A file for which no -.RB [ l ] stat (2) +.RB [ l ]\c +.BR stat (2) information was requested. The contents of the .I fts_statp @@ -329,10 +331,11 @@ field are undefined. .TP .I fts_statp A pointer to -.RB [ l ] stat (2) +.RB [ l ]\c +.BR stat (2) information for the file. .\" .El -.PP +.P A single buffer is used for all of the paths of all of the files in the file hierarchy. Therefore, the @@ -366,7 +369,7 @@ function takes a pointer to an array of character pointers naming one or more paths which make up a logical file hierarchy to be traversed. The array must be terminated by a null pointer. -.PP +.P There are a number of options, at least one of which (either .B FTS_LOGICAL @@ -464,7 +467,7 @@ This option prevents fts from descending into directories that have a different device number than the file from which the descent began. .\" .El -.PP +.P The argument .BR compar () specifies a user-defined function which may be used to order the traversal @@ -516,7 +519,7 @@ All other files are visited at least once. (Hard links between directories that do not cause cycles or symbolic links to symbolic links may cause files to be visited more than once, or directories more than twice.) -.PP +.P If all the members of the hierarchy have been returned, .BR fts_read () returns NULL and sets @@ -535,7 +538,7 @@ structure is returned, and .I errno may or may not have been set (see .IR fts_info ). -.PP +.P The .I FTSENT structures returned by @@ -570,7 +573,7 @@ structure, and is ordered by the user-specified comparison function, if any. Repeated calls to .BR fts_children () will re-create this linked list. -.PP +.P As a special case, if .BR fts_read () has not yet been called for a hierarchy, @@ -598,7 +601,7 @@ NULL and sets .I errno to indicate the error. -.PP +.P The .I FTSENT structures returned by @@ -609,7 +612,7 @@ may be overwritten after a call to or .BR fts_read () on the same file hierarchy stream. -.PP +.P The .I instr argument is either zero or the following value: @@ -636,7 +639,7 @@ The .BR fts_set () function returns 0 on success, and \-1 if an error occurs. -.PP +.P The .I instr argument is either 0 (meaning "do nothing") or one of the following values: @@ -721,7 +724,7 @@ for any of the errors specified for .BR open (2) and .BR malloc (3). -.PP +.P In addition, .BR fts_open () may fail and set @@ -732,7 +735,7 @@ as follows: Any element of .I path_argv was an empty string. -.PP +.P The function .BR fts_close () may fail and set @@ -741,7 +744,7 @@ for any of the errors specified for .BR chdir (2) and .BR close (2). -.PP +.P The functions .BR fts_read () and @@ -754,8 +757,9 @@ for any of the errors specified for .BR opendir (3), .BR readdir (3), and -.RB [ l ] stat (2). -.PP +.RB [ l ]\c +.BR stat (2). +.P In addition, .BR fts_children (), .BR fts_open (), @@ -792,7 +796,6 @@ T{ .BR fts_children () T} Thread safety MT-Unsafe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/ftw.3 b/man3/ftw.3 index b231135..1488b92 100644 --- a/man3/ftw.3 +++ b/man3/ftw.3 @@ -15,7 +15,7 @@ .\" 2006-05-24, Michael Kerrisk .\" Added an example program. .\" -.TH ftw 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ftw 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ftw, nftw \- file tree walk .SH LIBRARY @@ -24,24 +24,24 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int nftw(const char *" dirpath , .BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , .BI " int " typeflag ", struct FTW *" ftwbuf ), .BI " int " nopenfd ", int " flags ); -.PP +.P .B [[deprecated]] .BI "int ftw(const char *" dirpath , .BI " int (*" fn ")(const char *" fpath ", const struct stat *" sb , .BI " int " typeflag ), .BI " int " nopenfd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nftw (): .nf _XOPEN_SOURCE >= 500 @@ -53,7 +53,7 @@ located under the directory \fIdirpath\fP, and calls \fIfn\fP() once for each entry in the tree. By default, directories are handled before the files and subdirectories they contain (preorder traversal). -.PP +.P To avoid using up all of the calling process's file descriptors, \fInopenfd\fP specifies the maximum number of directories that .BR nftw () @@ -66,7 +66,7 @@ directories have to be closed and reopened. .BR nftw () uses at most one file descriptor for each level in the directory tree. -.PP +.P For each entry found in the tree, .BR nftw () calls @@ -94,7 +94,7 @@ structure returned by a call to .BR stat (2) for .IR fpath . -.PP +.P The .I typeflag argument passed to @@ -167,7 +167,7 @@ contains information returned by performing .BR lstat (2) on the "dangling" symbolic link. (But see BUGS.) -.PP +.P The fourth argument .RI ( ftwbuf ) that @@ -175,7 +175,7 @@ that supplies when calling \fIfn\fP() is a pointer to a structure of type \fIFTW\fP: -.PP +.P .in +4n .EX struct FTW { @@ -184,7 +184,7 @@ struct FTW { }; .EE .in -.PP +.P .I base is the offset of the filename (i.e., basename component) in the pathname given in @@ -195,7 +195,7 @@ is the depth of in the directory tree, relative to the root of the tree .RI ( dirpath , which has depth 0). -.PP +.P To stop the tree walk, \fIfn\fP() returns a nonzero value; this value will become the return value of .BR nftw (). @@ -206,7 +206,7 @@ in which case it will return zero, or until it encounters an error (such as a .BR malloc (3) failure), in which case it will return \-1. -.PP +.P Because .BR nftw () uses dynamic data structures, the only safe way to @@ -216,7 +216,7 @@ have the handler set a global flag that is checked by \fIfn\fP(). \fIDon't\fP use .BR longjmp (3) unless the program is going to terminate. -.PP +.P The \fIflags\fP argument of .BR nftw () is formed by ORing zero or more of the @@ -258,10 +258,10 @@ Causes .BR nftw () to return immediately with the return value \fBFTW_STOP\fP. -.PP +.P Other return values could be associated with new actions in the future; \fIfn\fP() should not return values other than those listed above. -.PP +.P The feature test macro .B _GNU_SOURCE must be defined @@ -335,14 +335,14 @@ and (possibly) .BR FTW_SL . .SH RETURN VALUE These functions return 0 on success, and \-1 if an error occurs. -.PP +.P If \fIfn\fP() returns nonzero, then the tree walk is terminated and the value returned by \fIfn\fP() is returned as the result of .BR ftw () or .BR nftw (). -.PP +.P If .BR nftw () is called with the \fBFTW_ACTIONRETVAL\fP flag, @@ -369,7 +369,6 @@ T{ .BR ftw () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS In some implementations (e.g., glibc), .BR ftw () diff --git a/man3/futimes.3 b/man3/futimes.3 index 0f57891..f008526 100644 --- a/man3/futimes.3 +++ b/man3/futimes.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH futimes 3 2023-07-20 "Linux man-pages 6.05.01" +.TH futimes 3 2023-10-31 "Linux man-pages 6.7" .SH NAME futimes, lutimes \- change file timestamps .SH LIBRARY @@ -12,16 +12,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int futimes(int " fd ", const struct timeval " tv [2]); .BI "int lutimes(const char *" filename ", const struct timeval " tv [2]); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR futimes (), .BR lutimes (): .nf @@ -38,7 +38,7 @@ with the difference that the file whose timestamps are to be changed is specified via a file descriptor, .IR fd , rather than via a pathname. -.PP +.P .BR lutimes () changes the access and modification times of a file in the same way as .BR utimes (2), @@ -65,7 +65,7 @@ is not a valid file descriptor. The .I /proc filesystem could not be accessed. -.PP +.P The following additional error may occur for .BR lutimes (): .TP @@ -86,7 +86,6 @@ T{ .BR lutimes () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS Linux, BSD. .SH HISTORY diff --git a/man3/fwide.3 b/man3/fwide.3 index 6b33de0..b833b57 100644 --- a/man3/fwide.3 +++ b/man3/fwide.3 @@ -8,7 +8,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH fwide 3 2023-03-30 "Linux man-pages 6.05.01" +.TH fwide 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fwide \- set and determine the orientation of a FILE stream .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fwide(FILE *" stream ", int " mode ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fwide (): .nf _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE @@ -46,10 +46,10 @@ returns zero if \fIstream\fP has no orientation yet; in this case the next I/O operation might change the orientation (to byte oriented if it is a char I/O operation, or to wide-character oriented if it is a wide-character I/O operation). -.PP +.P Once a stream has an orientation, it cannot be changed and persists until the stream is closed. -.PP +.P When \fImode\fP is nonzero, the .BR fwide () function first attempts to set @@ -78,7 +78,7 @@ function with the and .B %ls directives. -.PP +.P Char oriented output to a wide-character oriented stream can be performed through the .BR fwprintf (3) diff --git a/man3/gamma.3 b/man3/gamma.3 index 2dc9075..3080624 100644 --- a/man3/gamma.3 +++ b/man3/gamma.3 @@ -5,7 +5,7 @@ .\" .\" Modified 2003-11-18, aeb: historical remarks .\" -.TH gamma 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gamma 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gamma, gammaf, gammal \- (logarithm of the) gamma function .SH LIBRARY @@ -14,24 +14,24 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] double gamma(double " x ");" .BI "[[deprecated]] float gammaf(float " x ");" .BI "[[deprecated]] long double gammal(long double " x ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gamma (): .nf _XOPEN_SOURCE || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR gammaf (), .BR gammal (): .nf @@ -45,7 +45,7 @@ These functions are deprecated: instead, use either the or the .BR lgamma (3) functions, as appropriate. -.PP +.P For the definition of the Gamma function, see .BR tgamma (3). .SS *BSD version @@ -80,15 +80,14 @@ T{ .BR gammal () T} Thread safety MT-Unsafe race:signgam .TE -.sp 1 .SH STANDARDS None. .SH HISTORY SVID 2. -.PP +.P Because of historical variations in behavior across systems, this function is not specified in any recent standard. -.PP +.P 4.2BSD had a .BR gamma () that computed @@ -100,12 +99,12 @@ in the external integer In 4.3BSD the name was changed to .BR lgamma (3), and the man page promises -.PP +.P .in +4n "At some time in the future the name gamma will be rehabilitated and used for the Gamma function" .in -.PP +.P This did indeed happen in 4.4BSD, where .BR gamma () computes the Gamma function (with no effect on diff --git a/man3/gcvt.3 b/man3/gcvt.3 index a43ade7..54d4943 100644 --- a/man3/gcvt.3 +++ b/man3/gcvt.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:32:25 1993 by Rik Faith (faith@cs.unc.edu) -.TH gcvt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gcvt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gcvt \- convert a floating-point number to a string .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *gcvt(double " number ", int " ndigit ", char *" buf ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gcvt (): .nf Since glibc 2.17 @@ -66,7 +66,6 @@ T{ .BR gcvt () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/get_nprocs.3 b/man3/get_nprocs.3 index 583054d..b07bed3 100644 --- a/man3/get_nprocs.3 +++ b/man3/get_nprocs.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH get_nprocs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH get_nprocs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME get_nprocs, get_nprocs_conf \- get number of processors .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int get_nprocs(void); .B int get_nprocs_conf(void); .fi @@ -21,7 +21,7 @@ Standard C library The function .BR get_nprocs_conf () returns the number of processors configured by the operating system. -.PP +.P The function .BR get_nprocs () returns the number of processors currently available in the system. @@ -45,7 +45,6 @@ T{ .BR get_nprocs_conf () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH NOTES @@ -55,12 +54,12 @@ implementation of these functions is rather expensive, since they open and parse files in the .I /sys filesystem each time they are called. -.PP +.P The following .BR sysconf (3) calls make use of the functions documented on this page to return the same information. -.PP +.P .in +4n .EX np = sysconf(_SC_NPROCESSORS_CONF); /* processors configured */ @@ -73,7 +72,7 @@ The following example shows how and .BR get_nprocs_conf () can be used. -.PP +.P .\" SRC BEGIN (get_nprocs_conf.c) .EX #include diff --git a/man3/get_phys_pages.3 b/man3/get_phys_pages.3 index 71cd4c9..714e397 100644 --- a/man3/get_phys_pages.3 +++ b/man3/get_phys_pages.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH get_phys_pages 3 2023-05-03 "Linux man-pages 6.05.01" +.TH get_phys_pages 3 2023-10-31 "Linux man-pages 6.7" .SH NAME get_phys_pages, get_avphys_pages \- get total and available physical page counts @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .B long get_phys_pages(void); .B long get_avphys_pages(void); .fi @@ -20,7 +20,7 @@ Standard C library The function .BR get_phys_pages () returns the total number of physical pages of memory available on the system. -.PP +.P The function .BR get_avphys_pages () returns the number of currently available physical pages of memory on the @@ -56,7 +56,7 @@ The following .BR sysconf (3) calls provide a portable means of obtaining the same information as the functions described on this page. -.PP +.P .in +4n .EX total_pages = sysconf(_SC_PHYS_PAGES); /* total pages */ @@ -69,7 +69,7 @@ The following example shows how and .BR get_avphys_pages () can be used. -.PP +.P .\" SRC BEGIN (get_phys_pages.c) .EX #include diff --git a/man3/getaddrinfo.3 b/man3/getaddrinfo.3 index 1bbbb23..e036e94 100644 --- a/man3/getaddrinfo.3 +++ b/man3/getaddrinfo.3 @@ -22,7 +22,7 @@ .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support .\" and is SCTP support now also there? .\" -.TH getaddrinfo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getaddrinfo 3 2024-02-18 "Linux man-pages 6.7" .SH NAME getaddrinfo, freeaddrinfo, gai_strerror \- network address and service translation @@ -34,22 +34,22 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "int getaddrinfo(const char *restrict " node , .BI " const char *restrict " service , .BI " const struct addrinfo *restrict " hints , .BI " struct addrinfo **restrict " res ); -.PP +.P .BI "void freeaddrinfo(struct addrinfo *" res ); -.PP +.P .BI "const char *gai_strerror(int " errcode ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getaddrinfo (), .BR freeaddrinfo (), .BR gai_strerror (): @@ -84,13 +84,13 @@ and functions into a single interface, but unlike the latter functions, .BR getaddrinfo () is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies. -.PP +.P The .I addrinfo structure used by .BR getaddrinfo () contains the following fields: -.PP +.P .in +4n .EX struct addrinfo { @@ -105,7 +105,7 @@ struct addrinfo { }; .EE .in -.PP +.P The .I hints argument points to an @@ -160,11 +160,11 @@ any protocol can be returned by .I ai_flags This field specifies additional options, described below. Multiple flags are specified by bitwise OR-ing them together. -.PP +.P All the other fields in the structure pointed to by .I hints must contain either 0 or a null pointer, as appropriate. -.PP +.P Specifying .I hints as NULL is equivalent to setting @@ -199,7 +199,7 @@ must be a numerical network address. The .B AI_NUMERICHOST flag suppresses any potentially lengthy network host address lookups. -.PP +.P If the .B AI_PASSIVE flag is specified in @@ -224,7 +224,7 @@ If is not NULL, then the .B AI_PASSIVE flag is ignored. -.PP +.P If the .B AI_PASSIVE flag is not set in @@ -244,7 +244,7 @@ for IPv4 addresses, for IPv6 address); this is used by applications that intend to communicate with peers running on the same host. -.PP +.P .I service sets the port in each returned address structure. If this argument is a service name (see @@ -267,13 +267,13 @@ is not NULL, then must point to a string containing a numeric port number. This flag is used to inhibit the invocation of a name resolution service in cases where it is known not to be required. -.PP +.P Either .I node or .IR service , but not both, may be NULL. -.PP +.P The .BR getaddrinfo () function allocates and initializes a linked list of @@ -289,7 +289,7 @@ and returns a pointer to the start of the list in The items in the linked list are linked by the .I ai_next field. -.PP +.P There are several reasons why the linked list may have more than one .I addrinfo @@ -311,7 +311,7 @@ is defined in RFC\ 3484; the order can be tweaked for a particular system by editing .I /etc/gai.conf (available since glibc 2.5). -.PP +.P If .I hints.ai_flags includes the @@ -326,7 +326,7 @@ official name of the host. .\" structure was set pointing to the canonical name; that was .\" more than POSIX.1-2001 specified, or other implementations provided. .\" MTK, Aug 05 -.PP +.P The remaining fields of each returned .I addrinfo structure are initialized as follows: @@ -360,7 +360,7 @@ field, and the length of the socket address, in bytes, is placed in the .I ai_addrlen field. -.PP +.P If .I hints.ai_flags includes the @@ -379,7 +379,7 @@ does not return IPv6 socket addresses that would always fail in .BR connect (2) or .BR bind (2). -.PP +.P If .I hints.ai_flags specifies the @@ -404,7 +404,7 @@ in the list pointed to by is ignored if .B AI_V4MAPPED is not also specified. -.PP +.P The .BR freeaddrinfo () function frees the memory that was allocated @@ -462,7 +462,9 @@ The resulting string is encoded using the current locale's encoding. .\"If no component of the returned name starts with xn\-\- the IDN .\"step can be skipped, therefore avoiding unnecessary slowdowns. .TP -.BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES +.B AI_IDN_ALLOW_UNASSIGNED +.TQ +.B AI_IDN_USE_STD3_ASCII_RULES Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 @@ -499,7 +501,7 @@ contains invalid flags; or, included .B AI_CANONNAME and -.I name +.I node was NULL. .TP .B EAI_FAIL @@ -570,7 +572,7 @@ respectively). Other system error; .I errno is set to indicate the error. -.PP +.P The .BR gai_strerror () function translates these error codes to a human readable string, @@ -597,7 +599,6 @@ T{ .BR gai_strerror () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS According to POSIX.1, specifying .\" POSIX.1-2001, POSIX.1-2008 diff --git a/man3/getaddrinfo_a.3 b/man3/getaddrinfo_a.3 index 4b891ab..fe27b6c 100644 --- a/man3/getaddrinfo_a.3 +++ b/man3/getaddrinfo_a.3 @@ -8,7 +8,7 @@ .\" References: http://people.redhat.com/drepper/asynchnl.pdf, .\" http://www.imperialviolet.org/2005/06/01/asynchronous-dns-lookups-with-glibc.html .\" -.TH getaddrinfo_a 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getaddrinfo_a 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getaddrinfo_a, gai_suspend, gai_error, gai_cancel \- asynchronous network address and service translation @@ -19,12 +19,12 @@ Asynchronous name lookup library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int getaddrinfo_a(int " mode ", struct gaicb *" list [restrict], .BI " int " nitems ", struct sigevent *restrict " sevp ); .BI "int gai_suspend(const struct gaicb *const " list "[], int " nitems , .BI " const struct timespec *" timeout ); -.PP +.P .BI "int gai_error(struct gaicb *" req ); .BI "int gai_cancel(struct gaicb *" req ); .fi @@ -35,7 +35,7 @@ function performs the same task as .BR getaddrinfo (3), but allows multiple name look-ups to be performed asynchronously, with optional notification on completion of look-up operations. -.PP +.P The .I mode argument has one of the following values: @@ -51,7 +51,7 @@ and the requests are resolved in the background. See the discussion of the .I sevp argument below. -.PP +.P The array .I list specifies the look-up requests to process. @@ -66,7 +66,7 @@ are ignored. Each request is described by a .I gaicb structure, defined as follows: -.PP +.P .in +4n .EX struct gaicb { @@ -77,7 +77,7 @@ struct gaicb { }; .EE .in -.PP +.P The elements of this structure correspond to the arguments of .BR getaddrinfo (3). Thus, @@ -106,7 +106,7 @@ The .I addrinfo structure referenced by the last two elements is described in .BR getaddrinfo (3). -.PP +.P When .I mode is specified as @@ -118,7 +118,7 @@ structure pointed to by the .I sevp argument. For the definition and general details of this structure, see -.BR sigevent (7). +.BR sigevent (3type). The .I sevp\->sigev_notify field can have the following values: @@ -131,7 +131,7 @@ When a look-up completes, generate the signal .I sigev_signo for the process. See -.BR sigevent (7) +.BR sigevent (3type) for general details. The .I si_code @@ -147,9 +147,9 @@ When a look-up completes, invoke .I sigev_notify_function as if it were the start function of a new thread. See -.BR sigevent (7) +.BR sigevent (3type) for details. -.PP +.P For .B SIGEV_SIGNAL and @@ -158,7 +158,7 @@ it may be useful to point .I sevp\->sigev_value.sival_ptr to .IR list . -.PP +.P The .BR gai_suspend () function suspends execution of the calling thread, @@ -188,12 +188,12 @@ If .I timeout is NULL, then the call blocks indefinitely (until one of the events above occurs). -.PP +.P No explicit indication of which request was completed is given; you must determine which request(s) have completed by iterating with .BR gai_error () over the list of requests. -.PP +.P The .BR gai_error () function returns the status of the request @@ -203,7 +203,7 @@ either if the request was not completed yet, 0 if it was handled successfully, or an error code if the request could not be resolved. -.PP +.P The .BR gai_cancel () function cancels the request @@ -237,7 +237,7 @@ Out of memory. .B EAI_SYSTEM .I mode is invalid. -.PP +.P The .BR gai_suspend () function returns 0 if at least one of the listed requests has been completed. @@ -253,7 +253,7 @@ There were no actual requests given to the function. A signal has interrupted the function. Note that this interruption might have been caused by signal notification of some completed look-up request. -.PP +.P The .BR gai_error () function can return @@ -265,7 +265,7 @@ for an unfinished look-up request, or the error code .B EAI_CANCELED if the request has been canceled explicitly before it could be finished. -.PP +.P The .BR gai_cancel () function can return one of these values: @@ -278,7 +278,7 @@ The request has not been canceled. .TP .B EAI_ALLDONE The request has already completed. -.PP +.P The .BR gai_strerror (3) function translates these error codes to a human readable string, @@ -300,12 +300,11 @@ T{ .BR gai_cancel () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY glibc 2.2.3. -.PP +.P The interface of .BR getaddrinfo_a () was modeled after the @@ -320,7 +319,7 @@ The program below simply resolves several hostnames in parallel, giving a speed-up compared to resolving the hostnames sequentially using .BR getaddrinfo (3). The program might be used like this: -.PP +.P .in +4n .EX $ \fB./a.out mirrors.kernel.org enoent.linuxfoundation.org gnu.org\fP @@ -329,17 +328,20 @@ enoent.linuxfoundation.org: Name or service not known gnu.org: 209.51.188.116 .EE .in -.PP +.P Here is the program source code -.PP +.P .\" SRC BEGIN (sync.c) .EX #define _GNU_SOURCE +#include #include #include #include #include \& +#define MALLOC(n, type) ((type *) reallocarray(NULL, n, sizeof(type))) +\& int main(int argc, char *argv[]) { @@ -354,11 +356,10 @@ main(int argc, char *argv[]) } \& for (size_t i = 0; i < argc \- 1; i++) { - reqs[i] = malloc(sizeof(*reqs[0])); - if (reqs[i] == NULL) { - perror("malloc"); - exit(EXIT_FAILURE); - } + reqs[i] = MALLOC(1, struct gaicb); + if (reqs[i] == NULL) + err(EXIT_FAILURE, "malloc"); +\& memset(reqs[i], 0, sizeof(*reqs[0])); reqs[i]\->ar_name = argv[i + 1]; } @@ -399,9 +400,9 @@ This example shows a simple interactive .BR getaddrinfo_a () front-end. The notification facility is not demonstrated. -.PP +.P An example session might look like this: -.PP +.P .in +4n .EX $ \fB./a.out\fP @@ -420,20 +421,42 @@ $ \fB./a.out\fP [02] gnu.org: 209.51.188.116 .EE .in -.PP +.P The program source is as follows: -.PP +.P .\" SRC BEGIN (async.c) .EX #define _GNU_SOURCE +#include +#include #include #include #include #include \& +#define CALLOC(n, type) ((type *) calloc(n, sizeof(type))) +\& +#define REALLOCF(ptr, n, type) \e +({ \e + static_assert(__builtin_types_compatible_p(typeof(ptr), type *)); \e + \e + (type *) reallocarrayf(ptr, n, sizeof(type)); \e +}) +\& static struct gaicb **reqs = NULL; static size_t nreqs = 0; \& +static inline void * +reallocarrayf(void *p, size_t nmemb, size_t size) +{ + void *q; +\& + q = reallocarray(p, nmemb, size); + if (q == NULL && nmemb != 0 && size != 0) + free(p); + return q; +} +\& static char * getcmd(void) { @@ -459,9 +482,14 @@ add_requests(void) \& while ((host = strtok(NULL, " "))) { nreqs++; - reqs = realloc(reqs, sizeof(reqs[0]) * nreqs); + reqs = REALLOCF(reqs, nreqs, struct gaicb *); + if (reqs == NULL) + err(EXIT_FAILURE, "reallocf"); +\& + reqs[nreqs \- 1] = CALLOC(1, struct gaicb); + if (reqs[nreqs \- 1] == NULL) + err(EXIT_FAILURE, "calloc"); \& - reqs[nreqs \- 1] = calloc(1, sizeof(*reqs[0])); reqs[nreqs \- 1]\->ar_name = strdup(host); } \& @@ -483,7 +511,12 @@ wait_requests(void) char *id; int ret; size_t n; - struct gaicb const **wait_reqs = calloc(nreqs, sizeof(*wait_reqs)); + struct gaicb const **wait_reqs; +\& + wait_reqs = CALLOC(nreqs, const struct gaicb *); + if (wait_reqs == NULL) + err(EXIT_FAILURE, "calloc"); +\& /* NULL elements are ignored by gai_suspend(). */ \& while ((id = strtok(NULL, " ")) != NULL) { @@ -609,4 +642,4 @@ main(void) .BR lio_listio (3), .BR hostname (7), .BR ip (7), -.BR sigevent (7) +.BR sigevent (3type) diff --git a/man3/getauxval.3 b/man3/getauxval.3 index 8e7d5e4..c41cce0 100644 --- a/man3/getauxval.3 +++ b/man3/getauxval.3 @@ -5,7 +5,7 @@ .\" .\" See also https://lwn.net/Articles/519085/ .\" -.TH getauxval 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getauxval 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getauxval \- retrieve a value from the auxiliary vector .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "unsigned long getauxval(unsigned long " type ); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ function retrieves values from the auxiliary vector, a mechanism that the kernel's ELF binary loader uses to pass certain information to user space when a program is executed. -.PP +.P Each entry in the auxiliary vector consists of a pair of values: a type that identifies what this entry represents, and a value for that type. @@ -32,7 +32,7 @@ Given the argument .IR type , .BR getauxval () returns the corresponding value. -.PP +.P The value returned for each .I type is given in the following list. @@ -224,7 +224,6 @@ T{ .BR getauxval () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -238,19 +237,19 @@ that allows the kernel to communicate a certain set of standard information that the dynamic linker usually or always needs. In some cases, the same information could be obtained by system calls, but using the auxiliary vector is cheaper. -.PP +.P The auxiliary vector resides just above the argument list and environment in the process address space. The auxiliary vector supplied to a program can be viewed by setting the .B LD_SHOW_AUXV environment variable when running a program: -.PP +.P .in +4n .EX $ LD_SHOW_AUXV=1 sleep 1 .EE .in -.PP +.P The auxiliary vector of any process can (subject to file permissions) be obtained via .IR /proc/ pid /auxv ; diff --git a/man3/getcontext.3 b/man3/getcontext.3 index 4cd604c..6515075 100644 --- a/man3/getcontext.3 +++ b/man3/getcontext.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getcontext 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getcontext 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getcontext, setcontext \- get or set the user context .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getcontext(ucontext_t *" ucp ); .BI "int setcontext(const ucontext_t *" ucp ); .fi @@ -31,7 +31,7 @@ and .BR swapcontext (3) that allow user-level context switching between multiple threads of control within a process. -.PP +.P The .I mcontext_t type is machine-dependent and opaque. @@ -39,7 +39,7 @@ The .I ucontext_t type is a structure that has at least the following fields: -.PP +.P .in +4n .EX typedef struct ucontext_t { @@ -51,7 +51,7 @@ typedef struct ucontext_t { } ucontext_t; .EE .in -.PP +.P with .I sigset_t and @@ -76,14 +76,14 @@ and is the machine-specific representation of the saved context, that includes the calling thread's machine registers. -.PP +.P The function .BR getcontext () initializes the structure pointed to by .I ucp to the currently active context. -.PP +.P The function .BR setcontext () restores the user context @@ -99,11 +99,11 @@ handler (see the discussion of the .B SA_SIGINFO flag in .BR sigaction (2)). -.PP +.P If the context was obtained by a call of .BR getcontext (), program execution continues as if this call just returned. -.PP +.P If the context was obtained by a call of .BR makecontext (3), program execution continues by a call to the function @@ -120,7 +120,7 @@ specified as the first argument of that call to .BR makecontext (3). When this member is NULL, the thread exits. -.PP +.P If the context was obtained by a call to a signal handler, then old standard text says that "program execution continues with the program instruction following the instruction interrupted @@ -153,12 +153,11 @@ T{ .BR setcontext () T} Thread safety MT-Safe race:ucp .TE -.sp 1 .SH STANDARDS None. .SH HISTORY SUSv2, POSIX.1-2001. -.PP +.P POSIX.1-2008 removes these functions, citing portability issues, and recommending that applications be rewritten to use POSIX threads instead. @@ -181,7 +180,7 @@ is from the first call, or via a call. The user has to invent their own bookkeeping device, and a register variable won't do since registers are restored. -.PP +.P When a signal occurs, the current user context is saved and a new context is created by the kernel for the signal handler. Do not leave the handler using diff --git a/man3/getcwd.3 b/man3/getcwd.3 index 7149581..1004458 100644 --- a/man3/getcwd.3 +++ b/man3/getcwd.3 @@ -10,7 +10,7 @@ .\" Modified Mon Dec 11 13:32:51 MET 2000 by aeb .\" Modified Thu Apr 22 03:49:15 CEST 2002 by Roger Luethi .\" -.TH getcwd 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getcwd 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getcwd, getwd, get_current_dir_name \- get current working directory .SH LIBRARY @@ -19,23 +19,23 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *getcwd(char " buf [. size "], size_t " size ); .B "char *get_current_dir_name(void);" -.PP +.P .BI "[[deprecated]] char *getwd(char " buf [PATH_MAX]); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR get_current_dir_name (): .nf _GNU_SOURCE .fi -.PP +.P .BR getwd (): .nf Since glibc 2.12: @@ -53,7 +53,7 @@ the calling process. The pathname is returned as the function result and via the argument .IR buf , if present. -.PP +.P The .BR getcwd () function copies an absolute pathname of the current working directory @@ -61,7 +61,7 @@ to the array pointed to by .IR buf , which is of length .IR size . -.PP +.P If the length of the absolute pathname of the current working directory, including the terminating null byte, exceeds .I size @@ -71,7 +71,7 @@ is set to .BR ERANGE ; an application should check for this error, and allocate a larger buffer if necessary. -.PP +.P As an extension to the POSIX.1-2001 standard, glibc's .BR getcwd () allocates the buffer dynamically using @@ -89,7 +89,7 @@ is allocated as big as necessary. The caller should .BR free (3) the returned buffer. -.PP +.P .BR get_current_dir_name () will .BR malloc (3) @@ -102,7 +102,7 @@ is set, and its value is correct, then that value will be returned. The caller should .BR free (3) the returned buffer. -.PP +.P .BR getwd () does not .BR malloc (3) @@ -136,7 +136,7 @@ and .BR getwd () this is the same value as .IR buf . -.PP +.P On failure, these functions return NULL, and .I errno is set to indicate the error. @@ -202,14 +202,13 @@ T{ .BR get_current_dir_name () T} Thread safety MT-Safe env .TE -.sp 1 .SH VERSIONS POSIX.1-2001 leaves the behavior of .BR getcwd () unspecified if .I buf is NULL. -.PP +.P POSIX.1-2001 does not define any errors for .BR getwd (). @@ -234,7 +233,7 @@ exceeds this limit, then the system call fails with the error .BR ENAMETOOLONG . In this case, the library functions fall back to a (slower) alternative implementation that returns the full pathname. -.PP +.P Following a change in Linux 2.6.36, .\" commit 8df9d1a4142311c084ffeeacb67cd34d190eff74 the pathname returned by the @@ -272,7 +271,7 @@ Removed in POSIX.1-2008. Use .BR getcwd () instead. -.PP +.P Under Linux, these functions make use of the .BR getcwd () system call (available since Linux 2.1.92). diff --git a/man3/getdate.3 b/man3/getdate.3 index fefc370..fe15e6b 100644 --- a/man3/getdate.3 +++ b/man3/getdate.3 @@ -8,7 +8,7 @@ .\" Modified, 2001-12-26, aeb .\" 2008-09-07, mtk, Various rewrites; added an example program. .\" -.TH getdate 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getdate 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getdate, getdate_r \- convert a date-plus-time string to broken-down time .SH LIBRARY @@ -17,25 +17,25 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "struct tm *getdate(const char *" string ); -.PP +.P .B "extern int getdate_err;" -.PP +.P .BI "int getdate_r(const char *restrict " string ", struct tm *restrict " res ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getdate (): .nf _XOPEN_SOURCE >= 500 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED .fi -.PP +.P .BR getdate_r (): .nf _GNU_SOURCE @@ -56,7 +56,7 @@ This structure is allocated in static storage, and consequently it will be overwritten by further calls to .BR getdate (). -.PP +.P In contrast to .BR strptime (3), (which has a @@ -68,11 +68,11 @@ whose full pathname is given in the environment variable .BR DATEMSK . The first line in the file that matches the given input string is used for the conversion. -.PP +.P The matching is done case insensitively. Superfluous whitespace, either in the pattern or in the string to be converted, is ignored. -.PP +.P The conversion specifications that a pattern can contain are those given for .BR strptime (3). One more conversion specification is specified in POSIX.1-2001: @@ -83,7 +83,7 @@ Timezone name. .\" Looking at the glibc 2.21 source code, where the implementation uses .\" strptime(), suggests that it might be supported. This is not implemented in glibc. -.PP +.P When .B %Z is given, the structure containing the broken-down time @@ -92,21 +92,21 @@ time in the given timezone. Otherwise, the structure is initialized to the broken-down time corresponding to the current local time (as by a call to .BR localtime (3)). -.PP +.P When only the day of the week is given, the day is taken to be the first such day on or after today. -.PP +.P When only the month is given (and no year), the month is taken to be the first such month equal to or after the current month. If no day is given, it is the first day of the month. -.PP +.P When no hour, minute, and second are given, the current hour, minute, and second are taken. -.PP +.P If no date is given, but we know the hour, then that hour is taken to be the first such hour equal to or after the current hour. -.PP +.P .BR getdate_r () is a GNU extension that provides a reentrant version of .BR getdate (). @@ -127,7 +127,7 @@ to one of the error numbers shown below. Changes to .I errno are unspecified. -.PP +.P On success .BR getdate_r () returns 0; @@ -174,7 +174,9 @@ Invalid input specification. .B DATEMSK File containing format patterns. .TP -.BR TZ ", " LC_TIME +.B TZ +.TQ +.B LC_TIME Variables used by .BR strptime (3). .SH ATTRIBUTES @@ -204,7 +206,6 @@ T} Thread safety T{ MT-Safe env locale T} .TE -.sp 1 .SH VERSIONS The POSIX.1 specification for .BR strptime (3) @@ -231,7 +232,7 @@ and for each call displays the values in the fields of the returned .I tm structure. The following shell session demonstrates the operation of the program: -.PP +.P .in +4n .EX .RB "$" " TFILE=$PWD/tfile" diff --git a/man3/getdirentries.3 b/man3/getdirentries.3 index 67d6da1..78fcf25 100644 --- a/man3/getdirentries.3 +++ b/man3/getdirentries.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getdirentries 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getdirentries 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getdirentries \- get directory entries in a filesystem-independent format .SH LIBRARY @@ -14,17 +14,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t getdirentries(int " fd ", char " buf "[restrict ." nbytes "], \ size_t " nbytes , .BI " off_t *restrict " basep ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getdirentries (): .nf Since glibc 2.19: @@ -67,7 +67,6 @@ T{ .BR getdirentries () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS BSD. .SH NOTES diff --git a/man3/getdtablesize.3 b/man3/getdtablesize.3 index 40b940f..b792ea9 100644 --- a/man3/getdtablesize.3 +++ b/man3/getdtablesize.3 @@ -5,7 +5,7 @@ .\" .\" Modified 2002-04-15 by Roger Luethi and aeb .\" -.TH getdtablesize 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getdtablesize 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getdtablesize \- get file descriptor table size .SH LIBRARY @@ -14,15 +14,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int getdtablesize(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getdtablesize (): .nf Since glibc 2.20: @@ -59,7 +59,6 @@ T{ .BR getdtablesize () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The glibc version of .BR getdtablesize () @@ -73,7 +72,7 @@ when that fails. .\" The libc4 and libc5 versions return .\" .B OPEN_MAX .\" (set to 256 since Linux 0.98.4). -.PP +.P Portable applications should employ .I sysconf(_SC_OPEN_MAX) instead of this call. diff --git a/man3/getentropy.3 b/man3/getentropy.3 index f09a209..7c70623 100644 --- a/man3/getentropy.3 +++ b/man3/getentropy.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getentropy 3 2023-03-30 "Linux man-pages 6.05.01" +.TH getentropy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getentropy \- fill a buffer with random bytes .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getentropy(void " buffer [. length "], size_t " length ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getentropy (): .nf _DEFAULT_SOURCE @@ -35,7 +35,7 @@ at the location pointed to by The maximum permitted value for the .I length argument is 256. -.PP +.P A successful call to .BR getentropy () always provides the requested number of bytes of entropy. @@ -76,19 +76,19 @@ The .BR getentropy () function is implemented using .BR getrandom (2). -.PP +.P Whereas the glibc wrapper makes .BR getrandom (2) a cancelation point, .BR getentropy () is not a cancelation point. -.PP +.P .BR getentropy () is also declared in .BR . (No feature test macro need be defined to obtain the declaration from that header file.) -.PP +.P A call to .BR getentropy () may block if the system has just booted and the kernel has diff --git a/man3/getenv.3 b/man3/getenv.3 index 705eb43..50b17cf 100644 --- a/man3/getenv.3 +++ b/man3/getenv.3 @@ -11,7 +11,7 @@ .\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl) .\" -.TH getenv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getenv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getenv, secure_getenv \- get an environment variable .SH LIBRARY @@ -20,16 +20,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *getenv(const char *" name ); .BI "char *secure_getenv(const char *" name ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR secure_getenv (): .nf _GNU_SOURCE @@ -43,7 +43,7 @@ environment variable and returns a pointer to the corresponding .I value string. -.PP +.P The GNU-specific .BR secure_getenv () function is just like @@ -60,10 +60,10 @@ set-group-ID program); the effective capability bit was set on the executable file; or .IP \[bu] the process has a nonempty permitted capability set. -.PP +.P Secure execution may also be required if triggered by some Linux security modules. -.PP +.P The .BR secure_getenv () function is intended for use in general-purpose libraries @@ -90,7 +90,6 @@ T{ .BR secure_getenv () T} Thread safety MT-Safe env .TE -.sp 1 .SH STANDARDS .TP .BR getenv () @@ -107,13 +106,13 @@ POSIX.1-2001, C89, C99, SVr4, 4.3BSD. glibc 2.17. .SH NOTES The strings in the environment list are of the form \fIname=value\fP. -.PP +.P As typically implemented, .BR getenv () returns a pointer to a string within the environment list. The caller must take care not to modify this string, since that would change the environment of the process. -.PP +.P The implementation of .BR getenv () is not required to be reentrant. @@ -126,7 +125,7 @@ and can be modified by a subsequent call to .BR setenv (3), or .BR unsetenv (3). -.PP +.P The "secure execution" mode of .BR secure_getenv () is controlled by the diff --git a/man3/getfsent.3 b/man3/getfsent.3 index 5a03bd9..2bcb958 100644 --- a/man3/getfsent.3 +++ b/man3/getfsent.3 @@ -5,7 +5,7 @@ .\" .\" Inspired by a page written by Walter Harms. .\" -.TH getfsent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getfsent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getfsent, getfsspec, getfsfile, setfsent, endfsent \- handle fstab entries .SH LIBRARY @@ -14,11 +14,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "int setfsent(void);" .B "struct fstab *getfsent(void);" .B "void endfsent(void);" -.PP +.P .BI "struct fstab *getfsfile(const char *" mount_point ); .BI "struct fstab *getfsspec(const char *" special_file ); .fi @@ -28,7 +28,7 @@ These functions read from the file The .I struct fstab is defined by: -.PP +.P .in +4n .EX struct fstab { @@ -42,26 +42,26 @@ struct fstab { }; .EE .in -.PP +.P Here the field .I fs_type contains (on a *BSD system) one of the five strings "rw", "rq", "ro", "sw", "xx" (read-write, read-write with quota, read-only, swap, ignore). -.PP +.P The function .BR setfsent () opens the file when required and positions it at the first line. -.PP +.P The function .BR getfsent () parses the next line from the file. (After opening it when required.) -.PP +.P The function .BR endfsent () closes the file when required. -.PP +.P The function .BR getfsspec () searches the file from the start and returns the first entry found @@ -70,7 +70,7 @@ for which the field matches the .I special_file argument. -.PP +.P The function .BR getfsfile () searches the file from the start and returns the first entry found @@ -121,7 +121,6 @@ T} Thread safety T{ MT-Unsafe race:fsent locale T} .TE -.sp 1 .SH VERSIONS Several operating systems have these functions, for example, *BSD, SunOS, Digital UNIX, AIX (which also has a @@ -141,7 +140,7 @@ The function appeared in 4.0BSD; the other four functions appeared in 4.3BSD. .SH NOTES These functions are not thread-safe. -.PP +.P Since Linux allows mounting a block special device in several places, and since several devices can have the same mount point, where the last device with a given mount point is the interesting one, diff --git a/man3/getgrent.3 b/man3/getgrent.3 index cd5beda..66c478a 100644 --- a/man3/getgrent.3 +++ b/man3/getgrent.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:29:54 1993 by Rik Faith (faith@cs.unc.edu) -.TH getgrent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getgrent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getgrent, setgrent, endgrent \- get group file entry .SH LIBRARY @@ -18,18 +18,18 @@ Standard C library .nf .B #include .B #include -.PP +.P .B struct group *getgrent(void); -.PP +.P .B void setgrent(void); .B void endgrent(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setgrent (): .nf _XOPEN_SOURCE >= 500 @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see || /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR getgrent (), .BR endgrent (): .nf @@ -62,19 +62,19 @@ The first time .BR getgrent () is called, it returns the first entry; thereafter, it returns successive entries. -.PP +.P The .BR setgrent () function rewinds to the beginning of the group database, to allow repeated scans. -.PP +.P The .BR endgrent () function is used to close the group database after all processing has been performed. -.PP +.P The \fIgroup\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct group { @@ -86,7 +86,7 @@ struct group { }; .EE .in -.PP +.P For more information about the fields of this structure, see .BR group (5). .SH RETURN VALUE @@ -96,14 +96,14 @@ function returns a pointer to a .I group structure, or NULL if there are no more entries or an error occurs. -.PP +.P Upon error, .I errno may be set. If one wants to check .I errno after the call, it should be set to zero before the call. -.PP +.P The return value may point to a static area, and may be overwritten by subsequent calls to .BR getgrent (), @@ -180,8 +180,7 @@ T} Thread safety T{ MT-Unsafe race:grent locale T} .TE -.sp 1 -.PP +.P In the above table, .I grent in diff --git a/man3/getgrent_r.3 b/man3/getgrent_r.3 index b70c36e..f4a2b5b 100644 --- a/man3/getgrent_r.3 +++ b/man3/getgrent_r.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH getgrent_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getgrent_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getgrent_r, fgetgrent_r \- get group file entry reentrantly .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getgrent_r(struct group *restrict " gbuf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct group **restrict " gbufp ); @@ -20,18 +20,18 @@ Standard C library .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct group **restrict " gbufp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getgrent_r (): .nf _GNU_SOURCE .fi .\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug? -.PP +.P .BR fgetgrent_r (): .nf Since glibc 2.19: @@ -52,11 +52,11 @@ The former reads the next group entry from the stream initialized by .BR setgrent (3). The latter reads the next group entry from .IR stream . -.PP +.P The \fIgroup\fP structure is defined in .I as follows: -.PP +.P .in +4n .EX struct group { @@ -68,10 +68,10 @@ struct group { }; .EE .in -.PP +.P For more information about the fields of this structure, see .BR group (5). -.PP +.P The nonreentrant functions return a pointer to static storage, where this static storage contains further pointers to group name, password, and members. @@ -132,7 +132,7 @@ T} Thread safety T{ MT-Safe T} .TE -.sp 1 +.P In the above table, .I grent in @@ -147,16 +147,16 @@ are used in parallel in different threads of a program, then data races could occur. .SH VERSIONS Other systems use the prototype -.PP +.P .in +4n .EX struct group *getgrent_r(struct group *grp, char *buf, int buflen); .EE .in -.PP +.P or, better, -.PP +.P .in +4n .EX int getgrent_r(struct group *grp, char *buf, int buflen, diff --git a/man3/getgrnam.3 b/man3/getgrnam.3 index b79e15f..fb53c6e 100644 --- a/man3/getgrnam.3 +++ b/man3/getgrnam.3 @@ -11,7 +11,7 @@ .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2003-11-15 by aeb .\" -.TH getgrnam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getgrnam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry .SH LIBRARY @@ -21,10 +21,10 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "struct group *getgrnam(const char *" name ); .BI "struct group *getgrgid(gid_t " gid ); -.PP +.P .BI "int getgrnam_r(const char *restrict " name \ ", struct group *restrict " grp , .BI " char " buf "[restrict ." buflen "], size_t " buflen , @@ -33,12 +33,12 @@ Standard C library .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct group **restrict " result ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getgrnam_r (), .BR getgrgid_r (): .nf @@ -55,16 +55,16 @@ the broken-out fields of the record in the group database NIS, and LDAP) that matches the group name .IR name . -.PP +.P The .BR getgrgid () function returns a pointer to a structure containing the broken-out fields of the record in the group database that matches the group ID .IR gid . -.PP +.P The \fIgroup\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct group { @@ -76,10 +76,10 @@ struct group { }; .EE .in -.PP +.P For more information about the fields of this structure, see .BR group (5). -.PP +.P The .BR getgrnam_r () and @@ -102,15 +102,15 @@ of size A pointer to the result (in case of success) or NULL (in case no entry was found or an error occurred) is stored in .IR *result . -.PP +.P The call -.PP +.P .in +4n .EX sysconf(_SC_GETGR_R_SIZE_MAX) .EE .in -.PP +.P returns either \-1, without changing .IR errno , or an initial suggested size for @@ -134,7 +134,7 @@ is set to indicate the error. If one wants to check .I errno after the call, it should be set to zero before the call. -.PP +.P The return value may point to a static area, and may be overwritten by subsequent calls to .BR getgrent (3), @@ -143,7 +143,7 @@ or .BR getgrnam (). (Do not pass the returned pointer to .BR free (3).) -.PP +.P On success, .BR getgrnam_r () and @@ -225,7 +225,6 @@ T{ .BR getgrgid_r () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS The formulation given above under "RETURN VALUE" is from POSIX.1. .\" POSIX.1-2001, POSIX.1-2008 diff --git a/man3/getgrouplist.3 b/man3/getgrouplist.3 index 0fe3690..33e344d 100644 --- a/man3/getgrouplist.3 +++ b/man3/getgrouplist.3 @@ -7,7 +7,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getgrouplist 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getgrouplist 3 2024-03-16 "Linux man-pages 6.7" .SH NAME getgrouplist \- get list of groups to which a user belongs .SH LIBRARY @@ -16,16 +16,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getgrouplist(const char *" user ", gid_t " group , .BI " gid_t *" groups ", int *" ngroups ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getgrouplist (): .nf Since glibc 2.19: @@ -45,7 +45,7 @@ Up to .I *ngroups of these groups are returned in the array .IR groups . -.PP +.P If it was not among the groups defined for .I user in the group database, then @@ -55,7 +55,7 @@ is included in the list of groups returned by typically this argument is specified as the group ID from the password record for .IR user . -.PP +.P The .I ngroups argument is a value-result argument: @@ -73,7 +73,7 @@ is a member is less than or equal to then the value .I *ngroups is returned. -.PP +.P If the user is a member of more than .I *ngroups groups, then @@ -97,7 +97,6 @@ T{ .BR getgrouplist () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -119,7 +118,7 @@ The second command-line argument specifies the value to be supplied to .BR getgrouplist (). The following shell session shows examples of the use of this program: -.PP +.P .in +4n .EX .RB "$" " ./a.out cecilia 0" @@ -143,10 +142,10 @@ ngroups = 3 int main(int argc, char *argv[]) { - int ngroups; - struct passwd *pw; - struct group *gr; - gid_t *groups; + int ngroups; + gid_t *groups; + struct group *gr; + struct passwd *pw; \& if (argc != 3) { fprintf(stderr, "Usage: %s \en", argv[0]); @@ -180,7 +179,7 @@ main(int argc, char *argv[]) /* Display list of retrieved groups, along with group names. */ \& fprintf(stderr, "ngroups = %d\en", ngroups); - for (size_t j = 0; j < ngroups; j++) { + for (int j = 0; j < ngroups; j++) { printf("%d", groups[j]); gr = getgrgid(groups[j]); if (gr != NULL) diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3 index 620d492..01cc0f7 100644 --- a/man3/gethostbyname.3 +++ b/man3/gethostbyname.3 @@ -16,7 +16,7 @@ .\" Modified 2002-08-05, Michael Kerrisk .\" Modified 2004-10-31, Andries Brouwer .\" -.TH gethostbyname 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gethostbyname 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno, @@ -30,31 +30,31 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void sethostent(int " stayopen ); .B void endhostent(void); -.PP +.P .B [[deprecated]] extern int h_errno; -.PP +.P .BI "[[deprecated]] struct hostent *gethostbyname(const char *" name ); .BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. len ], .BI " socklen_t " len ", int " type ); -.PP +.P .BI "[[deprecated]] void herror(const char *" s ); .BI "[[deprecated]] const char *hstrerror(int " err ); -.PP +.P /* System V/POSIX extension */ .B struct hostent *gethostent(void); -.PP +.P /* GNU extensions */ .B [[deprecated]] .BI "struct hostent *gethostbyname2(const char *" name ", int " af ); -.PP +.P .BI "int gethostent_r(struct hostent *restrict " ret , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct hostent **restrict " result , .BI " int *restrict " h_errnop ); -.PP +.P .B [[deprecated]] .BI "int gethostbyaddr_r(const void " addr "[restrict ." len "], socklen_t " len , .BI " int " type , @@ -75,12 +75,12 @@ Standard C library .BI " struct hostent **restrict " result , .BI " int *restrict " h_errnop ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gethostbyname2 (), .BR gethostent_r (), .BR gethostbyaddr_r (), @@ -92,7 +92,7 @@ Feature Test Macro Requirements for glibc (see glibc up to and including 2.19: _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR herror (), .BR hstrerror (): .nf @@ -103,7 +103,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.8: none .fi -.PP +.P .BR h_errno : .nf Since glibc 2.19 @@ -127,19 +127,19 @@ Applications should use and .BR gai_strerror (3) instead. -.PP +.P The .BR sethostent () function specifies, if \fIstayopen\fP is true (1), that a connected TCP socket should be used for the name server queries and that the connection should remain open during successive queries. Otherwise, name server queries will use UDP datagrams. -.PP +.P The .BR endhostent () function ends the use of a TCP connection for name server queries. -.PP +.P The .BR gethostbyname () function returns a structure of type @@ -178,7 +178,7 @@ will first be searched for for the file format). The current domain and its parents are searched unless \fIname\fP ends in a dot. -.PP +.P The .BR gethostbyaddr () function returns a structure of type \fIhostent\fP @@ -196,17 +196,17 @@ obtained via a call to .BR inet_addr (3)) for address type .BR AF_INET . -.PP +.P The (obsolete) .BR herror () function prints the error message associated with the current value of \fIh_errno\fP on \fIstderr\fP. -.PP +.P The (obsolete) .BR hstrerror () function takes an error number (typically \fIh_errno\fP) and returns the corresponding message string. -.PP +.P The domain name queries carried out by .BR gethostbyname () and @@ -224,15 +224,15 @@ configured sources, failing that, a local name server The .BR nsswitch.conf (5) file is the modern way of controlling the order of host lookups. -.PP +.P In glibc 2.4 and earlier, the .I order keyword was used to control the order of host lookups as defined in .I /etc/host.conf .RB ( host.conf (5)). -.PP +.P The \fIhostent\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct hostent { @@ -245,7 +245,7 @@ struct hostent { #define h_addr h_addr_list[0] /* for backward compatibility */ .EE .in -.PP +.P The members of the \fIhostent\fP structure are: .TP .I h_name @@ -387,7 +387,7 @@ T{ .BR gethostbyname2_r () T} Thread safety MT-Safe env locale .TE -.sp 1 +.P In the above table, .I hostent in @@ -445,7 +445,7 @@ later calls. Copying the .I struct hostent does not suffice, since it contains pointers; a deep copy is required. -.PP +.P In the original BSD implementation the .I len argument @@ -469,7 +469,7 @@ POSIX.1-2001 makes it which is OK.) See also .BR accept (2). -.PP +.P The BSD prototype for .BR gethostbyaddr () uses @@ -498,7 +498,7 @@ glibc2 also has a that works like .BR gethostbyname (), but permits to specify the address family to which the address must belong. -.PP +.P glibc2 also has reentrant versions .BR gethostent_r (), .BR gethostbyaddr_r (), diff --git a/man3/gethostid.3 b/man3/gethostid.3 index 02a97d7..7930497 100644 --- a/man3/gethostid.3 +++ b/man3/gethostid.3 @@ -7,7 +7,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond -.TH gethostid 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gethostid 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gethostid, sethostid \- get or set the unique identifier of the current host .SH LIBRARY @@ -16,16 +16,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B long gethostid(void); .BI "int sethostid(long " hostid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gethostid (): .nf Since glibc 2.20: @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE >= 500 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED .fi -.PP +.P .BR sethostid (): .nf Since glibc 2.21: @@ -57,7 +57,7 @@ This normally resembles the Internet address for the local machine, as returned by .BR gethostbyname (3), and thus usually never needs to be set. -.PP +.P The .BR sethostid () call is restricted to the superuser. @@ -65,7 +65,7 @@ call is restricted to the superuser. .BR gethostid () returns the 32-bit identifier for the current host as set by .BR sethostid (). -.PP +.P On success, .BR sethostid () returns 0; on error, \-1 is returned, and @@ -109,7 +109,6 @@ T} Thread safety T{ MT-Unsafe const:hostid T} .TE -.sp 1 .SH VERSIONS In the glibc implementation, the .I hostid @@ -119,7 +118,7 @@ is stored in the file .I /var/adm/hostid was used.) .\" libc5 used /etc/hostid; libc4 didn't have these functions -.PP +.P In the glibc implementation, if .BR gethostid () cannot open the file containing the host ID, diff --git a/man3/getifaddrs.3 b/man3/getifaddrs.3 index 3f82c93..e8c2bde 100644 --- a/man3/getifaddrs.3 +++ b/man3/getifaddrs.3 @@ -14,7 +14,7 @@ .\" for glibc specificities, provide an example. .\" 2009-01-14 mtk, many edits and changes, rewrote example program. .\" -.TH getifaddrs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getifaddrs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getifaddrs, freeifaddrs \- get interface addresses .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int getifaddrs(struct ifaddrs **" "ifap" ); .BI "void freeifaddrs(struct ifaddrs *" "ifa" ); .fi @@ -38,7 +38,7 @@ and stores the address of the first item of the list in The list consists of .I ifaddrs structures, defined as follows: -.PP +.P .in +4n .EX struct ifaddrs { @@ -59,19 +59,19 @@ struct ifaddrs { }; .EE .in -.PP +.P The .I ifa_next field contains a pointer to the next structure on the list, or NULL if this is the last item of the list. -.PP +.P The .I ifa_name points to the null-terminated interface name. .\" The constant .\" .B IF NAMESIZE .\" indicates the maximum length of this field. -.PP +.P The .I ifa_flags field contains the interface flags, as returned by the @@ -80,7 +80,7 @@ field contains the interface flags, as returned by the operation (see .BR netdevice (7) for a list of these flags). -.PP +.P The .I ifa_addr field points to a structure containing the interface address. @@ -89,14 +89,14 @@ field points to a structure containing the interface address. subfield should be consulted to determine the format of the address structure.) This field may contain a null pointer. -.PP +.P The .I ifa_netmask field points to a structure containing the netmask associated with .IR ifa_addr , if applicable for the address family. This field may contain a null pointer. -.PP +.P Depending on whether the bit .B IFF_BROADCAST or @@ -111,12 +111,12 @@ will contain the broadcast address associated with (if applicable for the address family) or .I ifa_dstaddr will contain the destination address of the point-to-point interface. -.PP +.P The .I ifa_data field points to a buffer containing address-family-specific data; this field may be NULL if there is no such data for this interface. -.PP +.P The data returned by .BR getifaddrs () is dynamically allocated and should be freed using @@ -157,7 +157,6 @@ T{ .BR freeifaddrs () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -179,7 +178,7 @@ differs on various systems. .\" appears to be confused and obsolete on this point. .\" i.e., commonly it still says one of them will be NULL, even if .\" the ifa_ifu union is already present -.PP +.P .BR getifaddrs () first appeared in glibc 2.3, but before glibc 2.3.3, the implementation supported only IPv4 addresses; @@ -210,7 +209,7 @@ The program below demonstrates the use of and .BR getnameinfo (3). Here is what we see when running this program on one system: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man3/getipnodebyname.3 b/man3/getipnodebyname.3 index 5babfeb..23bb958 100644 --- a/man3/getipnodebyname.3 +++ b/man3/getipnodebyname.3 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" References: RFC 2553 -.TH getipnodebyname 3 2023-03-30 "Linux man-pages 6.05.01" +.TH getipnodebyname 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getipnodebyname, getipnodebyaddr, freehostent \- get network hostnames and addresses @@ -15,7 +15,7 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "[[deprecated]] struct hostent *getipnodebyname(const char *" name ", int " af , .BI " int " flags ", int *" error_num ); .BI "[[deprecated]] struct hostent *getipnodebyaddr(const void " addr [. len ], @@ -30,7 +30,7 @@ Use and .BR getnameinfo (3) instead. -.PP +.P The .BR getipnodebyname () and @@ -38,7 +38,7 @@ and functions return the names and addresses of a network host. These functions return a pointer to the following structure: -.PP +.P .in +4n .EX struct hostent { @@ -50,7 +50,7 @@ struct hostent { }; .EE .in -.PP +.P These functions replace the .BR gethostbyname (3) and @@ -61,7 +61,7 @@ The and .BR getipnodebyaddr () functions can access multiple network address families. -.PP +.P Unlike the .B gethostby functions, @@ -95,7 +95,7 @@ The .I name argument points to a hexadecimal IPv6 address or a name of an IPv6 network host. -.PP +.P The .I flags argument specifies additional options. @@ -185,7 +185,7 @@ The domain name server returned a permanent failure response. .B TRY_AGAIN The domain name server returned a temporary failure response. You might have better luck next time. -.PP +.P A successful query returns a pointer to a .I hostent structure that contains the following fields: @@ -242,7 +242,7 @@ None. .SH HISTORY .\" Not in POSIX.1-2001. RFC\ 2553. -.PP +.P Present in glibc 2.1.91-95, but removed again. Several UNIX-like systems support them, but all call them deprecated. diff --git a/man3/getline.3 b/man3/getline.3 index 2b9d74a..991993e 100644 --- a/man3/getline.3 +++ b/man3/getline.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getline 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getline 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getline, getdelim \- delimited string input .SH LIBRARY @@ -13,18 +13,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t getline(char **restrict " lineptr ", size_t *restrict " n , .BI " FILE *restrict " stream ); .BI "ssize_t getdelim(char **restrict " lineptr ", size_t *restrict " n , .BI " int " delim ", FILE *restrict " stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getline (), .BR getdelim (): .nf @@ -40,7 +40,7 @@ storing the address of the buffer containing the text into .IR *lineptr . The buffer is null-terminated and includes the newline character, if one was found. -.PP +.P If .I *lineptr is set to NULL before the call, then @@ -50,7 +50,7 @@ This buffer should be freed by the user program even if .BR getline () failed. -.PP +.P Alternatively, before calling .BR getline (), .I *lineptr @@ -68,13 +68,13 @@ updating and .I *n as necessary. -.PP +.P In either case, on a successful call, .I *lineptr and .I *n will be updated to reflect the buffer address and allocated size respectively. -.PP +.P .BR getdelim () works like .BR getline (), @@ -94,13 +94,13 @@ return the number of characters read, including the delimiter character, but not including the terminating null byte (\[aq]\e0\[aq]). This value can be used to handle embedded null bytes in the line read. -.PP +.P Both functions return \-1 on failure to read a line (including end-of-file condition). In the event of a failure, .I errno is set to indicate the error. -.PP +.P If .I *lineptr was set to NULL before the call, then the buffer should be freed by the @@ -133,7 +133,6 @@ T{ .BR getdelim () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/getloadavg.3 b/man3/getloadavg.3 index 5be1ab9..e328282 100644 --- a/man3/getloadavg.3 +++ b/man3/getloadavg.3 @@ -8,7 +8,7 @@ .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH getloadavg 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getloadavg 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getloadavg \- get system load averages .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getloadavg(double " loadavg[] ", int " nelem ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getloadavg (): .nf Since glibc 2.19: @@ -61,7 +61,6 @@ T{ .BR getloadavg () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY diff --git a/man3/getlogin.3 b/man3/getlogin.3 index 5b88d77..bdf8376 100644 --- a/man3/getlogin.3 +++ b/man3/getlogin.3 @@ -6,7 +6,7 @@ .\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3 .\" added ref to /etc/utmp, added BUGS section, etc. .\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use -.TH getlogin 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getlogin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getlogin, getlogin_r, cuserid \- get username .SH LIBRARY @@ -15,26 +15,26 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "char *getlogin(void);" .BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize ); -.PP +.P .B #include -.PP +.P .BI "char *cuserid(char *" string ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getlogin_r (): .nf .\" Deprecated: _REENTRANT || _POSIX_C_SOURCE >= 199506L .fi -.PP +.P .BR cuserid (): .nf Since glibc 2.24: @@ -52,13 +52,13 @@ The string is statically allocated and might be overwritten on subsequent calls to this function or to .BR cuserid (). -.PP +.P .BR getlogin_r () returns this same username in the array .I buf of size .IR bufsize . -.PP +.P .BR cuserid () returns a pointer to a string containing a username associated with the effective user ID of the process. @@ -70,18 +70,18 @@ This string is statically allocated and might be overwritten on subsequent calls to this function or to .BR getlogin (). -.PP +.P The macro \fBL_cuserid\fP is an integer constant that indicates how long an array you might need to store a username. \fBL_cuserid\fP is declared in \fI\fP. -.PP +.P These functions let your program identify positively the user who is running .RB ( cuserid ()) or the user who logged in this session .RB ( getlogin ()). (These can differ when set-user-ID programs are involved.) -.PP +.P For most purposes, it is more useful to use the environment variable \fBLOGNAME\fP to find out who the user is. This is more flexible @@ -111,7 +111,7 @@ The calling process has no controlling terminal. The length of the username, including the terminating null byte (\[aq]\e0\[aq]), is larger than .IR bufsize . -.PP +.P Linux/glibc also has: .TP .B ENOENT @@ -169,7 +169,7 @@ T} Thread safety T{ MT-Unsafe race:cuserid/!string locale T} .TE -.sp 1 +.P In the above table, .I utent in @@ -232,7 +232,7 @@ of our program need not be the user who started it. Avoid .BR getlogin () for security-related purposes. -.PP +.P Note that glibc does not follow the POSIX specification and uses .I stdin instead of @@ -242,7 +242,7 @@ A bug. all return the login name also when .I stdin is redirected.) -.PP +.P Nobody knows precisely what .BR cuserid () does; avoid it in portable programs. diff --git a/man3/getmntent.3 b/man3/getmntent.3 index 9bfa296..cf90b17 100644 --- a/man3/getmntent.3 +++ b/man3/getmntent.3 @@ -10,7 +10,7 @@ .\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 961109, 031115, aeb .\" -.TH getmntent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getmntent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getmntent, setmntent, addmntent, endmntent, hasmntopt, getmntent_r \- get filesystem descriptor file entry @@ -21,31 +21,31 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "FILE *setmntent(const char *" filename ", const char *" type ); -.PP +.P .BI "struct mntent *getmntent(FILE *" stream ); -.PP +.P .BI "int addmntent(FILE *restrict " stream , .BI " const struct mntent *restrict " mnt ); -.PP +.P .BI "int endmntent(FILE *" streamp ); -.PP +.P .BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt ); -.PP +.P /* GNU extension */ .B #include -.PP +.P .BI "struct mntent *getmntent_r(FILE *restrict " streamp , .BI " struct mntent *restrict " mntbuf , .BI " char " buf "[restrict ." buflen "], int " buflen ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getmntent_r (): .nf Since glibc 2.19: @@ -58,7 +58,7 @@ These routines are used to access the filesystem description file .I /etc/fstab and the mounted filesystem description file .IR /etc/mtab . -.PP +.P The .BR setmntent () function opens the filesystem description file @@ -76,7 +76,7 @@ The returned stream should be closed using .BR endmntent () rather than .BR fclose (3). -.PP +.P The .BR getmntent () function reads the next line of the filesystem @@ -88,7 +88,7 @@ The pointer points to a static area of memory which is overwritten by subsequent calls to .BR getmntent (). -.PP +.P The .BR addmntent () function adds the @@ -98,13 +98,13 @@ structure to the end of the open .IR stream . -.PP +.P The .BR endmntent () function closes the .I stream associated with the filesystem description file. -.PP +.P The .BR hasmntopt () function scans the @@ -121,7 +121,7 @@ See and .BR mount (8) for valid mount options. -.PP +.P The reentrant .BR getmntent_r () function is similar to @@ -136,13 +136,13 @@ in the provided array .I buf of size .IR buflen . -.PP +.P The .I mntent structure is defined in .I as follows: -.PP +.P .in +4n .EX struct mntent { @@ -155,7 +155,7 @@ struct mntent { }; .EE .in -.PP +.P Since fields in the mtab and fstab files are separated by whitespace, octal escapes are used to represent the characters space (\e040), tab (\e011), newline (\e012), and backslash (\e\e) in those files @@ -179,15 +179,15 @@ functions return a pointer to the .I mntent structure or NULL on failure. -.PP +.P The .BR addmntent () function returns 0 on success and 1 on failure. -.PP +.P The .BR endmntent () function always returns 1. -.PP +.P The .BR hasmntopt () function returns the address of the substring if @@ -238,7 +238,6 @@ T{ .BR getmntent_r () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -248,7 +247,7 @@ A routine was introduced in HP-UX 10, but it returns an .IR int . The prototype shown above is glibc-only. -.PP +.P System V also has a .BR getmntent () function but the calling sequence diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3 index 580a265..c1453ba 100644 --- a/man3/getnameinfo.3 +++ b/man3/getnameinfo.3 @@ -8,7 +8,7 @@ .\" 2004-12-14, mtk, Added EAI_OVERFLOW error .\" 2004-12-14 Fixed description of error return .\" -.TH getnameinfo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getnameinfo 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getnameinfo \- address-to-name translation in protocol-independent manner .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int getnameinfo(const struct sockaddr *restrict " addr \ ", socklen_t " addrlen , .BI " char " host "[_Nullable restrict ." hostlen ], @@ -27,12 +27,12 @@ Standard C library .BI " socklen_t " servlen , .BI " int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getnameinfo (): .nf Since glibc 2.22: @@ -55,7 +55,7 @@ but unlike those functions, .BR getnameinfo () is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies. -.PP +.P The .I addr argument is a pointer to a generic socket address structure @@ -78,7 +78,7 @@ respectively) into which .BR getnameinfo () places null-terminated strings containing the host and service names respectively. -.PP +.P The caller can specify that no hostname (or no service name) is required by providing a NULL .I host @@ -91,7 +91,7 @@ argument or a zero argument. However, at least one of hostname or service name must be requested. -.PP +.P The .I flags argument modifies the behavior of @@ -140,7 +140,9 @@ converted from IDN format to the locale's encoding if necessary. ASCII-only names are not affected by the conversion, which makes this flag usable in existing programs and environments. .TP -.BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES +.B NI_IDN_ALLOW_UNASSIGNED +.TQ +.B NI_IDN_USE_STD3_ASCII_RULES Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 @@ -200,7 +202,7 @@ was too small. A system error occurred. The error code can be found in .IR errno . -.PP +.P The .BR gai_strerror (3) function translates these error codes to a human readable string, @@ -225,14 +227,13 @@ T{ .BR getnameinfo () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. RFC\ 2553. .SH HISTORY glibc 2.1. POSIX.1-2001. -.PP +.P Before glibc 2.2, the .I hostlen and @@ -244,14 +245,14 @@ In order to assist the programmer in choosing reasonable sizes for the supplied buffers, .I defines the constants -.PP +.P .in +4n .EX #define NI_MAXHOST 1025 #define NI_MAXSERV 32 .EE .in -.PP +.P Since glibc 2.8, these definitions are exposed only if suitable feature test macros are defined, namely: @@ -262,7 +263,7 @@ or (in glibc versions up to and including 2.19) .B _BSD_SOURCE or .BR _SVID_SOURCE . -.PP +.P The former is the constant .B MAXDNAME in recent versions of BIND's @@ -275,7 +276,7 @@ The following code tries to get the numeric hostname and service name, for a given socket address. Note that there is no hardcoded reference to a particular address family. -.PP +.P .in +4n .EX struct sockaddr *addr; /* input */ @@ -287,10 +288,10 @@ if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf, printf("host=%s, serv=%s\en", hbuf, sbuf); .EE .in -.PP +.P The following version checks if the socket address has a reverse address mapping. -.PP +.P .in +4n .EX struct sockaddr *addr; /* input */ @@ -304,7 +305,7 @@ else printf("host=%s\en", hbuf); .EE .in -.PP +.P An example program using .BR getnameinfo () can be found in @@ -324,17 +325,17 @@ can be found in .BR services (5), .BR hostname (7), .BR named (8) -.PP +.P R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens, .IR "Basic Socket Interface Extensions for IPv6" , RFC\ 2553, March 1999. -.PP +.P Tatsuya Jinmei and Atsushi Onoe, .IR "An Extension of Format for IPv6 Scoped Addresses" , internet draft, work in progress .UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt .UE . -.PP +.P Craig Metz, .IR "Protocol Independence Using the Sockets API" , Proceedings of the freenix track: diff --git a/man3/getnetent.3 b/man3/getnetent.3 index 9a58458..4ec28e1 100644 --- a/man3/getnetent.3 +++ b/man3/getnetent.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 21:48:06 1993 by Rik Faith (faith@cs.unc.edu) -.TH getnetent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getnetent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getnetent, getnetbyname, getnetbyaddr, setnetent, endnetent \- get network entry @@ -18,12 +18,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct netent *getnetent(void); -.PP +.P .BI "struct netent *getnetbyname(const char *" name ); .BI "struct netent *getnetbyaddr(uint32_t " net ", int " type ); -.PP +.P .BI "void setnetent(int " stayopen ); .B void endnetent(void); .fi @@ -36,7 +36,7 @@ and returns a structure containing the broken-out fields from the entry. A connection is opened to the database if necessary. -.PP +.P The .BR getnetbyname () function returns a @@ -45,7 +45,7 @@ structure for the entry from the database that matches the network .IR name . -.PP +.P The .BR getnetbyaddr () function returns a @@ -59,7 +59,7 @@ of type The .I net argument must be in host byte order. -.PP +.P The .BR setnetent () function opens a connection to the database, @@ -71,17 +71,17 @@ then the connection to the database will not be closed between calls to one of the .BR getnet* () functions. -.PP +.P The .BR endnetent () function closes the connection to the database. -.PP +.P The .I netent structure is defined in .I as follows: -.PP +.P .in +4n .EX struct netent { @@ -92,7 +92,7 @@ struct netent { } .EE .in -.PP +.P The members of the .I netent structure are: @@ -174,7 +174,7 @@ MT-Unsafe race:netent env locale T} .TE -.sp 1 +.P In the above table, .I netent in @@ -190,7 +190,7 @@ then data races could occur. POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P Before glibc 2.2, the .I net argument of diff --git a/man3/getnetent_r.3 b/man3/getnetent_r.3 index eda9652..fabb4c5 100644 --- a/man3/getnetent_r.3 +++ b/man3/getnetent_r.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getnetent_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getnetent_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getnetent_r, getnetbyname_r, getnetbyaddr_r \- get network entry (reentrant) @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getnetent_r(struct netent *restrict " result_buf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct netent **restrict " result , @@ -29,13 +29,13 @@ Standard C library .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct netent **restrict " result , .BI " int *restrict " h_errnop ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getnetent_r (), .BR getnetbyname_r (), .BR getnetbyaddr_r (): @@ -62,13 +62,13 @@ structure is returned, and in the function calling signature and return value. This manual page describes just the differences from the nonreentrant functions. -.PP +.P Instead of returning a pointer to a statically allocated .I netent structure as the function result, these functions copy the structure into the location pointed to by .IR result_buf . -.PP +.P The .I buf array is used to store the string fields pointed to by the returned @@ -85,7 +85,7 @@ and the caller must try again with a larger buffer. (A buffer of length 1024 bytes should be sufficient for most applications.) .\" I can find no information on the required/recommended buffer size; .\" the nonreentrant functions use a 1024 byte buffer -- mtk. -.PP +.P If the function call successfully obtains a network record, then .I *result is set pointing to @@ -93,7 +93,7 @@ is set pointing to otherwise, .I *result is set to NULL. -.PP +.P The buffer pointed to by .I h_errnop is used to return the value that would be stored in the global variable @@ -104,7 +104,7 @@ by the nonreentrant versions of these functions. .SH RETURN VALUE On success, these functions return 0. On error, they return one of the positive error numbers listed in ERRORS. -.PP +.P On error, record not found .RB ( getnetbyname_r (), .BR getnetbyaddr_r ()), @@ -140,7 +140,6 @@ T{ .BR getnetbyaddr_r () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS Functions with similar names exist on some other systems, though typically with different calling signatures. diff --git a/man3/getopt.3 b/man3/getopt.3 index 88fd167..71c3675 100644 --- a/man3/getopt.3 +++ b/man3/getopt.3 @@ -20,7 +20,7 @@ .\" the start of optstring .\" Modified 2006-12-15, mtk, Added getopt() example program. .\" -.TH getopt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getopt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt \- Parse command-line options @@ -30,15 +30,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getopt(int " argc ", char *" argv [], .BI " const char *" optstring ); -.PP +.P .BI "extern char *" optarg ; .BI "extern int " optind ", " opterr ", " optopt ; -.PP +.P .B #include -.PP +.P .BI "int getopt_long(int " argc ", char *" argv [], .BI " const char *" optstring , .BI " const struct option *" longopts ", int *" longindex ); @@ -46,17 +46,17 @@ Standard C library .BI " const char *" optstring , .BI " const struct option *" longopts ", int *" longindex ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getopt (): .nf _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE .fi -.PP +.P .BR getopt_long (), .BR getopt_long_only (): .nf @@ -82,7 +82,7 @@ If .BR getopt () is called repeatedly, it returns successively each of the option characters from each of the option elements. -.PP +.P The variable .I optind is the index of the next element to be processed in @@ -91,7 +91,7 @@ The system initializes this value to 1. The caller can reset it to 1 to restart scanning of the same .IR argv , or when scanning a new argument vector. -.PP +.P If .BR getopt () finds another option character, it returns that @@ -101,13 +101,13 @@ variable \fInextchar\fP so that the next call to can resume the scan with the following option character or \fIargv\fP-element. -.PP +.P If there are no more option characters, .BR getopt () returns \-1. Then \fIoptind\fP is the index in \fIargv\fP of the first \fIargv\fP-element that is not an option. -.PP +.P .I optstring is a string containing the legitimate option characters. A legitimate option character is any visible one byte @@ -139,7 +139,7 @@ is treated as the long option option is reserved by POSIX.2 for implementation extensions.) This behavior is a GNU extension, not available with libraries before glibc 2. -.PP +.P By default, .BR getopt () permutes the contents of \fIargv\fP as it @@ -166,7 +166,7 @@ written to expect options and other \fIargv\fP-elements in any order and that care about the ordering of the two.) The special argument "\-\-" forces an end of option-scanning regardless of the scanning mode. -.PP +.P While processing the option list, .BR getopt () can detect two kinds of errors: @@ -220,14 +220,14 @@ may take a parameter, of the form .B \-\-arg=param or .BR "\-\-arg param" . -.PP +.P .I longopts is a pointer to the first element of an array of .I struct option declared in .I as -.PP +.P .in +4n .EX struct option { @@ -238,7 +238,7 @@ struct option { }; .EE .in -.PP +.P The meanings of the different fields are: .TP .I name @@ -267,13 +267,13 @@ option is found, but left unchanged if the option is not found. \fIval\fP is the value to return, or to load into the variable pointed to by \fIflag\fP. -.PP +.P The last element of the array has to be filled with zeros. -.PP +.P If \fIlongindex\fP is not NULL, it points to a variable which is set to the index of the long option relative to .IR longopts . -.PP +.P .BR getopt_long_only () is like .BR getopt_long (), @@ -301,7 +301,7 @@ then the return value depends on the first character in .IR optstring : if it is \[aq]:\[aq], then \[aq]:\[aq] is returned; otherwise \[aq]?\[aq] is returned. -.PP +.P .BR getopt_long () and .BR getopt_long_only () @@ -347,7 +347,6 @@ T} Thread safety T{ MT-Unsafe race:getopt env T} .TE -.sp 1 .SH VERSIONS POSIX specifies that the .I argv @@ -378,7 +377,7 @@ is a GNU extension. .TP .BR getopt () POSIX.1-2001, and POSIX.2. -.PP +.P On some older implementations, .BR getopt () was declared in @@ -411,7 +410,7 @@ routine that rechecks .B POSIXLY_CORRECT and checks for GNU extensions in .IR optstring .) -.PP +.P Command-line arguments are parsed in strict order meaning that an option requiring an argument will consume the next argument, regardless of whether that argument is the correctly specified option argument @@ -438,7 +437,7 @@ to handle two program options: with no associated value; and .IR "\-t val" , which expects an associated value. -.PP +.P .\" SRC BEGIN (getopt.c) .EX #include @@ -490,7 +489,7 @@ main(int argc, char *argv[]) The following example program illustrates the use of .BR getopt_long () with most of its features. -.PP +.P .\" SRC BEGIN (getopt_long.c) .EX #include diff --git a/man3/getpass.3 b/man3/getpass.3 index 359ebd4..40420c9 100644 --- a/man3/getpass.3 +++ b/man3/getpass.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH getpass 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getpass 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getpass \- get a password .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] char *getpass(const char *" prompt ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpass (): .nf Since glibc 2.2.2: @@ -39,7 +39,7 @@ see the description of the .I ECHO flag in .BR termios (3). -.PP +.P The .BR getpass () function opens @@ -81,7 +81,6 @@ T{ .BR getpass () T} Thread safety MT-Unsafe term .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -113,7 +112,7 @@ You should use instead .BR readpassphrase (3bsd), provided by .IR libbsd . -.PP +.P In the GNU C library implementation, if .I /dev/tty cannot be opened, the prompt is written to @@ -122,7 +121,7 @@ and the password is read from .IR stdin . There is no limit on the length of the password. Line editing is not disabled. -.PP +.P According to SUSv2, the value of .B PASS_MAX must be defined in diff --git a/man3/getprotoent.3 b/man3/getprotoent.3 index 8aad2d3..1eb9773 100644 --- a/man3/getprotoent.3 +++ b/man3/getprotoent.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:26:03 1993 by Rik Faith (faith@cs.unc.edu) -.TH getprotoent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getprotoent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getprotoent, getprotobyname, getprotobynumber, setprotoent, endprotoent \- get protocol entry @@ -18,12 +18,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct protoent *getprotoent(void); -.PP +.P .BI "struct protoent *getprotobyname(const char *" name ); .BI "struct protoent *getprotobynumber(int " proto ); -.PP +.P .BI "void setprotoent(int " stayopen ); .B void endprotoent(void); .fi @@ -37,7 +37,7 @@ and returns a structure containing the broken-out fields from the entry. A connection is opened to the database if necessary. -.PP +.P The .BR getprotobyname () function returns a @@ -47,7 +47,7 @@ for the entry from the database that matches the protocol name .IR name . A connection is opened to the database if necessary. -.PP +.P The .BR getprotobynumber () function returns a @@ -57,7 +57,7 @@ for the entry from the database that matches the protocol number .IR number . A connection is opened to the database if necessary. -.PP +.P The .BR setprotoent () function opens a connection to the database, @@ -69,17 +69,17 @@ then the connection to the database will not be closed between calls to one of the .BR getproto* () functions. -.PP +.P The .BR endprotoent () function closes the connection to the database. -.PP +.P The .I protoent structure is defined in .I as follows: -.PP +.P .in +4n .EX struct protoent { @@ -89,7 +89,7 @@ struct protoent { } .EE .in -.PP +.P The members of the .I protoent structure are: @@ -169,7 +169,7 @@ MT-Unsafe race:protoent locale T} .TE -.sp 1 +.P In the above table, .I protoent in diff --git a/man3/getprotoent_r.3 b/man3/getprotoent_r.3 index 5028e4f..d802b4c 100644 --- a/man3/getprotoent_r.3 +++ b/man3/getprotoent_r.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getprotoent_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getprotoent_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getprotoent_r, getprotobyname_r, getprotobynumber_r \- get protocol entry (reentrant) @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getprotoent_r(struct protoent *restrict " result_buf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct protoent **restrict " result ); @@ -26,13 +26,13 @@ Standard C library .BI " struct protoent *restrict " result_buf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct protoent **restrict " result ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getprotoent_r (), .BR getprotobyname_r (), .BR getprotobynumber_r (): @@ -59,13 +59,13 @@ structure is returned, and in the function calling signature and return value. This manual page describes just the differences from the nonreentrant functions. -.PP +.P Instead of returning a pointer to a statically allocated .I protoent structure as the function result, these functions copy the structure into the location pointed to by .IR result_buf . -.PP +.P The .I buf array is used to store the string fields pointed to by the returned @@ -83,7 +83,7 @@ and the caller must try again with a larger buffer. .\" I can find no information on the required/recommended buffer size; .\" the nonreentrant functions use a 1024 byte buffer. .\" The 1024 byte value is also what the Solaris man page suggests. -- mtk -.PP +.P If the function call successfully obtains a protocol record, then .I *result is set pointing to @@ -94,7 +94,7 @@ is set to NULL. .SH RETURN VALUE On success, these functions return 0. On error, they return one of the positive error numbers listed in ERRORS. -.PP +.P On error, record not found .RB ( getprotobyname_r (), .BR getprotobynumber_r ()), @@ -130,7 +130,6 @@ T{ .BR getprotobynumber_r () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS Functions with similar names exist on some other systems, though typically with different calling signatures. @@ -150,7 +149,7 @@ fails with the error .BR ERANGE , the program retries with larger buffer sizes. The following shell session shows a couple of sample runs: -.PP +.P .in +4n .EX .RB "$" " ./a.out tcp 1" diff --git a/man3/getpt.3 b/man3/getpt.3 index 6434f90..fa6cd1c 100644 --- a/man3/getpt.3 +++ b/man3/getpt.3 @@ -5,7 +5,7 @@ .\" Redistribute and modify at will. .\" %%%LICENSE_END .\" -.TH getpt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getpt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getpt \- open a new pseudoterminal master .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .B "int getpt(void);" .fi .SH DESCRIPTION @@ -23,13 +23,13 @@ Standard C library opens a new pseudoterminal device and returns a file descriptor that refers to that device. It is equivalent to opening the pseudoterminal multiplexor device -.PP +.P .in +4n .EX open("/dev/ptmx", O_RDWR); .EE .in -.PP +.P on Linux systems, though the pseudoterminal multiplexor device is located elsewhere on some systems that use the GNU C library. .SH RETURN VALUE @@ -57,7 +57,6 @@ T{ .BR getpt () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Use .BR posix_openpt (3) diff --git a/man3/getpw.3 b/man3/getpw.3 index b94e117..70b53ec 100644 --- a/man3/getpw.3 +++ b/man3/getpw.3 @@ -10,7 +10,7 @@ .\" Modified Sat Jul 24 19:23:25 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) .\" -.TH getpw 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getpw 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getpw \- reconstruct password line entry .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include .B #include -.PP +.P .BI "[[deprecated]] int getpw(uid_t " uid ", char *" buf ); .fi .SH DESCRIPTION @@ -30,15 +30,15 @@ The function reconstructs the password line entry for the given user ID \fIuid\fP in the buffer \fIbuf\fP. The returned buffer contains a line of format -.PP +.P .in +4n .EX .B name:passwd:uid:gid:gecos:dir:shell .EE .in -.PP +.P The \fIpasswd\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct passwd { @@ -52,7 +52,7 @@ struct passwd { }; .EE .in -.PP +.P For more information about the fields of this structure, see .BR passwd (5). .SH RETURN VALUE @@ -61,7 +61,7 @@ The function returns 0 on success; on error, it returns \-1, and .I errno is set to indicate the error. -.PP +.P If .I uid is not found in the password database, @@ -103,7 +103,6 @@ T{ .BR getpw () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/getpwent.3 b/man3/getpwent.3 index c46af20..cd8ba99 100644 --- a/man3/getpwent.3 +++ b/man3/getpwent.3 @@ -11,7 +11,7 @@ .\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) .\" -.TH getpwent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getpwent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getpwent, setpwent, endpwent \- get password file entry .SH LIBRARY @@ -21,17 +21,17 @@ Standard C library .nf .B #include .B #include -.PP +.P .B struct passwd *getpwent(void); .B void setpwent(void); .B void endpwent(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpwent (), .BR setpwent (), .BR endpwent (): @@ -53,19 +53,19 @@ The first time .BR getpwent () is called, it returns the first entry; thereafter, it returns successive entries. -.PP +.P The .BR setpwent () function rewinds to the beginning of the password database. -.PP +.P The .BR endpwent () function is used to close the password database after all processing has been performed. -.PP +.P The \fIpasswd\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct passwd { @@ -79,7 +79,7 @@ struct passwd { }; .EE .in -.PP +.P For more information about the fields of this structure, see .BR passwd (5). .SH RETURN VALUE @@ -95,7 +95,7 @@ is set to indicate the error. If one wants to check .I errno after the call, it should be set to zero before the call. -.PP +.P The return value may point to a static area, and may be overwritten by subsequent calls to .BR getpwent (), @@ -161,7 +161,7 @@ T} Thread safety T{ MT-Unsafe race:pwent locale T} .TE -.sp 1 +.P In the above table, .I pwent in diff --git a/man3/getpwent_r.3 b/man3/getpwent_r.3 index 1cefc57..6b4b34a 100644 --- a/man3/getpwent_r.3 +++ b/man3/getpwent_r.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH getpwent_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getpwent_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getpwent_r, fgetpwent_r \- get passwd file entry reentrantly .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getpwent_r(struct passwd *restrict " pwbuf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct passwd **restrict " pwbufp ); @@ -21,12 +21,12 @@ Standard C library .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct passwd **restrict " pwbufp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpwent_r (), .nf Since glibc 2.19: @@ -34,7 +34,7 @@ Feature Test Macro Requirements for glibc (see glibc 2.19 and earlier: _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR fgetpwent_r (): .nf Since glibc 2.19: @@ -55,11 +55,11 @@ The former reads the next passwd entry from the stream initialized by .BR setpwent (3). The latter reads the next passwd entry from .IR stream . -.PP +.P The \fIpasswd\fP structure is defined in .I as follows: -.PP +.P .in +4n .EX struct passwd { @@ -73,10 +73,10 @@ struct passwd { }; .EE .in -.PP +.P For more information about the fields of this structure, see .BR passwd (5). -.PP +.P The nonreentrant functions return a pointer to static storage, where this static storage contains further pointers to user name, password, gecos field, home directory and shell. @@ -133,7 +133,7 @@ T{ .BR fgetpwent_r () T} Thread safety MT-Safe .TE -.sp 1 +.P In the above table, .I pwent in @@ -148,16 +148,16 @@ are used in parallel in different threads of a program, then data races could occur. .SH VERSIONS Other systems use the prototype -.PP +.P .in +4n .EX struct passwd * getpwent_r(struct passwd *pwd, char *buf, int buflen); .EE .in -.PP +.P or, better, -.PP +.P .in +4n .EX int diff --git a/man3/getpwnam.3 b/man3/getpwnam.3 index 3e6af83..424ee55 100644 --- a/man3/getpwnam.3 +++ b/man3/getpwnam.3 @@ -15,7 +15,7 @@ .\" Modified 2003-11-15 by aeb .\" 2008-11-07, mtk, Added an example program for getpwnam_r(). .\" -.TH getpwnam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getpwnam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry .SH LIBRARY @@ -25,10 +25,10 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "struct passwd *getpwnam(const char *" name ); .BI "struct passwd *getpwuid(uid_t " uid ); -.PP +.P .BI "int getpwnam_r(const char *restrict " name ", \ struct passwd *restrict " pwd , .BI " char " buf "[restrict ." buflen "], size_t " buflen , @@ -37,12 +37,12 @@ struct passwd *restrict " pwd , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct passwd **restrict " result ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getpwnam_r (), .BR getpwuid_r (): .nf @@ -59,16 +59,16 @@ the broken-out fields of the record in the password database NIS, and LDAP) that matches the username .IR name . -.PP +.P The .BR getpwuid () function returns a pointer to a structure containing the broken-out fields of the record in the password database that matches the user ID .IR uid . -.PP +.P The \fIpasswd\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct passwd { @@ -82,11 +82,11 @@ struct passwd { }; .EE .in -.PP +.P See .BR passwd (5) for more information about these fields. -.PP +.P The .BR getpwnam_r () and @@ -108,15 +108,15 @@ of size A pointer to the result (in case of success) or NULL (in case no entry was found or an error occurred) is stored in .IR *result . -.PP +.P The call -.PP +.P .in +4n .EX sysconf(_SC_GETPW_R_SIZE_MAX) .EE .in -.PP +.P returns either \-1, without changing .IR errno , or an initial suggested size for @@ -140,7 +140,7 @@ is set to indicate the error. If one wants to check .I errno after the call, it should be set to zero before the call. -.PP +.P The return value may point to a static area, and may be overwritten by subsequent calls to .BR getpwent (3), @@ -149,7 +149,7 @@ or .BR getpwuid (). (Do not pass the returned pointer to .BR free (3).) -.PP +.P On success, .BR getpwnam_r () and @@ -235,7 +235,6 @@ T} Thread safety T{ MT-Safe locale T} .TE -.sp 1 .SH VERSIONS The .I pw_gecos @@ -265,7 +264,7 @@ situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others. .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM .\" SunOS 5.8 - gives EBADF .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 -.PP +.P The .I pw_dir field contains the name of the initial working directory of the user. @@ -288,7 +287,7 @@ The program below demonstrates the use of .BR getpwnam_r () to find the full username and user ID for the username supplied as a command-line argument. -.PP +.P .\" SRC BEGIN (getpwnam.c) .EX #include diff --git a/man3/getrpcent.3 b/man3/getrpcent.3 index be94a0e..253b7ca 100644 --- a/man3/getrpcent.3 +++ b/man3/getrpcent.3 @@ -6,7 +6,7 @@ .\" %%%LICENSE_END .\" .\" @(#)getrpcent.3n 2.2 88/08/02 4.0 RPCSRC; from 1.11 88/03/14 SMI -.TH getrpcent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getrpcent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getrpcent, getrpcbyname, getrpcbynumber, setrpcent, endrpcent \- get RPC entry @@ -16,12 +16,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct rpcent *getrpcent(void); -.PP +.P .BI "struct rpcent *getrpcbyname(const char *" name ); .BI "struct rpcent *getrpcbynumber(int " number ); -.PP +.P .BI "void setrpcent(int " stayopen ); .B void endrpcent(void); .fi @@ -34,7 +34,7 @@ and functions each return a pointer to an object with the following structure containing the broken-out fields of an entry in the RPC program number data base. -.PP +.P .in +4n .EX struct rpcent { @@ -44,7 +44,7 @@ struct rpcent { }; .EE .in -.PP +.P The members of this structure are: .TP .I r_name @@ -55,12 +55,12 @@ A NULL-terminated list of alternate names for the RPC program. .TP .I r_number The RPC program number for this service. -.PP +.P The .BR getrpcent () function reads the next entry from the database. A connection is opened to the database if necessary. -.PP +.P The .BR setrpcent () function opens a connection to the database, @@ -72,11 +72,11 @@ then the connection to the database will not be closed between calls to one of the .BR getrpc* () functions. -.PP +.P The .BR endrpcent () function closes the connection to the database. -.PP +.P The .BR getrpcbyname () and @@ -120,7 +120,6 @@ T{ .BR endrpcent () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY diff --git a/man3/getrpcent_r.3 b/man3/getrpcent_r.3 index fd58a9f..c33f3b6 100644 --- a/man3/getrpcent_r.3 +++ b/man3/getrpcent_r.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getrpcent_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getrpcent_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getrpcent_r, getrpcbyname_r, getrpcbynumber_r \- get RPC entry (reentrant) @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getrpcent_r(struct rpcent *" result_buf ", char " buf [. buflen ], .BI " size_t " buflen ", struct rpcent **" result ); .BI "int getrpcbyname_r(const char *" name , @@ -23,13 +23,13 @@ Standard C library .BI "int getrpcbynumber_r(int " number , .BI " struct rpcent *" result_buf ", char " buf [. buflen ], .BI " size_t " buflen ", struct rpcent **" result ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getrpcent_r (), .BR getrpcbyname_r (), .BR getrpcbynumber_r (): @@ -56,13 +56,13 @@ structure is returned, and in the function calling signature and return value. This manual page describes just the differences from the nonreentrant functions. -.PP +.P Instead of returning a pointer to a statically allocated .I rpcent structure as the function result, these functions copy the structure into the location pointed to by .IR result_buf . -.PP +.P The .I buf array is used to store the string fields pointed to by the returned @@ -79,7 +79,7 @@ and the caller must try again with a larger buffer. (A buffer of length 1024 bytes should be sufficient for most applications.) .\" I can find no information on the required/recommended buffer size; .\" the nonreentrant functions use a 1024 byte buffer -- mtk. -.PP +.P If the function call successfully obtains an RPC record, then .I *result is set pointing to @@ -90,7 +90,7 @@ is set to NULL. .SH RETURN VALUE On success, these functions return 0. On error, they return one of the positive error numbers listed in ERRORS. -.PP +.P On error, record not found .RB ( getrpcbyname_r (), .BR getrpcbynumber_r ()), @@ -126,7 +126,6 @@ T{ .BR getrpcbynumber_r () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS Functions with similar names exist on some other systems, though typically with different calling signatures. diff --git a/man3/getrpcport.3 b/man3/getrpcport.3 index 56b6188..aa7623c 100644 --- a/man3/getrpcport.3 +++ b/man3/getrpcport.3 @@ -6,7 +6,7 @@ .\" %%%LICENSE_END .\" .\" @(#)getrpcport.3r 2.2 88/08/02 4.0 RPCSRC; from 1.12 88/02/26 SMI -.TH getrpcport 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getrpcport 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getrpcport \- get RPC port number .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int getrpcport(const char *" host ", unsigned long " prognum , .BI " unsigned long " versnum ", unsigned int " proto ); .fi @@ -53,7 +53,6 @@ T{ .BR getrpcport () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY diff --git a/man3/gets.3 b/man3/gets.3 index 9bf383a..e0cb43b 100644 --- a/man3/gets.3 +++ b/man3/gets.3 @@ -7,7 +7,7 @@ .\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) .\" Modified 2013-12-31, David Malcolm .\" Split gets(3) into its own page; fgetc() et al. move to fgetc(3) -.TH gets 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gets 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gets \- get a string from standard input (DEPRECATED) .SH LIBRARY @@ -16,12 +16,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] char *gets(char *" "s" ); .fi .SH DESCRIPTION .IR "Never use this function" . -.PP +.P .BR gets () reads a line from .I stdin @@ -53,12 +53,11 @@ T{ .BR gets () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001. -.PP +.P LSB deprecates .BR gets (). POSIX.1-2008 marks @@ -84,7 +83,7 @@ It has been used to break computer security. Use .BR fgets () instead. -.PP +.P For more information, see CWE-242 (aka "Use of Inherently Dangerous Function") at http://cwe.mitre.org/data/definitions/242.html diff --git a/man3/getservent.3 b/man3/getservent.3 index fdd5d91..ce650aa 100644 --- a/man3/getservent.3 +++ b/man3/getservent.3 @@ -12,7 +12,7 @@ .\" Modified Mon Apr 22 01:50:54 1996 by Martin Schulze .\" 2001-07-25 added a clause about NULL proto (Martin Michlmayr or David N. Welton) .\" -.TH getservent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getservent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getservent, getservbyname, getservbyport, setservent, endservent \- get service entry @@ -22,12 +22,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct servent *getservent(void); -.PP +.P .BI "struct servent *getservbyname(const char *" name ", const char *" proto ); .BI "struct servent *getservbyport(int " port ", const char *" proto ); -.PP +.P .BI "void setservent(int " stayopen ); .B void endservent(void); .fi @@ -41,7 +41,7 @@ and returns a structure containing the broken-out fields from the entry. A connection is opened to the database if necessary. -.PP +.P The .BR getservbyname () function returns a @@ -56,7 +56,7 @@ If .I proto is NULL, any protocol will be matched. A connection is opened to the database if necessary. -.PP +.P The .BR getservbyport () function returns a @@ -72,7 +72,7 @@ If .I proto is NULL, any protocol will be matched. A connection is opened to the database if necessary. -.PP +.P The .BR setservent () function opens a connection to the database, @@ -84,17 +84,17 @@ then the connection to the database will not be closed between calls to one of the .BR getserv* () functions. -.PP +.P The .BR endservent () function closes the connection to the database. -.PP +.P The .I servent structure is defined in .I as follows: -.PP +.P .in +4n .EX struct servent { @@ -105,7 +105,7 @@ struct servent { } .EE .in -.PP +.P The members of the .I servent structure are: @@ -186,7 +186,7 @@ MT-Unsafe race:servent locale T} .TE -.sp 1 +.P In the above table, .I servent in diff --git a/man3/getservent_r.3 b/man3/getservent_r.3 index 04397ee..76c42f3 100644 --- a/man3/getservent_r.3 +++ b/man3/getservent_r.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getservent_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getservent_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getservent_r, getservbyname_r, getservbyport_r \- get service entry (reentrant) @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getservent_r(struct servent *restrict " result_buf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct servent **restrict " result ); @@ -28,13 +28,13 @@ Standard C library .BI " struct servent *restrict " result_buf , .BI " char " buf "[restrict ." buflen "], size_t " buflen , .BI " struct servent **restrict " result ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getservent_r (), .BR getservbyname_r (), .BR getservbyport_r (): @@ -61,13 +61,13 @@ structure is returned, and in the function calling signature and return value. This manual page describes just the differences from the nonreentrant functions. -.PP +.P Instead of returning a pointer to a statically allocated .I servent structure as the function result, these functions copy the structure into the location pointed to by .IR result_buf . -.PP +.P The .I buf array is used to store the string fields pointed to by the returned @@ -84,7 +84,7 @@ and the caller must try again with a larger buffer. (A buffer of length 1024 bytes should be sufficient for most applications.) .\" I can find no information on the required/recommended buffer size; .\" the nonreentrant functions use a 1024 byte buffer -- mtk. -.PP +.P If the function call successfully obtains a service record, then .I *result is set pointing to @@ -95,7 +95,7 @@ is set to NULL. .SH RETURN VALUE On success, these functions return 0. On error, they return one of the positive error numbers listed in errors. -.PP +.P On error, record not found .RB ( getservbyname_r (), .BR getservbyport_r ()), @@ -131,7 +131,6 @@ T{ .BR getservbyport_r () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS Functions with similar names exist on some other systems, though typically with different calling signatures. @@ -151,7 +150,7 @@ fails with the error .BR ERANGE , the program retries with larger buffer sizes. The following shell session shows a couple of sample runs: -.PP +.P .in +4n .EX .RB "$" " ./a.out 7 tcp 1" diff --git a/man3/getspnam.3 b/man3/getspnam.3 index f0752cb..d3f9626 100644 --- a/man3/getspnam.3 +++ b/man3/getspnam.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH getspnam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getspnam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, @@ -16,31 +16,31 @@ Standard C library .nf /* General shadow password file API */ .B #include -.PP +.P .BI "struct spwd *getspnam(const char *" name ); .B struct spwd *getspent(void); -.PP +.P .B void setspent(void); .B void endspent(void); -.PP +.P .BI "struct spwd *fgetspent(FILE *" stream ); .BI "struct spwd *sgetspent(const char *" s ); -.PP +.P .BI "int putspent(const struct spwd *" p ", FILE *" stream ); -.PP +.P .B int lckpwdf(void); .B int ulckpwdf(void); -.PP +.P /* GNU extension */ .B #include -.PP +.P .BI "int getspent_r(struct spwd *" spbuf , .BI " char " buf [. buflen "], size_t " buflen ", \ struct spwd **" spbufp ); .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf , .BI " char " buf [. buflen "], size_t " buflen ", \ struct spwd **" spbufp ); -.PP +.P .BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf , .BI " char " buf [. buflen "], size_t " buflen ", \ struct spwd **" spbufp ); @@ -48,12 +48,12 @@ struct spwd **" spbufp ); .BI " char " buf [. buflen "], size_t " buflen ", \ struct spwd **" spbufp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getspent_r (), .BR getspnam_r (), .BR fgetspent_r (), @@ -76,7 +76,7 @@ the shadow password database .IR /etc/shadow , NIS, and LDAP), readable only by root. -.PP +.P The functions described below resemble those for the traditional password database (e.g., see @@ -93,14 +93,14 @@ and .\" (pluggable authentication modules), and the file .\" .I /etc/nsswitch.conf .\" now describes the sources to be used. -.PP +.P The .BR getspnam () function returns a pointer to a structure containing the broken-out fields of the record in the shadow password database that matches the username .IR name . -.PP +.P The .BR getspent () function returns a pointer to the next entry in the shadow password @@ -112,21 +112,21 @@ When done reading, the program may call so that resources can be deallocated. .\" some systems require a call of setspent() before the first getspent() .\" glibc does not -.PP +.P The .BR fgetspent () function is similar to .BR getspent () but uses the supplied stream instead of the one implicitly opened by .BR setspent (). -.PP +.P The .BR sgetspent () function parses the supplied string .I s into a struct .IR spwd . -.PP +.P The .BR putspent () function writes the contents of the supplied struct @@ -136,7 +136,7 @@ as a text line in the shadow password file format to .IR stream . String entries with value NULL and numerical entries with value \-1 are written as an empty string. -.PP +.P The .BR lckpwdf () function is intended to protect against multiple simultaneous accesses @@ -151,7 +151,7 @@ password file. Only programs that use .BR lckpwdf () will notice the lock. -.PP +.P These were the functions that formed the original shadow API. They are widely available. .\" Also in libc5 @@ -173,20 +173,20 @@ of size A pointer to the result (in case of success) or NULL (in case no entry was found or an error occurred) is stored in .IR *spbufp . -.PP +.P The functions .BR getspent_r (), .BR fgetspent_r (), and .BR sgetspent_r () are similarly analogous to their nonreentrant counterparts. -.PP +.P Some non-glibc systems also have functions with these names, often with different prototypes. .\" SUN doesn't have sgetspent_r() .SS Structure The shadow password structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct spwd { @@ -215,10 +215,10 @@ The functions which have \fIint\fP as the return value return 0 for success and \-1 for failure, with .I errno set to indicate the error. -.PP +.P For the nonreentrant functions, the return value may point to static area, and may be overwritten by subsequent calls to these functions. -.PP +.P The reentrant functions return zero on success. In case of error, an error number is returned. .SH ERRORS @@ -235,7 +235,7 @@ local shadow password database file .TP .I /etc/.pwd.lock lock file -.PP +.P The include file .I defines the constant @@ -320,7 +320,7 @@ T} Thread safety T{ MT-Safe T} .TE -.sp 1 +.P In the above table, .I getspent in diff --git a/man3/getsubopt.3 b/man3/getsubopt.3 index 8cbccb0..caf03a2 100644 --- a/man3/getsubopt.3 +++ b/man3/getsubopt.3 @@ -23,7 +23,7 @@ .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" %%%LICENSE_END .\" -.TH getsubopt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getsubopt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getsubopt \- parse suboption arguments from a string .SH LIBRARY @@ -32,16 +32,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getsubopt(char **restrict " optionp ", char *const *restrict " tokens , .BI " char **restrict " valuep ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getsubopt (): .nf _XOPEN_SOURCE >= 500 @@ -62,13 +62,13 @@ which is separated from the suboption name by an equal sign. The following is an example of the kind of string that might be passed in .IR optionp : -.PP +.P .in +4n .EX .B ro,name=xyz .EE .in -.PP +.P The .I tokens argument is a pointer to a NULL-terminated array of pointers to the tokens that @@ -77,7 +77,7 @@ will look for in .IR optionp . The tokens should be distinct, null-terminated strings containing at least one character, with no embedded equal signs or commas. -.PP +.P Each call to .BR getsubopt () returns information about the next unprocessed suboption in @@ -98,11 +98,11 @@ The first comma in is overwritten with a null byte, so .I *valuep is precisely the "value string" for that suboption. -.PP +.P If the suboption is recognized, but no value string was found, .I *valuep is set to NULL. -.PP +.P When .BR getsubopt () returns, @@ -122,7 +122,7 @@ Otherwise, \-1 is returned and is the entire .IB name [= value ] string. -.PP +.P Since .I *optionp is changed, the first suboption before the call to @@ -143,7 +143,6 @@ T{ .BR getsubopt () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -156,7 +155,7 @@ overwrites any commas it finds in the string that string must be writable; it cannot be a string constant. .SH EXAMPLES The following program expects suboptions following a "\-o" option. -.PP +.P .\" SRC BEGIN (getsubopt.c) .EX #define _XOPEN_SOURCE 500 diff --git a/man3/getttyent.3 b/man3/getttyent.3 index 81c4c4c..aeb87ac 100644 --- a/man3/getttyent.3 +++ b/man3/getttyent.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH getttyent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getttyent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getttyent, getttynam, setttyent, endttyent \- get ttys file entry .SH LIBRARY @@ -12,10 +12,10 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .B "struct ttyent *getttyent(void);" .BI "struct ttyent *getttynam(const char *" name ); -.PP +.P .B "int setttyent(void);" .B "int endttyent(void);" .fi @@ -24,22 +24,22 @@ These functions provide an interface to the file .B _PATH_TTYS (e.g., .IR /etc/ttys ). -.PP +.P The function .BR setttyent () opens the file or rewinds it if already open. -.PP +.P The function .BR endttyent () closes the file. -.PP +.P The function .BR getttynam () searches for a given terminal name in the file. It returns a pointer to a .I ttyent structure (description below). -.PP +.P The function .BR getttyent () opens the file @@ -49,7 +49,7 @@ If the file is already open, the next entry. The .I ttyent structure has the form: -.PP +.P .in +4n .EX struct ttyent { @@ -62,10 +62,10 @@ struct ttyent { }; .EE .in -.PP +.P .I ty_status can be: -.PP +.P .in +4n .EX #define TTY_ON 0x01 /* enable logins (start ty_getty program) */ @@ -89,7 +89,6 @@ T{ .BR getttynam () T} Thread safety MT-Unsafe race:ttyent .TE -.sp 1 .SH STANDARDS BSD. .SH NOTES diff --git a/man3/getusershell.3 b/man3/getusershell.3 index cbd1d1a..41c5a68 100644 --- a/man3/getusershell.3 +++ b/man3/getusershell.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 19:17:53 1993 by Rik Faith (faith@cs.unc.edu) -.TH getusershell 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getusershell 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getusershell, setusershell, endusershell \- get permitted user shells .SH LIBRARY @@ -17,17 +17,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B char *getusershell(void); .B void setusershell(void); .B void endusershell(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getusershell (), .BR setusershell (), .BR endusershell (): @@ -58,12 +58,12 @@ behaves as if and .I /bin/csh were listed in the file. -.PP +.P The .BR setusershell () function rewinds .IR /etc/shells . -.PP +.P The .BR endusershell () function closes @@ -90,7 +90,6 @@ T{ .BR endusershell () T} Thread safety MT-Unsafe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/getutent.3 b/man3/getutent.3 index d2aefcf..f55286f 100644 --- a/man3/getutent.3 +++ b/man3/getutent.3 @@ -10,7 +10,7 @@ .\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt .\" .\" -.TH getutent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getutent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- access utmp file entries @@ -20,22 +20,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct utmp *getutent(void); .BI "struct utmp *getutid(const struct utmp *" ut ); .BI "struct utmp *getutline(const struct utmp *" ut ); -.PP +.P .BI "struct utmp *pututline(const struct utmp *" ut ); -.PP +.P .B void setutent(void); .B void endutent(void); -.PP +.P .BI "int utmpname(const char *" file ); .fi .SH DESCRIPTION New applications should use the POSIX.1-specified "utmpx" versions of these functions; see STANDARDS. -.PP +.P .BR utmpname () sets the name of the utmp-format file for the other utmp functions to access. @@ -44,24 +44,24 @@ If is not used to set the filename before the other functions are used, they assume \fB_PATH_UTMP\fP, as defined in \fI\fP. -.PP +.P .BR setutent () rewinds the file pointer to the beginning of the utmp file. It is generally a good idea to call it before any of the other functions. -.PP +.P .BR endutent () closes the utmp file. It should be called when the user code is done accessing the file with the other functions. -.PP +.P .BR getutent () reads a line from the current file position in the utmp file. It returns a pointer to a structure containing the fields of the line. The definition of this structure is shown in .BR utmp (5). -.PP +.P .BR getutid () searches forward from the current file position in the utmp file based upon \fIut\fP. @@ -77,7 +77,7 @@ will find the first entry whose .I ut_id field matches \fIut\->ut_id\fP. -.PP +.P .BR getutline () searches forward from the current file position in the utmp file. It scans entries whose @@ -87,7 +87,7 @@ or \fBLOGIN_PROCESS\fP and returns the first one whose .I ut_line field matches \fIut\->ut_line\fP. -.PP +.P .BR pututline () writes the .I utmp @@ -108,16 +108,16 @@ return a pointer to a \fIstruct utmp\fP on success, and NULL on failure (which includes the "record not found" case). This \fIstruct utmp\fP is allocated in static storage, and may be overwritten by subsequent calls. -.PP +.P On success .BR pututline () returns .IR ut ; on failure, it returns NULL. -.PP +.P .BR utmpname () returns 0 if the new name was successfully stored, or \-1 on failure. -.PP +.P On failure, these functions .I errno set to indicate the error. @@ -128,7 +128,7 @@ Out of memory. .TP .B ESRCH Record not found. -.PP +.P .BR setutent (), .BR pututline (), and the @@ -189,7 +189,7 @@ T{ .BR utmpname () T} Thread safety MT-Unsafe race:utent .TE -.sp 1 +.P In the above table, .I utent in @@ -209,7 +209,7 @@ then data races could occur. None. .SH HISTORY XPG2, SVr4. -.PP +.P In XPG2 and SVID 2 the function .BR pututline () is documented to return void, and that is what it does on many systems @@ -218,15 +218,15 @@ HP-UX introduces a new function .BR _pututline () with the prototype given above for .BR pututline (). -.PP +.P All these functions are obsolete now on non-Linux systems. POSIX.1-2001 and POSIX.1-2008, following SUSv1, does not have any of these functions, but instead uses -.PP +.P .RS 4 .EX .B #include -.PP +.P .B struct utmpx *getutxent(void); .B struct utmpx *getutxid(const struct utmpx *); .B struct utmpx *getutxline(const struct utmpx *); @@ -235,7 +235,7 @@ does not have any of these functions, but instead uses .B void endutxent(void); .EE .RE -.PP +.P These functions are provided by glibc, and perform the same task as their equivalents without the "x", but use .IR "struct utmpx" , @@ -244,7 +244,7 @@ defined on Linux to be the same as For completeness, glibc also provides .BR utmpxname (), although this function is not specified by POSIX.1. -.PP +.P On some other systems, the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure, with additional fields, and larger versions of the existing fields, @@ -252,7 +252,7 @@ and parallel files are maintained, often .I /var/*/utmpx and .IR /var/*/wtmpx . -.PP +.P Linux glibc on the other hand does not use a parallel \fIutmpx\fP file since its \fIutmp\fP structure is already large enough. The "x" functions listed above are just aliases for @@ -264,20 +264,20 @@ is an alias for .SS glibc notes The above functions are not thread-safe. glibc adds reentrant versions -.PP +.P .nf .B #include -.PP +.P .BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp ); .BI "int getutid_r(struct utmp *" ut , .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); .BI "int getutline_r(struct utmp *" ut , .BI " struct utmp *" ubuf ", struct utmp **" ubufp ); .fi -.PP +.P Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): -.PP +.P .BR getutent_r (), .BR getutid_r (), .BR getutline_r (): @@ -286,7 +286,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P These functions are GNU extensions, analogs of the functions of the same name without the _r suffix. The @@ -305,7 +305,7 @@ should check the return values of .BR getpwuid (3) and .BR ttyname (3). -.PP +.P .\" SRC BEGIN (getutent.c) .EX #include @@ -327,7 +327,7 @@ main(void) strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/")); /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */ strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty")); - time(&entry.ut_time); + entry.ut_time = time(NULL); strcpy(entry.ut_user, getpwuid(getuid())\->pw_name); memset(entry.ut_host, 0, UT_HOSTSIZE); entry.ut_addr = 0; diff --git a/man3/getutmp.3 b/man3/getutmp.3 index 04cf0ad..6694c1a 100644 --- a/man3/getutmp.3 +++ b/man3/getutmp.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getutmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getutmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getutmp, getutmpx \- copy utmp structure to utmpx, and vice versa .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void getutmp(const struct utmpx *" ux ", struct utmp *" u ); .BI "void getutmpx(const struct utmp *" u ", struct utmpx *" ux ); .fi @@ -49,7 +49,6 @@ T{ .BR getutmpx () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/getw.3 b/man3/getw.3 index f96512f..a19bace 100644 --- a/man3/getw.3 +++ b/man3/getw.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH getw 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getw 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getw, putw \- input and output of words (ints) .SH LIBRARY @@ -12,16 +12,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getw(FILE *" stream ); .BI "int putw(int " w ", FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR getw (), .BR putw (): .nf @@ -39,7 +39,7 @@ It's provided for compatibility with SVr4. We recommend you use .BR fread (3) instead. -.PP +.P .BR putw () writes the word \fIw\fP (that is, an \fIint\fP) to \fIstream\fP. @@ -68,7 +68,6 @@ T{ .BR putw () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/getwchar.3 b/man3/getwchar.3 index 0ce51ce..d846804 100644 --- a/man3/getwchar.3 +++ b/man3/getwchar.3 @@ -10,7 +10,7 @@ .\" http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH getwchar 3 2023-07-20 "Linux man-pages 6.05.01" +.TH getwchar 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getwchar \- read a wide character from standard input .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "wint_t getwchar(void);" .fi .SH DESCRIPTION @@ -42,7 +42,7 @@ to .B EILSEQ and returns .BR WEOF . -.PP +.P For a nonlocking counterpart, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -65,7 +65,6 @@ T{ .BR getwchar () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -77,7 +76,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P It is reasonable to expect that .BR getwchar () will actually diff --git a/man3/glob.3 b/man3/glob.3 index 34a2745..9457de6 100644 --- a/man3/glob.3 +++ b/man3/glob.3 @@ -12,7 +12,7 @@ .\" Expanded the description of various flags .\" Various wording fixes. .\" -.TH glob 3 2023-07-20 "Linux man-pages 6.05.01" +.TH glob 3 2023-10-31 "Linux man-pages 6.7" .SH NAME glob, globfree \- find pathnames matching a pattern, free memory from glob() .SH LIBRARY @@ -21,7 +21,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int glob(const char *restrict " pattern ", int " flags , .BI " int (*" errfunc ")(const char *" epath ", int " eerrno ), .BI " glob_t *restrict " pglob ); @@ -37,13 +37,13 @@ according to the rules used by the shell (see No tilde expansion or parameter substitution is done; if you want these, use .BR wordexp (3). -.PP +.P The .BR globfree () function frees the dynamically allocated storage from an earlier call to .BR glob (). -.PP +.P The results of a .BR glob () call are stored in the structure pointed to by @@ -54,7 +54,7 @@ This structure is of type .IR ) and includes the following elements defined by POSIX.2 (more may be present as an extension): -.PP +.P .in +4n .EX typedef struct { @@ -64,9 +64,9 @@ typedef struct { } glob_t; .EE .in -.PP +.P Results are stored in dynamically allocated storage. -.PP +.P The argument .I flags is made up of the bitwise OR of zero or more the following symbolic @@ -117,7 +117,7 @@ character. Normally, a backslash can be used to quote the following character, providing a mechanism to turn off the special meaning metacharacters. -.PP +.P .I flags may also include any of the following, which are GNU extensions and not defined by POSIX.2: @@ -193,7 +193,7 @@ However, the caller must still check that returned files are directories. (The purpose of this flag is merely to optimize performance when the caller is interested only in directories.) -.PP +.P If .I errfunc is not NULL, @@ -216,14 +216,14 @@ is set, .BR glob () will terminate after the call to .IR errfunc . -.PP +.P Upon successful return, .I pglob\->gl_pathc contains the number of matched pathnames and .I pglob\->gl_pathv contains a pointer to the list of pointers to matched pathnames. The list of pointers is terminated by a null pointer. -.PP +.P It is possible to call .BR glob () several times. @@ -232,7 +232,7 @@ In that case, the flag has to be set in .I flags on the second and later invocations. -.PP +.P As a GNU extension, .I pglob\->gl_flags is set to the flags specified, @@ -278,7 +278,7 @@ T{ .BR globfree () T} Thread safety MT-Safe .TE -.sp 1 +.P In the above table, .I utent in @@ -319,15 +319,15 @@ These will store their error code in .IR errno . .SH EXAMPLES One example of use is the following code, which simulates typing -.PP +.P .in +4n .EX ls \-l *.c ../*.c .EE .in -.PP +.P in the shell: -.PP +.P .in +4n .EX glob_t globbuf; diff --git a/man3/gnu_get_libc_version.3 b/man3/gnu_get_libc_version.3 index a1af9d1..e02390e 100644 --- a/man3/gnu_get_libc_version.3 +++ b/man3/gnu_get_libc_version.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH gnu_get_libc_version 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gnu_get_libc_version 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gnu_get_libc_version, gnu_get_libc_release \- get glibc version and release .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B const char *gnu_get_libc_version(void); .B const char *gnu_get_libc_release(void); .fi @@ -21,7 +21,7 @@ Standard C library The function .BR gnu_get_libc_version () returns a string that identifies the glibc version available on the system. -.PP +.P The function .BR gnu_get_libc_release () returns a string indicates the release status of the glibc version @@ -43,14 +43,13 @@ T{ .BR gnu_get_libc_release () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY glibc 2.1. .SH EXAMPLES When run, the program below will produce output such as the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man3/grantpt.3 b/man3/grantpt.3 index 174c5c9..8f1aca0 100644 --- a/man3/grantpt.3 +++ b/man3/grantpt.3 @@ -3,7 +3,7 @@ .\" This page is in the public domain. - aeb .\" %%%LICENSE_END .\" -.TH grantpt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH grantpt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME grantpt \- grant access to the slave pseudoterminal .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int grantpt(int " fd ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR grantpt (): .nf Since glibc 2.24: @@ -39,7 +39,7 @@ The user ID of the slave is set to the real UID of the calling process. The group ID is set to an unspecified value (e.g., .IR tty ). The mode of the slave is set to 0620 (crw\-\-w\-\-\-\-). -.PP +.P The behavior of .BR grantpt () is unspecified if a signal handler is installed to catch @@ -80,16 +80,15 @@ T{ .BR grantpt () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.1. POSIX.1-2001. -.PP +.P This is part of the UNIX 98 pseudoterminal support, see .BR pts (4). -.PP +.P Historical systems implemented this function via a set-user-ID helper binary called "pt_chown". glibc on Linux before glibc 2.33 could do so as well, diff --git a/man3/group_member.3 b/man3/group_member.3 index 620b59f..688b9cb 100644 --- a/man3/group_member.3 +++ b/man3/group_member.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH group_member 3 2023-03-30 "Linux man-pages 6.05.01" +.TH group_member 3 2023-10-31 "Linux man-pages 6.7" .SH NAME group_member \- test whether a process is in a group .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int group_member(gid_t " gid ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR group_member (): .nf _GNU_SOURCE diff --git a/man3/gsignal.3 b/man3/gsignal.3 index 4587650..4c41dbd 100644 --- a/man3/gsignal.3 +++ b/man3/gsignal.3 @@ -5,7 +5,7 @@ .\" .\" This replaces an earlier man page written by Walter Harms .\" . -.TH gsignal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH gsignal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME gsignal, ssignal \- software signal facility .SH LIBRARY @@ -14,19 +14,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B typedef void (*sighandler_t)(int); -.PP +.P .BI "[[deprecated]] int gsignal(int " signum ); -.PP +.P .BI "[[deprecated]] sighandler_t ssignal(int " signum ", sighandler_t " action ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR gsignal (), .BR ssignal (): .nf @@ -43,7 +43,7 @@ aliases for and .BR signal (2), respectively. -.PP +.P Elsewhere, on System V-like systems, these functions implement software signaling, entirely independent of the classical .BR signal (2) @@ -100,7 +100,6 @@ T{ .BR ssignal () T} Thread safety MT-Safe sigintr .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/hash.3 b/man3/hash.3 index ed99fe1..6ab717f 100644 --- a/man3/hash.3 +++ b/man3/hash.3 @@ -5,7 +5,7 @@ .\" .\" @(#)hash.3 8.6 (Berkeley) 8/18/94 .\" -.TH hash 3 2022-12-04 "Linux man-pages 6.05.01" +.TH hash 3 2023-10-31 "Linux man-pages 6.7" .UC 7 .SH NAME hash \- hash database access method @@ -26,7 +26,7 @@ Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the .I libdb library instead. -.PP +.P The routine .BR dbopen (3) is the library interface to database files. @@ -34,15 +34,15 @@ One of the supported file formats is hash files. The general description of the database access methods is in .BR dbopen (3), this manual page describes only the hash-specific information. -.PP +.P The hash data structure is an extensible, dynamic hashing scheme. -.PP +.P The access-method-specific data structure provided to .BR dbopen (3) is defined in the .I include file as follows: -.PP +.P .in +4n .EX typedef struct { @@ -55,7 +55,7 @@ typedef struct { } HASHINFO; .EE .in -.PP +.P The elements of this structure are as follows: .TP 10 .I bsize @@ -99,7 +99,7 @@ If is 0 (no order is specified), the current host order is used. If the file already exists, the specified value is ignored and the value specified when the tree was created is used. -.PP +.P If the file already exists (and the .B O_TRUNC flag is not specified), the @@ -111,12 +111,12 @@ and .I nelem are ignored and the values specified when the tree was created are used. -.PP +.P If a hash function is specified, .I hash_open attempts to determine if the hash function specified is the same as the one with which the database was created, and fails if it is not. -.PP +.P Backward-compatible interfaces to the routines described in .BR dbm (3), and @@ -137,9 +137,9 @@ Only big and little endian byte order are supported. .BR dbopen (3), .BR mpool (3), .BR recno (3) -.PP +.P .IR "Dynamic Hash Tables" , Per-Ake Larson, Communications of the ACM, April 1988. -.PP +.P .IR "A New Hash Package for UNIX" , Margo Seltzer, USENIX Proceedings, Winter 1991. diff --git a/man3/hsearch.3 b/man3/hsearch.3 index dd801df..93e6794 100644 --- a/man3/hsearch.3 +++ b/man3/hsearch.3 @@ -14,7 +14,7 @@ .\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from .\" Timothy S. Nelson .\" -.TH hsearch 3 2023-07-20 "Linux man-pages 6.05.01" +.TH hsearch 3 2023-10-31 "Linux man-pages 6.7" .SH NAME hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- hash table management @@ -24,18 +24,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int hcreate(size_t " nel ); .B "void hdestroy(void);" -.PP +.P .BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab ); .BI "void hdestroy_r(struct hsearch_data *" htab ); -.PP +.P .BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval , .BI " struct hsearch_data *" htab ); .fi @@ -48,7 +48,7 @@ and allow the caller to create and manage a hash search table containing entries consisting of a key (a string) and associated data. Using these functions, only one hash table can be used at a time. -.PP +.P The three functions .BR hcreate_r (), .BR hsearch_r (), @@ -62,7 +62,7 @@ on which the function is to operate. The programmer should treat this structure as opaque (i.e., do not attempt to directly access or modify the fields in this structure). -.PP +.P First a hash table must be created using .BR hcreate (). The argument \fInel\fP specifies the maximum number of entries @@ -71,7 +71,7 @@ in the table. The implementation may adjust this value upward to improve the performance of the resulting hash table. .\" e.g., in glibc it is raised to the next higher prime number -.PP +.P The .BR hcreate_r () function performs the same task as @@ -82,7 +82,7 @@ The structure pointed to by .I htab must be zeroed before the first call to .BR hcreate_r (). -.PP +.P The function .BR hdestroy () frees the memory occupied by the hash table that was created by @@ -97,17 +97,17 @@ function performs the analogous task for a hash table described by .IR *htab , which was previously created using .BR hcreate_r (). -.PP +.P The .BR hsearch () function searches the hash table for an item with the same key as \fIitem\fP (where "the same" is determined using .BR strcmp (3)), and if successful returns a pointer to it. -.PP +.P The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in \fI\fP as follows: -.PP +.P .in +4n .EX typedef struct entry { @@ -116,11 +116,11 @@ typedef struct entry { } ENTRY; .EE .in -.PP +.P The field \fIkey\fP points to a null-terminated string which is the search key. The field \fIdata\fP points to data that is associated with that key. -.PP +.P The argument \fIaction\fP determines what .BR hsearch () does after an unsuccessful search. @@ -139,7 +139,7 @@ is then .I data is ignored.) -.PP +.P The .BR hsearch_r () function is like @@ -161,7 +161,7 @@ return nonzero on success. They return 0 on error, with .I errno set to indicate the error. -.PP +.P On success, .BR hsearch () returns a pointer to an entry in the hash table. @@ -184,7 +184,7 @@ can fail for the following reasons: .B EINVAL .I htab is NULL. -.PP +.P .BR hsearch () and .BR hsearch_r () @@ -205,7 +205,7 @@ was and .I key was not found in the table. -.PP +.P POSIX.1 specifies only the .\" PROX.1-2001, POSIX.1-2008 .B ENOMEM @@ -233,7 +233,6 @@ T{ .BR hdestroy_r () T} Thread safety MT-Safe race:htab .TE -.sp 1 .SH STANDARDS .TP .BR hcreate () @@ -271,7 +270,7 @@ Typically, this means that .I nel should be at least 25% larger than the maximum number of elements that the caller expects to store in the table. -.PP +.P The .BR hdestroy () and @@ -296,12 +295,12 @@ should not do anything for a successful search. In libc and glibc (before glibc 2.3), the implementation violates the specification, updating the \fIdata\fP for the given \fIkey\fP in this case. -.PP +.P Individual hash table entries can be added, but not deleted. .SH EXAMPLES The following program inserts 24 items into a hash table, then prints some of them. -.PP +.P .\" SRC BEGIN (hsearch.c) .EX #include diff --git a/man3/hypot.3 b/man3/hypot.3 index 5f106c6..a7d4563 100644 --- a/man3/hypot.3 +++ b/man3/hypot.3 @@ -11,7 +11,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH hypot 3 2023-07-20 "Linux man-pages 6.05.01" +.TH hypot 3 2023-10-31 "Linux man-pages 6.7" .SH NAME hypot, hypotf, hypotl \- Euclidean distance function .SH LIBRARY @@ -20,17 +20,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double hypot(double " x ", double " y ); .BI "float hypotf(float " x ", float " y ); .BI "long double hypotl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR hypot (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -38,7 +38,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR hypotf (), .BR hypotl (): .nf @@ -57,7 +57,7 @@ and or the distance of the point .RI ( x , y ) from the origin. -.PP +.P The calculation is performed without undue overflow or underflow during the intermediate steps of the calculation. .\" e.g., hypot(DBL_MIN, DBL_MIN) does the right thing, as does, say @@ -69,14 +69,14 @@ with sides of length .I x and .IR y . -.PP +.P If .I x or .I y is an infinity, positive infinity is returned. -.PP +.P If .I x or @@ -84,7 +84,7 @@ or is a NaN, and the other argument is not an infinity, a NaN is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -93,7 +93,7 @@ and the functions return or .BR HUGE_VALL , respectively. -.PP +.P If both arguments are subnormal, and the result is subnormal, .\" Actually, could the result not be subnormal if both arguments .\" are subnormal? I think not -- mtk, Jul 2008 @@ -104,7 +104,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result overflow @@ -141,12 +141,11 @@ T{ .BR hypotl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/iconv.3 b/man3/iconv.3 index 6e4a091..1f9f96f 100644 --- a/man3/iconv.3 +++ b/man3/iconv.3 @@ -11,7 +11,7 @@ .\" 2000-06-30 correction by Yuichi SATO .\" 2000-11-15 aeb, fixed prototype .\" -.TH iconv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iconv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iconv \- perform character set conversion .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t iconv(iconv_t " cd , .BI " char **restrict " inbuf ", size_t *restrict " inbytesleft , .BI " char **restrict " outbuf ", size_t *restrict " outbytesleft ); @@ -50,7 +50,7 @@ argument is the address of a variable that points to the first byte available in the output buffer; .I outbytesleft indicates the number of bytes available in the output buffer. -.PP +.P The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. In this case, the .BR iconv () @@ -58,7 +58,7 @@ function converts the multibyte sequence starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. -.PP +.P The .BR iconv () function converts one multibyte character at a time, and for @@ -134,7 +134,7 @@ beginning of the incomplete multibyte sequence. The output buffer has no more room for the next converted character. In this case, it sets \fIerrno\fP to \fBE2BIG\fP and returns .IR (size_t)\ \-1 . -.PP +.P A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but \fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the @@ -148,7 +148,7 @@ If the output buffer has no more room for this reset sequence, it sets Otherwise, it increments \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes written. -.PP +.P A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and \fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the @@ -191,8 +191,7 @@ T{ .BR iconv () T} Thread safety MT-Safe race:cd .TE -.sp 1 -.PP +.P The .BR iconv () function is MT-Safe, as long as callers arrange for @@ -209,7 +208,7 @@ In each series of calls to .BR iconv (), the last should be one with \fIinbuf\fP or \fI*inbuf\fP equal to NULL, in order to flush out any partially converted input. -.PP +.P Although .I inbuf and @@ -221,7 +220,7 @@ as C strings or as arrays of characters: the interpretation of character byte sequences is handled internally by the conversion functions. In some encodings, a zero byte may be a valid part of a multibyte character. -.PP +.P The caller of .BR iconv () must ensure that the pointers passed to the function are suitable diff --git a/man3/iconv_close.3 b/man3/iconv_close.3 index 089843c..85ba846 100644 --- a/man3/iconv_close.3 +++ b/man3/iconv_close.3 @@ -7,7 +7,7 @@ .\" GNU glibc-2 source code and manual .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH iconv_close 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iconv_close 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iconv_close \- deallocate descriptor for character set conversion .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iconv_close(iconv_t " cd ); .fi .SH DESCRIPTION @@ -46,7 +46,6 @@ T{ .BR iconv_close () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/iconv_open.3 b/man3/iconv_open.3 index 13ae778..f6a64b9 100644 --- a/man3/iconv_open.3 +++ b/man3/iconv_open.3 @@ -11,7 +11,7 @@ .\" 2007-03-31 Bruno Haible, Describe the glibc/libiconv //TRANSLIT .\" and //IGNORE extensions for 'tocode'. .\" -.TH iconv_open 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iconv_open 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iconv_open \- allocate descriptor for character set conversion .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "iconv_t iconv_open(const char *" tocode ", const char *" fromcode ); .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ for converting byte sequences from character encoding to character encoding .IR tocode . -.PP +.P The values permitted for .I fromcode and @@ -61,13 +61,13 @@ When the string "//IGNORE" is appended to .IR tocode , characters that cannot be represented in the target character set will be silently discarded. -.PP +.P The resulting conversion descriptor can be used with .BR iconv (3) any number of times. It remains valid until deallocated using .BR iconv_close (3). -.PP +.P A conversion descriptor contains a conversion state. After creation using .BR iconv_open (), @@ -114,7 +114,6 @@ T{ .BR iconv_open () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/if_nameindex.3 b/man3/if_nameindex.3 index 39b72a0..7f4c42e 100644 --- a/man3/if_nameindex.3 +++ b/man3/if_nameindex.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH if_nameindex 3 2023-07-20 "Linux man-pages 6.05.01" +.TH if_nameindex 3 2023-10-31 "Linux man-pages 6.7" .SH NAME if_nameindex, if_freenameindex \- get network interface names and indexes .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "struct if_nameindex *if_nameindex(" void ); .BI "void if_freenameindex(struct if_nameindex *" "ptr" ); .fi @@ -27,14 +27,14 @@ about one of the network interfaces on the local system. The .I if_nameindex structure contains at least the following entries: -.PP +.P .in +4n .EX unsigned int if_index; /* Index of interface (1, 2, ...) */ char *if_name; /* Null\-terminated name ("eth0", etc.) */ .EE .in -.PP +.P The .I if_index field contains the interface index. @@ -46,7 +46,7 @@ The end of the array is indicated by entry with set to zero and .I if_name set to NULL. -.PP +.P The data structure returned by .BR if_nameindex () is dynamically allocated and should be freed using @@ -67,7 +67,7 @@ if: .TP .B ENOBUFS Insufficient resources available. -.PP +.P .BR if_nameindex () may also fail for any of the errors specified for .BR socket (2), @@ -93,14 +93,13 @@ T{ .BR if_freenameindex () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008, RFC\ 3493. .SH HISTORY glibc 2.1. POSIX.1-2001. BSDi. -.PP +.P Before glibc 2.3.4, the implementation supported only interfaces with IPv4 addresses. Support of interfaces that don't have IPv4 addresses is available only @@ -109,7 +108,7 @@ on kernels that support netlink. The program below demonstrates the use of the functions described on this page. An example of the output this program might produce is the following: -.PP +.P .in +4n .EX $ \fB./a.out\fI diff --git a/man3/if_nametoindex.3 b/man3/if_nametoindex.3 index ebbd257..e4e183e 100644 --- a/man3/if_nametoindex.3 +++ b/man3/if_nametoindex.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH if_nametoindex 3 2023-07-20 "Linux man-pages 6.05.01" +.TH if_nametoindex 3 2023-10-31 "Linux man-pages 6.7" .SH NAME if_nametoindex, if_indextoname \- mappings between network interface names and indexes @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "unsigned int if_nametoindex(const char *" "ifname" ); .BI "char *if_indextoname(unsigned int ifindex, char *" ifname ); .fi @@ -23,7 +23,7 @@ The function returns the index of the network interface corresponding to the name .IR ifname . -.PP +.P The .BR if_indextoname () function returns the name of the network interface @@ -41,7 +41,7 @@ returns the index number of the network interface; on error, 0 is returned and .I errno is set to indicate the error. -.PP +.P On success, .BR if_indextoname () returns @@ -57,7 +57,7 @@ if: .TP .B ENODEV No interface found with given name. -.PP +.P .BR if_indextoname () may fail and set .I errno @@ -65,7 +65,7 @@ if: .TP .B ENXIO No interface found for the index. -.PP +.P .BR if_nametoindex () and .BR if_indextoname () @@ -88,7 +88,6 @@ T{ .BR if_indextoname () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008, RFC\ 3493. .SH HISTORY diff --git a/man3/ilogb.3 b/man3/ilogb.3 index 100b0c8..69ce0a4 100644 --- a/man3/ilogb.3 +++ b/man3/ilogb.3 @@ -7,7 +7,7 @@ .\" .\" Inspired by a page by Walter Harms created 2002-08-10 .\" -.TH ilogb 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ilogb 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ilogb, ilogbf, ilogbl \- get integer exponent of a floating-point value .SH LIBRARY @@ -16,17 +16,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int ilogb(double " x ); .BI "int ilogbf(float " x ); .BI "int ilogbl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ilogb (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR ilogbf (), .BR ilogbl (): .nf @@ -55,7 +55,7 @@ functions, cast to On success, these functions return the exponent of .IR x , as a signed integer. -.PP +.P If .I x is zero, then a domain error occurs, and the functions return @@ -63,14 +63,14 @@ is zero, then a domain error occurs, and the functions return .\" case, but for ilogb() it says domain error. .BR FP_ILOGB0 . .\" glibc: The numeric value is either `INT_MIN' or `-INT_MAX'. -.PP +.P If .I x is a NaN, then a domain error occurs, and the functions return .BR FP_ILOGBNAN . .\" glibc: The numeric value is either `INT_MIN' or `INT_MAX'. .\" On i386, FP_ILOGB0 and FP_ILOGBNAN have the same value. -.PP +.P If .I x is negative infinity or positive infinity, then @@ -88,7 +88,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is 0 or a NaN @@ -124,7 +124,6 @@ T{ .BR ilogbl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/index.3 b/man3/index.3 index 56c2bb3..ebccd46 100644 --- a/man3/index.3 +++ b/man3/index.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH index 3 2023-03-30 "Linux man-pages 6.05.01" +.TH index 3 2023-10-31 "Linux man-pages 6.7" .SH NAME index, rindex \- locate character in string .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] char *index(const char *" s ", int " c ); .BI "[[deprecated]] char *rindex(const char *" s ", int " c ); .fi @@ -19,11 +19,11 @@ Standard C library .BR index () is identical to .BR strchr (3). -.PP +.P .BR rindex () is identical to .BR strrchr (3). -.PP +.P Use .BR strchr (3) and diff --git a/man3/inet.3 b/man3/inet.3 index 557bb2d..554fd11 100644 --- a/man3/inet.3 +++ b/man3/inet.3 @@ -20,7 +20,7 @@ .\" Add discussion of Classful Addressing, noting that it is obsolete. .\" Added an EXAMPLE program. .\" -.TH inet 3 2023-07-20 "Linux man-pages 6.05.01" +.TH inet 3 2023-10-31 "Linux man-pages 6.7" .SH NAME inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, inet_netof \- Internet address manipulation routines @@ -32,26 +32,26 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "int inet_aton(const char *" cp ", struct in_addr *" inp ); -.PP +.P .BI "in_addr_t inet_addr(const char *" cp ); .BI "in_addr_t inet_network(const char *" cp ); -.PP +.P .BI "[[deprecated]] char *inet_ntoa(struct in_addr " in ); -.PP +.P .BI "[[deprecated]] struct in_addr inet_makeaddr(in_addr_t " net , .BI " in_addr_t " host ); -.PP +.P .BI "[[deprecated]] in_addr_t inet_lnaof(struct in_addr " in ); .BI "[[deprecated]] in_addr_t inet_netof(struct in_addr " in ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR inet_aton (), .BR inet_ntoa (): .nf @@ -104,7 +104,7 @@ The value .I a is interpreted as a 32-bit value that is stored directly into the binary address without any byte rearrangement. -.PP +.P In all of the above forms, components of the dotted address can be specified in decimal, octal (with a leading @@ -117,7 +117,7 @@ The form that uses exactly four decimal numbers is referred to as .I IPv4 dotted-decimal notation (or sometimes: .IR "IPv4 dotted-quad notation" ). -.PP +.P .BR inet_aton () returns 1 if the supplied string was successfully interpreted, or 0 if the string is invalid @@ -125,7 +125,7 @@ or 0 if the string is invalid is .I not set on error). -.PP +.P The .BR inet_addr () function converts the Internet host address @@ -142,7 +142,7 @@ Avoid its use in favor of or .BR getaddrinfo (3), which provide a cleaner way to indicate error return. -.PP +.P The .BR inet_network () function converts @@ -152,7 +152,7 @@ into a number in host byte order suitable for use as an Internet network address. On success, the converted address is returned. If the input is invalid, \-1 is returned. -.PP +.P The .BR inet_ntoa () function converts the Internet host address @@ -160,19 +160,19 @@ function converts the Internet host address dotted-decimal notation. The string is returned in a statically allocated buffer, which subsequent calls will overwrite. -.PP +.P The .BR inet_lnaof () function returns the local network address part of the Internet address \fIin\fP. The returned value is in host byte order. -.PP +.P The .BR inet_netof () function returns the network number part of the Internet address \fIin\fP. The returned value is in host byte order. -.PP +.P The .BR inet_makeaddr () function is the converse of @@ -183,7 +183,7 @@ It returns an Internet host address in network byte order, created by combining the network number \fInet\fP with the local address \fIhost\fP, both in host byte order. -.PP +.P The structure \fIin_addr\fP as used in .BR inet_ntoa (), .BR inet_makeaddr (), @@ -193,7 +193,7 @@ and is defined in .I as: -.PP +.P .in +4n .EX typedef uint32_t in_addr_t; @@ -227,7 +227,6 @@ T{ .BR inet_netof () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR inet_addr () @@ -243,7 +242,7 @@ None. .TQ .BR inet_ntoa () POSIX.1-2001, 4.3BSD. -.PP +.P .BR inet_lnaof (), .BR inet_netof (), and @@ -270,7 +269,7 @@ This address type is indicated by the binary value 110 in the most significant three bits of the address. The network address is contained in the three most significant bytes, and the host address occupies the remaining byte. -.PP +.P Classful network addresses are now obsolete, having been superseded by Classless Inter-Domain Routing (CIDR), which divides addresses into network and host components at @@ -286,7 +285,7 @@ and .BR inet_ntoa () is shown below. Here are some example runs: -.PP +.P .in +4n .EX .RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal" diff --git a/man3/inet_net_pton.3 b/man3/inet_net_pton.3 index 2a74441..e8264e8 100644 --- a/man3/inet_net_pton.3 +++ b/man3/inet_net_pton.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inet_net_pton 3 2023-05-03 "Linux man-pages 6.05.01" +.TH inet_net_pton 3 2023-10-31 "Linux man-pages 6.7" .SH NAME inet_net_pton, inet_net_ntop \- Internet network number conversion .SH LIBRARY @@ -11,7 +11,7 @@ Resolver library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int inet_net_pton(int " af ", const char *" pres , .BI " void " netp [. nsize "], size_t " nsize ); .BI "char *inet_net_ntop(int " af , @@ -19,12 +19,12 @@ Resolver library .BI " int " bits , .BI " char " pres [. psize "], size_t " psize ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR inet_net_pton (), .BR inet_net_ntop (): .nf @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION These functions convert network numbers between presentation (i.e., printable) format and network (i.e., binary) format. -.PP +.P For both functions, .I af specifies the address family for the conversion; @@ -61,7 +61,7 @@ The .I nsize argument specifies the number of bytes available in .IR netp . -.PP +.P On success, .BR inet_net_pton () returns the number of bits in the network number field @@ -69,7 +69,7 @@ of the result placed in .IR netp . For a discussion of the input presentation format and the return value, see NOTES. -.PP +.P .IR Note : the buffer pointed to by .I netp @@ -91,7 +91,7 @@ The .I bits argument specifies the number of bits in the network number in .IR *netp . -.PP +.P The null-terminated presentation-format string is placed in the buffer pointed to by .IR pres . @@ -109,7 +109,7 @@ returns the number of bits in the network number. On error, it returns \-1, and .I errno is set to indicate the error. -.PP +.P On success, .BR inet_net_ntop () returns @@ -138,16 +138,16 @@ None. The network number may be specified either as a hexadecimal value or in dotted-decimal notation. -.PP +.P Hexadecimal values are indicated by an initial "0x" or "0X". The hexadecimal digits populate the nibbles (half octets) of the network number from left to right in network byte order. .\" If the hexadecimal string is short, the remaining nibbles are zeroed. -.PP +.P In dotted-decimal notation, up to four octets are specified, as decimal numbers separated by dots. Thus, any of the following forms are accepted: -.PP +.P .in +4n .EX a.b.c.d @@ -156,7 +156,7 @@ a.b a .EE .in -.PP +.P Each part is a number in the range 0 to 255 that populates one byte of the resulting network number, going from left to right, in network-byte (big endian) order. @@ -164,7 +164,7 @@ Where a part is omitted, the resulting byte in the network number is zero. .\" Reading other man pages, some other implementations treat .\" 'c' in a.b.c as a 16-bit number that populates right-most two bytes .\" 'b' in a.b as a 24-bit number that populates right-most three bytes -.PP +.P For either hexadecimal or dotted-decimal format, the network number can optionally be followed by a slash and a number in the range 0 to 32, @@ -210,7 +210,7 @@ is 16. Otherwise, .I bits is 8. -.PP +.P If the resulting .I bits value from the above steps is greater than or equal to 8, @@ -233,7 +233,7 @@ It then uses .BR inet_net_ntop () to convert the binary form back to presentation format, and displays the resulting string. -.PP +.P In order to demonstrate that .BR inet_net_pton () may not write to all bytes of its @@ -247,11 +247,11 @@ the program displays all of the bytes of the buffer returned by .BR inet_net_pton () allowing the user to see which bytes have not been touched by .BR inet_net_pton (). -.PP +.P An example run, showing that .BR inet_net_pton () infers the number of bits in the network number: -.PP +.P .in +4n .EX $ \fB./a.out 193.168\fP @@ -260,11 +260,11 @@ inet_net_ntop() yielded: 193.168.0/24 Raw address: c1a80000 .EE .in -.PP +.P Demonstrate that .BR inet_net_pton () does not zero out unused bytes in its result buffer: -.PP +.P .in +4n .EX $ \fB./a.out 193.168 0xffffffff\fP @@ -273,13 +273,13 @@ inet_net_ntop() yielded: 193.168.0/24 Raw address: c1a800ff .EE .in -.PP +.P Demonstrate that .BR inet_net_pton () will widen the inferred size of the network number, if the supplied number of bytes in the presentation string exceeds the inferred value: -.PP +.P .in +4n .EX $ \fB./a.out 193.168.1.128\fP @@ -288,13 +288,13 @@ inet_net_ntop() yielded: 193.168.1.128/32 Raw address: c1a80180 .EE .in -.PP +.P Explicitly specifying the size of the network number overrides any inference about its size (but any extra bytes that are explicitly specified will still be used by .BR inet_net_pton (): to populate the result buffer): -.PP +.P .in +4n .EX $ \fB./a.out 193.168.1.128/24\fP diff --git a/man3/inet_ntop.3 b/man3/inet_ntop.3 index 6f6d853..3d2d78b 100644 --- a/man3/inet_ntop.3 +++ b/man3/inet_ntop.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" References: RFC 2553 -.TH inet_ntop 3 2023-07-20 "Linux man-pages 6.05.01" +.TH inet_ntop 3 2023-10-31 "Linux man-pages 6.7" .SH NAME inet_ntop \- convert IPv4 and IPv6 addresses from binary to text form .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "const char *inet_ntop(int " af ", const void *restrict " src , .BI " char " dst "[restrict ." size "], socklen_t " size ); .fi @@ -29,7 +29,7 @@ which must be a non-null pointer. The caller specifies the number of bytes available in this buffer in the argument .IR size . -.PP +.P .BR inet_ntop () extends the .BR inet_ntoa (3) @@ -95,12 +95,11 @@ T{ .BR inet_ntop () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Note that RFC\ 2553 defines a prototype where the last argument .I size is of type diff --git a/man3/inet_pton.3 b/man3/inet_pton.3 index 420a642..37eb97c 100644 --- a/man3/inet_pton.3 +++ b/man3/inet_pton.3 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" References: RFC 2553 -.TH inet_pton 3 2023-07-20 "Linux man-pages 6.05.01" +.TH inet_pton 3 2023-10-31 "Linux man-pages 6.7" .SH NAME inet_pton \- convert IPv4 and IPv6 addresses from text to binary form .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int inet_pton(int " af ", const char *restrict " src \ ", void *restrict " dst ); .fi @@ -35,7 +35,7 @@ or .BR AF_INET6 . .I dst is written in network byte order. -.PP +.P The following address families are currently supported: .TP .B AF_INET @@ -127,7 +127,6 @@ T{ .BR inet_pton () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS Unlike .BR inet_aton (3) @@ -163,7 +162,7 @@ The program below demonstrates the use of and .BR inet_ntop (3). Here are some example runs: -.PP +.P .in +4n .EX .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" diff --git a/man3/initgroups.3 b/man3/initgroups.3 index 81505cb..b389f2b 100644 --- a/man3/initgroups.3 +++ b/man3/initgroups.3 @@ -10,7 +10,7 @@ .\" Modified 1993-07-24 by Rik Faith .\" Modified 2004-10-10 by aeb .\" -.TH initgroups 3 2023-07-20 "Linux man-pages 6.05.01" +.TH initgroups 3 2023-10-31 "Linux man-pages 6.7" .SH NAME initgroups \- initialize the supplementary group access list .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int initgroups(const char *" user ", gid_t " group ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR initgroups (): .nf Since glibc 2.19: @@ -50,7 +50,7 @@ The additional group .I group is also added to the list. -.PP +.P The .I user argument must be non-NULL. @@ -88,7 +88,6 @@ T{ .BR initgroups () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/insque.3 b/man3/insque.3 index d3444ce..dba8dfb 100644 --- a/man3/insque.3 +++ b/man3/insque.3 @@ -14,7 +14,7 @@ .\" mtk, 2010-09-09: Noted glibc 2.4 bug, added info on circular .\" lists, added example program .\" -.TH insque 3 2023-07-20 "Linux man-pages 6.05.01" +.TH insque 3 2023-10-31 "Linux man-pages 6.7" .SH NAME insque, remque \- insert/remove an item from a queue .SH LIBRARY @@ -23,16 +23,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void insque(void *" elem ", void *" prev ); .BI "void remque(void *" elem ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR insque (), .BR remque (): .nf @@ -53,19 +53,19 @@ backward pointer. The linked list may be linear (i.e., NULL forward pointer at the end of the list and NULL backward pointer at the start of the list) or circular. -.PP +.P The .BR insque () function inserts the element pointed to by \fIelem\fP immediately after the element pointed to by \fIprev\fP. -.PP +.P If the list is linear, then the call .I "insque(elem, NULL)" can be used to insert the initial list element, and the call sets the forward and backward pointers of .I elem to NULL. -.PP +.P If the list is circular, the caller should ensure that the forward and backward pointers of the first element are initialized to point to that element, @@ -74,7 +74,7 @@ and the argument of the .BR insque () call should also point to the element. -.PP +.P The .BR remque () function removes the element pointed to by \fIelem\fP from the @@ -94,13 +94,12 @@ T{ .BR remque () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On ancient systems, .\" e.g., SunOS, Linux libc4 and libc5 the arguments of these functions were of type \fIstruct qelem *\fP, defined as: -.PP +.P .in +4n .EX struct qelem { @@ -110,12 +109,12 @@ struct qelem { }; .EE .in -.PP +.P This is still what you will get if .B _GNU_SOURCE is defined before including \fI\fP. -.PP +.P The location of the prototypes for these functions differs among several versions of UNIX. The above is the POSIX version. @@ -137,7 +136,7 @@ with the forward and backward pointers in each element suitably initialized. The program below demonstrates the use of .BR insque (). Here is an example run of the program: -.PP +.P .in +4n .EX .RB "$ " "./a.out \-c a b c" diff --git a/man3/intro.3 b/man3/intro.3 index 7f72ae6..f714614 100644 --- a/man3/intro.3 +++ b/man3/intro.3 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" 2007-10-23 mtk, Nearly a complete rewrite of the earlier page. -.TH intro 3 2023-02-05 "Linux man-pages 6.05.01" +.TH intro 3 2023-10-31 "Linux man-pages 6.7" .SH NAME intro \- introduction to library functions .SH DESCRIPTION @@ -12,7 +12,7 @@ excluding the library functions (system call wrappers) described in Section 2, which implement system calls. -.PP +.P Many of the functions described in the section are part of the Standard C Library .RI ( libc ). @@ -30,7 +30,7 @@ and .IR \-lrt , respectively, for the aforementioned libraries). -.PP +.P In some cases, the programmer must define a feature test macro in order to obtain the declaration of a function from the header file specified @@ -86,12 +86,12 @@ and its many implementations: 3head .IP \[bu] 3type -.PP +.P This difficult history frequently makes it a poor example to follow in design, implementation, and presentation. -.PP +.P Ideally, a library for the C language is designed such that each header file diff --git a/man3/isalpha.3 b/man3/isalpha.3 index cf0d54a..68afb7a 100644 --- a/man3/isalpha.3 +++ b/man3/isalpha.3 @@ -8,7 +8,7 @@ .\" Modified Sat Sep 2 21:52:01 1995 by Jim Van Zandt .\" Modified Mon May 27 22:55:26 1996 by Martin Schulze (joey@linux.de) .\" -.TH isalpha 3 2023-07-30 "Linux man-pages 6.05.01" +.TH isalpha 3 2024-02-25 "Linux man-pages 6.7" .SH NAME isalnum, isalpha, isascii, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int isalnum(int " c ); .BI "int isalpha(int " c ); .BI "int iscntrl(int " c ); @@ -34,10 +34,10 @@ Standard C library .BI "int isspace(int " c ); .BI "int isupper(int " c ); .BI "int isxdigit(int " c ); -.PP +.P .BI "int isascii(int " c ); .BI "int isblank(int " c ); -.PP +.P .BI "int isalnum_l(int " c ", locale_t " locale ); .BI "int isalpha_l(int " c ", locale_t " locale ); .BI "int isblank_l(int " c ", locale_t " locale ); @@ -50,28 +50,28 @@ Standard C library .BI "int isspace_l(int " c ", locale_t " locale ); .BI "int isupper_l(int " c ", locale_t " locale ); .BI "int isxdigit_l(int " c ", locale_t " locale ); -.PP +.P .BI "int isascii_l(int " c ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE .ad l -.PP +.P .BR isascii (): .nf _XOPEN_SOURCE || /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE .fi -.PP +.P .BR isblank (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L .fi -.PP +.P .BR \%salnum_l (), .BR \%salpha_l (), .BR \%sblank_l (), @@ -90,7 +90,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.10: _GNU_SOURCE .fi -.PP +.P .BR isascii_l (): .nf Since glibc 2.10: @@ -109,7 +109,7 @@ or falls into a certain character class according to the specified locale. The functions without the "_l" suffix perform the check based on the current locale. -.PP +.P The functions with the "_l" suffix perform the check based on the locale specified by the locale object .IR locale . @@ -120,7 +120,7 @@ is the special locale object (see .BR duplocale (3)) or is not a valid locale object handle. -.PP +.P The list below explains the operation of the functions without the "_l" suffix; the functions with the "_l" suffix differ only in using the locale object @@ -170,9 +170,9 @@ alphanumeric character. .BR isspace () checks for white-space characters. In the -.B """C""" +.B \[dq]C\[dq] and -.B """POSIX""" +.B \[dq]POSIX\[dq] locales, these are: space, form-feed .RB ( \[aq]\ef\[aq] ), newline @@ -221,7 +221,6 @@ T{ .BR isxdigit () T} Thread safety MT-Safe .TE -.sp 1 .\" FIXME: need a thread-safety statement about the *_l functions .SH STANDARDS .TP @@ -357,7 +356,7 @@ is of type it must be cast to .IR "unsigned char" , as in the following example: -.PP +.P .in +4n .EX char c; @@ -365,7 +364,7 @@ char c; res = toupper((unsigned char) c); .EE .in -.PP +.P This is necessary because .I char may be the equivalent of @@ -375,7 +374,7 @@ converting to .IR int , yielding a value that is outside the range of .IR "unsigned char" . -.PP +.P The details of what characters belong to which class depend on the locale. For example, diff --git a/man3/isatty.3 b/man3/isatty.3 index fe44c88..2276550 100644 --- a/man3/isatty.3 +++ b/man3/isatty.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH isatty 3 2023-07-20 "Linux man-pages 6.05.01" +.TH isatty 3 2023-10-31 "Linux man-pages 6.7" .SH NAME isatty \- test whether a file descriptor refers to a terminal .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int isatty(int " fd ); .fi .SH DESCRIPTION @@ -59,7 +59,6 @@ T{ .BR isatty () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/isfdtype.3 b/man3/isfdtype.3 index e8eb1f4..1717a1c 100644 --- a/man3/isfdtype.3 +++ b/man3/isfdtype.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH isfdtype 3 2023-03-30 "Linux man-pages 6.05.01" +.TH isfdtype 3 2023-10-31 "Linux man-pages 6.7" .SH NAME isfdtype \- test file type of a file descriptor .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int isfdtype(int " fd ", int " fdtype ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR isfdtype (): .nf Since glibc 2.20: diff --git a/man3/isgreater.3 b/man3/isgreater.3 index b5c30d5..e097523 100644 --- a/man3/isgreater.3 +++ b/man3/isgreater.3 @@ -6,7 +6,7 @@ .\" 2002-07-27 Walter Harms .\" this was done with the help of the glibc manual .\" -.TH isgreater 3 2023-07-20 "Linux man-pages 6.05.01" +.TH isgreater 3 2023-10-31 "Linux man-pages 6.7" .SH NAME isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered \- floating-point relational tests without exception for NaN @@ -16,7 +16,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int isgreater(" x ", " y ); .BI "int isgreaterequal(" x ", " y ); .BI "int isless(" x ", " y ); @@ -24,12 +24,12 @@ Math library .BI "int islessgreater(" x ", " y ); .BI "int isunordered(" x ", " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf All functions described here: _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -41,7 +41,7 @@ The normal relational operations (like fail if one of the operands is NaN. This will cause an exception. To avoid this, C99 defines the macros listed below. -.PP +.P These macros are guaranteed to evaluate their arguments only once. The arguments must be of real floating-point type (note: do not pass integer values as arguments to these macros, since the arguments will @@ -102,7 +102,7 @@ The macros other than .BR isunordered () return the result of the relational comparison; these macros return 0 if either argument is a NaN. -.PP +.P .BR isunordered () returns 1 if .I x @@ -130,7 +130,6 @@ T{ .BR isunordered () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Not all hardware supports these functions, and where hardware support isn't provided, they will be emulated by macros. diff --git a/man3/iswalnum.3 b/man3/iswalnum.3 index 9d5bb24..2010987 100644 --- a/man3/iswalnum.3 +++ b/man3/iswalnum.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswalnum 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswalnum 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswalnum \- test for alphanumeric wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswalnum(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,26 +31,26 @@ It tests whether .I wc is a wide character belonging to the wide-character class "alnum". -.PP +.P The wide-character class "alnum" is a subclass of the wide-character class "graph", and therefore also a subclass of the wide-character class "print". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "alnum" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "alnum" is disjoint from the wide-character class "space" and its subclass "blank". -.PP +.P The wide-character class "alnum" is disjoint from the wide-character class "punct". -.PP +.P The wide-character class "alnum" is the union of the wide-character classes "alpha" and "digit". As such, it also contains the wide-character class "xdigit". -.PP +.P The wide-character class "alnum" always contains at least the letters \[aq]A\[aq] to \[aq]Z\[aq], @@ -79,7 +79,6 @@ T{ .BR iswalnum () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswalpha.3 b/man3/iswalpha.3 index a05dfe9..612a8d8 100644 --- a/man3/iswalpha.3 +++ b/man3/iswalpha.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswalpha 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswalpha 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswalpha \- test for alphabetic wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswalpha(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,30 +31,30 @@ It tests whether .I wc is a wide character belonging to the wide-character class "alpha". -.PP +.P The wide-character class "alpha" is a subclass of the wide-character class "alnum", and therefore also a subclass of the wide-character class "graph" and of the wide-character class "print". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "alpha" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "alpha" is disjoint from the wide-character class "space" and its subclass "blank". -.PP +.P Being a subclass of the wide-character class "alnum", the wide-character class "alpha" is disjoint from the wide-character class "punct". -.PP +.P The wide-character class "alpha" is disjoint from the wide-character class "digit". -.PP +.P The wide-character class "alpha" contains the wide-character classes "upper" and "lower". -.PP +.P The wide-character class "alpha" always contains at least the letters \[aq]A\[aq] to \[aq]Z\[aq] and \[aq]a\[aq] to \[aq]z\[aq]. .SH RETURN VALUE @@ -80,7 +80,6 @@ T{ .BR iswalpha () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswblank.3 b/man3/iswblank.3 index 84599ab..d50034c 100644 --- a/man3/iswblank.3 +++ b/man3/iswblank.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswblank 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswblank 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswblank \- test for whitespace wide character .SH LIBRARY @@ -18,15 +18,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswblank(wint_t " wc ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR iswblank (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -39,16 +39,16 @@ function is the wide-character equivalent of the function. It tests whether \fIwc\fP is a wide character belonging to the wide-character class "blank". -.PP +.P The wide-character class "blank" is a subclass of the wide-character class "space". -.PP +.P Being a subclass of the wide-character class "space", the wide-character class "blank" is disjoint from the wide-character class "graph" and therefore also disjoint from its subclasses "alnum", "alpha", "upper", "lower", "digit", "xdigit", "punct". -.PP +.P The wide-character class "blank" always contains at least the space character and the control character \[aq]\et\[aq]. @@ -73,7 +73,6 @@ T{ .BR iswblank () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/iswcntrl.3 b/man3/iswcntrl.3 index 40d78e8..bd1a3df 100644 --- a/man3/iswcntrl.3 +++ b/man3/iswcntrl.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswcntrl 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswcntrl 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswcntrl \- test for control wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswcntrl(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,11 +31,11 @@ It tests whether .I wc is a wide character belonging to the wide-character class "cntrl". -.PP +.P The wide-character class "cntrl" is disjoint from the wide-character class "print" and therefore also disjoint from its subclasses "graph", "alpha", "upper", "lower", "digit", "xdigit", "punct". -.PP +.P For an unsigned char .IR c , .I iscntrl(c) @@ -64,7 +64,6 @@ T{ .BR iswcntrl () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswctype.3 b/man3/iswctype.3 index 6326345..78e9686 100644 --- a/man3/iswctype.3 +++ b/man3/iswctype.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswctype 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswctype 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswctype \- wide-character classification .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswctype(wint_t " wc ", wctype_t " desc ); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ If is .BR WEOF , zero is returned. -.PP +.P .I desc must be a character property descriptor returned by the @@ -67,7 +67,6 @@ T{ .BR iswctype () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswdigit.3 b/man3/iswdigit.3 index b4d187d..c055919 100644 --- a/man3/iswdigit.3 +++ b/man3/iswdigit.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswdigit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswdigit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswdigit \- test for decimal digit wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswdigit(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,29 +31,29 @@ It tests whether .I wc is a wide character belonging to the wide-character class "digit". -.PP +.P The wide-character class "digit" is a subclass of the wide-character class "xdigit", and therefore also a subclass of the wide-character class "alnum", of the wide-character class "graph" and of the wide-character class "print". -.PP +.P Being a subclass of the wide character class "print", the wide-character class "digit" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "digit" is disjoint from the wide-character class "space" and its subclass "blank". -.PP +.P Being a subclass of the wide-character class "alnum", the wide-character class "digit" is disjoint from the wide-character class "punct". -.PP +.P The wide-character class "digit" is disjoint from the wide-character class "alpha" and therefore also disjoint from its subclasses "lower", "upper". -.PP +.P The wide-character class "digit" always contains exactly the digits \[aq]0\[aq] to \[aq]9\[aq]. .SH RETURN VALUE @@ -79,7 +79,6 @@ T{ .BR iswdigit () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswgraph.3 b/man3/iswgraph.3 index 3af1b76..35ee1a3 100644 --- a/man3/iswgraph.3 +++ b/man3/iswgraph.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswgraph 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswgraph 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswgraph \- test for graphic wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswgraph(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,20 +31,20 @@ It tests whether .I wc is a wide character belonging to the wide-character class "graph". -.PP +.P The wide-character class "graph" is a subclass of the wide-character class "print". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "graph" is disjoint from the wide-character class "cntrl". -.PP +.P The wide-character class "graph" is disjoint from the wide-character class "space" and therefore also disjoint from its subclass "blank". .\" Note: UNIX98 (susv2/xbd/locale.html) says that "graph" and "space" may .\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 .\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. -.PP +.P The wide-character class "graph" contains all the wide characters from the wide-character class "print" except the space character. It therefore contains @@ -72,7 +72,6 @@ T{ .BR iswgraph () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswlower.3 b/man3/iswlower.3 index 1115275..8aa7742 100644 --- a/man3/iswlower.3 +++ b/man3/iswlower.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswlower 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswlower 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswlower \- test for lowercase wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswlower(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,28 +31,28 @@ It tests whether .I wc is a wide character belonging to the wide-character class "lower". -.PP +.P The wide-character class "lower" is a subclass of the wide-character class "alpha", and therefore also a subclass of the wide-character class "alnum", of the wide-character class "graph" and of the wide-character class "print". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "lower" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "lower" is disjoint from the wide-character class "space" and its subclass "blank". -.PP +.P Being a subclass of the wide-character class "alnum", the wide-character class "lower" is disjoint from the wide-character class "punct". -.PP +.P Being a subclass of the wide-character class "alpha", the wide-character class "lower" is disjoint from the wide-character class "digit". -.PP +.P The wide-character class "lower" contains at least those characters .I wc @@ -60,7 +60,7 @@ which are equal to .I towlower(wc) and different from .IR towupper(wc) . -.PP +.P The wide-character class "lower" always contains at least the letters \[aq]a\[aq] to \[aq]z\[aq]. .SH RETURN VALUE @@ -86,7 +86,6 @@ T{ .BR iswlower () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -98,7 +97,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P This function is not very appropriate for dealing with Unicode characters, because Unicode knows about three cases: upper, lower, and title case. .SH SEE ALSO diff --git a/man3/iswprint.3 b/man3/iswprint.3 index cfd1e94..bc58b25 100644 --- a/man3/iswprint.3 +++ b/man3/iswprint.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswprint 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswprint 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswprint \- test for printing wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswprint(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,10 +31,10 @@ It tests whether .I wc is a wide character belonging to the wide-character class "print". -.PP +.P The wide-character class "print" is disjoint from the wide-character class "cntrl". -.PP +.P The wide-character class "print" contains the wide-character class "graph". .SH RETURN VALUE The @@ -58,7 +58,6 @@ T{ .BR iswprint () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswpunct.3 b/man3/iswpunct.3 index b3b9f57..6e74b60 100644 --- a/man3/iswpunct.3 +++ b/man3/iswpunct.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswpunct 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswpunct 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswpunct \- test for punctuation or symbolic wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswpunct(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,18 +31,18 @@ It tests whether .I wc is a wide character belonging to the wide-character class "punct". -.PP +.P The wide-character class "punct" is a subclass of the wide-character class "graph", and therefore also a subclass of the wide-character class "print". -.PP +.P The wide-character class "punct" is disjoint from the wide-character class "alnum" and therefore also disjoint from its subclasses "alpha", "upper", "lower", "digit", "xdigit". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "punct" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "punct" is disjoint from the wide-character class "space" and its subclass @@ -70,7 +70,6 @@ T{ .BR iswpunct () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -82,7 +81,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P This function's name is a misnomer when dealing with Unicode characters, because the wide-character class "punct" contains both punctuation characters and symbol (math, currency, etc.) characters. diff --git a/man3/iswspace.3 b/man3/iswspace.3 index fce481d..e87b80a 100644 --- a/man3/iswspace.3 +++ b/man3/iswspace.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswspace 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswspace 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswspace \- test for whitespace wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswspace(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,16 +31,16 @@ It tests whether .I wc is a wide character belonging to the wide-character class "space". -.PP +.P The wide-character class "space" is disjoint from the wide-character class "graph" and therefore also disjoint from its subclasses "alnum", "alpha", "upper", "lower", "digit", "xdigit", "punct". .\" Note: UNIX98 (susv2/xbd/locale.html) says that "space" and "graph" may .\" have characters in common, except U+0020. But C99 (ISO/IEC 9899:1999 .\" section 7.25.2.1.10) says that "space" and "graph" are disjoint. -.PP +.P The wide-character class "space" contains the wide-character class "blank". -.PP +.P The wide-character class "space" always contains at least the space character and the control characters @@ -67,7 +67,6 @@ T{ .BR iswspace () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/iswupper.3 b/man3/iswupper.3 index 64bc4f0..82ec81b 100644 --- a/man3/iswupper.3 +++ b/man3/iswupper.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswupper 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswupper 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswupper \- test for uppercase wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswupper(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,31 +31,31 @@ It tests whether .I wc is a wide character belonging to the wide-character class "upper". -.PP +.P The wide-character class "upper" is a subclass of the wide-character class "alpha", and therefore also a subclass of the wide-character class "alnum", of the wide-character class "graph" and of the wide-character class "print". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "upper" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "upper" is disjoint from the wide-character class "space" and its subclass "blank". -.PP +.P Being a subclass of the wide-character class "alnum", the wide-character class "upper" is disjoint from the wide-character class "punct". -.PP +.P Being a subclass of the wide-character class "alpha", the wide-character class "upper" is disjoint from the wide-character class "digit". -.PP +.P The wide-character class "upper" contains at least those characters .I wc which are equal to .I towupper(wc) and different from .IR towlower(wc) . -.PP +.P The wide-character class "upper" always contains at least the letters \[aq]A\[aq] to \[aq]Z\[aq]. .SH RETURN VALUE @@ -80,7 +80,6 @@ T{ .BR iswupper () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -92,7 +91,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P This function is not very appropriate for dealing with Unicode characters, because Unicode knows about three cases: upper, lower, and title case. .SH SEE ALSO diff --git a/man3/iswxdigit.3 b/man3/iswxdigit.3 index 7be65b5..5eb226b 100644 --- a/man3/iswxdigit.3 +++ b/man3/iswxdigit.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH iswxdigit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH iswxdigit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME iswxdigit \- test for hexadecimal digit wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int iswxdigit(wint_t " wc ); .fi .SH DESCRIPTION @@ -31,21 +31,21 @@ It tests whether .I wc is a wide character belonging to the wide-character class "xdigit". -.PP +.P The wide-character class "xdigit" is a subclass of the wide-character class "alnum", and therefore also a subclass of the wide-character class "graph" and of the wide-character class "print". -.PP +.P Being a subclass of the wide-character class "print", the wide-character class "xdigit" is disjoint from the wide-character class "cntrl". -.PP +.P Being a subclass of the wide-character class "graph", the wide-character class "xdigit" is disjoint from the wide-character class "space" and its subclass "blank". -.PP +.P Being a subclass of the wide-character class "alnum", the wide-character class "xdigit" is disjoint from the wide-character class "punct". -.PP +.P The wide-character class "xdigit" always contains at least the letters \[aq]A\[aq] to \[aq]F\[aq], \[aq]a\[aq] to \[aq]f\[aq] and the digits \[aq]0\[aq] to \[aq]9\[aq]. @@ -71,7 +71,6 @@ T{ .BR iswxdigit () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/j0.3 b/man3/j0.3 index 1ca739b..919c256 100644 --- a/man3/j0.3 +++ b/man3/j0.3 @@ -14,7 +14,7 @@ .\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB .\" 2008-07-24, mtk, moved yxx() material into separate y0.3 page .\" -.TH j0 3 2023-07-20 "Linux man-pages 6.05.01" +.TH j0 3 2023-10-31 "Linux man-pages 6.7" .SH NAME j0, j0f, j0l, j1, j1f, j1l, jn, jnf, jnl \- Bessel functions of the first kind @@ -24,25 +24,25 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double j0(double " x ); .BI "double j1(double " x ); .BI "double jn(int " n ", double " x ); -.PP +.P .BI "float j0f(float " x ); .BI "float j1f(float " x ); .BI "float jnf(int " n ", float " x ); -.PP +.P .BI "long double j0l(long double " x ); .BI "long double j1l(long double " x ); .BI "long double jnl(int " n ", long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR j0 (), .BR j1 (), .BR jn (): @@ -51,7 +51,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P .BR j0f (), .BR j0l (), .BR j1f (), @@ -79,7 +79,7 @@ returns the Bessel function of .I x of the first kind of order .IR n . -.PP +.P The .BR j0f (), .BR j1f (), @@ -100,11 +100,11 @@ values. On success, these functions return the appropriate Bessel value of the first kind for .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is too large in magnitude, @@ -116,14 +116,14 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result underflow, or \fIx\fP is too large in magnitude .I errno is set to .BR ERANGE . -.PP +.P These functions do not raise exceptions for .BR fetestexcept (3). .\" e.g., j0(1.5e16) @@ -159,7 +159,6 @@ T{ .BR jnl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR j0 () diff --git a/man3/key_setsecret.3 b/man3/key_setsecret.3 index 13e8051..a8c4470 100644 --- a/man3/key_setsecret.3 +++ b/man3/key_setsecret.3 @@ -5,7 +5,7 @@ .\" .\" I had no way the check the functions out .\" be careful -.TH key_setsecret 3 2023-07-20 "Linux man-pages 6.05.01" +.TH key_setsecret 3 2023-10-31 "Linux man-pages 6.7" .SH NAME key_decryptsession, key_encryptsession, key_setsecret, key_gendes, key_secretkey_is_set \- interfaces to rpc keyserver daemon @@ -15,12 +15,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int key_decryptsession(char *" remotename ", des_block *" deskey ); .BI "int key_encryptsession(char *" remotename ", des_block *" deskey ); -.PP +.P .BI "int key_gendes(des_block *" deskey ); -.PP +.P .BI "int key_setsecret(char *" key ); .B int key_secretkey_is_set(void); .fi @@ -29,29 +29,29 @@ The functions here are used within the RPC's secure authentication mechanism (AUTH_DES). There should be no need for user programs to use this functions. -.PP +.P The function .BR key_decryptsession () uses the (remote) server netname and takes the DES key for decrypting. It uses the public key of the server and the secret key associated with the effective UID of the calling process. -.PP +.P The function .BR key_encryptsession () is the inverse of .BR key_decryptsession (). It encrypts the DES keys with the public key of the server and the secret key associated with the effective UID of the calling process. -.PP +.P The function .BR key_gendes () is used to ask the keyserver for a secure conversation key. -.PP +.P The function .BR key_setsecret () is used to set the key for the effective UID of the calling process. -.PP +.P The function .BR key_secretkey_is_set () can be used to determine whether a key has been @@ -76,13 +76,12 @@ T{ .BR key_secretkey_is_set () T} Thread safety MT-Safe .TE -.sp 1 .SH NOTES Note that we talk about two types of encryption here. One is asymmetric using a public and secret key. The other is symmetric, the 64-bit DES. -.PP +.P These routines were part of the Linux/Doors-project, abandoned by now. .SH SEE ALSO .BR crypt (3) diff --git a/man3/killpg.3 b/man3/killpg.3 index a146316..14533ef 100644 --- a/man3/killpg.3 +++ b/man3/killpg.3 @@ -11,7 +11,7 @@ .\" Added notes on CAP_KILL .\" Modified 2004-06-21 by aeb .\" -.TH killpg 3 2023-03-30 "Linux man-pages 6.05.01" +.TH killpg 3 2023-10-31 "Linux man-pages 6.7" .SH NAME killpg \- send signal to a process group .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int killpg(int " pgrp ", int " sig ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR killpg (): .nf _XOPEN_SOURCE >= 500 @@ -45,7 +45,7 @@ to the process group See .BR signal (7) for a list of signals. -.PP +.P If .I pgrp is 0, @@ -54,7 +54,7 @@ sends the signal to the calling process's process group. (POSIX says: if .I pgrp is less than or equal to 1, the behavior is undefined.) -.PP +.P For the permissions required to send a signal to another process, see .BR kill (2). .SH RETURN VALUE diff --git a/man3/ldexp.3 b/man3/ldexp.3 index e1fb88c..926aa47 100644 --- a/man3/ldexp.3 +++ b/man3/ldexp.3 @@ -12,7 +12,7 @@ .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2004-10-31 by aeb .\" -.TH ldexp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ldexp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ldexp, ldexpf, ldexpl \- multiply floating-point number by integral power of 2 .SH LIBRARY @@ -21,17 +21,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double ldexp(double " x ", int " exp ); .BI "float ldexpf(float " x ", int " exp ); .BI "long double ldexpl(long double " x ", int " exp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ldexpf (), .BR ldexpl (): .nf @@ -47,27 +47,27 @@ by 2 raised to the power .SH RETURN VALUE On success, these functions return .IR "x * (2\[ha]exp)" . -.PP +.P If .I exp is zero, then .I x is returned. -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity (negative infinity), positive infinity (negative infinity) is returned. -.PP +.P If the result underflows, a range error occurs, and zero is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -82,7 +82,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error, overflow @@ -116,12 +116,11 @@ T{ .BR ldexpl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/lgamma.3 b/man3/lgamma.3 index cbcf363..cd4d57a 100644 --- a/man3/lgamma.3 +++ b/man3/lgamma.3 @@ -6,7 +6,7 @@ .\" .\" based on glibc infopages .\" -.TH lgamma 3 2023-03-30 "Linux man-pages 6.05.01" +.TH lgamma 3 2023-10-31 "Linux man-pages 6.7" .SH NAME lgamma, lgammaf, lgammal, lgamma_r, lgammaf_r, lgammal_r, signgam \- log gamma function @@ -16,30 +16,30 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double lgamma(double " x ); .BI "float lgammaf(float " x ); .BI "long double lgammal(long double " x ); -.PP +.P .BI "double lgamma_r(double " x ", int *" signp ); .BI "float lgammaf_r(float " x ", int *" signp ); .BI "long double lgammal_r(long double " x ", int *" signp ); -.PP +.P .BI "extern int " signgam ; .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR lgamma (): _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR lgammaf (), .BR lgammal (): .nf @@ -47,7 +47,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR lgamma_r (), .BR lgammaf_r (), .BR lgammal_r (): @@ -55,7 +55,7 @@ Feature Test Macro Requirements for glibc (see /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .IR signgam : .nf _XOPEN_SOURCE @@ -65,7 +65,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION For the definition of the Gamma function, see .BR tgamma (3). -.PP +.P The .BR lgamma (), .BR lgammaf (), @@ -80,7 +80,7 @@ declared in .IR . It is 1 when the Gamma function is positive or zero, \-1 when it is negative. -.PP +.P Since using a constant location .I signgam is not thread-safe, the functions @@ -92,20 +92,20 @@ have been introduced; they return the sign via the argument .IR signp . .SH RETURN VALUE On success, these functions return the natural logarithm of Gamma(x). -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is 1 or 2, +0 is returned. -.PP +.P If .I x is positive infinity or negative infinity, positive infinity is returned. -.PP +.P If .I x is a nonpositive integer, @@ -116,7 +116,7 @@ and the functions return or .RB + HUGE_VALL , respectively. -.PP +.P If the result overflows, a range error occurs, .\" e.g., lgamma(DBL_MAX) @@ -131,7 +131,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Pole error: \fIx\fP is a nonpositive integer diff --git a/man3/lio_listio.3 b/man3/lio_listio.3 index 0cca6e4..1829358 100644 --- a/man3/lio_listio.3 +++ b/man3/lio_listio.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH lio_listio 3 2023-07-20 "Linux man-pages 6.05.01" +.TH lio_listio 3 2023-10-31 "Linux man-pages 6.7" .SH NAME lio_listio \- initiate a list of I/O requests .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int lio_listio(int " mode , .BI " struct aiocb *restrict const " aiocb_list [restrict], .BI " int " nitems ", struct sigevent *restrict " sevp ); @@ -22,7 +22,7 @@ The .BR lio_listio () function initiates the list of I/O operations described by the array .IR aiocb_list . -.PP +.P The .I mode operation has one of the following values: @@ -39,12 +39,12 @@ When all of the I/O operations complete, asynchronous notification occurs, as specified by the .I sevp argument; see -.BR sigevent (7) +.BR sigevent (3type) for details. If .I sevp is NULL, no asynchronous notification occurs. -.PP +.P The .I aiocb_list argument is an array of pointers to @@ -58,7 +58,7 @@ argument specifies the size of the array Null pointers in .I aiocb_list are ignored. -.PP +.P In each control block in .IR aiocb_list , the @@ -79,7 +79,7 @@ specifying this control block. .TP .B LIO_NOP Ignore this control block. -.PP +.P The remaining fields in each control block have the same meanings as for .BR aio_read (3) and @@ -99,7 +99,7 @@ returns 0 if all I/O operations are successfully queued. Otherwise, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P If .I mode is @@ -109,7 +109,7 @@ returns 0 when all of the I/O operations have completed successfully. Otherwise, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P The return status from .BR lio_listio () provides information only about the call itself, @@ -168,7 +168,7 @@ failed. .\" e.g., ioa_reqprio or aio_lio_opcode was invalid The application can check the status of each operation using .BR aio_return (3). -.PP +.P If .BR lio_listio () fails with the error @@ -197,7 +197,6 @@ T{ .BR lio_listio () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -211,7 +210,7 @@ The buffer areas being read into or written from .\" or the control block of the operation must not be accessed during the operations or undefined results may occur. The memory areas involved must remain valid. -.PP +.P Simultaneous I/O operations specifying the same .I aiocb structure produce undefined results. diff --git a/man3/list.3 b/man3/list.3 index 270d5e6..cc77bde 100644 --- a/man3/list.3 +++ b/man3/list.3 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH LIST 3 2023-05-03 "Linux man-pages 6.05.01" +.TH LIST 3 2023-10-31 "Linux man-pages 6.7" .SH NAME LIST_EMPTY, LIST_ENTRY, @@ -31,43 +31,43 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B LIST_ENTRY(TYPE); -.PP +.P .B LIST_HEAD(HEADNAME, TYPE); .BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head ); .BI "void LIST_INIT(LIST_HEAD *" head ); -.PP +.P .BI "int LIST_EMPTY(LIST_HEAD *" head ); -.PP +.P .BI "void LIST_INSERT_HEAD(LIST_HEAD *" head , .BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); .BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm , .BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); .BI "void LIST_INSERT_AFTER(struct TYPE *" listelm , .BI " struct TYPE *" elm ", LIST_ENTRY " NAME ); -.PP +.P .BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head ); .\" .BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head , .\" .BI " struct TYPE, LIST_ENTRY " NAME ); .BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME ); -.PP +.P .BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ); .\" .BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ); -.\" .PP +.\" .P .\" .BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head , .\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var ); .\" .BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head , .\" .BI " LIST_ENTRY " NAME ", struct TYPE *" temp_var ); -.PP +.P .BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME ); -.\" .PP +.\" .P .\" .BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 , .\" .BI " struct TYPE, LIST_ENTRY " NAME ); .fi .SH DESCRIPTION These macros define and operate on doubly linked lists. -.PP +.P In the macro definitions, .I TYPE is the name of a user-defined structure, @@ -94,43 +94,43 @@ or at the head of the list. A .I LIST_HEAD structure is declared as follows: -.PP +.P .in +4 .EX LIST_HEAD(HEADNAME, TYPE) head; .EE .in -.PP +.P where .I struct HEADNAME is the structure to be defined, and .I struct TYPE is the type of the elements to be linked into the list. A pointer to the head of the list can later be declared as: -.PP +.P .in +4 .EX struct HEADNAME *headp; .EE .in -.PP +.P (The names .I head and .I headp are user selectable.) -.PP +.P .BR LIST_ENTRY () declares a structure that connects the elements in the list. -.PP +.P .BR LIST_HEAD_INITIALIZER () evaluates to an initializer for the list .IR head . -.PP +.P .BR LIST_INIT () initializes the list referenced by .IR head . -.PP +.P .BR LIST_EMPTY () evaluates to true if there are no elements in the list. .SS Insertion @@ -138,13 +138,13 @@ evaluates to true if there are no elements in the list. inserts the new element .I elm at the head of the list. -.PP +.P .BR LIST_INSERT_BEFORE () inserts the new element .I elm before the element .IR listelm . -.PP +.P .BR LIST_INSERT_AFTER () inserts the new element .I elm @@ -153,24 +153,24 @@ after the element .SS Traversal .BR LIST_FIRST () returns the first element in the list, or NULL if the list is empty. -.\" .PP +.\" .P .\" .BR LIST_PREV () .\" returns the previous element in the list, or NULL if this is the first. .\" List .\" .I head .\" must contain element .\" .IR elm . -.PP +.P .BR LIST_NEXT () returns the next element in the list, or NULL if this is the last. -.PP +.P .BR LIST_FOREACH () traverses the list referenced by .I head in the forward direction, assigning each element in turn to .IR var . -.\" .PP +.\" .P .\" .BR LIST_FOREACH_FROM () .\" behaves identically to .\" .BR LIST_FOREACH () @@ -182,7 +182,7 @@ assigning each element in turn to .\" .I var .\" instead of the first element in the LIST referenced by .\" .IR head . -.\" .PP +.\" .P .\" .BR LIST_FOREACH_SAFE () .\" traverses the list referenced by .\" .I head @@ -194,7 +194,7 @@ assigning each element in turn to .\" .I var .\" as well as free it from within the loop safely without interfering with the .\" traversal. -.\" .PP +.\" .P .\" .BR LIST_FOREACH_FROM_SAFE () .\" behaves identically to .\" .BR LIST_FOREACH_SAFE () @@ -221,14 +221,14 @@ from the list. .BR LIST_EMPTY () returns nonzero if the list is empty, and zero if the list contains at least one entry. -.PP +.P .BR LIST_FIRST (), and .BR LIST_NEXT () return a pointer to the first or next .I TYPE structure, respectively. -.PP +.P .BR LIST_HEAD_INITIALIZER () returns an initializer that can be assigned to the list .IR head . diff --git a/man3/localeconv.3 b/man3/localeconv.3 index 063fe11..a4b17a9 100644 --- a/man3/localeconv.3 +++ b/man3/localeconv.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Sat Jul 24 19:01:20 1993 by Rik Faith (faith@cs.unc.edu) -.TH localeconv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH localeconv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME localeconv \- get numeric formatting information .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct lconv *localeconv(void); .fi .SH DESCRIPTION @@ -64,7 +64,6 @@ T} Thread safety T{ MT-Unsafe race:localeconv locale T} .TE -.sp 1 .SH STANDARDS C11. .SH HISTORY diff --git a/man3/lockf.3 b/man3/lockf.3 index a4043ba..f8b005f 100644 --- a/man3/lockf.3 +++ b/man3/lockf.3 @@ -7,7 +7,7 @@ .\" Added section stuff, aeb, 2002-04-22. .\" Corrected include file, drepper, 2003-06-15. .\" -.TH lockf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH lockf 3 2024-03-03 "Linux man-pages 6.7" .SH NAME lockf \- apply, test or remove a POSIX lock on an open file .SH LIBRARY @@ -16,15 +16,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "int lockf(int " fd ", int " cmd ", off_t " len ); +.P +.BI "int lockf(int " fd ", int " op ", off_t " len ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR lockf (): .nf _XOPEN_SOURCE >= 500 @@ -37,7 +37,7 @@ Apply, test, or remove a POSIX lock on a section of an open file. The file is specified by .IR fd , a file descriptor open for writing, the action by -.IR cmd , +.IR op , and the section consists of byte positions .IR pos .. pos + len \-1 if @@ -53,7 +53,7 @@ is the current file position, and if is zero, the section extends from the current file position to infinity, encompassing the present and future end-of-file positions. In all cases, the section may extend past current end-of-file. -.PP +.P On Linux, .BR lockf () is just an interface on top of @@ -68,7 +68,7 @@ and locks unspecified. A portable application should probably avoid mixing calls to these interfaces. -.PP +.P Valid operations are given below: .TP .B F_LOCK @@ -118,7 +118,7 @@ been memory-mapped by another process. .B EBADF .I fd is not an open file descriptor; or -.I cmd +.I op is .B F_LOCK or @@ -128,7 +128,8 @@ and is not a writable file descriptor. .TP .B EDEADLK -The command was +.I op +was .B F_LOCK and this lock operation would cause a deadlock. .TP @@ -139,7 +140,7 @@ delivery of a signal caught by a handler; see .TP .B EINVAL An invalid operation was specified in -.IR cmd . +.IR op . .TP .B ENOLCK Too many segment locks open, lock table is full. @@ -157,7 +158,6 @@ T{ .BR lockf () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -165,7 +165,7 @@ POSIX.1-2001, SVr4. .SH SEE ALSO .BR fcntl (2), .BR flock (2) -.PP +.P .I locks.txt and .I mandatory\-locking.txt diff --git a/man3/log.3 b/man3/log.3 index 23ad8f9..89d3075 100644 --- a/man3/log.3 +++ b/man3/log.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH log 3 2023-07-20 "Linux man-pages 6.05.01" +.TH log 3 2023-10-31 "Linux man-pages 6.7" .SH NAME log, logf, logl \- natural logarithmic function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double log(double " x ); .BI "float logf(float " x ); .BI "long double logl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR logf (), .BR logl (): .nf @@ -47,21 +47,21 @@ These functions return the natural logarithm of .SH RETURN VALUE On success, these functions return the natural logarithm of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is 1, the result is +0. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is zero, @@ -71,7 +71,7 @@ then a pole error occurs, and the functions return or .RB \- HUGE_VALL , respectively. -.PP +.P If .I x is negative (including negative infinity), then @@ -81,7 +81,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is negative @@ -115,12 +115,11 @@ T{ .BR logl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/log10.3 b/man3/log10.3 index 9d3a0bb..3090864 100644 --- a/man3/log10.3 +++ b/man3/log10.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH log10 3 2023-07-20 "Linux man-pages 6.05.01" +.TH log10 3 2024-03-12 "Linux man-pages 6.7" .SH NAME log10, log10f, log10l \- base-10 logarithmic function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double log10(double " x ); .BI "float log10f(float " x ); .BI "long double log10l(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR log10f (), .BR log10l (): .nf @@ -42,12 +42,12 @@ Feature Test Macro Requirements for glibc (see || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi .SH DESCRIPTION -These functions return the base 10 logarithm of +These functions return the base-10 logarithm of .IR x . .SH RETURN VALUE -On success, these functions return the base 10 logarithm of +On success, these functions return the base-10 logarithm of .IR x . -.PP +.P For special cases, including where .I x is 0, 1, negative, infinity, or NaN, see @@ -57,7 +57,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P For a discussion of the errors that can occur for these functions, see .BR log (3). .SH ATTRIBUTES @@ -76,12 +76,11 @@ T{ .BR log10l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/log1p.3 b/man3/log1p.3 index c3285a9..dff3b5b 100644 --- a/man3/log1p.3 +++ b/man3/log1p.3 @@ -7,7 +7,7 @@ .\" .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) -.TH log1p 3 2023-07-20 "Linux man-pages 6.05.01" +.TH log1p 3 2023-10-31 "Linux man-pages 6.7" .SH NAME log1p, log1pf, log1pl \- logarithm of 1 plus argument .SH LIBRARY @@ -16,17 +16,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double log1p(double " x ); .BI "float log1pf(float " x ); .BI "long double log1pl(long double " x ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .nf .BR log1p (): _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR log1pf (), .BR log1pl (): .nf @@ -45,11 +45,11 @@ Feature Test Macro Requirements for glibc (see .fi .SH DESCRIPTION These functions return a value equivalent to -.PP +.P .nf log (1 + \fIx\fP) .fi -.PP +.P The result is computed in a way that is accurate even if the value of .I x @@ -57,16 +57,16 @@ is near zero. .SH RETURN VALUE On success, these functions return the natural logarithm of .IR "(1\ +\ x)" . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is \-1, a pole error occurs, @@ -76,7 +76,7 @@ and the functions return or .RB \- HUGE_VALL , respectively. -.PP +.P If .I x is less than \-1 (including negative infinity), @@ -89,7 +89,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is less than \-1 @@ -125,7 +125,6 @@ T{ .BR log1pl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -138,7 +137,7 @@ Before glibc 2.22, the glibc implementation did not set to .B EDOM when a domain error occurred. -.PP +.P Before glibc 2.22, the glibc implementation did not set .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6792 .I errno diff --git a/man3/log2.3 b/man3/log2.3 index 223ac99..29cc1ef 100644 --- a/man3/log2.3 +++ b/man3/log2.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH log2 3 2023-07-20 "Linux man-pages 6.05.01" +.TH log2 3 2024-03-12 "Linux man-pages 6.7" .SH NAME log2, log2f, log2l \- base-2 logarithmic function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double log2(double " x ); .BI "float log2f(float " x ); .BI "long double log2l(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR log2 (), .BR log2f (), .BR log2l (): @@ -41,12 +41,12 @@ Feature Test Macro Requirements for glibc (see _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L .fi .SH DESCRIPTION -These functions return the base 2 logarithm of +These functions return the base-2 logarithm of .IR x . .SH RETURN VALUE -On success, these functions return the base 2 logarithm of +On success, these functions return the base-2 logarithm of .IR x . -.PP +.P For special cases, including where .I x is 0, 1, negative, infinity, or NaN, see @@ -56,7 +56,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P For a discussion of the errors that can occur for these functions, see .BR log (3). .SH ATTRIBUTES @@ -75,13 +75,12 @@ T{ .BR log2l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY glibc 2.1. C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/logb.3 b/man3/logb.3 index 1bde61b..1319d94 100644 --- a/man3/logb.3 +++ b/man3/logb.3 @@ -7,7 +7,7 @@ .\" .\" Inspired by a page by Walter Harms created 2002-08-10 .\" -.TH logb 3 2023-07-20 "Linux man-pages 6.05.01" +.TH logb 3 2024-03-12 "Linux man-pages 6.7" .SH NAME logb, logbf, logbl \- get exponent of a floating-point value .SH LIBRARY @@ -16,17 +16,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double logb(double " x ); .BI "float logbf(float " x ); .BI "long double logbl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR logb (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -35,7 +35,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR logbf (), .BR logbl (): .nf @@ -57,10 +57,11 @@ If .B FLT_RADIX is 2, .BI logb( x ) -is equal to -.BI floor(log2( x ))\fR, -except that it is probably faster. -.PP +is similar to +.BI floor(log2(fabs( x )))\f[R],\f[] +except that the latter may give an incorrect integer +due to intermediate rounding. +.P If .I x is subnormal, @@ -71,12 +72,12 @@ would have if it were normalized. .SH RETURN VALUE On success, these functions return the exponent of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is zero, then a pole error occurs, and the functions return @@ -85,7 +86,7 @@ is zero, then a pole error occurs, and the functions return or .RB \- HUGE_VALL , respectively. -.PP +.P If .I x is negative infinity or positive infinity, then @@ -95,7 +96,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Pole error: \fIx\fP is 0 @@ -105,7 +106,7 @@ Pole error: \fIx\fP is 0 A divide-by-zero floating-point exception .RB ( FE_DIVBYZERO ) is raised. -.PP +.P These functions do not set .IR errno . .\" FIXME . Is it intentional that these functions do not set errno? @@ -128,7 +129,6 @@ T{ .BR logbl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/login.3 b/man3/login.3 index b6fa4ae..a77a728 100644 --- a/man3/login.3 +++ b/man3/login.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH login 3 2023-07-20 "Linux man-pages 6.05.01" +.TH login 3 2023-10-31 "Linux man-pages 6.7" .SH NAME login, logout \- write utmp and wtmp entries .SH LIBRARY @@ -13,7 +13,7 @@ System utilities library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void login(const struct utmp *" ut ); .BI "int logout(const char *" ut_line ); .fi @@ -22,14 +22,14 @@ The utmp file records who is currently using the system. The wtmp file records all logins and logouts. See .BR utmp (5). -.PP +.P The function .BR login () takes the supplied .IR "struct utmp" , .IR ut , and writes it to both the utmp and the wtmp file. -.PP +.P The function .BR logout () clears the entry in the utmp file again. @@ -59,7 +59,7 @@ On the other hand, if no terminal name was found, this field is filled with "???" and the struct is not written to the utmp file. After this, the struct is written to the wtmp file. -.PP +.P The .BR logout () function searches the utmp file for an entry matching the @@ -113,7 +113,7 @@ MT-Unsafe race:utent sig:ALRM timer T} .TE -.sp 1 +.P In the above table, .I utent in diff --git a/man3/lrint.3 b/man3/lrint.3 index 66f8598..af42930 100644 --- a/man3/lrint.3 +++ b/man3/lrint.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH lrint 3 2023-07-20 "Linux man-pages 6.05.01" +.TH lrint 3 2023-10-31 "Linux man-pages 6.7" .SH NAME lrint, lrintf, lrintl, llrint, llrintf, llrintl \- round to nearest integer .SH LIBRARY @@ -14,21 +14,21 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long lrint(double " x ); .BI "long lrintf(float " x ); .BI "long lrintl(long double " x ); -.PP +.P .BI "long long llrint(double " x ); .BI "long long llrintf(float " x ); .BI "long long llrintl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -37,7 +37,7 @@ All functions shown above: These functions round their argument to the nearest integer value, using the current rounding direction (see .BR fesetround (3)). -.PP +.P Note that unlike the .BR rint (3) family of functions, @@ -45,7 +45,7 @@ the return type of these functions differs from that of their arguments. .SH RETURN VALUE These functions return the rounded integer value. -.PP +.P If .I x is a NaN or an infinity, @@ -62,7 +62,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large @@ -72,7 +72,7 @@ Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large An invalid floating-point exception .RB ( FE_INVALID ) is raised. -.PP +.P These functions do not set .IR errno . .\" FIXME . Is it intentional that these functions do not set errno? @@ -96,7 +96,6 @@ T{ .BR llrintl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/lround.3 b/man3/lround.3 index e48f71a..1e947ff 100644 --- a/man3/lround.3 +++ b/man3/lround.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH lround 3 2023-07-20 "Linux man-pages 6.05.01" +.TH lround 3 2023-10-31 "Linux man-pages 6.7" .SH NAME lround, lroundf, lroundl, llround, llroundf, llroundl \- round to nearest integer @@ -15,21 +15,21 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long lround(double " x ); .BI "long lroundf(float " x ); .BI "long lroundl(long double " x ); -.PP +.P .BI "long long llround(double " x ); .BI "long long llroundf(float " x ); .BI "long long llroundl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -39,7 +39,7 @@ These functions round their argument to the nearest integer value, rounding halfway cases away from zero, regardless of the current rounding direction (see .BR fenv (3)). -.PP +.P Note that unlike the .BR round (3) and @@ -48,7 +48,7 @@ functions, the return type of these functions differs from that of their arguments. .SH RETURN VALUE These functions return the rounded integer value. -.PP +.P If .I x is a NaN or an infinity, @@ -65,7 +65,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large @@ -75,7 +75,7 @@ Domain error: \fIx\fP is a NaN or infinite, or the rounded value is too large An invalid floating-point exception .RB ( FE_INVALID ) is raised. -.PP +.P These functions do not set .IR errno . .\" FIXME . Is it intentional that these functions do not set errno? @@ -99,7 +99,6 @@ T{ .BR llroundl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/lsearch.3 b/man3/lsearch.3 index a419435..211f41c 100644 --- a/man3/lsearch.3 +++ b/man3/lsearch.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Corrected prototype and include, aeb, 990927 -.TH lsearch 3 2023-07-20 "Linux man-pages 6.05.01" +.TH lsearch 3 2023-10-31 "Linux man-pages 6.7" .SH NAME lfind, lsearch \- linear search of an array .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *lfind(const void " key [. size "], \ const void " base [. size " * ." nmemb ], .BI " size_t *" nmemb ", size_t " size , @@ -47,7 +47,7 @@ returns zero if the .I key object matches the array member, and nonzero otherwise. -.PP +.P If .BR lsearch () does not find a matching element, then the @@ -81,7 +81,6 @@ T{ .BR lsearch () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/lseek64.3 b/man3/lseek64.3 index aee84ed..9e2801f 100644 --- a/man3/lseek64.3 +++ b/man3/lseek64.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH lseek64 3 2023-07-20 "Linux man-pages 6.05.01" +.TH lseek64 3 2023-10-31 "Linux man-pages 6.7" .SH NAME lseek64 \- reposition 64-bit read/write file offset .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .BR "#define _LARGEFILE64_SOURCE" " /* See feature_test_macros(7) */" .B #include .B #include -.PP +.P .BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); .fi .SH DESCRIPTION @@ -35,10 +35,10 @@ has the value or .BR SEEK_END , respectively. -.PP +.P For more details, return value, and errors, see .BR lseek (2). -.PP +.P Four interfaces are available: .BR lseek (), .BR lseek64 (), @@ -51,36 +51,36 @@ and .\" .SS lseek() Prototype: -.PP +.P .in +4n .EX .BI "off_t lseek(int " fd ", off_t " offset ", int " whence ); .EE .in -.PP +.P The C library's .BR lseek () wrapper function uses the type .IR off_t . This is a 32-bit signed type on 32-bit architectures, unless one compiles with -.PP +.P .in +4n .EX #define _FILE_OFFSET_BITS 64 .EE .in -.PP +.P in which case it is a 64-bit signed type. .SS lseek64() Prototype: -.PP +.P .in +4n .EX .BI "off64_t lseek64(int " fd ", off64_t " offset ", int " whence ); .EE .in -.PP +.P The .BR lseek64 () library function uses a 64-bit type even when @@ -89,13 +89,13 @@ is a 32-bit type. Its prototype (and the type .IR off64_t ) is available only when one compiles with -.PP +.P .in +4n .EX #define _LARGEFILE64_SOURCE .EE .in -.PP +.P The function .BR lseek64 () .\" in glibc 2.0.94, not in glibc 2.0.6 @@ -103,13 +103,13 @@ is available since glibc 2.1. .\" .SS llseek() Prototype: -.PP +.P .in +4n .EX .BI "loff_t llseek(int " fd ", loff_t " offset ", int " whence ); .EE .in -.PP +.P The type .I loff_t is a 64-bit signed type. @@ -122,14 +122,14 @@ the above prototype, or something equivalent, to their own source. When users complained about data loss caused by a miscompilation of .BR e2fsck (8), glibc 2.1.3 added the link-time warning -.PP +.P .in +4n "the \`llseek\' function may be dangerous; use \`lseek64\' instead." .in -.PP +.P This makes this function unusable if one desires a warning-free compilation. -.PP +.P Since glibc 2.28, .\" glibc commit 5c5c0dd747070db624c8e2c43691cec854f114ef this function symbol is no longer available to newly linked applications. @@ -139,17 +139,17 @@ On 32-bit architectures, this is the system call that is used (by the C library wrapper functions) to implement all of the above functions. The prototype is: -.PP +.P .in +4n .EX .BI "int _llseek(int " fd ", off_t " offset_hi ", off_t " offset_lo , .BI " loff_t *" result ", int " whence ); .EE .in -.PP +.P For more details, see .BR llseek (2). -.PP +.P 64-bit systems don't need an .BR _llseek () system call. @@ -182,7 +182,6 @@ T{ .BR lseek64 () T} Thread safety MT-Safe .TE -.sp 1 .SH NOTES .BR lseek64 () is one of the functions that was specified in the Large File Summit (LFS) diff --git a/man3/makecontext.3 b/man3/makecontext.3 index c4e2378..5fc342f 100644 --- a/man3/makecontext.3 +++ b/man3/makecontext.3 @@ -6,7 +6,7 @@ .\" .\" 2006-08-02, mtk, Added example program .\" -.TH makecontext 3 2023-07-20 "Linux man-pages 6.05.01" +.TH makecontext 3 2023-10-31 "Linux man-pages 6.7" .SH NAME makecontext, swapcontext \- manipulate user context .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(), int " argc \ ", ...);" .BI "int swapcontext(ucontext_t *restrict " oucp , @@ -36,7 +36,7 @@ and .BR swapcontext () that allow user-level context switching between multiple threads of control within a process. -.PP +.P The .BR makecontext () function modifies the context pointed to @@ -48,7 +48,7 @@ the caller must allocate a new stack for this context and assign its address to \fIucp\->uc_stack\fP, and define a successor context and assign its address to \fIucp\->uc_link\fP. -.PP +.P When this context is later activated (using .BR setcontext (3) or @@ -62,7 +62,7 @@ the caller must specify the number of these arguments in .IR argc . When this function returns, the successor context is activated. If the successor context pointer is NULL, the thread exits. -.PP +.P The .BR swapcontext () function saves the current context in @@ -112,7 +112,6 @@ T} Thread safety T{ MT-Safe race:oucp race:ucp T} .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -129,7 +128,7 @@ to be used as the stack, regardless of the direction of growth of the stack. Thus, it is not necessary for the user program to worry about this direction. -.PP +.P On architectures where .I int and pointer types are the same size @@ -152,7 +151,7 @@ The example program below demonstrates the use of and .BR swapcontext (). Running the program produces the following output: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man3/makedev.3 b/man3/makedev.3 index af44a79..dbf851a 100644 --- a/man3/makedev.3 +++ b/man3/makedev.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH makedev 3 2023-07-20 "Linux man-pages 6.05.01" +.TH makedev 3 2023-10-31 "Linux man-pages 6.7" .SH NAME makedev, major, minor \- manage a device number .SH LIBRARY @@ -13,9 +13,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "dev_t makedev(unsigned int " maj ", unsigned int " min ); -.PP +.P .BI "unsigned int major(dev_t " dev ); .BI "unsigned int minor(dev_t " dev ); .fi @@ -25,14 +25,14 @@ a major ID, identifying the class of the device, and a minor ID, identifying a specific instance of a device in that class. A device ID is represented using the type .IR dev_t . -.PP +.P Given major and minor device IDs, .BR makedev () combines these to produce a device ID, returned as the function result. This device ID can be given to .BR mknod (2), for example. -.PP +.P The .BR major () and @@ -58,7 +58,6 @@ T{ .BR minor () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The BSDs expose the definitions for these macros via .IR . @@ -68,7 +67,7 @@ None. BSD, HP-UX, Solaris, AIX, Irix. .\" The header location is inconsistent: .\" Could be sys/mkdev.h, sys/sysmacros.h, or sys/types.h. -.PP +.P These interfaces are defined as macros. Since glibc 2.3.3, they have been aliases for three GNU-specific functions: @@ -77,7 +76,7 @@ they have been aliases for three GNU-specific functions: and .BR gnu_dev_minor (). The latter names are exported, but the traditional names are more portable. -.PP +.P Depending on the version, glibc also exposes definitions for these macros from .I diff --git a/man3/mallinfo.3 b/man3/mallinfo.3 index af08137..dcac910 100644 --- a/man3/mallinfo.3 +++ b/man3/mallinfo.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mallinfo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mallinfo 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mallinfo, mallinfo2 \- obtain memory allocation information .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B struct mallinfo mallinfo(void); .B struct mallinfo2 mallinfo2(void); .fi @@ -25,18 +25,18 @@ The structure returned by each function contains the same fields. However, the older function, .BR mallinfo (), is deprecated since the type used for the fields is too small (see BUGS). -.PP +.P Note that not all allocations are visible to these functions; see BUGS and consider using .BR malloc_info (3) instead. -.PP +.P The .I mallinfo2 structure returned by .BR mallinfo2 () is defined as follows: -.PP +.P .in +4n .EX struct mallinfo2 { @@ -54,14 +54,14 @@ struct mallinfo2 { }; .EE .in -.PP +.P The .I mallinfo structure returned by the deprecated .BR mallinfo () function is exactly the same, except that the fields are typed as .IR int . -.PP +.P The structure fields contain the following information: .TP 10 .I arena @@ -134,7 +134,7 @@ T} Thread safety T{ MT-Unsafe init const:mallopt T} .TE -.sp 1 +.P .BR mallinfo ()/ .BR mallinfo2 () would access some global internal objects. @@ -173,7 +173,7 @@ See and .BR malloc_info (3) for alternatives that include information about other arenas. -.PP +.P The fields of the .I mallinfo structure that is returned by the older @@ -189,11 +189,11 @@ The program below employs to retrieve memory allocation statistics before and after allocating and freeing some blocks of memory. The statistics are displayed on standard output. -.PP +.P The first two command-line arguments specify the number and size of blocks to be allocated with .BR malloc (3). -.PP +.P The remaining three arguments specify which of the allocated blocks should be freed with .BR free (3). @@ -207,11 +207,11 @@ of the last block to be freed (default is one greater than the maximum block number). If these three arguments are omitted, then the defaults cause all allocated blocks to be freed. -.PP +.P In the following example run of the program, 1000 allocations of 100 bytes are performed, and then every second allocated block is freed: -.PP +.P .in +4n .EX $ \fB./a.out 1000 100 2\fP diff --git a/man3/malloc.3 b/man3/malloc.3 index eee0b30..0ef2cc9 100644 --- a/man3/malloc.3 +++ b/man3/malloc.3 @@ -12,7 +12,7 @@ .\" FIXME . Review http://austingroupbugs.net/view.php?id=374 .\" to see what changes are required on this page. .\" -.TH malloc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH malloc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory .SH LIBRARY @@ -21,19 +21,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *malloc(size_t " size ); .BI "void free(void *_Nullable " ptr ); .BI "void *calloc(size_t " nmemb ", size_t " size ); .BI "void *realloc(void *_Nullable " ptr ", size_t " size ); .BI "void *reallocarray(void *_Nullable " ptr ", size_t " nmemb ", size_t " size ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR reallocarray (): .nf Since glibc 2.29: @@ -87,7 +87,7 @@ is 0, then .BR calloc () returns a unique pointer value that can later be successfully passed to .BR free (). -.PP +.P If the multiplication of .I nmemb and @@ -99,7 +99,7 @@ By contrast, an integer overflow would not be detected in the following call to .BR malloc (), with the result that an incorrectly sized block of memory would be allocated: -.PP +.P .in +4n .EX malloc(nmemb * size); @@ -119,14 +119,14 @@ up to the minimum of the old and new sizes. If the new size is larger than the old size, the added memory will .I not be initialized. -.PP +.P If .I ptr is NULL, then the call is equivalent to .IR malloc(size) , for all values of .IR size . -.PP +.P If .I size is equal to zero, @@ -135,7 +135,7 @@ and is not NULL, then the call is equivalent to .I free(ptr) (but see "Nonportable behavior" for portability issues). -.PP +.P Unless .I ptr is NULL, it must have been returned by an earlier call to @@ -156,13 +156,13 @@ elements, each of which is .I size bytes. It is equivalent to the call -.PP +.P .in +4n .EX realloc(ptr, nmemb * size); .EE .in -.PP +.P However, unlike that .BR realloc () call, @@ -187,12 +187,12 @@ Attempting to allocate more than .B PTRDIFF_MAX bytes is considered an error, as an object that large could cause later pointer subtraction to overflow. -.PP +.P The .BR free () function returns no value, and preserves .IR errno . -.PP +.P The .BR realloc () and @@ -247,7 +247,6 @@ T{ .BR realloc () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR malloc () @@ -275,12 +274,12 @@ POSIX.1-2001, C89. .BR reallocarray () glibc 2.26. OpenBSD 5.6, FreeBSD 11.0. -.PP +.P .BR malloc () and related functions rejected sizes greater than .B PTRDIFF_MAX starting in glibc 2.30. -.PP +.P .BR free () preserved .I errno @@ -301,7 +300,7 @@ in .BR proc (5), and the Linux kernel source file .IR Documentation/vm/overcommit\-accounting.rst . -.PP +.P Normally, .BR malloc () allocates memory from the heap, and adjusts the size of the heap @@ -324,7 +323,7 @@ were unaffected by the resource limit; since Linux 4.7, this limit is also enforced for allocations performed using .BR mmap (2). -.PP +.P To avoid corruption in multithreaded applications, mutexes are used internally to protect the memory-management data structures employed by these functions. @@ -342,7 +341,7 @@ by the system or .BR mmap (2)), and managed with its own mutexes. -.PP +.P If your program uses a private memory allocator, it should do so by replacing .BR malloc (), @@ -364,11 +363,11 @@ fail without having a valid reason in .IR errno . Private memory allocators may also need to replace other glibc functions; see "Replacing malloc" in the glibc manual for details. -.PP +.P Crashes in memory allocators are almost always related to heap corruption, such as overflowing an allocated chunk or freeing the same pointer twice. -.PP +.P The .BR malloc () implementation is tunable via environment variables; see @@ -383,14 +382,14 @@ other implementations may return NULL without setting and portable POSIX programs should tolerate such behavior. See .BR realloc (3p). -.PP +.P POSIX requires memory allocators to set .I errno upon failure. However, the C standard does not require this, and applications portable to non-POSIX platforms should not assume this. -.PP +.P Portable programs should not use private memory allocators, as POSIX and the C standard do not allow replacement of .BR malloc (), @@ -455,7 +454,7 @@ my_mallocarray(size_t nmemb, size_t size) .BR mcheck (3), .BR mtrace (3), .BR posix_memalign (3) -.PP +.P For details of the GNU C library implementation, see .UR https://sourceware.org/glibc/wiki/MallocInternals .UE . diff --git a/man3/malloc_get_state.3 b/man3/malloc_get_state.3 index 1577735..bf6fe5e 100644 --- a/man3/malloc_get_state.3 +++ b/man3/malloc_get_state.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH malloc_get_state 3 2023-07-20 "Linux man-pages 6.05.01" +.TH malloc_get_state 3 2023-11-01 "Linux man-pages 6.7" .SH NAME malloc_get_state, malloc_set_state \- record and restore state of malloc implementation @@ -13,14 +13,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B void *malloc_get_state(void); .BI "int malloc_set_state(void *" state ); .fi .SH DESCRIPTION .IR Note : -these function are removed in glibc 2.25. -.PP +these functions are removed in glibc 2.25. +.P The .BR malloc_get_state () function records the current state of all @@ -37,7 +37,7 @@ and a pointer to that data structure is returned as the function result. (It is the caller's responsibility to .BR free (3) this memory.) -.PP +.P The .BR malloc_set_state () function restores the state of all @@ -52,7 +52,7 @@ returns a pointer to a newly allocated opaque data structure. On error (for example, memory could not be allocated for the data structure), .BR malloc_get_state () returns NULL. -.PP +.P On success, .BR malloc_set_state () returns 0. @@ -85,7 +85,6 @@ T{ .BR malloc_set_state () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH NOTES @@ -94,7 +93,7 @@ These functions are useful when using this implementation as part of a shared library, and the heap contents are saved/restored via some other method. This technique is used by GNU Emacs to implement its "dumping" function. -.PP +.P Hook function pointers are never saved or restored by these functions, with two exceptions: if malloc checking (see diff --git a/man3/malloc_hook.3 b/man3/malloc_hook.3 index 8ade1b1..bb1aa69 100644 --- a/man3/malloc_hook.3 +++ b/man3/malloc_hook.3 @@ -5,7 +5,7 @@ .\" Heavily based on glibc documentation .\" Polished, added docs, removed glibc doc bug, 2002-07-20, aeb .\" -.TH __malloc_hook 3 2023-05-03 "Linux man-pages 6.05.01" +.TH __malloc_hook 3 2023-10-31 "Linux man-pages 6.7" .SH NAME __malloc_hook, __malloc_initialize_hook, __memalign_hook, __free_hook, __realloc_hook, @@ -16,19 +16,19 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "void *(*volatile __malloc_hook)(size_t " size ", const void *" caller ); -.PP +.P .BI "void *(*volatile __realloc_hook)(void *" ptr ", size_t " size , .BI " const void *" caller ); -.PP +.P .BI "void *(*volatile __memalign_hook)(size_t " alignment ", size_t " size , .BI " const void *" caller ); -.PP +.P .BI "void (*volatile __free_hook)(void *" ptr ", const void *" caller ); -.PP +.P .B "void (*__malloc_initialize_hook)(void);" -.PP +.P .B "void (*volatile __after_morecore_hook)(void);" .fi .SH DESCRIPTION @@ -41,24 +41,24 @@ by specifying appropriate hook functions. You can use these hooks to help you debug programs that use dynamic memory allocation, for example. -.PP +.P The variable .B __malloc_initialize_hook points at a function that is called once when the malloc implementation is initialized. This is a weak variable, so it can be overridden in the application with a definition like the following: -.PP +.P .in +4n .EX void (*__malloc_initialize_hook)(void) = my_init_hook; .EE .in -.PP +.P Now the function .IR my_init_hook () can do the initialization of all hooks. -.PP +.P The four functions pointed to by .BR __malloc_hook , .BR __realloc_hook , @@ -74,7 +74,7 @@ respectively, except that they have a final argument that gives the address of the caller of .BR malloc (3), etc. -.PP +.P The variable .B __after_morecore_hook points at a function that is called each time after @@ -101,7 +101,7 @@ and .BR calloc (). .SH EXAMPLES Here is a short example of how to use these variables. -.PP +.P .EX #include #include diff --git a/man3/malloc_info.3 b/man3/malloc_info.3 index 045430b..9df31cf 100644 --- a/man3/malloc_info.3 +++ b/man3/malloc_info.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH malloc_info 3 2023-07-20 "Linux man-pages 6.05.01" +.TH malloc_info 3 2024-02-26 "Linux man-pages 6.7" .SH NAME malloc_info \- export malloc state to a stream .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int malloc_info(int " options ", FILE *" stream ); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ The string is printed on the file stream .IR stream . The exported string includes information about all arenas (see .BR malloc (3)). -.PP +.P As currently implemented, .I options must be zero. @@ -55,7 +55,6 @@ T{ .BR malloc_info () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -66,13 +65,13 @@ The memory-allocation information is provided as an XML string because the information may change over time (according to changes in the underlying implementation). The output XML string includes a version field. -.PP +.P The .BR open_memstream (3) function can be used to send the output of .BR malloc_info () directly into a buffer in memory, rather than to a file. -.PP +.P The .BR malloc_info () function is designed to address deficiencies in @@ -90,14 +89,14 @@ The third argument controls the size of the blocks to be allocated. The main thread creates blocks of this size, the second thread created by the program allocates blocks of twice this size, the third thread allocates blocks of three times this size, and so on. -.PP +.P The program calls .BR malloc_info () twice to display the memory-allocation state. The first call takes place before any threads are created or memory allocated. The second call is performed after all threads have allocated memory. -.PP +.P In the following example, the command-line arguments specify the creation of one additional thread, and both the main thread and the additional thread @@ -105,7 +104,7 @@ allocate 10000 blocks of memory. After the blocks of memory have been allocated, .BR malloc_info () shows the state of two allocation arenas. -.PP +.P .in +4n .EX .RB "$ " "getconf GNU_LIBC_VERSION" diff --git a/man3/malloc_stats.3 b/man3/malloc_stats.3 index 7c17d2c..95980e5 100644 --- a/man3/malloc_stats.3 +++ b/man3/malloc_stats.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH malloc_stats 3 2023-07-20 "Linux man-pages 6.05.01" +.TH malloc_stats 3 2023-10-31 "Linux man-pages 6.7" .SH NAME malloc_stats \- print memory allocation statistics .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B void malloc_stats(void); .fi .SH DESCRIPTION @@ -49,7 +49,6 @@ T{ .BR malloc_stats () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY diff --git a/man3/malloc_trim.3 b/man3/malloc_trim.3 index f57de44..02dba1e 100644 --- a/man3/malloc_trim.3 +++ b/man3/malloc_trim.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH malloc_trim 3 2023-07-20 "Linux man-pages 6.05.01" +.TH malloc_trim 3 2023-10-31 "Linux man-pages 6.7" .SH NAME malloc_trim \- release free memory from the heap .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int malloc_trim(size_t " pad ); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ function attempts to release free memory from the heap or .BR madvise (2) with suitable arguments). -.PP +.P The .I pad argument specifies the amount of free space to leave untrimmed @@ -56,7 +56,6 @@ T{ .BR malloc_trim () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH VERSIONS @@ -67,13 +66,13 @@ Only the main heap (using honors the .I pad argument; thread heaps do not. -.PP +.P Since glibc 2.8 this function frees memory in all arenas and in all chunks with whole free pages. .\" See commit 68631c8eb92ff38d9da1ae34f6aa048539b199cc .\" (dated 2007-12-16) which adds iteration over all .\" arenas and frees all pages in chunks which are free. -.PP +.P Before glibc 2.8 this function only freed memory at the top of the heap in the main arena. .SH SEE ALSO diff --git a/man3/malloc_usable_size.3 b/man3/malloc_usable_size.3 index 91d22d8..3c30aae 100644 --- a/man3/malloc_usable_size.3 +++ b/man3/malloc_usable_size.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH malloc_usable_size 3 2023-07-20 "Linux man-pages 6.05.01" +.TH malloc_usable_size 3 2023-10-31 "Linux man-pages 6.7" .SH NAME malloc_usable_size \- obtain size of block of memory allocated from heap .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t malloc_usable_size(void *_Nullable " ptr ); .fi .SH DESCRIPTION @@ -42,7 +42,6 @@ T{ .BR malloc_usable_size () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH CAVEATS diff --git a/man3/mallopt.3 b/man3/mallopt.3 index 5fdda5c..6922b0f 100644 --- a/man3/mallopt.3 +++ b/man3/mallopt.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mallopt 3 2023-05-03 "Linux man-pages 6.05.01" +.TH mallopt 3 2024-02-26 "Linux man-pages 6.7" .SH NAME mallopt \- set memory allocation parameters .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mallopt(int " param ", int " value ); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ The argument specifies the parameter to be modified, and .I value specifies the new value for that parameter. -.PP +.P The following values can be specified for .IR param : .TP @@ -355,7 +355,7 @@ then the settings take precedence.) For security reasons, these variables are ignored in set-user-ID and set-group-ID programs. -.PP +.P The environment variables are as follows (note the trailing underscore at the end of the name of some variables): .TP @@ -455,7 +455,7 @@ glibc 2.0. Specifying an invalid value for .I param does not generate an error. -.PP +.P A calculation error within the glibc implementation means that a call of the form: .\" FIXME . This looks buggy: @@ -463,13 +463,13 @@ a call of the form: .\" malloc requests are rounded up: .\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12129 -.PP +.P .in +4n .EX mallopt(M_MXFAST, n) .EE .in -.PP +.P does not result in fastbins being employed for all allocations of size up to .IR n . To ensure desired results, @@ -480,7 +480,7 @@ where .I k is an integer. .\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t) -.PP +.P If .BR mallopt () is used to set @@ -510,11 +510,11 @@ then that argument is used to set the parameter. The program then allocates a block of memory, and frees it twice (an error). -.PP +.P The following shell session shows what happens when we run this program under glibc, with the default value for .BR M_CHECK_ACTION : -.PP +.P .in +4n .EX $ \fB./a.out\fP @@ -536,10 +536,10 @@ bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack] Aborted (core dumped) .EE .in -.PP +.P The following runs show the results when employing other values for .BR M_CHECK_ACTION : -.PP +.P .in +4n .EX $ \fB./a.out 1\fP # Diagnose error and continue @@ -554,11 +554,11 @@ main(): returned from first free() call main(): returned from second free() call .EE .in -.PP +.P The next run shows how to set the same parameter using the .B MALLOC_CHECK_ environment variable: -.PP +.P .in +4n .EX $ \fBMALLOC_CHECK_=1 ./a.out\fP diff --git a/man3/matherr.3 b/man3/matherr.3 index 8e9a973..351baf5 100644 --- a/man3/matherr.3 +++ b/man3/matherr.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH matherr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH matherr 3 2024-02-26 "Linux man-pages 6.7" .SH NAME matherr \- SVID math library exception handling .SH LIBRARY @@ -13,9 +13,9 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int matherr(struct exception *" exc ); -.PP +.P .B [[deprecated]] extern _LIB_VERSION_TYPE _LIB_VERSION; .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ and This page documents the .BR matherr () mechanism as an aid for maintaining and porting older applications. -.PP +.P The System V Interface Definition (SVID) specifies that various math functions should invoke a function called .BR matherr () @@ -42,7 +42,7 @@ after .BR matherr () returns, the system then returns to the math function, which in turn returns to the caller. -.PP +.P To employ .BR matherr (), the programmer must define the @@ -55,7 +55,7 @@ and assign the value .B _SVID_ to the external variable .BR _LIB_VERSION . -.PP +.P The system provides a default version of .BR matherr (). This version does nothing, and returns zero @@ -67,7 +67,7 @@ version, which will be invoked when an exception occurs. The function is invoked with one argument, a pointer to an .I exception structure, defined as follows: -.PP +.P .in +4n .EX struct exception { @@ -79,7 +79,7 @@ struct exception { } .EE .in -.PP +.P The .I type field has one of the following values: @@ -130,7 +130,7 @@ is set to Partial loss of significance. This value is unused on glibc (and many other systems). -.PP +.P The .I arg1 and @@ -138,7 +138,7 @@ and fields are the arguments supplied to the function .RI ( arg2 is undefined for functions that take only one argument). -.PP +.P The .I retval field specifies the return value that the math @@ -146,14 +146,14 @@ function will return to its caller. The programmer-defined .BR matherr () can modify this field to change the return value of the math function. -.PP +.P If the .BR matherr () function returns zero, then the system sets .I errno as described above, and may print an error message on standard error (see below). -.PP +.P If the .BR matherr () function returns a nonzero value, then the system does not set @@ -169,15 +169,15 @@ when calling .BR matherr (). The "Result" column is the default return value assigned to .IR exc\->retval . -.PP +.P The "Msg?" and "errno" columns describe the default behavior if .BR matherr () returns zero. If the "Msg?" columns contains "y", then the system prints an error message on standard error. -.PP +.P The table uses the following notations and abbreviations: -.PP +.P .RS .TS l l. @@ -270,7 +270,6 @@ T{ .BR matherr () T} Thread safety MT-Safe .TE -.sp 1 .SH EXAMPLES The example program demonstrates the use of .BR matherr () @@ -292,12 +291,12 @@ If the optional third command-line argument is supplied, then it specifies an alternative return value that .BR matherr () should assign as the return value of the math function. -.PP +.P The following example run, where .BR log (3) is given an argument of 0.0, does not use .BR matherr (): -.PP +.P .in +4n .EX .RB "$" " ./a.out 0.0" @@ -305,11 +304,11 @@ errno: Numerical result out of range x=\-inf .EE .in -.PP +.P In the following run, .BR matherr () is called, and returns 0: -.PP +.P .in +4n .EX .RB "$" " ./a.out 0.0 0" @@ -321,13 +320,13 @@ errno: Numerical argument out of domain x=\-340282346638528859811704183484516925440.000000 .EE .in -.PP +.P The message "log: SING error" was printed by the C library. -.PP +.P In the following run, .BR matherr () is called, and returns a nonzero value: -.PP +.P .in +4n .EX .RB "$" " ./a.out 0.0 1" @@ -337,16 +336,16 @@ matherr SING exception in log() function x=\-340282346638528859811704183484516925440.000000 .EE .in -.PP +.P In this case, the C library did not print a message, and .I errno was not set. -.PP +.P In the following run, .BR matherr () is called, changes the return value of the math function, and returns a nonzero value: -.PP +.P .in +4n .EX .RB "$" " ./a.out 0.0 1 12345.0" @@ -358,7 +357,7 @@ x=12345.000000 .in .SS Program source \& -.\" [[deprecated]] SRC BEGIN (matherr.c) +.\" SRC BEGIN (matherr.c) .EX #define _SVID_SOURCE #include diff --git a/man3/mblen.3 b/man3/mblen.3 index 0a8bbde..6946b00 100644 --- a/man3/mblen.3 +++ b/man3/mblen.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mblen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mblen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mblen \- determine number of bytes in next multibyte character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mblen(const char " s [. n "], size_t " n ); .fi .SH DESCRIPTION @@ -39,7 +39,7 @@ If the multibyte character is not the null wide character, it returns the number of bytes that were consumed from .IR s . If the multibyte character is the null wide character, it returns 0. -.PP +.P If the .I n bytes starting at @@ -53,14 +53,14 @@ This can happen even if is greater than or equal to .IR MB_CUR_MAX , if the multibyte string contains redundant shift sequences. -.PP +.P If the multibyte string starting at .I s contains an invalid multibyte sequence before the next complete character, .BR mblen () also returns \-1. -.PP +.P If .I s is NULL, the @@ -97,7 +97,6 @@ T{ .BR mblen () T} Thread safety MT-Unsafe race .TE -.sp 1 .SH VERSIONS The function .BR mbrlen (3) diff --git a/man3/mbrlen.3 b/man3/mbrlen.3 index bf19f88..a444a6a 100644 --- a/man3/mbrlen.3 +++ b/man3/mbrlen.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mbrlen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbrlen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mbrlen \- determine number of bytes in next multibyte character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t mbrlen(const char " s "[restrict ." n "], size_t " n , .BI " mbstate_t *restrict " ps ); .fi @@ -40,7 +40,7 @@ If the multibyte character is the null wide character, it resets the shift state .I *ps to the initial state and returns 0. -.PP +.P If the .I n bytes starting at @@ -56,7 +56,7 @@ This can happen even if .IR MB_CUR_MAX , if the multibyte string contains redundant shift sequences. -.PP +.P If the multibyte string starting at .I s contains an invalid multibyte @@ -72,7 +72,7 @@ In this case, the effects on .I *ps are undefined. -.PP +.P If .I ps is NULL, a static anonymous state known only to the @@ -115,7 +115,6 @@ T{ .BR mbrlen () T} Thread safety MT-Unsafe race:mbrlen/!ps .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/mbrtowc.3 b/man3/mbrtowc.3 index 2dc8f15..c35f540 100644 --- a/man3/mbrtowc.3 +++ b/man3/mbrtowc.3 @@ -10,7 +10,7 @@ .\" http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mbrtowc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbrtowc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mbrtowc \- convert a multibyte sequence to a wide character .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t mbrtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n ], .BI " size_t " n ", mbstate_t *restrict " ps ); .fi @@ -50,7 +50,7 @@ If the converted wide character is L\[aq]\e0\[aq], it resets the shift state .I *ps to the initial state and returns 0. -.PP +.P If the .I n bytes starting at @@ -66,7 +66,7 @@ This can happen even if .IR MB_CUR_MAX , if the multibyte string contains redundant shift sequences. -.PP +.P If the multibyte string starting at .I s contains an invalid multibyte @@ -82,7 +82,7 @@ In this case, the effects on .I *ps are undefined. -.PP +.P A different case is when .I s is not NULL but @@ -92,7 +92,7 @@ In this case, the .BR mbrtowc () function behaves as above, except that it does not store the converted wide character in memory. -.PP +.P A third case is when .I s is NULL. @@ -124,7 +124,7 @@ function puts .I *ps in the initial state and returns 0. -.PP +.P In all of the above cases, if .I ps is NULL, a static anonymous @@ -142,7 +142,7 @@ object .I a can be initialized to the initial state by zeroing it, for example using -.PP +.P .in +4n .EX memset(&a, 0, sizeof(a)); @@ -185,7 +185,6 @@ T{ .BR mbrtowc () T} Thread safety MT-Unsafe race:mbrtowc/!ps .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/mbsinit.3 b/man3/mbsinit.3 index 41a43a4..fc76d62 100644 --- a/man3/mbsinit.3 +++ b/man3/mbsinit.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mbsinit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbsinit 3 2024-01-28 "Linux man-pages 6.7" .SH NAME mbsinit \- test for initial shift state .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mbsinit(const mbstate_t *" ps ); .fi .SH DESCRIPTION @@ -29,8 +29,8 @@ Conversion of a string uses a finite-state machine; when it is interrupted after the complete conversion of a number of characters, it may need to save a state for processing the remaining characters. Such a conversion -state is needed for the sake of encodings such as ISO-2022 and UTF-7. -.PP +state is needed for the sake of encodings such as ISO/IEC\~2022 and UTF-7. +.P The initial state is the state at the beginning of conversion of a string. There are two kinds of state: the one used by multibyte to wide character conversion functions, such as @@ -42,7 +42,7 @@ but they both fit in a .IR mbstate_t , and they both have the same representation for an initial state. -.PP +.P For 8-bit encodings, all states are equivalent to the initial state. For multibyte encodings like UTF-8, EUC-*, BIG5, or SJIS, the wide character to multibyte conversion functions never produce non-initial states, but the @@ -50,26 +50,26 @@ multibyte to wide-character conversion functions like .BR mbrtowc (3) do produce non-initial states when interrupted in the middle of a character. -.PP +.P One possible way to create an .I mbstate_t in initial state is to set it to zero: -.PP +.P .in +4n .EX mbstate_t state; memset(&state, 0, sizeof(state)); .EE .in -.PP +.P On Linux, the following works as well, but might generate compiler warnings: -.PP +.P .in +4n .EX mbstate_t state = { 0 }; .EE .in -.PP +.P The function .BR mbsinit () tests whether @@ -98,7 +98,6 @@ T{ .BR mbsinit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/mbsnrtowcs.3 b/man3/mbsnrtowcs.3 index b9d0029..5d683a0 100644 --- a/man3/mbsnrtowcs.3 +++ b/man3/mbsnrtowcs.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH mbsnrtowcs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbsnrtowcs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mbsnrtowcs \- convert a multibyte string to a wide-character string .SH LIBRARY @@ -17,17 +17,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t mbsnrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src , .BI " size_t " nms ", size_t " len \ ", mbstate_t *restrict " ps ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mbsnrtowcs (): .nf Since glibc 2.10: @@ -46,7 +46,7 @@ the number of bytes to be converted, starting at is limited to at most .I nms bytes. -.PP +.P If .I dest is not NULL, the @@ -120,13 +120,13 @@ characters written to .IR dest , excluding the terminating null wide character, is returned. -.PP +.P According to POSIX.1, if the input buffer ends with an incomplete character, it is unspecified whether conversion stops at the end of the previous character (if any), or at the end of the input buffer. The glibc implementation adopts the former behavior. -.PP +.P If .I dest is NULL, @@ -135,14 +135,14 @@ is ignored, and the conversion proceeds as above, except that the converted wide characters are not written out to memory, and that no destination length limit exists. -.PP +.P In both of the above cases, if .I ps is NULL, a static anonymous state known only to the .BR mbsnrtowcs () function is used instead. -.PP +.P The programmer must ensure that there is room for at least .I len wide @@ -179,7 +179,6 @@ T} Thread safety T{ MT-Unsafe race:mbsnrtowcs/!ps T} .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH NOTES @@ -189,7 +188,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P Passing NULL as .I ps is not multithread safe. diff --git a/man3/mbsrtowcs.3 b/man3/mbsrtowcs.3 index e613a14..6844536 100644 --- a/man3/mbsrtowcs.3 +++ b/man3/mbsrtowcs.3 @@ -9,31 +9,31 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mbsrtowcs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbsrtowcs 3 2024-02-26 "Linux man-pages 6.7" .SH NAME -mbsrtowcs \- convert a multibyte string to a wide-character string +mbsrtowcs \- convert a multibyte string to a wide-character string (restartable) .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf .B #include -.PP -.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." len "], const char **restrict " src , -.BI " size_t " len ", mbstate_t *restrict " ps ); +.P +.BI "size_t mbsrtowcs(wchar_t " dest "[restrict ." dsize ], +.BI " const char **restrict " src , +.BI " size_t " dsize ", mbstate_t *restrict " ps ); .fi .SH DESCRIPTION If .I dest -is not NULL, the -.BR mbsrtowcs () -function converts the +is not NULL, +convert the multibyte string .I *src to a wide-character string starting at .IR dest . At most -.I len +.I dsize wide characters are written to .IR dest . The shift state @@ -63,7 +63,7 @@ and is set to .BR EILSEQ . .IP \[bu] -.I len +.I dsize non-L\[aq]\e0\[aq] wide characters have been stored at .IR dest . In this case, @@ -86,16 +86,16 @@ is set to NULL, and the number of wide characters written to .IR dest , excluding the terminating null wide character, is returned. -.PP +.P If .I dest is NULL, -.I len +.I dsize is ignored, and the conversion proceeds as above, except that the converted wide characters are not written out to memory, and that no length limit exists. -.PP +.P In both of the above cases, if .I ps @@ -103,16 +103,23 @@ is NULL, a static anonymous state known only to the .BR mbsrtowcs () function is used instead. -.PP +.P +In order to avoid the case 2 above, the programmer should make sure +.I dsize +is +greater than or equal to +.IR "mbsrtowcs(NULL,src,0,ps)+1" . +.P The programmer must ensure that there is room for at least -.I len +.I dsize wide characters at .IR dest . +.P +This function is a restartable version of +.BR mbstowcs (3). .SH RETURN VALUE -The -.BR mbsrtowcs () -function returns the number of wide characters that make +The number of wide characters that make up the converted part of the wide-character string, not including the terminating null wide character. If an invalid multibyte sequence was @@ -140,7 +147,6 @@ T} Thread safety T{ MT-Unsafe race:mbsrtowcs/!ps T} .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -152,7 +158,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P Passing NULL as .I ps is not multithread safe. diff --git a/man3/mbstowcs.3 b/man3/mbstowcs.3 index c66b9c2..6a0d655 100644 --- a/man3/mbstowcs.3 +++ b/man3/mbstowcs.3 @@ -10,7 +10,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mbstowcs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbstowcs 3 2023-11-14 "Linux man-pages 6.7" .SH NAME mbstowcs \- convert a multibyte string to a wide-character string .SH LIBRARY @@ -19,24 +19,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP -.BI "size_t mbstowcs(wchar_t " dest "[restrict ." n "], \ +.P +.BI "size_t mbstowcs(wchar_t " dest "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " n ); +.BI " size_t " dsize ); .fi .SH DESCRIPTION If .I dest is not NULL, -the -.BR mbstowcs () -function converts the +convert the multibyte string .I src to a wide-character string starting at .IR dest . At most -.I n +.I dsize wide characters are written to .IR dest . The sequence of characters in the string @@ -49,7 +47,7 @@ In this case, .I (size_t)\ \-1 is returned. .IP \[bu] -.I n +.I dsize non-L\[aq]\e0\[aq] wide characters have been stored at .IR dest . In this case, the number of wide characters written to @@ -62,30 +60,28 @@ terminating null character (\[aq]\e0\[aq]). In this case, the number of wide characters written to .IR dest , excluding the terminating null wide character, is returned. -.PP -The programmer must ensure that there is room for at least -.I n -wide -characters at -.IR dest . -.PP +.P If .I dest is NULL, -.I n +.I dsize is ignored, and the conversion proceeds as above, except that the converted wide characters are not written out to memory, and that no length limit exists. -.PP +.P In order to avoid the case 2 above, the programmer should make sure -.I n +.I dsize is greater than or equal to .IR "mbstowcs(NULL,src,0)+1" . +.P +The programmer must ensure that there is room for at least +.I dsize +wide +characters at +.IR dest . .SH RETURN VALUE -The -.BR mbstowcs () -function returns the number of wide characters that make +The number of wide characters that make up the converted part of the wide-character string, not including the terminating null wide character. If an invalid multibyte sequence was @@ -106,7 +102,6 @@ T{ .BR mbstowcs () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The function .BR mbsrtowcs (3) @@ -128,7 +123,7 @@ The program below illustrates the use of .BR mbstowcs (), as well as some of the wide character classification functions. An example run is the following: -.PP +.P .in +4n .EX $ ./t_mbstowcs de_DE.UTF\-8 Grüße! diff --git a/man3/mbtowc.3 b/man3/mbtowc.3 index 743e5a7..0e07144 100644 --- a/man3/mbtowc.3 +++ b/man3/mbtowc.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH mbtowc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mbtowc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mbtowc \- convert a multibyte sequence to a wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mbtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n "], \ size_t " n ); .fi @@ -47,7 +47,7 @@ does not point to a null byte (\[aq]\e0\[aq]), it returns the number of bytes that were consumed from .IR s , otherwise it returns 0. -.PP +.P If the .I n bytes starting at @@ -61,7 +61,7 @@ This can happen even if >= .IR MB_CUR_MAX , if the multibyte string contains redundant shift sequences. -.PP +.P A different case is when .I s is not NULL but @@ -71,7 +71,7 @@ In this case, the .BR mbtowc () function behaves as above, except that it does not store the converted wide character in memory. -.PP +.P A third case is when .I s is NULL. @@ -102,7 +102,7 @@ or 0 if .I s points to a null byte, or \-1 upon failure. -.PP +.P If .I s is NULL, the @@ -124,7 +124,6 @@ T{ .BR mbtowc () T} Thread safety MT-Unsafe race .TE -.sp 1 .SH VERSIONS This function is not multithread safe. The function diff --git a/man3/mcheck.3 b/man3/mcheck.3 index 97f217f..7b6c7da 100644 --- a/man3/mcheck.3 +++ b/man3/mcheck.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mcheck 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mcheck 3 2024-02-26 "Linux man-pages 6.7" .SH NAME mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking .SH LIBRARY @@ -12,11 +12,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus )); .BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus )); .B void mcheck_check_all(void); -.PP +.P .BI "enum mcheck_status mprobe(void *" ptr ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ on the state of the heap. The checks can detect application errors such as freeing a block of memory more than once or corrupting the bookkeeping data structures that immediately precede a block of allocated memory. -.PP +.P To be effective, the .BR mcheck () function must be called before the first call to @@ -42,7 +42,7 @@ inserts an implicit call to .BR mcheck () (with a NULL argument) before the first call to a memory-allocation function. -.PP +.P The .BR mcheck_pedantic () function is similar to @@ -50,14 +50,14 @@ function is similar to but performs checks on all allocated blocks whenever one of the memory-allocation functions is called. This can be very slow! -.PP +.P The .BR mcheck_check_all () function causes an immediate check on all allocated blocks. This call is effective only if .BR mcheck () is called beforehand. -.PP +.P If the system detects an inconsistency in the heap, the caller-supplied function pointed to by .I abortfunc @@ -70,7 +70,7 @@ is NULL, a default function prints an error message on .I stderr and calls .BR abort (3). -.PP +.P The .BR mprobe () function performs a consistency check on @@ -82,7 +82,7 @@ function should be called beforehand (otherwise .BR mprobe () returns .BR MCHECK_DISABLED ). -.PP +.P The following list describes the values returned by .BR mprobe () or passed as the @@ -135,7 +135,6 @@ MT-Unsafe race:mcheck const:malloc_hooks T} .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -167,7 +166,7 @@ The program below calls with a NULL argument and then frees the same block of memory twice. The following shell session demonstrates what happens when running the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man3/memccpy.3 b/man3/memccpy.3 index 6d14698..71e4fce 100644 --- a/man3/memccpy.3 +++ b/man3/memccpy.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:57:24 1993 by Rik Faith (faith@cs.unc.edu) -.TH memccpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memccpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memccpy \- copy memory area .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *memccpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], .BI " int " c ", size_t " n ); .fi @@ -35,7 +35,7 @@ stopping when the character .I c is found. -.PP +.P If the memory areas overlap, the results are undefined. .SH RETURN VALUE The @@ -66,7 +66,6 @@ T{ .BR memccpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/memchr.3 b/man3/memchr.3 index 92708cd..716fabc 100644 --- a/man3/memchr.3 +++ b/man3/memchr.3 @@ -10,7 +10,7 @@ .\" Modified Wed Feb 20 21:09:36 2002, Ian Redfern (redferni@logica.com) .\" 2008-07-09, mtk, add rawmemchr() .\" -.TH memchr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memchr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memchr, memrchr, rawmemchr \- scan memory for a character .SH LIBRARY @@ -19,18 +19,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *memchr(const void " s [. n "], int " c ", size_t " n ); .BI "void *memrchr(const void " s [. n "], int " c ", size_t " n ); -.PP +.P .BI "[[deprecated]] void *rawmemchr(const void *" s ", int " c ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR memrchr (), .BR rawmemchr (): .nf @@ -52,7 +52,7 @@ and the bytes of the memory area pointed to by .I s are interpreted as .IR "unsigned char" . -.PP +.P The .BR memrchr () function is like the @@ -63,7 +63,7 @@ except that it searches backward from the end of the bytes pointed to by .I s instead of forward from the beginning. -.PP +.P The .BR rawmemchr () function is similar to @@ -90,7 +90,7 @@ and functions return a pointer to the matching byte or NULL if the character does not occur in the given memory area. -.PP +.P The .BR rawmemchr () function returns a pointer to the matching byte. @@ -110,7 +110,6 @@ T{ .BR rawmemchr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR memchr () diff --git a/man3/memcmp.3 b/man3/memcmp.3 index f3d94ea..76a8934 100644 --- a/man3/memcmp.3 +++ b/man3/memcmp.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:55:27 1993 by Rik Faith (faith@cs.unc.edu) -.TH memcmp 3 2023-07-30 "Linux man-pages 6.05.01" +.TH memcmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memcmp \- compare memory areas .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int memcmp(const void " s1 [. n "], const void " s2 [. n "], size_t " n ); .fi .SH DESCRIPTION @@ -33,7 +33,7 @@ function returns an integer less than, equal to, or greater than zero if the first \fIn\fP bytes of \fIs1\fP is found, respectively, to be less than, to match, or be greater than the first \fIn\fP bytes of \fIs2\fP. -.PP +.P For a nonzero return value, the sign is determined by the sign of the difference between the first pair of bytes (interpreted as .IR "unsigned char" ) @@ -41,7 +41,7 @@ that differ in .I s1 and .IR s2 . -.PP +.P If .I n is zero, the return value is zero. @@ -59,7 +59,6 @@ T{ .BR memcmp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/memcpy.3 b/man3/memcpy.3 index ec8e3b4..553a261 100644 --- a/man3/memcpy.3 +++ b/man3/memcpy.3 @@ -9,7 +9,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sun Jul 25 10:41:09 1993 by Rik Faith (faith@cs.unc.edu) -.TH memcpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memcpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memcpy \- copy memory area .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *memcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], .BI " size_t " n ); .fi @@ -49,7 +49,6 @@ T{ .BR memcpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -70,7 +69,7 @@ in which bytes were copied from .I src to .IR dest . -.PP +.P This change revealed breakages in a number of applications that performed copying with overlapping areas. .\" Adobe Flash player was the highest profile example: diff --git a/man3/memfrob.3 b/man3/memfrob.3 index 3f19845..7f7e344 100644 --- a/man3/memfrob.3 +++ b/man3/memfrob.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:54:45 1993 by Rik Faith (faith@cs.unc.edu) -.TH memfrob 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memfrob 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memfrob \- frobnicate (obfuscate) a memory area .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void *memfrob(void " s [. n "], size_t " n ); .fi .SH DESCRIPTION @@ -31,7 +31,7 @@ The effect can be reversed by using .BR memfrob () on the obfuscated memory area. -.PP +.P Note that this function is not a proper encryption routine as the XOR constant is fixed, and is suitable only for hiding strings. .SH RETURN VALUE @@ -53,7 +53,6 @@ T{ .BR memfrob () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH SEE ALSO diff --git a/man3/memmem.3 b/man3/memmem.3 index f87203c..711361d 100644 --- a/man3/memmem.3 +++ b/man3/memmem.3 @@ -8,7 +8,7 @@ .\" 386BSD man pages .\" Modified Sat Jul 24 18:50:48 1993 by Rik Faith (faith@cs.unc.edu) .\" Interchanged 'needle' and 'haystack'; added history, aeb, 980113. -.TH memmem 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memmem 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memmem \- locate a substring .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void *memmem(const void " haystack [. haystacklen "], size_t " haystacklen , .BI " const void " needle [. needlelen "], size_t " needlelen ); .fi @@ -54,7 +54,6 @@ T{ .BR memmem () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/memmove.3 b/man3/memmove.3 index 6b3b8f0..f0e3e9f 100644 --- a/man3/memmove.3 +++ b/man3/memmove.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:49:59 1993 by Rik Faith (faith@cs.unc.edu) -.TH memmove 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memmove 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memmove \- copy memory area .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *memmove(void " dest [. n "], const void " src [. n "], size_t " n ); .fi .SH DESCRIPTION @@ -57,7 +57,6 @@ T{ .BR memmove () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/mempcpy.3 b/man3/mempcpy.3 index 46337c2..376636f 100644 --- a/man3/mempcpy.3 +++ b/man3/mempcpy.3 @@ -6,7 +6,7 @@ .\" Heavily based on glibc infopages, copyright Free Software Foundation .\" .\" aeb, 2003, polished a little -.TH mempcpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mempcpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mempcpy, wmempcpy \- copy memory area .SH LIBRARY @@ -16,13 +16,13 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void *mempcpy(void " dest "[restrict ." n "], const void " src "[restrict ." n ], .BI " size_t " n ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "wchar_t *wmempcpy(wchar_t " dest "[restrict ." n ], .BI " const wchar_t " src "[restrict ." n ], .BI " size_t " n ); @@ -42,10 +42,10 @@ into the object pointed to by But instead of returning the value of .I dest it returns a pointer to the byte following the last written byte. -.PP +.P This function is useful in situations where a number of objects shall be copied to consecutive memory positions. -.PP +.P The .BR wmempcpy () function is identical but takes @@ -72,7 +72,6 @@ T{ .BR wmempcpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY diff --git a/man3/memset.3 b/man3/memset.3 index b56ef46..64eb203 100644 --- a/man3/memset.3 +++ b/man3/memset.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:49:23 1993 by Rik Faith (faith@cs.unc.edu) -.TH memset 3 2023-07-20 "Linux man-pages 6.05.01" +.TH memset 3 2023-10-31 "Linux man-pages 6.7" .SH NAME memset \- fill memory with a constant byte .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void *memset(void " s [. n "], int " c ", size_t " n ); .fi .SH DESCRIPTION @@ -49,7 +49,6 @@ T{ .BR memset () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/mkdtemp.3 b/man3/mkdtemp.3 index 4c55259..d7daaee 100644 --- a/man3/mkdtemp.3 +++ b/man3/mkdtemp.3 @@ -4,7 +4,7 @@ .\" and GNU libc documentation .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH mkdtemp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mkdtemp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mkdtemp \- create a unique temporary directory .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *mkdtemp(char *" template ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mkdtemp (): .nf /* Since glibc 2.19: */ _DEFAULT_SOURCE @@ -53,7 +53,7 @@ is set to indicate the error. .B EINVAL The last six characters of \fItemplate\fP were not XXXXXX. Now \fItemplate\fP is unchanged. -.PP +.P Also see .BR mkdir (2) for other possible values for \fIerrno\fP. @@ -71,7 +71,6 @@ T{ .BR mkdtemp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/mkfifo.3 b/man3/mkfifo.3 index f43f07d..0f5c21c 100644 --- a/man3/mkfifo.3 +++ b/man3/mkfifo.3 @@ -6,7 +6,7 @@ .\" .\" changed section from 2 to 3, aeb, 950919 .\" -.TH mkfifo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mkfifo 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mkfifo, mkfifoat \- make a FIFO special file (a named pipe) .SH LIBRARY @@ -16,20 +16,20 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int mkfifo(const char *" pathname ", mode_t " mode ); -.PP +.P .BR "#include " "/* Definition of AT_* constants */" .B #include -.PP +.P .BI "int mkfifoat(int " dirfd ", const char *" pathname ", mode_t " mode ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mkfifoat (): .nf Since glibc 2.10: @@ -44,14 +44,14 @@ makes a FIFO special file with name \fIpathname\fP. It is modified by the process's \fBumask\fP in the usual way: the permissions of the created file are \fB(\fP\fImode\fP\fB & \[ti]umask)\fP. -.PP +.P A FIFO special file is similar to a pipe, except that it is created in a different way. Instead of being an anonymous communications channel, a FIFO special file is entered into the filesystem by calling .BR mkfifo (). -.PP +.P Once you have created a FIFO special file in this way, any process can open it for reading or writing, in the same way as an ordinary file. However, it has to be open at both ends simultaneously before you can @@ -67,7 +67,7 @@ The function operates in exactly the same way as .BR mkfifo (), except for the differences described here. -.PP +.P If the pathname given in .I pathname is relative, then it is interpreted relative to the directory @@ -77,7 +77,7 @@ referred to by the file descriptor the calling process, as is done by .BR mkfifo () for a relative pathname). -.PP +.P If .I pathname is relative and @@ -89,13 +89,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR mkfifo ()). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -177,7 +177,6 @@ T{ .BR mkfifoat () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS It is implemented using .BR mknodat (2). diff --git a/man3/mkstemp.3 b/man3/mkstemp.3 index dbfa252..2b7a986 100644 --- a/man3/mkstemp.3 +++ b/man3/mkstemp.3 @@ -13,7 +13,7 @@ .\" Modified 990328, aeb .\" 2008-06-19, mtk, Added mkostemp(); various other changes .\" -.TH mkstemp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mkstemp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mkstemp, mkostemp, mkstemps, mkostemps \- create a unique temporary file .SH LIBRARY @@ -22,18 +22,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mkstemp(char *" template ); .BI "int mkostemp(char *" template ", int " flags ); .BI "int mkstemps(char *" template ", int " suffixlen ); .BI "int mkostemps(char *" template ", int " suffixlen ", int " flags ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mkstemp (): .nf _XOPEN_SOURCE >= 500 @@ -41,18 +41,18 @@ Feature Test Macro Requirements for glibc (see || /* glibc >= 2.12: */ _POSIX_C_SOURCE >= 200809L || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P .BR mkostemp (): .nf _GNU_SOURCE .fi -.PP +.P .BR mkstemps (): .nf /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P .BR mkostemps (): .nf _GNU_SOURCE @@ -64,7 +64,7 @@ function generates a unique temporary filename from .IR template , creates and opens the file, and returns an open file descriptor for the file. -.PP +.P The last six characters of .I template must be "XXXXXX" and these are replaced with a string that makes the @@ -72,7 +72,7 @@ filename unique. Since it will be modified, .I template must not be a string constant, but should be declared as a character array. -.PP +.P The file is created with permissions 0600, that is, read plus write for owner only. The returned file descriptor provides both read and write access to the file. @@ -80,7 +80,7 @@ The file is opened with the .BR open (2) .B O_EXCL flag, guaranteeing that the caller is the process that creates the file. -.PP +.P The .BR mkostemp () function is like @@ -111,7 +111,7 @@ argument given to is unnecessary, and produces errors on some .\" Reportedly, FreeBSD systems. -.PP +.P The .BR mkstemps () function is like @@ -127,7 +127,7 @@ is of the form .IR "prefixXXXXXXsuffix" , and the string XXXXXX is modified as for .BR mkstemp (). -.PP +.P The .BR mkostemps () function is to @@ -166,7 +166,7 @@ is less than characters long, or the last 6 characters before the suffix in .I template were not XXXXXX. -.PP +.P These functions may also fail with any of the errors described for .BR open (2). .SH ATTRIBUTES @@ -186,7 +186,6 @@ T{ .BR mkostemps () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR mkstemp () @@ -215,14 +214,14 @@ glibc 2.7. .TP .BR mkostemps () glibc 2.11. -.PP +.P In glibc versions 2.06 and earlier, the file is created with permissions 0666, that is, read and write for all users. This old behavior may be a security risk, especially since other UNIX flavors use 0600, and somebody might overlook this detail when porting programs. POSIX.1-2008 adds a requirement that the file be created with mode 0600. -.PP +.P More generally, the POSIX specification of .BR mkstemp () does not say anything diff --git a/man3/mktemp.3 b/man3/mktemp.3 index c925dd0..fb40594 100644 --- a/man3/mktemp.3 +++ b/man3/mktemp.3 @@ -12,7 +12,7 @@ .\" (prompted by Scott Burkett ) .\" Modified Sun Mar 28 23:44:38 1999 by Andries Brouwer (aeb@cwi.nl) .\" -.TH mktemp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mktemp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mktemp \- make a unique temporary filename .SH LIBRARY @@ -21,15 +21,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *mktemp(char *" template ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mktemp (): .nf Since glibc 2.12: @@ -43,7 +43,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION .IR "Never use this function" ; see BUGS. -.PP +.P The .BR mktemp () function generates a unique temporary filename @@ -83,7 +83,6 @@ T{ .BR mktemp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/modf.3 b/man3/modf.3 index 118d213..c510733 100644 --- a/man3/modf.3 +++ b/man3/modf.3 @@ -11,7 +11,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH modf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH modf 3 2023-10-31 "Linux man-pages 6.7" .SH NAME modf, modff, modfl \- extract signed integral and fractional values from floating-point number @@ -21,17 +21,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double modf(double " x ", double *" iptr ); .BI "float modff(float " x ", float *" iptr ); .BI "long double modfl(long double " x ", long double *" iptr ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR modff (), .BR modfl (): .nf @@ -50,13 +50,13 @@ The integral part is stored in the location pointed to by .SH RETURN VALUE These functions return the fractional part of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned, and .I *iptr is set to a NaN. -.PP +.P If .I x is positive infinity (negative infinity), +0 (\-0) is returned, and @@ -80,12 +80,11 @@ T{ .BR modfl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/mpool.3 b/man3/mpool.3 index 20dd313..38f1366 100644 --- a/man3/mpool.3 +++ b/man3/mpool.3 @@ -5,7 +5,7 @@ .\" .\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 .\" -.TH mpool 3 2023-03-30 "Linux man-pages 6.05.01" +.TH mpool 3 2023-10-31 "Linux man-pages 6.7" .UC 7 .SH NAME mpool \- shared memory buffer pool @@ -16,18 +16,18 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \ ", pgno_t " maxcache ); -.PP +.P .BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *)," .BI " void (*" pgout ")(void *, pgno_t, void *)," .BI " void *" pgcookie ); -.PP +.P .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr ); .BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags ); .BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags ); -.PP +.P .BI "int mpool_sync(MPOOL *" mp ); .BI "int mpool_close(MPOOL *" mp ); .fi @@ -38,12 +38,12 @@ Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the .I libdb library instead. -.PP +.P .I Mpool is the library interface intended to provide page oriented buffer management of files. The buffers may be shared between processes. -.PP +.P The function .BR mpool_open () initializes a memory pool. @@ -64,7 +64,7 @@ If is non-NULL and matches a file already being mapped, the .I fd argument is ignored. -.PP +.P The .I pagesize argument is the size, in bytes, of the pages into which the file is broken up. @@ -75,7 +75,7 @@ at any one time. This value is not relative to the number of processes which share a file's buffers, but will be the largest value specified by any of the processes sharing the file. -.PP +.P The .BR mpool_filter () function is intended to make transparent input and output processing of the @@ -91,7 +91,7 @@ backing file. Both functions are called with the .I pgcookie pointer, the page number and a pointer to the page to being read or written. -.PP +.P The function .BR mpool_new () takes an @@ -104,7 +104,7 @@ address. Otherwise, NULL is returned and .I errno is set. -.PP +.P The function .BR mpool_get () takes an @@ -117,7 +117,7 @@ is set. The .I flags argument is not currently used. -.PP +.P The function .BR mpool_put () unpins the page referenced by @@ -132,10 +132,10 @@ any of the following values: .TP .B MPOOL_DIRTY The page has been modified and needs to be written to the backing file. -.PP +.P .BR mpool_put () returns 0 on success and \-1 if an error occurs. -.PP +.P The function .BR mpool_sync () writes all modified pages associated with the @@ -144,7 +144,7 @@ pointer to the backing file. .BR mpool_sync () returns 0 on success and \-1 if an error occurs. -.PP +.P The .BR mpool_close () function free's up any allocated memory associated with the memory pool @@ -161,7 +161,7 @@ function may fail and set .I errno for any of the errors specified for the library routine .BR malloc (3). -.PP +.P The .BR mpool_get () function may fail and set @@ -170,7 +170,7 @@ for the following: .TP 15 .B EINVAL The requested record doesn't exist. -.PP +.P The .BR mpool_new () and @@ -182,14 +182,14 @@ for any of the errors specified for the library routines .BR write (2), and .BR malloc (3). -.PP +.P The .BR mpool_sync () function may fail and set .I errno for any of the errors specified for the library routine .BR write (2). -.PP +.P The .BR mpool_close () function may fail and set diff --git a/man3/mq_close.3 b/man3/mq_close.3 index 4834660..1f12165 100644 --- a/man3/mq_close.3 +++ b/man3/mq_close.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_close 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_close 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_close \- close a message queue descriptor .SH LIBRARY @@ -12,14 +12,14 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mq_close(mqd_t " mqdes ); .fi .SH DESCRIPTION .BR mq_close () closes the message queue descriptor .IR mqdes . -.PP +.P If the calling process has attached a notification request (see .BR mq_notify (3)) to this message queue via @@ -52,7 +52,6 @@ T{ .BR mq_close () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/mq_getattr.3 b/man3/mq_getattr.3 index 7c183e7..7c124ea 100644 --- a/man3/mq_getattr.3 +++ b/man3/mq_getattr.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_getattr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_getattr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_getattr, mq_setattr \- get/set message queue attributes .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr ); .BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr , .BI " struct mq_attr *restrict " oldattr ); @@ -24,14 +24,14 @@ and respectively retrieve and modify attributes of the message queue referred to by the message queue descriptor .IR mqdes . -.PP +.P .BR mq_getattr () returns an .I mq_attr structure in the buffer pointed by .IR attr . This structure is defined as: -.PP +.P .in +4n .EX struct mq_attr { @@ -42,7 +42,7 @@ struct mq_attr { }; .EE .in -.PP +.P The .I mq_flags field contains flags associated with the open message queue description. @@ -50,7 +50,7 @@ This field is initialized when the queue is created by .BR mq_open (3). The only flag that can appear in this field is .BR O_NONBLOCK . -.PP +.P The .I mq_maxmsg and @@ -71,11 +71,11 @@ Two .I /proc files that place ceilings on the values for these fields are described in .BR mq_overview (7). -.PP +.P The .I mq_curmsgs field returns the number of messages currently held in the queue. -.PP +.P .BR mq_setattr () sets message queue attributes using information supplied in the .I mq_attr @@ -129,7 +129,6 @@ T{ .BR mq_setattr () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On Linux, .BR mq_getattr () @@ -153,7 +152,7 @@ in which the .I attr argument is NULL. Here is an example run of the program: -.PP +.P .in +4n .EX $ \fB./a.out /testq\fP @@ -161,13 +160,13 @@ Maximum # of messages on queue: 10 Maximum message size: 8192 .EE .in -.PP +.P Since Linux 3.5, the following .I /proc files (described in .BR mq_overview (7)) can be used to control the defaults: -.PP +.P .in +4n .EX $ \fBuname \-sr\fP diff --git a/man3/mq_notify.3 b/man3/mq_notify.3 index bb0d514..591eb32 100644 --- a/man3/mq_notify.3 +++ b/man3/mq_notify.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_notify 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_notify 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_notify \- register for notification when a message is available .SH LIBRARY @@ -13,7 +13,7 @@ Real-time library .nf .B #include .BR "#include " "/* Definition of SIGEV_* constants */" -.PP +.P .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp ); .fi .SH DESCRIPTION @@ -22,15 +22,15 @@ allows the calling process to register or unregister for delivery of an asynchronous notification when a new message arrives on the empty message queue referred to by the message queue descriptor .IR mqdes . -.PP +.P The .I sevp argument is a pointer to a .I sigevent structure. For the definition and general details of this structure, see -.BR sigevent (7). -.PP +.BR sigevent (3type). +.P If .I sevp is a non-null pointer, then @@ -54,7 +54,7 @@ for notification, but when a message arrives, no notification is sent. Notify the process by sending the signal specified in .IR sigev_signo . See -.BR sigevent (7) +.BR sigevent (3type) for general details. The .I si_code @@ -75,26 +75,26 @@ Upon message delivery, invoke .I sigev_notify_function as if it were the start function of a new thread. See -.BR sigevent (7) +.BR sigevent (3type) for details. -.PP +.P Only one process can be registered to receive notification from a message queue. -.PP +.P If .I sevp is NULL, and the calling process is currently registered to receive notifications for this message queue, then the registration is removed; another process can then register to receive a message notification for this queue. -.PP +.P Message notification occurs only when a new message arrives and the queue was previously empty. If the queue was not empty at the time .BR mq_notify () was called, then a notification will occur only after the queue is emptied and a new message arrives. -.PP +.P If another process or thread is waiting to read a message from an empty queue using .BR mq_receive (3), @@ -102,7 +102,7 @@ then any message notification registration is ignored: the message is delivered to the process or thread calling .BR mq_receive (3), and the message notification registration remains in effect. -.PP +.P Notification occurs once: after a notification is delivered, the notification registration is removed, and another process can register for message notification. @@ -142,7 +142,7 @@ is not a valid signal number. .TP .B ENOMEM Insufficient memory. -.PP +.P POSIX.1-2008 says that an implementation .I may generate an @@ -167,7 +167,6 @@ T{ .BR mq_notify () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel differences In the glibc implementation, the @@ -271,4 +270,4 @@ main(int argc, char *argv[]) .BR mq_send (3), .BR mq_unlink (3), .BR mq_overview (7), -.BR sigevent (7) +.BR sigevent (3type) diff --git a/man3/mq_open.3 b/man3/mq_open.3 index 32ff069..09b112f 100644 --- a/man3/mq_open.3 +++ b/man3/mq_open.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_open 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_open 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_open \- open a message queue .SH LIBRARY @@ -14,7 +14,7 @@ Real-time library .BR "#include " " /* For O_* constants */" .BR "#include " " /* For mode constants */" .B #include -.PP +.P .BI "mqd_t mq_open(const char *" name ", int " oflag ); .BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode , .BI " struct mq_attr *" attr ); @@ -28,7 +28,7 @@ For details of the construction of .IR name , see .BR mq_overview (7). -.PP +.P The .I oflag argument specifies flags that control the operation of the call. @@ -45,7 +45,7 @@ Open the queue to send messages only. .TP .B O_RDWR Open the queue to both send and receive messages. -.PP +.P Zero or more of the following flags can additionally be .IR OR ed in @@ -84,7 +84,7 @@ and .BR mq_send (3) would normally block, these functions instead fail with the error .BR EAGAIN . -.PP +.P If .B O_CREAT is specified in @@ -98,7 +98,7 @@ as for (Symbolic definitions for the permissions bits can be obtained by including .IR .) The permissions settings are masked against the process umask. -.PP +.P The fields of the .I struct mq_attr pointed to @@ -106,7 +106,7 @@ pointed to specify the maximum number of messages and the maximum size of messages that the queue will allow. This structure is defined as follows: -.PP +.P .in +4n .EX struct mq_attr { @@ -118,7 +118,7 @@ struct mq_attr { }; .EE .in -.PP +.P Only the .I mq_maxmsg and @@ -126,7 +126,7 @@ and fields are employed when calling .BR mq_open (); the values in the remaining fields are ignored. -.PP +.P If .I attr is NULL, then the queue is created with implementation-defined @@ -262,7 +262,6 @@ T{ .BR mq_open () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel differences The diff --git a/man3/mq_receive.3 b/man3/mq_receive.3 index 40e9973..aa90aaa 100644 --- a/man3/mq_receive.3 +++ b/man3/mq_receive.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_receive 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_receive 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_receive, mq_timedreceive \- receive a message from a message queue .SH LIBRARY @@ -12,25 +12,25 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ], .BI " size_t " msg_len ", unsigned int *" msg_prio ); -.PP +.P .B #include .B #include -.PP +.P .BI "ssize_t mq_timedreceive(mqd_t " mqdes ", \ char *restrict " msg_ptr [. msg_len ], .BI " size_t " msg_len ", unsigned int *restrict " msg_prio , .BI " const struct timespec *restrict " abs_timeout ); .fi -.PP +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mq_timedreceive (): .nf _POSIX_C_SOURCE >= 200112L @@ -54,7 +54,7 @@ If .I msg_prio is not NULL, then the buffer to which it points is used to return the priority associated with the received message. -.PP +.P If the queue is empty, then, by default, .BR mq_receive () blocks until a message becomes available, @@ -64,7 +64,7 @@ If the flag is enabled for the message queue description, then the call instead fails immediately with the error .BR EAGAIN . -.PP +.P .BR mq_timedreceive () behaves just like .BR mq_receive (), @@ -78,7 +78,7 @@ since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), specified in a .BR timespec (3) structure. -.PP +.P If no message is available, and the timeout has already expired by the time of the call, .BR mq_timedreceive () @@ -141,7 +141,6 @@ T{ .BR mq_timedreceive () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On Linux, .BR mq_timedreceive () diff --git a/man3/mq_send.3 b/man3/mq_send.3 index 7e1b6c6..a083dbe 100644 --- a/man3/mq_send.3 +++ b/man3/mq_send.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_send 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_send 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_send, mq_timedsend \- send a message to a message queue .SH LIBRARY @@ -12,24 +12,24 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mq_send(mqd_t " mqdes ", const char " msg_ptr [. msg_len ], .BI " size_t " msg_len ", unsigned int " msg_prio ); -.PP +.P .B #include .B #include -.PP +.P .BI "int mq_timedsend(mqd_t " mqdes ", const char " msg_ptr [. msg_len ], .BI " size_t " msg_len ", unsigned int " msg_prio , .BI " const struct timespec *" abs_timeout ); .fi -.PP +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR mq_timedsend (): .nf _POSIX_C_SOURCE >= 200112L @@ -48,7 +48,7 @@ this length must be less than or equal to the queue's .I mq_msgsize attribute. Zero-length messages are allowed. -.PP +.P The .I msg_prio argument is a nonnegative integer that specifies the priority @@ -59,7 +59,7 @@ older messages with the same priority. See .BR mq_overview (7) for details on the range for the message priority. -.PP +.P If the message queue is already full (i.e., the number of messages on the queue equals the queue's .I mq_maxmsg @@ -72,7 +72,7 @@ If the flag is enabled for the message queue description, then the call instead fails immediately with the error .BR EAGAIN . -.PP +.P .BR mq_timedsend () behaves just like .BR mq_send (), @@ -86,7 +86,7 @@ since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), specified in a .BR timespec (3) structure. -.PP +.P If the message queue is full, and the timeout has already expired by the time of the call, .BR mq_timedsend () @@ -148,7 +148,6 @@ T{ .BR mq_timedsend () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On Linux, .BR mq_timedsend () diff --git a/man3/mq_unlink.3 b/man3/mq_unlink.3 index 7564ccf..819dd21 100644 --- a/man3/mq_unlink.3 +++ b/man3/mq_unlink.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_unlink 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mq_unlink 3 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_unlink \- remove a message queue .SH LIBRARY @@ -12,7 +12,7 @@ Real-time library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int mq_unlink(const char *" name ); .fi .SH DESCRIPTION @@ -54,7 +54,6 @@ T{ .BR mq_unlink () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/mtrace.3 b/man3/mtrace.3 index 442da6f..61e8251 100644 --- a/man3/mtrace.3 +++ b/man3/mtrace.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mtrace 3 2023-07-20 "Linux man-pages 6.05.01" +.TH mtrace 3 2024-02-26 "Linux man-pages 6.7" .SH NAME mtrace, muntrace \- malloc tracing .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .B "void mtrace(void);" .B "void muntrace(void);" .fi @@ -28,7 +28,7 @@ These hook functions record tracing information about memory allocation and deallocation. The tracing information can be used to discover memory leaks and attempts to free nonallocated memory in a program. -.PP +.P The .BR muntrace () function disables the hook functions installed by @@ -39,7 +39,7 @@ If no hook functions were successfully installed by .BR mtrace (), .BR muntrace () does nothing. -.PP +.P When .BR mtrace () is called, it checks the value of the environment variable @@ -47,7 +47,7 @@ is called, it checks the value of the environment variable which should contain the pathname of a file in which the tracing information is to be recorded. If the pathname is successfully opened, it is truncated to zero length. -.PP +.P If .B MALLOC_TRACE is not set, @@ -75,7 +75,6 @@ T{ .BR muntrace () T} Thread safety MT-Unsafe .TE -.sp 1 .\" FIXME: The marking is different from that in the glibc manual, .\" markings in glibc manual are more detailed: .\" @@ -93,7 +92,7 @@ In normal usage, is called once at the start of execution of a program, and .BR muntrace () is never called. -.PP +.P The tracing output produced after a call to .BR mtrace () is textual, but not designed to be human readable. @@ -103,7 +102,7 @@ that interprets the trace log and produces human-readable output. For best results, the traced program should be compiled with debugging enabled, so that line-number information is recorded in the executable. -.PP +.P The tracing performed by .BR mtrace () incurs a performance penalty (if @@ -122,7 +121,7 @@ function and the .BR mtrace (1) command in a program that has memory leaks at two different locations. The demonstration uses the following program: -.PP +.P .in +4n .RB "$ " "cat t_mtrace.c" .\" SRC BEGIN (t_mtrace.c) @@ -145,11 +144,11 @@ main(void) .EE .\" SRC END .in -.PP +.P When we run the program as follows, we see that .BR mtrace () diagnosed memory leaks at two different locations in the program: -.PP +.P .in +4n .EX .RB "$ " "cc \-g t_mtrace.c \-o t_mtrace" @@ -164,7 +163,7 @@ Memory not freed: 0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16 .EE .in -.PP +.P The first two messages about unfreed memory correspond to the two .BR malloc (3) calls inside the diff --git a/man3/nan.3 b/man3/nan.3 index 9fa95b6..6773952 100644 --- a/man3/nan.3 +++ b/man3/nan.3 @@ -7,7 +7,7 @@ .\" .\" Corrections by aeb .\" -.TH nan 3 2023-07-20 "Linux man-pages 6.05.01" +.TH nan 3 2023-10-31 "Linux man-pages 6.7" .SH NAME nan, nanf, nanl \- return 'Not a Number' .SH LIBRARY @@ -16,17 +16,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double nan(const char *" tagp ); .BI "float nanf(const char *" tagp ); .BI "long double nanl(const char *" tagp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nan (), .BR nanf (), .BR nanl (): @@ -39,17 +39,17 @@ These functions return a representation (determined by of a quiet NaN. If the implementation does not support quiet NaNs, these functions return zero. -.PP +.P The call .I nan("char\-sequence") is equivalent to: -.PP +.P .in +4n .EX strtod("NAN(char\-sequence)", NULL); .EE .in -.PP +.P Similarly, calls to .BR nanf () and @@ -58,7 +58,7 @@ are equivalent to analogous calls to .BR strtof (3) and .BR strtold (3). -.PP +.P The argument .I tagp is used in an unspecified manner. @@ -82,10 +82,9 @@ T{ .BR nanl () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. -.PP +.P See also IEC 559 and the appendix with recommended functions in IEEE 754/IEEE 854. .SH HISTORY diff --git a/man3/netlink.3 b/man3/netlink.3 index eeb8875..5040521 100644 --- a/man3/netlink.3 +++ b/man3/netlink.3 @@ -5,7 +5,7 @@ .\" Based on the original comments from Alexey Kuznetsov .\" $Id: netlink.3,v 1.1 1999/05/14 17:17:24 freitag Exp $ .\" -.TH netlink 3 2023-03-30 "Linux man-pages 6.05.01" +.TH netlink 3 2023-10-31 "Linux man-pages 6.7" .SH NAME netlink \- Netlink macros .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int NLMSG_ALIGN(size_t " len ); .BI "int NLMSG_LENGTH(size_t " len ); .BI "int NLMSG_SPACE(size_t " len ); diff --git a/man3/newlocale.3 b/man3/newlocale.3 index 2c602a4..4bbaf14 100644 --- a/man3/newlocale.3 +++ b/man3/newlocale.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH newlocale 3 2023-05-03 "Linux man-pages 6.05.01" +.TH newlocale 3 2023-10-31 "Linux man-pages 6.7" .SH NAME newlocale, freelocale \- create, modify, and free a locale object .SH LIBRARY @@ -11,17 +11,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "locale_t newlocale(int " category_mask ", const char *" locale , .BI " locale_t " base ); .BI "void freelocale(locale_t " locobj ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR newlocale (), .BR freelocale (): .nf @@ -67,7 +67,7 @@ reference returned as the function result. If the call fails, the contents of .I base remain valid and unchanged. -.PP +.P If .I base is the special locale object @@ -78,7 +78,7 @@ or is not .I (locale_t)\ 0 and is not a valid locale object handle, the behavior is undefined. -.PP +.P The .I category_mask argument is a bit mask that specifies the locale categories @@ -101,7 +101,7 @@ and Alternatively, the mask can be specified as .BR LC_ALL_MASK , which is equivalent to ORing all of the preceding constants. -.PP +.P For each category specified in .IR category_mask , the locale data from @@ -112,7 +112,7 @@ If a new locale object is being created, data for all categories not specified in .I category_mask is taken from the default ("POSIX") locale. -.PP +.P The following preset values of .I locale are defined for all categories that can be specified in @@ -146,7 +146,7 @@ If is .B LC_GLOBAL_LOCALE or is not valid locale object handle, the results are undefined. -.PP +.P Once a locale object has been freed, the program should make no further use of it. .SH RETURN VALUE @@ -202,7 +202,7 @@ The second command-line argument is optional; if it is present, it is used to set the .B LC_TIME category of the locale object. -.PP +.P Having created and initialized the locale object, the program then applies it using .BR uselocale (3), @@ -220,15 +220,15 @@ Displaying the date. The format and language of the output will be affected by the .B LC_TIME setting. -.PP +.P The following shell sessions show some example runs of this program. -.PP +.P Set the .B LC_NUMERIC category to .I fr_FR (French): -.PP +.P .in +4n .EX $ \fB./a.out fr_FR\fP @@ -236,7 +236,7 @@ $ \fB./a.out fr_FR\fP Fri Mar 7 00:25:08 2014 .EE .in -.PP +.P Set the .B LC_NUMERIC category to @@ -247,7 +247,7 @@ and the category to .I it_IT (Italian): -.PP +.P .in +4n .EX $ \fB./a.out fr_FR it_IT\fP @@ -255,7 +255,7 @@ $ \fB./a.out fr_FR it_IT\fP ven 07 mar 2014 00:26:01 CET .EE .in -.PP +.P Specify the .B LC_TIME setting as an empty string, @@ -263,7 +263,7 @@ which causes the value to be taken from environment variable settings (which, here, specify .IR mi_NZ , New Zealand MÄori): -.PP +.P .in +4n .EX $ LC_ALL=mi_NZ ./a.out fr_FR "" diff --git a/man3/nextafter.3 b/man3/nextafter.3 index 3636b55..51b770f 100644 --- a/man3/nextafter.3 +++ b/man3/nextafter.3 @@ -7,7 +7,7 @@ .\" .\" Based on glibc infopages .\" -.TH nextafter 3 2023-07-20 "Linux man-pages 6.05.01" +.TH nextafter 3 2023-10-31 "Linux man-pages 6.7" .SH NAME nextafter, nextafterf, nextafterl, nexttoward, nexttowardf, nexttowardl \- floating-point number manipulation @@ -17,21 +17,21 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double nextafter(double " x ", double " y ); .BI "float nextafterf(float " x ", float " y ); .BI "long double nextafterl(long double " x ", long double " y ); -.PP +.P .BI "double nexttoward(double " x ", long double " y ); .BI "float nexttowardf(float " x ", long double " y ); .BI "long double nexttowardl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nextafter (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -40,7 +40,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR nextafterf (), .BR nextafterl (): .nf @@ -48,7 +48,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR nexttoward (), .BR nexttowardf (), .BR nexttowardl (): @@ -72,14 +72,14 @@ is less than .IR x , these functions will return the largest representable number less than .IR x . -.PP +.P If .I x equals .IR y , the functions return .IR y . -.PP +.P The .BR nexttoward (), .BR nexttowardf (), @@ -96,7 +96,7 @@ these functions return the next representable floating-point value after .I x in the direction of .IR y . -.PP +.P If .I x equals @@ -106,14 +106,14 @@ then (cast to the same type as .IR x ) is returned. -.PP +.P If .I x or .I y is a NaN, a NaN is returned. -.PP +.P If .I x is finite, @@ -126,7 +126,7 @@ and the functions return or .BR HUGE_VALL , respectively, with the correct mathematical sign. -.PP +.P If .I x is not equal to @@ -140,7 +140,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result overflow @@ -179,10 +179,9 @@ T{ .BR nexttowardl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. -.PP +.P This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854). .SH HISTORY @@ -192,7 +191,7 @@ In glibc 2.5 and earlier, these functions do not raise an underflow floating-point .RB ( FE_UNDERFLOW ) exception when an underflow occurs. -.PP +.P Before glibc 2.23 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6799 these functions did not set diff --git a/man3/nextup.3 b/man3/nextup.3 index 7a0eaaa..422143d 100644 --- a/man3/nextup.3 +++ b/man3/nextup.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH nextup 3 2023-07-20 "Linux man-pages 6.05.01" +.TH nextup 3 2023-10-31 "Linux man-pages 6.7" .SH NAME nextup, nextupf, nextupl, nextdown, nextdownf, nextdownl \- return next floating-point number toward positive/negative infinity @@ -14,11 +14,11 @@ Math library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "double nextup(double " x ); .BI "float nextupf(float " x ); .BI "long double nextupl(long double " x ); -.PP +.P .BI "double nextdown(double " x ); .BI "float nextdownf(float " x ); .BI "long double nextdownl(long double " x ); @@ -31,7 +31,7 @@ and .BR nextupl () functions return the next representable floating-point number greater than .IR x . -.PP +.P If .I x is the smallest representable negative number in the corresponding type, @@ -40,7 +40,7 @@ If .I x is 0, the returned value is the smallest representable positive number of the corresponding type. -.PP +.P If .I x is positive infinity, the returned value is positive infinity. @@ -49,12 +49,12 @@ If is negative infinity, the returned value is the largest representable finite negative number of the corresponding type. -.PP +.P If .I x is Nan, the returned value is NaN. -.PP +.P The value returned by .I nextdown(x) is @@ -82,7 +82,6 @@ T{ .BR nextdownl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS These functions are described in .I IEEE Std 754-2008 - Standard for Floating-Point Arithmetic diff --git a/man3/nl_langinfo.3 b/man3/nl_langinfo.3 index 2726c29..2b9fa51 100644 --- a/man3/nl_langinfo.3 +++ b/man3/nl_langinfo.3 @@ -11,7 +11,7 @@ .\" .\" Corrected prototype, 2002-10-18, aeb .\" -.TH nl_langinfo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH nl_langinfo 3 2024-01-28 "Linux man-pages 6.7" .SH NAME nl_langinfo, nl_langinfo_l \- query language and locale information .SH LIBRARY @@ -20,16 +20,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *nl_langinfo(nl_item " item ); .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nl_langinfo_l (): .nf Since glibc 2.24: @@ -56,13 +56,13 @@ which was previously created by .BR newlocale (3). Individual and additional elements of the locale categories can be queried. -.PP +.P Examples for the locale elements that can be specified in \fIitem\fP using the constants defined in \fI\fP are: .TP .BR CODESET \ (LC_CTYPE) Return a string with the name of the character encoding used in the -selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968" +selected locale, such as "UTF\-8", "ISO\-8859\-1", or "ANSI_X3.4\-1968" (better known as US-ASCII). This is the same string that you get with "locale charmap". @@ -202,7 +202,7 @@ conversion specification). Return name of the \fIn\fP-th day of the week. [Warning: this follows the US convention DAY_1 = Sunday, not the international convention -(ISO 8601) that Monday is the first day of the week.] +(ISO\~8601) that Monday is the first day of the week.] (Used in .B %A .BR strftime (3) @@ -249,7 +249,7 @@ function to recognize a negative response to a yes/no question. Return the currency symbol, preceded by "\-" if the symbol should appear before the value, "+" if the symbol should appear after the value, or "." if the symbol should replace the radix character. -.PP +.P The above list covers just some examples of items that can be requested. For a more detailed list, consult .IR "The GNU C Library Reference Manual" . @@ -258,7 +258,7 @@ On success, these functions return a pointer to a string which is the value corresponding to .I item in the specified locale. -.PP +.P If no locale has been selected by .BR setlocale (3) for the appropriate category, @@ -271,9 +271,9 @@ if specifies a locale where .I langinfo data is not defined. -.PP +.P If \fIitem\fP is not valid, a pointer to an empty string is returned. -.PP +.P The pointer returned by these functions may point to static data that may be overwritten, or the pointer itself may be invalidated, by a subsequent call to @@ -289,7 +289,7 @@ is freed or modified by .BR freelocale (3) or .BR newlocale (3). -.PP +.P POSIX specifies that the application may not modify the string returned by these functions. .SH ATTRIBUTES @@ -306,7 +306,6 @@ T{ .BR nl_langinfo () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -323,7 +322,7 @@ or is not a valid locale object handle. The following program sets the character type and the numeric locale according to the environment and queries the terminal character set and the radix character. -.PP +.P .\" SRC BEGIN (nl_langinfo.c) .EX #include @@ -350,5 +349,5 @@ main(void) .BR setlocale (3), .BR charsets (7), .BR locale (7) -.PP +.P The GNU C Library Reference Manual diff --git a/man3/ntp_gettime.3 b/man3/ntp_gettime.3 index 30ec3ce..cb1f4f1 100644 --- a/man3/ntp_gettime.3 +++ b/man3/ntp_gettime.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH ntp_gettime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ntp_gettime 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ntp_gettime, ntp_gettimex \- get time parameters (NTP daemon interface) .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int ntp_gettime(struct ntptimeval *" ntv ); .BI "int ntp_gettimex(struct ntptimeval *" ntv ); .fi @@ -20,7 +20,7 @@ Standard C library Both of these APIs return information to the caller via the .I ntv argument, a structure of the following type: -.PP +.P .in +4n .EX struct ntptimeval { @@ -33,7 +33,7 @@ struct ntptimeval { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I time @@ -69,7 +69,7 @@ This value is not used inside the kernel. .TP .I tai TAI (Atomic International Time) offset. -.PP +.P .BR ntp_gettime () returns an .I ntptimeval @@ -79,7 +79,7 @@ structure in which the and .I esterror fields are filled in. -.PP +.P .BR ntp_gettimex () performs the same task as .BR ntp_gettime (), @@ -110,7 +110,6 @@ T{ .BR ntp_gettimex () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR ntp_gettime () @@ -129,7 +128,7 @@ glibc 2.12. .BR adjtimex (2), .BR ntp_adjtime (3), .BR time (7) -.PP +.P .ad l .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm NTP "Kernel Application Program Interface" diff --git a/man3/offsetof.3 b/man3/offsetof.3 index 5dbccc8..3cf0301 100644 --- a/man3/offsetof.3 +++ b/man3/offsetof.3 @@ -25,7 +25,7 @@ .\" References: .\" /usr/lib/gcc/i486-linux-gnu/4.1.1/include/stddef.h .\" glibc-doc -.TH offsetof 3 2023-05-03 "Linux man-pages 6.05.01" +.TH offsetof 3 2023-10-31 "Linux man-pages 6.7" .SH NAME offsetof \- offset of a structure member .SH LIBRARY @@ -34,7 +34,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t offsetof(" type ", " member ); .fi .SH DESCRIPTION @@ -44,14 +44,14 @@ returns the offset of the field .I member from the start of the structure .IR type . -.PP +.P This macro is useful because the sizes of the fields that compose a structure can vary across implementations, and compilers may insert different numbers of padding bytes between fields. Consequently, an element's offset is not necessarily given by the sum of the sizes of the previous elements. -.PP +.P A compiler error will result if .I member is not aligned to a byte boundary @@ -71,7 +71,7 @@ POSIX.1-2001, C89. On a Linux/i386 system, when compiled using the default .BR gcc (1) options, the program below produces the following output: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man3/on_exit.3 b/man3/on_exit.3 index 4ab7aa1..1f5a33a 100644 --- a/man3/on_exit.3 +++ b/man3/on_exit.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified 1993-04-02, David Metcalfe .\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) -.TH on_exit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH on_exit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME on_exit \- register a function to be called at normal process termination .SH LIBRARY @@ -18,15 +18,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int on_exit(void (*" function ")(int, void *), void *" arg ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR on_exit (): .nf Since glibc 2.19: @@ -52,10 +52,10 @@ and the .I arg argument from .BR on_exit (). -.PP +.P The same function may be registered multiple times: it is called once for each registration. -.PP +.P When a child process is created via .BR fork (2), it inherits copies of its parent's registrations. @@ -81,7 +81,6 @@ T{ .BR on_exit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/open_memstream.3 b/man3/open_memstream.3 index ce9da19..ce5ad7c 100644 --- a/man3/open_memstream.3 +++ b/man3/open_memstream.3 @@ -5,28 +5,28 @@ .\" .\" 2008-12-04, Petr Baudis : Document open_wmemstream() .\" -.TH open_memstream 3 2023-07-20 "Linux man-pages 6.05.01" +.TH open_memstream 3 2023-12-28 "Linux man-pages 6.7" .SH NAME -open_memstream, open_wmemstream \- open a dynamic memory buffer stream +open_memstream, open_wmemstream \- open a dynamic memory buffer stream .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf .B #include -.PP +.P .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); -.PP +.P .B #include -.PP +.P .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR open_memstream (), .BR open_wmemstream (): .nf @@ -45,7 +45,7 @@ Initially, the buffer has a size of zero. After closing the stream, the caller should .BR free (3) this buffer. -.PP +.P The locations pointed to by .I ptr and @@ -61,13 +61,13 @@ These values remain valid only as long as the caller performs no further output on the stream. If further output is performed, then the stream must again be flushed before trying to access these values. -.PP +.P A null byte is maintained at the end of the buffer. This byte is .I not included in the size value stored at .IR sizeloc . -.PP +.P The stream maintains the notion of a current position, which is initially zero (the start of the buffer). Each write operation implicitly adjusts the buffer position. @@ -78,7 +78,7 @@ or Moving the buffer position past the end of the data already written fills the intervening space with null characters. -.PP +.P The .BR open_wmemstream () is similar to @@ -110,7 +110,6 @@ T{ .BR open_wmemstream () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/opendir.3 b/man3/opendir.3 index 4ecbd62..5c8fcca 100644 --- a/man3/opendir.3 +++ b/man3/opendir.3 @@ -10,7 +10,7 @@ .\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) .\" 2007-07-30 Ulrich Drepper : document fdopendir(). -.TH opendir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH opendir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME opendir, fdopendir \- open a directory .SH LIBRARY @@ -20,16 +20,16 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "DIR *opendir(const char *" name ); .BI "DIR *fdopendir(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR fdopendir (): .nf Since glibc 2.10: @@ -43,7 +43,7 @@ The function opens a directory stream corresponding to the directory \fIname\fP, and returns a pointer to the directory stream. The stream is positioned at the first entry in the directory. -.PP +.P The .BR fdopendir () function @@ -104,7 +104,6 @@ T{ .BR fdopendir () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH STANDARDS @@ -118,10 +117,10 @@ glibc 2.4. .SH NOTES Filename entries can be read from a directory stream using .BR readdir (3). -.PP +.P The underlying file descriptor of the directory stream can be obtained using .BR dirfd (3). -.PP +.P The .BR opendir () function sets the close-on-exec flag for the file descriptor underlying the diff --git a/man3/openpty.3 b/man3/openpty.3 index 9bdcb14..505c481 100644 --- a/man3/openpty.3 +++ b/man3/openpty.3 @@ -8,7 +8,7 @@ .\" .\" Added -lutil remark, 030718 .\" -.TH openpty 3 2023-07-20 "Linux man-pages 6.05.01" +.TH openpty 3 2023-10-31 "Linux man-pages 6.7" .SH NAME openpty, login_tty, forkpty \- terminal utility functions .SH LIBRARY @@ -17,16 +17,16 @@ System utilities library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int openpty(int *" amaster ", int *" aslave ", char *" name , .BI " const struct termios *" termp , .BI " const struct winsize *" winp ); .BI "pid_t forkpty(int *" amaster ", char *" name , .BI " const struct termios *" termp , .BI " const struct winsize *" winp ); -.PP +.P .B #include -.PP +.P .BI "int login_tty(int " fd ); .fi .SH DESCRIPTION @@ -50,7 +50,7 @@ If .I winp is not NULL, the window size of the slave will be set to the values in .IR winp . -.PP +.P The .BR login_tty () function prepares for a login on the terminal @@ -66,7 +66,7 @@ the controlling terminal for the calling process, setting to be the standard input, output, and error streams of the current process, and closing .IR fd . -.PP +.P The .BR forkpty () function combines @@ -112,14 +112,14 @@ fails if: .TP .B ENOENT There are no available terminals. -.PP +.P .BR login_tty () fails if .BR ioctl (2) fails to set .I fd to the controlling terminal of the calling process. -.PP +.P .BR forkpty () fails if either .BR openpty () @@ -146,7 +146,6 @@ T{ .BR login_tty () T} Thread safety MT-Unsafe race:ttyname .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY @@ -157,7 +156,7 @@ modifiers were added to the structure pointer arguments of and .BR forkpty () in glibc 2.8. -.PP +.P Before glibc 2.0.92, .BR openpty () returns file descriptors for a BSD pseudoterminal pair; diff --git a/man3/perror.3 b/man3/perror.3 index efb3e6f..2bd83c2 100644 --- a/man3/perror.3 +++ b/man3/perror.3 @@ -10,7 +10,7 @@ .\" (msmith@falcon.mercer.peachnet.edu) and various other changes. .\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de) .\" -.TH perror 3 2023-07-20 "Linux man-pages 6.05.01" +.TH perror 3 2023-10-31 "Linux man-pages 6.7" .SH NAME perror \- print a system error message .SH LIBRARY @@ -19,22 +19,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void perror(const char *" s ); -.PP +.P .B #include -.PP +.P .BI "int " errno "; \fR/* Not really declared this way; see errno(3) */" -.PP +.P .BI "[[deprecated]] const char *const " sys_errlist []; .BI "[[deprecated]] int " sys_nerr ; .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .IR sys_errlist , .IR sys_nerr : .nf @@ -48,7 +48,7 @@ The .BR perror () function produces a message on standard error describing the last error encountered during a call to a system or library function. -.PP +.P First (if .I s is not NULL and @@ -59,10 +59,10 @@ is printed, followed by a colon and a blank. Then an error message corresponding to the current value of .I errno and a new-line. -.PP +.P To be of most use, the argument string should include the name of the function that incurred the error. -.PP +.P The global error list .IR sys_errlist "[]," which can be indexed by @@ -78,7 +78,7 @@ The use of is nowadays deprecated; use .BR strerror (3) instead. -.PP +.P When a system call fails, it usually returns \-1 and sets the variable .I errno @@ -113,7 +113,6 @@ T{ .BR perror () T} Thread safety MT-Safe race:stderr .TE -.sp 1 .SH STANDARDS .TP .I errno diff --git a/man3/popen.3 b/man3/popen.3 index 698fe28..6c2cd00 100644 --- a/man3/popen.3 +++ b/man3/popen.3 @@ -10,7 +10,7 @@ .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de) .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) .\" -.TH popen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH popen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME popen, pclose \- pipe stream to or from a process .SH LIBRARY @@ -19,16 +19,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "FILE *popen(const char *" command ", const char *" type ); .BI "int pclose(FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR popen (), .BR pclose (): .nf @@ -44,7 +44,7 @@ Since a pipe is by definition unidirectional, the .I type argument may specify only reading or writing, not both; the resulting stream is correspondingly read-only or write-only. -.PP +.P The .I command argument is a pointer to a null-terminated string containing a shell @@ -54,7 +54,7 @@ This command is passed to using the .B \-c flag; interpretation, if any, is performed by the shell. -.PP +.P The .I type argument is a pointer to a null-terminated string which must contain @@ -69,7 +69,7 @@ see the description of the flag in .BR open (2) for reasons why this may be useful. -.PP +.P The return value from .BR popen () is a normal standard I/O stream in all respects save that it must be closed @@ -85,11 +85,11 @@ Conversely, reading from the stream reads the command's standard output, and the command's standard input is the same as that of the process that called .BR popen (). -.PP +.P Note that output .BR popen () streams are block buffered by default. -.PP +.P The .BR pclose () function waits for the associated process to terminate and returns the exit @@ -105,7 +105,7 @@ or .BR pipe (2) calls fail, or if the function cannot allocate memory, NULL is returned. -.PP +.P .BR pclose (): on success, returns the exit status of the command; if .\" These conditions actually give undefined results, so I commented @@ -117,7 +117,7 @@ on success, returns the exit status of the command; if .BR wait4 (2) returns an error, or some other error is detected, \-1 is returned. -.PP +.P On failure, both functions set .I errno to indicate the error. @@ -140,7 +140,7 @@ argument is invalid, and this condition is detected, .I errno is set to .BR EINVAL . -.PP +.P If .BR pclose () cannot obtain the child status, @@ -162,7 +162,6 @@ T{ .BR pclose () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The \[aq]e\[aq] value for .I type @@ -187,9 +186,9 @@ The latter can be avoided by calling .BR fflush (3) before .BR popen (). -.PP +.P Failure to execute the shell is indistinguishable from the shell's failure -to execute command, or an immediate exit of the command. +to execute the command, or an immediate exit of the command. The only hint is an exit status of 127. .\" .SH HISTORY .\" A diff --git a/man3/posix_fallocate.3 b/man3/posix_fallocate.3 index 1c5c189..f70d27c 100644 --- a/man3/posix_fallocate.3 +++ b/man3/posix_fallocate.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH posix_fallocate 3 2023-07-20 "Linux man-pages 6.05.01" +.TH posix_fallocate 3 2023-10-31 "Linux man-pages 6.7" .SH NAME posix_fallocate \- allocate file space .SH LIBRARY @@ -12,16 +12,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int posix_fallocate(int " fd ", off_t " offset ", off_t " len ); .fi -.PP +.P .ad l .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR posix_fallocate (): .nf _POSIX_C_SOURCE >= 200112L @@ -41,7 +41,7 @@ After a successful call to .BR posix_fallocate (), subsequent writes to bytes in the specified range are guaranteed not to fail because of lack of disk space. -.PP +.P If the size of the file is less than .IR offset + len , then the file is increased to this size; @@ -109,13 +109,12 @@ T} Thread safety T{ MT-Safe (but see NOTES) T} .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.1.94. POSIX.1-2001 -.PP +.P POSIX.1-2008 says that an implementation .I shall give the @@ -165,7 +164,7 @@ or .B O_WRONLY flags, the function fails with the error .BR EBADF . -.PP +.P In general, the emulation is not MT-safe. On Linux, applications may use .BR fallocate (2) diff --git a/man3/posix_madvise.3 b/man3/posix_madvise.3 index 25ab37d..440feb4 100644 --- a/man3/posix_madvise.3 +++ b/man3/posix_madvise.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH posix_madvise 3 2023-03-30 "Linux man-pages 6.05.01" +.TH posix_madvise 3 2023-10-31 "Linux man-pages 6.7" .SH NAME posix_madvise \- give advice about patterns of memory usage .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int posix_madvise(void " addr [. len "], size_t " len ", int " advice ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR posix_madvise (): .nf _POSIX_C_SOURCE >= 200112L @@ -37,7 +37,7 @@ The system is free to use this advice in order to improve the performance of memory accesses (or to ignore the advice altogether), but calling .BR posix_madvise () shall not affect the semantics of access to memory in the specified range. -.PP +.P The .I advice argument is one of the following: @@ -92,7 +92,7 @@ is 0. On Linux, specifying .I len as 0 is permitted (as a successful no-op). -.PP +.P In glibc, this function is implemented using .BR madvise (2). However, since glibc 2.6, diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 index f0c1f6f..194c55a 100644 --- a/man3/posix_memalign.3 +++ b/man3/posix_memalign.3 @@ -7,7 +7,7 @@ .\" 2001-10-11, 2003-08-22, aeb, added some details .\" 2012-03-23, Michael Kerrisk .\" Document pvalloc() and aligned_alloc() -.TH posix_memalign 3 2023-07-20 "Linux man-pages 6.05.01" +.TH posix_memalign 3 2023-11-24 "Linux man-pages 6.7" .SH NAME posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- allocate aligned memory @@ -17,32 +17,32 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); .BI "void *aligned_alloc(size_t " alignment ", size_t " size ); .BI "[[deprecated]] void *valloc(size_t " size ); -.PP +.P .B #include -.PP +.P .BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size ); .BI "[[deprecated]] void *pvalloc(size_t " size ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR posix_memalign (): .nf _POSIX_C_SOURCE >= 200112L .fi -.PP +.P .BR aligned_alloc (): .nf _ISOC11_SOURCE .fi -.PP +.P .BR valloc (): .nf Since glibc 2.12: @@ -54,7 +54,6 @@ Feature Test Macro Requirements for glibc (see .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED .fi .SH DESCRIPTION -The function .BR posix_memalign () allocates .I size @@ -74,7 +73,7 @@ the value placed in is either NULL .\" glibc does this: or a unique pointer value. -.PP +.P The obsolete function .BR memalign () allocates @@ -85,15 +84,14 @@ The memory address will be a multiple of which must be a power of two. .\" The behavior of memalign() for size==0 is as for posix_memalign() .\" but no standards govern this. -.PP -The function +.P .BR aligned_alloc () is the same as .BR memalign (), except for the added restriction that .I alignment must be a power of two. -.PP +.P The obsolete function .BR valloc () allocates @@ -102,14 +100,14 @@ bytes and returns a pointer to the allocated memory. The memory address will be a multiple of the page size. It is equivalent to .IR "memalign(sysconf(_SC_PAGESIZE),size)" . -.PP +.P The obsolete function .BR pvalloc () is similar to .BR valloc (), but rounds the size of the allocation up to the next multiple of the system page size. -.PP +.P For all of these functions, the memory is not zeroed. .SH RETURN VALUE .BR aligned_alloc (), @@ -120,7 +118,7 @@ and return a pointer to the allocated memory on success. On error, NULL is returned, and \fIerrno\fP is set to indicate the error. -.PP +.P .BR posix_memalign () returns zero on success, or one of the error values listed in the next section on failure. @@ -143,7 +141,7 @@ argument was not a power of two, or was not a multiple of .IR "sizeof(void\ *)" . .TP .B ENOMEM -There was insufficient memory to fulfill the allocation request. +Out of memory. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7). @@ -166,7 +164,6 @@ T{ .BR pvalloc () T} Thread safety MT-Unsafe init .TE -.sp 1 .SH STANDARDS .TP .BR aligned_alloc () @@ -209,11 +206,11 @@ glibc 2.0. Everybody agrees that .BR posix_memalign () is declared in \fI\fP. -.PP +.P On some systems .BR memalign () is declared in \fI\fP instead of \fI\fP. -.PP +.P According to SUSv2, .BR valloc () is declared in \fI\fP. @@ -230,7 +227,7 @@ call that tells what alignment is needed. Now one can use .BR posix_memalign () to satisfy this requirement. -.PP +.P .BR posix_memalign () verifies that .I alignment @@ -239,7 +236,7 @@ matches the requirements detailed above. may not check that the .I alignment argument is correct. -.PP +.P POSIX requires that memory obtained from .BR posix_memalign () can be freed using @@ -267,7 +264,7 @@ The glibc implementation allows memory obtained from any of these functions to be reclaimed with .BR free (3). -.PP +.P The glibc .BR malloc (3) always returns 8-byte aligned memory addresses, so these functions are diff --git a/man3/posix_openpt.3 b/man3/posix_openpt.3 index 09733d0..8d25557 100644 --- a/man3/posix_openpt.3 +++ b/man3/posix_openpt.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH posix_openpt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH posix_openpt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME posix_openpt \- open a pseudoterminal device .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int posix_openpt(int " flags ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR posix_openpt (): .nf _XOPEN_SOURCE >= 600 @@ -31,7 +31,7 @@ The .BR posix_openpt () function opens an unused pseudoterminal master device, returning a file descriptor that can be used to refer to that device. -.PP +.P The .I flags argument is a bit mask that ORs together zero or more of @@ -68,20 +68,19 @@ T{ .BR posix_openpt () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.2.1. POSIX.1-2001. -.PP +.P It is part of the UNIX 98 pseudoterminal support (see .BR pts (4)). .SH NOTES Some older UNIX implementations that support System V (aka UNIX 98) pseudoterminals don't have this function, but it can be easily implemented by opening the pseudoterminal multiplexor device: -.PP +.P .in +4n .EX int @@ -91,7 +90,7 @@ posix_openpt(int flags) } .EE .in -.PP +.P Calling .BR posix_openpt () creates a pathname for the corresponding pseudoterminal slave device. diff --git a/man3/posix_spawn.3 b/man3/posix_spawn.3 index 32fa8b3..8fa746f 100644 --- a/man3/posix_spawn.3 +++ b/man3/posix_spawn.3 @@ -8,7 +8,7 @@ .\" POSIX 1003.1-2004 documentation .\" (http://www.opengroup.org/onlinepubs/009695399) .\" -.TH posix_spawn 3 2023-05-03 "Linux man-pages 6.05.01" +.TH posix_spawn 3 2023-10-31 "Linux man-pages 6.7" .SH NAME posix_spawn, posix_spawnp \- spawn a process .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int posix_spawn(pid_t *restrict " pid ", const char *restrict " path , .BI " const posix_spawn_file_actions_t *restrict " file_actions , .BI " const posix_spawnattr_t *restrict " attrp , @@ -42,7 +42,7 @@ to support the .BR fork (2) system call. These machines are generally small, embedded systems lacking MMU support. -.PP +.P The .BR posix_spawn () and @@ -60,7 +60,7 @@ and system calls. In fact, they provide only a subset of the functionality that can be achieved by using the system calls. -.PP +.P The only difference between .BR posix_spawn () and @@ -83,7 +83,7 @@ For the remainder of this page, the discussion is phrased in terms of with the understanding that .BR posix_spawnp () differs only on the point just described. -.PP +.P The remaining arguments to these two functions are as follows: .TP .I pid @@ -125,7 +125,7 @@ functions. specify the argument list and environment for the program that is executed in the child process, as for .BR execve (2). -.PP +.P Below, the functions are described in terms of a three-step process: the .BR fork () step, the @@ -149,20 +149,20 @@ Older implementations use or possibly .BR vfork (2) (see below). -.PP +.P The PID of the new child process is placed in .IR *pid . The .BR posix_spawn () function then returns control to the parent process. -.PP +.P Subsequently, the parent can use one of the system calls described in .BR wait (2) to check the status of the child process. If the child fails in any of the housekeeping steps described below, or fails to execute the desired file, it exits with a status of 127. -.PP +.P Before glibc 2.24, the child process is created using .BR vfork (2) instead of @@ -190,7 +190,7 @@ does \fInot\fP contain .BR POSIX_SPAWN_SETPGROUP , or .BR POSIX_SPAWN_RESETIDS . -.PP +.P In other words, .BR vfork (2) is used if the caller requests it, @@ -231,7 +231,7 @@ functions. File descriptors with the .B FD_CLOEXEC flag set are closed. -.PP +.P All process attributes in the child, other than those affected by attributes specified in the object pointed to by @@ -242,7 +242,7 @@ will be affected as though the child was created with .BR fork (2) and it executed the program with .BR execve (2). -.PP +.P The process attributes actions are defined by the attributes object pointed to by .IR attrp . @@ -253,7 +253,7 @@ attribute (set using controls the general actions that occur, and other attributes in the object specify values to be used during those actions. -.PP +.P The effects of the flags that may be specified in .I spawn-flags are as follows: @@ -325,7 +325,7 @@ attribute of the object pointed to by .I attrp (but see BUGS). -.PP +.P If the .B POSIX_SPAWN_SETSCHEDPARAM and @@ -387,7 +387,7 @@ feature test macro must be defined to obtain the definition of this constant. .\" http://austingroupbugs.net/view.php?id=1044 .\" and has been implemented since glibc 2.26 .\" commit daeb1fa2e1b33323e719015f5f546988bd4cc73b -.PP +.P If .I attrp is NULL, then the default behaviors described above for each flag apply. @@ -398,7 +398,7 @@ is NULL, then the default behaviors described above for each flag apply. .\" .I attrp .\" when you are done with it; .\" however, on Linux systems this operation is a no-op. -.PP +.P The .I file_actions argument specifies a sequence of file operations @@ -415,7 +415,7 @@ except those for which the .B FD_CLOEXEC flag has been set. File locks remain in place. -.PP +.P If .I file_actions is not NULL, then it contains an ordered set of requests to @@ -444,7 +444,7 @@ The requested operations are performed in the order they were added to .\" closed by the earlier operations .\" added to .\" .I file_actions . -.PP +.P If any of the housekeeping actions fails (due to bogus values being passed or other reasons why signal handling, process scheduling, process group ID functions, @@ -454,7 +454,7 @@ the child process exits with exit value 127. Once the child has successfully forked and performed all requested pre-exec steps, the child runs the requested executable. -.PP +.P The child process takes its environment from the .I envp argument, which is interpreted as if it had been passed to @@ -479,7 +479,7 @@ the contents of .I *pid are unspecified, and these functions return an error number as described below. -.PP +.P Even when these functions return a success status, the child process may still fail for a plethora of reasons related to its pre-\fBexec\fR() initialization. @@ -503,7 +503,7 @@ which will be one of the errors described for .BR vfork (2), or .BR clone (2). -.PP +.P In addition, these functions fail if: .TP .B ENOSYS @@ -537,7 +537,7 @@ only the POSIX-specified functions. (In other words, although these objects may be implemented as structures containing fields, portable programs must avoid dependence on such implementation details.) -.PP +.P According to POSIX, it is unspecified whether fork handlers established with .BR pthread_atfork (3) are called when @@ -548,7 +548,7 @@ Since glibc 2.24, the fork handlers are not executed in any case. On older implementations, fork handlers are called only if the child is created using .BR fork (2). -.PP +.P There is no "posix_fspawn" function (i.e., a function that is to .BR posix_spawn () as @@ -582,13 +582,13 @@ The program accepts command-line attributes that can be used to create file actions and attributes objects. The remaining command-line arguments are used as the executable name and command-line arguments of the program that is executed in the child. -.PP +.P In the first run, the .BR date (1) command is executed in the child, and the .BR posix_spawn () call employs no file actions or attributes objects. -.PP +.P .in +4n .EX $ \fB./a.out date\fP @@ -597,7 +597,7 @@ Tue Feb 1 19:47:50 CEST 2011 Child status: exited, status=0 .EE .in -.PP +.P In the next run, the .I \-c command-line option is used to create a file actions object that closes @@ -605,7 +605,7 @@ standard output in the child. Consequently, .BR date (1) fails when trying to perform output and exits with a status of 1. -.PP +.P .in +4n .EX $ \fB./a.out \-c date\fP @@ -614,7 +614,7 @@ date: write error: Bad file descriptor Child status: exited, status=1 .EE .in -.PP +.P In the next run, the .I \-s command-line option is used to create an attributes object that @@ -629,24 +629,24 @@ Therefore, to kill the child, is necessary .RB ( SIGKILL can't be blocked). -.PP +.P .in +4n .EX $ \fB./a.out \-s sleep 60 &\fP [1] 7637 $ PID of child: 7638 -.PP +.P $ \fBkill 7638\fP $ \fBkill \-KILL 7638\fP $ Child status: killed by signal 9 [1]+ Done ./a.out \-s sleep 60 .EE .in -.PP +.P When we try to execute a nonexistent command in the child, the .BR exec (3) fails and the child exits with a status of 127. -.PP +.P .in +4n .EX $ \fB./a.out xxxxx diff --git a/man3/pow.3 b/man3/pow.3 index 3f0be5c..83fd8fb 100644 --- a/man3/pow.3 +++ b/man3/pow.3 @@ -13,7 +13,7 @@ .\" Modified 1995-08-14 by Arnt Gulbrandsen .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) -.TH pow 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pow 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pow, powf, powl \- power functions .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double pow(double " x ", double " y ); .BI "float powf(float " x ", float " y ); .BI "long double powl(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR powf (), .BR powl (): .nf @@ -51,7 +51,7 @@ On success, these functions return the value of .I x to the power of .IR y . -.PP +.P If the result overflows, a range error occurs, .\" The range error is generated at least as far back as glibc 2.4 @@ -61,14 +61,14 @@ and the functions return or .BR HUGE_VALL , respectively, with the mathematically correct sign. -.PP +.P If result underflows, and is not representable, a range error occurs, and 0.0 with the appropriate sign is returned. .\" POSIX.1 does not specify the sign of the zero, .\" but https://www.sourceware.org/bugzilla/show_bug.cgi?id=2678 .\" points out that the zero has the wrong sign in some cases. -.PP +.P .\" pow(\(+-0, <0 [[odd]]) = HUGE_VAL* If .I x @@ -84,7 +84,7 @@ or is returned, with the same sign as .IR x . -.PP +.P .\" pow(\(+-0, <0 [[!odd]]) = HUGE_VAL* If .I x @@ -99,7 +99,7 @@ a pole error occurs and or .RB + HUGE_VALL , is returned. -.PP +.P .\" pow(\(+-0, >0 [[odd]]) = \(+-0 If .I x @@ -108,7 +108,7 @@ and .I y is an odd integer greater than 0, the result is +0 (\-0). -.PP +.P .\" pow(\(+-0, >0 [[!odd]]) = +0 If .I x @@ -117,7 +117,7 @@ and .I y greater than 0 and not an odd integer, the result is +0. -.PP +.P .\" pow(-1, \(+-INFINITY) = 1.0 If .I x @@ -126,21 +126,21 @@ and .I y is positive infinity or negative infinity, the result is 1.0. -.PP +.P .\" pow(+1, y) = 1.0 If .I x is +1, the result is 1.0 (even if .I y is a NaN). -.PP +.P .\" pow(x, \(+-0) = 1.0 If .I y is 0, the result is 1.0 (even if .I x is a NaN). -.PP +.P .\" pow(<0, y) = NaN If .I x @@ -149,7 +149,7 @@ is a finite value less than 0, and is a finite noninteger, a domain error occurs, .\" The domain error is generated at least as far back as glibc 2.4 and a NaN is returned. -.PP +.P .\" pow(|x|<1, -INFINITY) = INFINITY If the absolute value of .I x @@ -158,7 +158,7 @@ and .I y is negative infinity, the result is positive infinity. -.PP +.P .\" pow(|x|>1, -INFINITY) = +0 If the absolute value of .I x @@ -167,7 +167,7 @@ and .I y is negative infinity, the result is +0. -.PP +.P .\" pow(|x|<1, INFINITY) = +0 If the absolute value of .I x @@ -176,7 +176,7 @@ and .I y is positive infinity, the result is +0. -.PP +.P .\" pow(|x|>1, INFINITY) = INFINITY If the absolute value of .I x @@ -185,7 +185,7 @@ and .I y is positive infinity, the result is positive infinity. -.PP +.P .\" pow(-INFINITY, <0 [[odd]]) = -0 If .I x @@ -194,7 +194,7 @@ and .I y is an odd integer less than 0, the result is \-0. -.PP +.P .\" pow(-INFINITY, <0 [[!odd]]) = +0 If .I x @@ -203,7 +203,7 @@ and .I y less than 0 and not an odd integer, the result is +0. -.PP +.P .\" pow(-INFINITY, >0 [[odd]]) = -INFINITY If .I x @@ -212,7 +212,7 @@ and .I y is an odd integer greater than 0, the result is negative infinity. -.PP +.P .\" pow(-INFINITY, >0 [[!odd]]) = INFINITY If .I x @@ -221,7 +221,7 @@ and .I y greater than 0 and not an odd integer, the result is positive infinity. -.PP +.P .\" pow(INFINITY, <0) = +0 If .I x @@ -230,7 +230,7 @@ and .I y less than 0, the result is +0. -.PP +.P .\" pow(INFINITY, >0) = INFINITY If .I x @@ -239,7 +239,7 @@ and .I y greater than 0, the result is positive infinity. -.PP +.P .\" pow(NaN, y) or pow(x, NaN) = NaN Except as specified above, if .I x @@ -271,7 +271,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger @@ -322,12 +322,11 @@ T{ .BR powl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to @@ -349,13 +348,13 @@ nor This problem was fixed .\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5 in glibc 2.28. -.PP +.P A number of bugs .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=3866 in the glibc implementation of .BR pow () were fixed in glibc 2.16. -.PP +.P In glibc 2.9 and earlier, .\" .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6776 @@ -369,7 +368,7 @@ Since glibc 2.10, .\" or possibly 2.9, I haven't found the source code change .\" and I don't have a 2.9 system to test glibc does the right thing. -.PP +.P In glibc 2.3.2 and earlier, .\" Actually, glibc 2.3.2 is the earliest test result I have; so yet .\" to confirm if this error occurs only in glibc 2.3.2. diff --git a/man3/pow10.3 b/man3/pow10.3 index bbbac22..0a0bdac 100644 --- a/man3/pow10.3 +++ b/man3/pow10.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pow10 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pow10 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pow10, pow10f, pow10l \- base-10 power functions .SH LIBRARY @@ -13,7 +13,7 @@ Math library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "double pow10(double " x ); .BI "float pow10f(float " x ); .BI "long double pow10l(long double " x ); @@ -21,7 +21,7 @@ Math library .SH DESCRIPTION These functions return the value of 10 raised to the power .IR x . -.PP +.P .BR "Note well" : These functions perform exactly the same task as the functions described in .BR exp10 (3), @@ -45,7 +45,6 @@ T{ .BR pow10l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH VERSIONS diff --git a/man3/powerof2.3 b/man3/powerof2.3 index fae024f..cc21e4d 100644 --- a/man3/powerof2.3 +++ b/man3/powerof2.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH powerof2 3 2023-03-30 "Linux man-pages 6.05.01" +.TH powerof2 3 2023-10-31 "Linux man-pages 6.7" .SH NAME powerof2 \- test if a value is a power of 2 .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int powerof2(" x ); .fi .SH DESCRIPTION @@ -19,7 +19,7 @@ This macro returns true if .I x is a power of 2, and false otherwise. -.PP +.P .B 0 is considered a power of 2. This can make sense considering wrapping of unsigned integers, @@ -34,7 +34,7 @@ respectively. BSD. .SH CAVEATS The arguments may be evaluated more than once. -.PP +.P Because this macro is implemented using bitwise operations, some negative values can invoke undefined behavior. For example, diff --git a/man3/printf.3 b/man3/printf.3 index edd6ba8..205bf9b 100644 --- a/man3/printf.3 +++ b/man3/printf.3 @@ -13,7 +13,7 @@ .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes .\" -.TH printf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH printf 3 2024-03-16 "Linux man-pages 6.7" .SH NAME printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf \- formatted output conversion @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int printf(const char *restrict " format ", ...);" .BI "int fprintf(FILE *restrict " stream , .BI " const char *restrict " format ", ...);" @@ -33,7 +33,7 @@ Standard C library .BI " const char *restrict " format ", ...);" .BI "int snprintf(char " str "[restrict ." size "], size_t " size , .BI " const char *restrict " format ", ...);" -.PP +.P .BI "int vprintf(const char *restrict " format ", va_list " ap ); .BI "int vfprintf(FILE *restrict " stream , .BI " const char *restrict " format ", va_list " ap ); @@ -44,19 +44,19 @@ Standard C library .BI "int vsnprintf(char " str "[restrict ." size "], size_t " size , .BI " const char *restrict " format ", va_list " ap ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR snprintf (), .BR vsnprintf (): .nf _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE .fi -.PP +.P .BR dprintf (), .BR vdprintf (): .nf @@ -90,7 +90,7 @@ and .BR vsnprintf () write to the character string .IR str . -.PP +.P The function .BR dprintf () is the same as @@ -100,7 +100,7 @@ except that it outputs to a file descriptor, instead of to a .BR stdio (3) stream. -.PP +.P The functions .BR snprintf () and @@ -109,7 +109,7 @@ write at most .I size bytes (including the terminating null byte (\[aq]\e0\[aq])) to .IR str . -.PP +.P The functions .BR vprintf (), .BR vfprintf (), @@ -135,14 +135,14 @@ macro, the value of is undefined after the call. See .BR stdarg (3). -.PP +.P All of these functions write the output under the control of a .I format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of .BR stdarg (3)) are converted for output. -.PP +.P C99 and POSIX.1-2001 specify that the results are undefined if a call to .BR sprintf (), .BR snprintf (), @@ -152,7 +152,7 @@ or would cause copying to take place between objects that overlap (e.g., if the target string array and one of the supplied input arguments refer to the same buffer). -See NOTES. +See CAVEATS. .SS Format of the format string The format string is a character string, beginning and ending in its initial shift state, if any. @@ -175,15 +175,15 @@ an optional .I precision and an optional .IR "length modifier" . -.PP +.P The overall syntax of a conversion specification is: -.PP +.P .in +4n .nf %[$][flags][width][.precision][length modifier]conversion .fi .in -.PP +.P The arguments must correspond properly (after type promotion) with the conversion specifier. By default, the arguments are used in the order @@ -200,21 +200,21 @@ where the decimal integer \fIm\fP denotes the position in the argument list of the desired argument, indexed starting from 1. Thus, -.PP +.P .in +4n .EX printf("%*d", width, num); .EE .in -.PP +.P and -.PP +.P .in +4n .EX printf("%2$*1$d", width, num); .EE .in -.PP +.P are equivalent. The second style allows repeated references to the same argument. @@ -228,7 +228,7 @@ There may be no gaps in the numbers of arguments specified using \[aq]$\[aq]; for example, if arguments 1 and 3 are specified, argument 2 must also be specified somewhere in the format string. -.PP +.P For some numeric conversions a radix character ("decimal point") or thousands' grouping character is used. The actual character used @@ -240,13 +240,13 @@ part of the locale. The POSIX locale uses \[aq].\[aq] as radix character, and does not have a grouping character. Thus, -.PP +.P .in +4n .EX printf("%\[aq].2f", 1234567.89); .EE .in -.PP +.P results in "1234567.89" in the POSIX locale, in "1234567,89" in the nl_NL locale, and in "1.234.567,89" in the da_DK locale. .SS Flag characters @@ -359,7 +359,7 @@ By default, a sign is used only for negative numbers. A .B + overrides a space if both are used. -.PP +.P The five flag characters above are defined in the C99 standard. The Single UNIX Specification specifies one further flag character. .TP @@ -386,7 +386,7 @@ whose locale information indicates no thousands' grouping character. Therefore, without a prior call to .BR setlocale (3), no thousands' grouping characters will be printed. -.PP +.P glibc 2.2 adds one further flag character. .TP .B I @@ -585,7 +585,7 @@ argument, or a following conversion corresponds to a pointer to a .I ptrdiff_t argument. -.PP +.P SUSv3 specifies all of the above, except for those modifiers explicitly noted as being nonstandard extensions. SUSv2 specified only the length modifiers @@ -616,7 +616,7 @@ and .BR Lf , .BR Lg , .BR LG ). -.PP +.P As a nonstandard extension, the GNU implementations treats .B ll and @@ -875,9 +875,9 @@ No argument is converted. The complete conversion specification is \[aq]%%\[aq]. .SH RETURN VALUE -Upon successful return, these functions return the number of characters +Upon successful return, these functions return the number of bytes printed (excluding the null byte used to end output to strings). -.PP +.P The functions .BR snprintf () and @@ -892,8 +892,8 @@ had been available. Thus, a return value of .I size or more means that the output was truncated. -(See also below under NOTES.) -.PP +(See also below under CAVEATS.) +.P If an output error is encountered, a negative value is returned. .SH ATTRIBUTES For an explanation of the terms used in this section, see @@ -916,7 +916,6 @@ T{ .BR vsnprintf () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS .TP .BR fprintf () @@ -980,7 +979,7 @@ with C99. .TQ .BR vdprintf () GNU, POSIX.1-2008. -.PP +.P .\" Linux libc4 knows about the five C standard flags. .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, .\" and the conversions @@ -994,7 +993,7 @@ GNU, POSIX.1-2008. .\" support for \fB%D\fP disappeared.) .\" No locale-dependent radix character, .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$". -.\" .PP +.\" .P .\" Linux libc5 knows about the five C standard flags and the \[aq] flag, .\" locale, "%m$" and "*m$". .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, @@ -1005,15 +1004,15 @@ GNU, POSIX.1-2008. .\" .BR m , .\" which outputs .\" .IR strerror(errno) . -.\" .PP +.\" .P .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. -.\" .PP +.\" .P glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP and conversion characters \fBa\fP and \fBA\fP. -.PP +.P glibc 2.2 adds the conversion character \fBF\fP with C99 semantics, and the flag character \fBI\fP. -.PP +.P glibc 2.35 gives a meaning to the alternate form .RB ( # ) of the @@ -1022,13 +1021,13 @@ conversion specifier, that is .IR %#m . .SH CAVEATS Some programs imprudently rely on code such as the following -.PP +.P .in +4n .EX sprintf(buf, "%s some further text", buf); .EE .in -.PP +.P to append text to .IR buf . However, the standards explicitly note that the results are undefined @@ -1044,7 +1043,7 @@ Depending on the version of used, and the compiler options employed, calls such as the above will .B not produce the expected results. -.PP +.P The glibc implementation of the functions .BR snprintf () and @@ -1103,7 +1102,7 @@ instead (or .BR asprintf (3) and .BR vasprintf (3)). -.\" .PP +.\" .P .\" Linux libc4.[45] does not have a .\" .BR snprintf (), .\" but provides a libbsd that contains an @@ -1116,7 +1115,7 @@ and .\" Thus, the use of .\" .BR snprintf () .\" with early libc4 leads to serious security problems. -.PP +.P Code such as .BI printf( foo ); often indicates a bug, since @@ -1127,14 +1126,14 @@ If comes from untrusted user input, it may contain \fB%n\fP, causing the .BR printf () call to write to memory and creating a security hole. -.\" .PP +.\" .P .\" Some floating-point conversions under early libc4 .\" caused memory leaks. .SH EXAMPLES To print .I Pi to five decimal places: -.PP +.P .in +4n .EX #include @@ -1142,14 +1141,14 @@ to five decimal places: fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); .EE .in -.PP +.P To print a date and time in the form "Sunday, July 3, 10:02", where .I weekday and .I month are pointers to strings: -.PP +.P .in +4n .EX #include @@ -1157,11 +1156,11 @@ fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", weekday, month, day, hour, min); .EE .in -.PP +.P Many countries use the day-month-year order. Hence, an internationalized version must be able to print the arguments in an order specified by the format: -.PP +.P .in +4n .EX #include @@ -1169,23 +1168,23 @@ fprintf(stdout, format, weekday, month, day, hour, min); .EE .in -.PP +.P where .I format depends on locale, and may permute the arguments. With the value: -.PP +.P .in +4n .EX "%1$s, %3$d. %2$s, %4$d:%5$.2d\en" .EE .in -.PP +.P one might obtain "Sonntag, 3. Juli, 10:02". -.PP +.P To allocate a sufficiently large string and print into it (code correct for both glibc 2.0 and glibc 2.1): -.PP +.P .EX #include #include @@ -1225,7 +1224,7 @@ make_message(const char *fmt, ...) return p; } .EE -.PP +.P If truncation occurs in glibc versions prior to glibc 2.0.6, this is treated as an error instead of being handled gracefully. .SH SEE ALSO diff --git a/man3/profil.3 b/man3/profil.3 index caa5f48..6bdb2e3 100644 --- a/man3/profil.3 +++ b/man3/profil.3 @@ -6,7 +6,7 @@ .\" Modified Fri Jun 23 01:35:19 1995 Andries Brouwer .\" (prompted by Bas V. de Bakker ) .\" Corrected (and moved to man3), 980612, aeb -.TH profil 3 2023-07-20 "Linux man-pages 6.05.01" +.TH profil 3 2023-10-31 "Linux man-pages 6.7" .SH NAME profil \- execution time profile .SH LIBRARY @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int profil(unsigned short *" buf ", size_t " bufsiz , .BI " size_t " offset ", unsigned int " scale ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR profil (): .nf Since glibc 2.21: @@ -73,7 +73,6 @@ T{ .BR profil () T} Thread safety MT-Unsafe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -84,7 +83,7 @@ cannot be used on a program that also uses .B ITIMER_PROF interval timers (see .BR setitimer (2)). -.PP +.P True kernel profiling provides more accurate results. .\" Libc 4.4 contained a kernel patch providing a system call profil. .SH SEE ALSO diff --git a/man3/program_invocation_name.3 b/man3/program_invocation_name.3 index 79bd2f7..b840ada 100644 --- a/man3/program_invocation_name.3 +++ b/man3/program_invocation_name.3 @@ -21,7 +21,7 @@ .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. .\" %%%LICENSE_END .\" -.TH program_invocation_name 3 2023-03-30 "Linux man-pages 6.05.01" +.TH program_invocation_name 3 2023-10-31 "Linux man-pages 6.7" .SH NAME program_invocation_name, program_invocation_short_name \- \ obtain name used to invoke calling program @@ -32,7 +32,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "extern char *" program_invocation_name ; .BI "extern char *" program_invocation_short_name ; .fi @@ -46,14 +46,14 @@ in with the difference that the scope of .I program_invocation_name is global. -.PP +.P .I program_invocation_short_name contains the basename component of name that was used to invoke the calling program. That is, it is the same value as .IR program_invocation_name , with all text up to and including the final slash (/), if any, removed. -.PP +.P These variables are automatically initialized by the glibc run-time startup code. .SH VERSIONS diff --git a/man3/psignal.3 b/man3/psignal.3 index e9c9728..011f44c 100644 --- a/man3/psignal.3 +++ b/man3/psignal.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:45:17 1993 by Rik Faith (faith@cs.unc.edu) -.TH psignal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH psignal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME psignal, psiginfo \- print signal description .SH LIBRARY @@ -17,16 +17,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void psignal(int " sig ", const char *" s ); .BI "void psiginfo(const siginfo_t *" pinfo ", const char *" s ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR psignal (): .nf Since glibc 2.19: @@ -34,7 +34,7 @@ Feature Test Macro Requirements for glibc (see glibc 2.19 and earlier: _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR psiginfo (): .nf _POSIX_C_SOURCE >= 200809L @@ -48,7 +48,7 @@ describing the signal number \fIsig\fP, and a trailing newline. If the string \fIs\fP is NULL or empty, the colon and space are omitted. If \fIsig\fP is invalid, the message displayed will indicate an unknown signal. -.PP +.P The .BR psiginfo () function is like @@ -90,7 +90,6 @@ T{ .BR psiginfo () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3 index 1bcfc7e..0c01904 100644 --- a/man3/pthread_atfork.3 +++ b/man3/pthread_atfork.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_atfork 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_atfork 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_atfork \- register fork handlers .SH LIBRARY @@ -11,7 +11,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_atfork(void (*" prepare ")(void), void (*" parent ")(void)," .BI " void (*" child ")(void));" .fi @@ -23,7 +23,7 @@ function registers fork handlers that are to be executed when is called by any thread in a process. The handlers are executed in the context of the thread that calls .BR fork (2). -.PP +.P Three kinds of handler can be registered: .IP \[bu] 3 .I prepare @@ -40,7 +40,7 @@ processing completes. specifies a handler that is executed in the child process after .BR fork (2) processing completes. -.PP +.P Any of the three arguments may be NULL if no handler is needed in the corresponding phase of .BR fork (2) @@ -88,7 +88,7 @@ was to provide a mechanism whereby the application (or a library) could ensure that mutexes and other process and thread state would be restored to a consistent state. In practice, this task is generally too difficult to be practicable. -.PP +.P After a .BR fork (2) in a multithreaded process returns in the child, @@ -97,7 +97,7 @@ the child should call only async-signal-safe functions (see until such time as it calls .BR execve (2) to execute a new program. -.PP +.P POSIX.1 specifies that .BR pthread_atfork () shall not fail with the error diff --git a/man3/pthread_attr_init.3 b/man3/pthread_attr_init.3 index 8792ab4..2f23061 100644 --- a/man3/pthread_attr_init.3 +++ b/man3/pthread_attr_init.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_init 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_init 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_init, pthread_attr_destroy \- initialize and destroy thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_init(pthread_attr_t *" attr ); .BI "int pthread_attr_destroy(pthread_attr_t *" attr ); .fi @@ -29,19 +29,19 @@ using various related functions (listed under SEE ALSO), and then the object can be used in one or more .BR pthread_create (3) calls that create threads. -.PP +.P Calling .BR pthread_attr_init () on a thread attributes object that has already been initialized results in undefined behavior. -.PP +.P When a thread attributes object is no longer required, it should be destroyed using the .BR pthread_attr_destroy () function. Destroying a thread attributes object has no effect on threads that were created using that object. -.PP +.P Once a thread attributes object has been destroyed, it can be reinitialized using .BR pthread_attr_init (). @@ -73,7 +73,6 @@ T{ .BR pthread_attr_destroy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -93,7 +92,7 @@ Once created, the thread uses the .BR pthread_getattr_np (3) function (a nonstandard GNU extension) to retrieve the thread's attributes, and then displays those attributes. -.PP +.P If the program is run with no command-line argument, then it passes NULL as the .I attr @@ -102,7 +101,7 @@ argument of so that the thread is created with default attributes. Running the program on Linux/x86-32 with the NPTL threading implementation, we see the following: -.PP +.P .in +4n .EX .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 @@ -120,7 +119,7 @@ Thread attributes: Stack size = 0x201000 bytes .EE .in -.PP +.P When we supply a stack size as a command-line argument, the program initializes a thread attributes object, sets various attributes in that object, @@ -128,7 +127,7 @@ and passes a pointer to the object in the call to .BR pthread_create (3). Running the program on Linux/x86-32 with the NPTL threading implementation, we see the following: -.PP +.P .in +4n .EX .\" Results from glibc 2.8, SUSE 11.0; Oct 2008 diff --git a/man3/pthread_attr_setaffinity_np.3 b/man3/pthread_attr_setaffinity_np.3 index 923ee0b..0ab2224 100644 --- a/man3/pthread_attr_setaffinity_np.3 +++ b/man3/pthread_attr_setaffinity_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setaffinity_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setaffinity_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setaffinity_np, pthread_attr_getaffinity_np \- set/get CPU affinity attribute in thread attributes object @@ -15,7 +15,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_attr_setaffinity_np(pthread_attr_t *" attr , .BI " size_t " cpusetsize ", const cpu_set_t *" cpuset ); .BI "int pthread_attr_getaffinity_np(const pthread_attr_t *" attr , @@ -33,7 +33,7 @@ to the value specified in This attribute determines the CPU affinity mask of a thread created using the thread attributes object .IR attr . -.PP +.P The .BR pthread_attr_getaffinity_np () function @@ -42,14 +42,14 @@ referred to by .I attr in the buffer pointed to by .IR cpuset . -.PP +.P The argument .I cpusetsize is the length (in bytes) of the buffer pointed to by .IR cpuset . Typically, this argument would be specified as .IR sizeof(cpu_set_t) . -.PP +.P For more details on CPU affinity masks, see .BR sched_setaffinity (2). For a description of a set of macros @@ -100,7 +100,6 @@ T{ .BR pthread_attr_getaffinity_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in the names. diff --git a/man3/pthread_attr_setdetachstate.3 b/man3/pthread_attr_setdetachstate.3 index c984943..2fcf6e0 100644 --- a/man3/pthread_attr_setdetachstate.3 +++ b/man3/pthread_attr_setdetachstate.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setdetachstate 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setdetachstate 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setdetachstate, pthread_attr_getdetachstate \- set/get detach state attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setdetachstate(pthread_attr_t *" attr \ ", int " detachstate ); .BI "int pthread_attr_getdetachstate(const pthread_attr_t *" attr , @@ -32,7 +32,7 @@ The detach state attribute determines whether a thread created using the thread attributes object .I attr will be created in a joinable or a detached state. -.PP +.P The following values may be specified in .IR detachstate : .TP @@ -45,11 +45,11 @@ will be created in a detached state. Threads that are created using .I attr will be created in a joinable state. -.PP +.P The default setting of the detach state attribute in a newly initialized thread attributes object is .BR PTHREAD_CREATE_JOINABLE . -.PP +.P The .BR pthread_attr_getdetachstate () returns the detach state attribute of the thread attributes object @@ -81,7 +81,6 @@ T{ .BR pthread_attr_getdetachstate () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -90,7 +89,7 @@ POSIX.1-2001. See .BR pthread_create (3) for more details on detached and joinable threads. -.PP +.P A thread that is created in a joinable state should eventually either be joined using .BR pthread_join (3) @@ -98,7 +97,7 @@ or detached using .BR pthread_detach (3); see .BR pthread_create (3). -.PP +.P It is an error to specify the thread ID of a thread that was created in a detached state in a later call to diff --git a/man3/pthread_attr_setguardsize.3 b/man3/pthread_attr_setguardsize.3 index 7d8d8cb..b436260 100644 --- a/man3/pthread_attr_setguardsize.3 +++ b/man3/pthread_attr_setguardsize.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setguardsize 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setguardsize 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setguardsize, pthread_attr_getguardsize \- set/get guard size attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setguardsize(pthread_attr_t *" attr \ ", size_t " guardsize ); .BI "int pthread_attr_getguardsize(const pthread_attr_t *restrict " attr , @@ -28,7 +28,7 @@ thread attributes object referred to by .I attr to the value specified in .IR guardsize . -.PP +.P If .I guardsize is greater than 0, @@ -38,15 +38,15 @@ the system allocates an additional region of at least .I guardsize bytes at the end of the thread's stack to act as the guard area for the stack (but see BUGS). -.PP +.P If .I guardsize is 0, then new threads created with .I attr will not have a guard area. -.PP +.P The default guard size is the same as the system page size. -.PP +.P If the stack address attribute has been set in .I attr (using @@ -61,7 +61,7 @@ it is the application's responsibility to handle stack overflow .BR mprotect (2) to manually define a guard area at the end of the stack that it has allocated). -.PP +.P The .BR pthread_attr_getguardsize () function returns the guard size attribute of the @@ -98,7 +98,6 @@ T{ .BR pthread_attr_getguardsize () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -118,11 +117,11 @@ the system page size when creating a thread. .BR pthread_attr_getguardsize () returns the guard size that was set by .BR pthread_attr_setguardsize ().) -.PP +.P Setting a guard size of 0 may be useful to save memory in an application that creates many threads and knows that stack overflow can never occur. -.PP +.P Choosing a guard size larger than the default size may be necessary for detecting stack overflows if a thread allocates large data structures on the stack. @@ -137,7 +136,7 @@ error from .BR pthread_create (3) if the guard size value is too large, leaving no space for the actual stack.) -.PP +.P The obsolete LinuxThreads implementation did the right thing, allocating extra space at the end of the stack for the guard area. .\" glibc includes the guardsize within the allocated stack size, diff --git a/man3/pthread_attr_setinheritsched.3 b/man3/pthread_attr_setinheritsched.3 index aa062d1..218522e 100644 --- a/man3/pthread_attr_setinheritsched.3 +++ b/man3/pthread_attr_setinheritsched.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setinheritsched 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setinheritsched 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setinheritsched, pthread_attr_getinheritsched \- set/get inherit-scheduler attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setinheritsched(pthread_attr_t *" attr , .BI " int " inheritsched ); .BI "int pthread_attr_getinheritsched(const pthread_attr_t *restrict " attr , @@ -34,7 +34,7 @@ the thread attributes object will inherit its scheduling attributes from the calling thread or whether it will take them from .IR attr . -.PP +.P The following scheduling attributes are affected by the inherit-scheduler attribute: scheduling policy @@ -43,7 +43,7 @@ scheduling priority .RB ( pthread_attr_setschedparam (3)), and contention scope .RB ( pthread_attr_setscope (3)). -.PP +.P The following values may be specified in .IR inheritsched : .TP @@ -61,11 +61,11 @@ Threads that are created using take their scheduling attributes from the values specified by the attributes object. .\" FIXME Document the defaults for scheduler settings -.PP +.P The default setting of the inherit-scheduler attribute in a newly initialized thread attributes object is .BR PTHREAD_INHERIT_SCHED . -.PP +.P The .BR pthread_attr_getinheritsched () returns the inherit-scheduler attribute of the thread attributes object @@ -82,7 +82,7 @@ can fail with the following error: .B EINVAL Invalid value in .IR inheritsched . -.PP +.P POSIX.1 also documents an optional .B ENOTSUP error ("attempt was made to set the attribute to an unsupported value") for @@ -102,7 +102,6 @@ T{ .BR pthread_attr_getinheritsched () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_attr_setschedparam.3 b/man3/pthread_attr_setschedparam.3 index 379f30c..b01f0f9 100644 --- a/man3/pthread_attr_setschedparam.3 +++ b/man3/pthread_attr_setschedparam.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setschedparam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setschedparam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setschedparam, pthread_attr_getschedparam \- set/get scheduling parameter attributes in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setschedparam(pthread_attr_t *restrict " attr , .BI " const struct sched_param *restrict " param ); .BI "int pthread_attr_getschedparam(const pthread_attr_t *restrict " attr , @@ -31,16 +31,16 @@ to the values specified in the buffer pointed to by These attributes determine the scheduling parameters of a thread created using the thread attributes object .IR attr . -.PP +.P The .BR pthread_attr_getschedparam () returns the scheduling parameter attributes of the thread attributes object .I attr in the buffer pointed to by .IR param . -.PP +.P Scheduling parameters are maintained in the following structure: -.PP +.P .in +4n .EX struct sched_param { @@ -48,12 +48,12 @@ struct sched_param { }; .EE .in -.PP +.P As can be seen, only one scheduling parameter is supported. For details of the permitted ranges for scheduling priorities in each scheduling policy, see .BR sched (7). -.PP +.P In order for the parameter setting made by .BR pthread_attr_setschedparam () to have effect when calling @@ -76,7 +76,7 @@ The priority specified in .I param does not make sense for the current scheduling policy of .IR attr . -.PP +.P POSIX.1 also documents an .B ENOTSUP error for @@ -99,7 +99,6 @@ T{ .BR pthread_attr_getschedparam () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_attr_setschedpolicy.3 b/man3/pthread_attr_setschedpolicy.3 index 9311af6..cbd630f 100644 --- a/man3/pthread_attr_setschedpolicy.3 +++ b/man3/pthread_attr_setschedpolicy.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setschedpolicy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setschedpolicy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setschedpolicy, pthread_attr_getschedpolicy \- set/get scheduling policy attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setschedpolicy(pthread_attr_t *" attr ", int " policy ); .BI "int pthread_attr_getschedpolicy(const pthread_attr_t *restrict " attr , .BI " int *restrict " policy ); @@ -30,7 +30,7 @@ to the value specified in This attribute determines the scheduling policy of a thread created using the thread attributes object .IR attr . -.PP +.P The supported values for .I policy are @@ -43,14 +43,14 @@ with the semantics described in .\" FIXME . pthread_setschedparam() places no restriction on the policy, .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 -.PP +.P The .BR pthread_attr_getschedpolicy () returns the scheduling policy attribute of the thread attributes object .I attr in the buffer pointed to by .IR policy . -.PP +.P In order for the policy setting made by .BR pthread_attr_setschedpolicy () to have effect when calling @@ -71,7 +71,7 @@ can fail with the following error: .B EINVAL Invalid value in .IR policy . -.PP +.P POSIX.1 also documents an optional .B ENOTSUP error ("attempt was made to set the attribute to an unsupported value") for @@ -91,7 +91,6 @@ T{ .BR pthread_attr_getschedpolicy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_attr_setscope.3 b/man3/pthread_attr_setscope.3 index c9acfc4..024efa5 100644 --- a/man3/pthread_attr_setscope.3 +++ b/man3/pthread_attr_setscope.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setscope 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setscope 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope ); .BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr , .BI " int *restrict " scope ); @@ -54,14 +54,14 @@ with other threads in the same process that were created with the .B PTHREAD_SCOPE_SYSTEM contention scope. -.PP +.P POSIX.1 requires that an implementation support at least one of these contention scopes. Linux supports .BR PTHREAD_SCOPE_SYSTEM , but not .BR PTHREAD_SCOPE_PROCESS . -.PP +.P On systems that support multiple contention scopes, then, in order for the parameter setting made by .BR pthread_attr_setscope () @@ -73,7 +73,7 @@ to set the inherit-scheduler attribute of the attributes object .I attr to .BR PTHREAD_EXPLICIT_SCHED . -.PP +.P The .BR pthread_attr_getscope () function returns the contention scope attribute of the @@ -112,7 +112,6 @@ T{ .BR pthread_attr_getscope () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -125,7 +124,7 @@ bound directly to a single kernel-scheduling entity. This is the case on Linux for the obsolete LinuxThreads implementation and the modern NPTL implementation, which are both 1:1 threading implementations. -.PP +.P POSIX.1 specifies that the default contention scope is implementation-defined. .SH SEE ALSO diff --git a/man3/pthread_attr_setsigmask_np.3 b/man3/pthread_attr_setsigmask_np.3 index ee789a6..0ff9bee 100644 --- a/man3/pthread_attr_setsigmask_np.3 +++ b/man3/pthread_attr_setsigmask_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setsigmask_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setsigmask_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setsigmask_np, pthread_attr_getsigmask_np \- set/get signal mask attribute in thread attributes object @@ -15,7 +15,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_attr_setsigmask_np(pthread_attr_t *" attr , .BI " const sigset_t *" sigmask ); .BI "int pthread_attr_getsigmask_np(const pthread_attr_t *" attr , @@ -34,7 +34,7 @@ If is specified as NULL, then any existing signal mask attribute in .I attr is unset. -.PP +.P The .BR pthread_attr_getsigmask_np () function returns the signal mask attribute of the thread attributes object @@ -50,7 +50,7 @@ as its result. The .BR pthread_attr_setsigmask_np () function returns 0 on success, or a nonzero error number on failure. -.PP +.P the .BR pthread_attr_getsigmask_np () function returns either 0 or @@ -61,7 +61,7 @@ A return value of .B PTHREAD_ATTR_NO_SIGMASK_NP indicates that the signal mask attribute is not set in .IR attr . -.PP +.P On error, these functions return a positive error number. .SH ERRORS .TP @@ -83,7 +83,6 @@ T{ .BR pthread_attr_getsigmask_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in the names. @@ -96,13 +95,13 @@ a thread created using the thread attributes object If this attribute is not set, then a thread created using .I attr will inherit a copy of the creating thread's signal mask. -.PP +.P For more details on signal masks, see .BR sigprocmask (2). For a description of a set of macros that can be used to manipulate and inspect signal sets, see .BR sigsetops (3). -.PP +.P In the absence of .BR pthread_attr_setsigmask_np () it is possible to create a thread with a desired signal mask as follows: @@ -119,7 +118,7 @@ The new thread sets its signal mask to the desired value using .BR pthread_sigmask (3). .IP \[bu] The creating thread restores its signal mask to the original value. -.PP +.P Following the above steps, there is no possibility for the new thread to receive a signal before it has adjusted its signal mask to the desired value. diff --git a/man3/pthread_attr_setstack.3 b/man3/pthread_attr_setstack.3 index 78c2ff4..1cf976b 100644 --- a/man3/pthread_attr_setstack.3 +++ b/man3/pthread_attr_setstack.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setstack 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setstack 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setstack, pthread_attr_getstack \- set/get stack attributes in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setstack(pthread_attr_t *" attr , .BI " void " stackaddr [. stacksize ], .BI " size_t " stacksize ); @@ -22,12 +22,12 @@ POSIX threads library .BI " void **restrict " stackaddr , .BI " size_t *restrict " stacksize ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_attr_getstack (), .BR pthread_attr_setstack (): .nf @@ -47,13 +47,13 @@ respectively. These attributes specify the location and size of the stack that should be used by a thread that is created using the thread attributes object .IR attr . -.PP +.P .I stackaddr should point to the lowest addressable byte of a buffer of .I stacksize bytes that was allocated by the caller. The pages of the allocated buffer should be both readable and writable. -.PP +.P The .BR pthread_attr_getstack () function returns the stack address and stack size attributes of the @@ -81,7 +81,7 @@ On some systems, this error may also occur if or .I stackaddr\~+\~stacksize is not suitably aligned. -.PP +.P POSIX.1 also documents an .B EACCES error if the stack area described by @@ -104,7 +104,6 @@ T{ .BR pthread_attr_getstack () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -118,7 +117,7 @@ and the use of these functions should be avoided. (Use .BR pthread_attr_setstacksize (3) if an application simply requires a stack size other than the default.) -.PP +.P When an application employs .BR pthread_attr_setstack (), it takes over the responsibility of allocating the stack. @@ -129,7 +128,7 @@ If deemed necessary, it is the application's responsibility to allocate a guard area (one or more pages protected against reading and writing) to handle the possibility of stack overflow. -.PP +.P The address specified in .I stackaddr should be suitably aligned: @@ -140,7 +139,7 @@ may be useful for allocation. Probably, .I stacksize should also be a multiple of the system page size. -.PP +.P If .I attr is used to create multiple threads, then the caller must change the diff --git a/man3/pthread_attr_setstackaddr.3 b/man3/pthread_attr_setstackaddr.3 index 9ec2e9a..7e9c2cc 100644 --- a/man3/pthread_attr_setstackaddr.3 +++ b/man3/pthread_attr_setstackaddr.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setstackaddr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setstackaddr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setstackaddr, pthread_attr_getstackaddr \- set/get stack address attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .B [[deprecated]] .BI "int pthread_attr_setstackaddr(pthread_attr_t *" attr \ ", void *" stackaddr ); @@ -30,7 +30,7 @@ Use and .BR pthread_attr_getstack (3) instead. -.PP +.P The .BR pthread_attr_setstackaddr () function sets the stack address attribute of the @@ -41,13 +41,13 @@ to the value specified in This attribute specifies the location of the stack that should be used by a thread that is created using the thread attributes object .IR attr . -.PP +.P .I stackaddr should point to a buffer of at least .B PTHREAD_STACK_MIN bytes that was allocated by the caller. The pages of the allocated buffer should be both readable and writable. -.PP +.P The .BR pthread_attr_getstackaddr () function returns the stack address attribute of the @@ -77,7 +77,6 @@ T{ .BR pthread_attr_getstackaddr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/pthread_attr_setstacksize.3 b/man3/pthread_attr_setstacksize.3 index 278346e..466a6ee 100644 --- a/man3/pthread_attr_setstacksize.3 +++ b/man3/pthread_attr_setstacksize.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_attr_setstacksize 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_attr_setstacksize 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_attr_setstacksize, pthread_attr_getstacksize \- set/get stack size attribute in thread attributes object @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_attr_setstacksize(pthread_attr_t *" attr \ ", size_t " stacksize ); .BI "int pthread_attr_getstacksize(const pthread_attr_t *restrict " attr , @@ -28,11 +28,11 @@ thread attributes object referred to by .I attr to the value specified in .IR stacksize . -.PP +.P The stack size attribute determines the minimum size (in bytes) that will be allocated for threads created using the thread attributes object .IR attr . -.PP +.P The .BR pthread_attr_getstacksize () function returns the stack size attribute of the @@ -51,7 +51,7 @@ can fail with the following error: The stack size is less than .B PTHREAD_STACK_MIN (16384) bytes. -.PP +.P On some systems, .\" e.g., MacOS .BR pthread_attr_setstacksize () @@ -75,7 +75,6 @@ T{ .BR pthread_attr_getstacksize () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS These functions are provided since glibc 2.1. .SH STANDARDS @@ -83,10 +82,10 @@ POSIX.1-2001, POSIX.1-2008. .SH NOTES For details on the default stack size of new threads, see .BR pthread_create (3). -.PP +.P A thread's stack size is fixed at the time of thread creation. Only the main thread can dynamically grow its stack. -.PP +.P The .BR pthread_attr_setstack (3) function allows an application to set both the size and location diff --git a/man3/pthread_cancel.3 b/man3/pthread_cancel.3 index 8230c80..c1a160b 100644 --- a/man3/pthread_cancel.3 +++ b/man3/pthread_cancel.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_cancel 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_cancel 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_cancel \- send a cancelation request to a thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_cancel(pthread_t " thread ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ its cancelability .I state and .IR type . -.PP +.P A thread's cancelability state, determined by .BR pthread_setcancelstate (3), can be @@ -40,7 +40,7 @@ then a cancelation request remains queued until the thread enables cancelation. If a thread has enabled cancelation, then its cancelability type determines when cancelation occurs. -.PP +.P A thread's cancelation type, determined by .BR pthread_setcanceltype (3), may be either @@ -56,7 +56,7 @@ the thread next calls a function that is a .IR "cancelation point" . A list of functions that are or may be cancelation points is provided in .BR pthreads (7). -.PP +.P When a cancelation requested is acted on, the following steps occur for .I thread (in this order): @@ -74,7 +74,7 @@ in an unspecified order. The thread is terminated. (See .BR pthread_exit (3).) -.PP +.P The above steps happen asynchronously with respect to the .BR pthread_cancel () call; @@ -82,7 +82,7 @@ the return status of .BR pthread_cancel () merely informs the caller whether the cancelation request was successfully queued. -.PP +.P After a canceled thread has terminated, a join with that thread using .BR pthread_join (3) @@ -116,7 +116,6 @@ T{ .BR pthread_cancel () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On Linux, cancelation is implemented using signals. Under the NPTL threading implementation, @@ -136,7 +135,7 @@ The main thread joins with the canceled thread to check that its exit status was .BR PTHREAD_CANCELED . The following shell session shows what happens when we run the program: -.PP +.P .in +4n .EX $ ./a.out diff --git a/man3/pthread_cleanup_push.3 b/man3/pthread_cleanup_push.3 index 9fcccb3..eec8c8e 100644 --- a/man3/pthread_cleanup_push.3 +++ b/man3/pthread_cleanup_push.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_cleanup_push 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_cleanup_push 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_cleanup_push, pthread_cleanup_pop \- push and pop thread cancelation clean-up handlers @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void pthread_cleanup_push(void (*" routine ")(void *), void *" arg ); .BI "void pthread_cleanup_pop(int " execute ); .fi @@ -26,7 +26,7 @@ when a thread is canceled (or in various other circumstances described below); it might, for example, unlock a mutex so that it becomes available to other threads in the process. -.PP +.P The .BR pthread_cleanup_push () function pushes @@ -37,14 +37,14 @@ When is later invoked, it will be given .I arg as its argument. -.PP +.P The .BR pthread_cleanup_pop () function removes the routine at the top of the stack of clean-up handlers, and optionally executes it if .I execute is nonzero. -.PP +.P A cancelation clean-up handler is popped from the stack and executed in the following circumstances: .IP \[bu] 3 @@ -67,7 +67,7 @@ When a thread calls with a nonzero .I execute argument, the top-most clean-up handler is popped and executed. -.PP +.P POSIX.1 permits .BR pthread_cleanup_push () and @@ -79,7 +79,7 @@ functions are paired within the same function, and at the same lexical nesting level. (In other words, a clean-up handler is established only during the execution of a specified section of code.) -.PP +.P Calling .BR longjmp (3) .RB ( siglongjmp (3)) @@ -118,7 +118,6 @@ T{ .BR pthread_cleanup_pop () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On glibc, the .BR pthread_cleanup_push () @@ -130,7 +129,7 @@ implemented as macros that expand to text containing \[aq]\fB{\fP\[aq] and \[aq]\fB}\fP\[aq], respectively. This means that variables declared within the scope of paired calls to these functions will be visible within only that scope. -.PP +.P POSIX.1 .\" The text was actually added in the 2004 TC2 says that the effect of using @@ -165,10 +164,10 @@ the main thread sends the other thread a cancelation request, or sets a global variable that causes the other thread to exit its loop and terminate normally (by doing a .IR return ). -.PP +.P In the following shell session, the main thread sends a cancelation request to the other thread: -.PP +.P .in +4n .EX $ \fB./a.out\fP @@ -180,16 +179,16 @@ Called clean\-up handler Thread was canceled; cnt = 0 .EE .in -.PP +.P From the above, we see that the thread was canceled, and that the cancelation clean-up handler was called and it reset the value of the global variable .I cnt to 0. -.PP +.P In the next run, the main program sets a global variable that causes other thread to terminate normally: -.PP +.P .in +4n .EX $ \fB./a.out x\fP @@ -199,18 +198,18 @@ cnt = 1 Thread terminated normally; cnt = 2 .EE .in -.PP +.P From the above, we see that the clean-up handler was not executed (because .I cleanup_pop_arg was 0), and therefore the value of .I cnt was not reset. -.PP +.P In the next run, the main program sets a global variable that causes the other thread to terminate normally, and supplies a nonzero value for .IR cleanup_pop_arg : -.PP +.P .in +4n .EX $ \fB./a.out x 1\fP @@ -221,7 +220,7 @@ Called clean\-up handler Thread terminated normally; cnt = 0 .EE .in -.PP +.P In the above, we see that although the thread was not canceled, the clean-up handler was executed, because the argument given to .BR pthread_cleanup_pop () diff --git a/man3/pthread_cleanup_push_defer_np.3 b/man3/pthread_cleanup_push_defer_np.3 index d72b3d2..ca0e3d4 100644 --- a/man3/pthread_cleanup_push_defer_np.3 +++ b/man3/pthread_cleanup_push_defer_np.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_cleanup_push_defer_np 3 2023-05-03 "Linux man-pages 6.05.01" +.TH pthread_cleanup_push_defer_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_cleanup_push_defer_np, pthread_cleanup_pop_restore_np \- push and pop thread cancelation clean-up handlers while saving cancelability type @@ -13,16 +13,16 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void pthread_cleanup_push_defer_np(void (*" routine ")(void *), void *" arg ); .BI "void pthread_cleanup_pop_restore_np(int " execute ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_cleanup_push_defer_np (), .BR pthread_cleanup_pop_defer_np (): .nf @@ -34,7 +34,7 @@ These functions are the same as and .BR pthread_cleanup_pop (3), except for the differences noted on this page. -.PP +.P Like .BR pthread_cleanup_push (3), .BR pthread_cleanup_push_defer_np () @@ -47,7 +47,7 @@ and sets the cancelability type to "deferred" (see this ensures that cancelation clean-up will occur even if the thread's cancelability type was "asynchronous" before the call. -.PP +.P Like .BR pthread_cleanup_pop (3), .BR pthread_cleanup_pop_restore_np () @@ -56,24 +56,24 @@ stack of cancelation clean-up handlers. In addition, it restores the thread's cancelability type to its value at the time of the matching .BR pthread_cleanup_push_defer_np (). -.PP +.P The caller must ensure that calls to these functions are paired within the same function, and at the same lexical nesting level. Other restrictions apply, as described in .BR pthread_cleanup_push (3). -.PP +.P This sequence of calls: -.PP +.P .in +4n .EX pthread_cleanup_push_defer_np(routine, arg); pthread_cleanup_pop_restore_np(execute); .EE .in -.PP +.P is equivalent to (but shorter and more efficient than): -.PP +.P .\" As far as I can see, LinuxThreads reverses the two substeps .\" in the push and pop below. .in +4n diff --git a/man3/pthread_cond_init.3 b/man3/pthread_cond_init.3 new file mode 100644 index 0000000..7fff419 --- /dev/null +++ b/man3/pthread_cond_init.3 @@ -0,0 +1,264 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_cond_init 3 2024-02-26 "Linux man-pages 6.7" +. +. +.SH NAME +pthread_cond_init, +pthread_cond_signal, +pthread_cond_broadcast, +pthread_cond_wait, +pthread_cond_timedwait, +pthread_cond_destroy +\- +operations on conditions +. +. +.SH SYNOPSIS +.B #include +.P +.BI "pthread_cond_t " cond " = PTHREAD_COND_INITIALIZER;" +.P +.BI "int pthread_cond_init(pthread_cond_t *" cond ", pthread_condattr_t *" cond_attr ");" +.BI "int pthread_cond_signal(pthread_cond_t *" cond ");" +.BI "int pthread_cond_broadcast(pthread_cond_t *" cond ");" +.BI "int pthread_cond_wait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ");" +.BI "int pthread_cond_timedwait(pthread_cond_t *" cond ", pthread_mutex_t *" mutex ", const struct timespec *" abstime ");" +.BI "int pthread_cond_destroy(pthread_cond_t *" cond ");" +. +. +.SH DESCRIPTION +A condition (short for ``condition variable'') +is a synchronization device that allows threads +to suspend execution and relinquish the processors +until some predicate on shared data is satisfied. +The basic operations on conditions are: +signal the condition (when the predicate becomes true), +and wait for the condition, +suspending the thread execution until another thread signals the condition. +.P +A condition variable must always be associated with a mutex, +to avoid the race condition where +a thread prepares to wait on a condition variable +and another thread signals the condition +just before the first thread actually waits on it. +.P +\fBpthread_cond_init\fP initializes the condition variable \fIcond\fP, +using the condition attributes specified in \fIcond_attr\fP, +or default attributes if \fIcond_attr\fP is \fBNULL\fP. +The LinuxThreads implementation supports no attributes for conditions, +hence the \fIcond_attr\fP parameter is actually ignored. +.P +Variables of type \fBpthread_cond_t\fP can also be initialized statically, +using the constant \fBPTHREAD_COND_INITIALIZER\fP. +.P +\fBpthread_cond_signal\fP restarts one of the threads that +are waiting on the condition variable \fIcond\fP. +If no threads are waiting on \fIcond\fP, +nothing happens. +If several threads are waiting on \fIcond\fP, +exactly one is restarted, +but it is not specified which. +.P +\fBpthread_cond_broadcast\fP restarts all the threads that +are waiting on the condition variable \fIcond\fP. +Nothing happens if no threads are waiting on \fIcond\fP. +.P +\fBpthread_cond_wait\fP atomically unlocks the \fImutex\fP +(as per \fBpthread_unlock_mutex\fP) +and waits for the condition variable \fIcond\fP to be signaled. +The thread execution is suspended and does not consume any CPU time +until the condition variable is signaled. +The \fImutex\fP must be locked by the calling thread +on entrance to \fBpthread_cond_wait\fP. +Before returning to the calling thread, +\fBpthread_cond_wait\fP re-acquires \fImutex\fP +(as per \fBpthread_lock_mutex\fP). +.P +Unlocking the mutex and suspending on the condition variable is done atomically. +Thus, +if all threads always acquire the mutex before signaling the condition, +this guarantees that the condition cannot be signaled (and thus ignored) +between the time a thread locks the mutex +and the time it waits on the condition variable. +.P +\fBpthread_cond_timedwait\fP atomically unlocks \fImutex\fP +and waits on \fIcond\fP, +as \fBpthread_cond_wait\fP does, +but it also bounds the duration of the wait. +If \fIcond\fP has not been signaled +within the amount of time specified by \fIabstime\fP, +the mutex \fImutex\fP is re-acquired +and \fBpthread_cond_timedwait\fP returns the error \fBETIMEDOUT\fP. +The \fIabstime\fP parameter specifies an absolute time, +with the same origin as \fBtime\fP(2) and \fBgettimeofday\fP(2): +an \fIabstime\fP of 0 +corresponds to 00:00:00 GMT, January 1, 1970. +.P +\fBpthread_cond_destroy\fP destroys a condition variable, +freeing the resources it might hold. +No threads must be waiting on the condition variable +on entrance to \fBpthread_cond_destroy\fP. +In the LinuxThreads implementation, +no resources are associated with condition variables, +thus \fBpthread_cond_destroy\fP actually does nothing +except checking that the condition has no waiting threads. +. +. +.SH CANCELLATION +\fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP +are cancelation points. +If a thread is cancelled while suspended in one of these functions, +the thread immediately resumes execution, +then locks again the \fImutex\fP +argument to \fBpthread_cond_wait\fP and \fBpthread_cond_timedwait\fP, +and finally executes the cancelation. +Consequently, +cleanup handlers are assured that \fImutex\fP is locked +when they are called. +. +. +.SH "ASYNC-SIGNAL SAFETY" +The condition functions are not async-signal safe, +and should not be called from a signal handler. +In particular, +calling \fBpthread_cond_signal\fP or \fBpthread_cond_broadcast\fP +from a signal handler +may deadlock the calling thread. +. +. +.SH "RETURN VALUE" +All condition variable functions return 0 on success +and a non-zero error code on error. +. +. +.SH ERRORS +\fBpthread_cond_init\fP, +\fBpthread_cond_signal\fP, +\fBpthread_cond_broadcast\fP, +and \fBpthread_cond_wait\fP +never return an error code. +.P +The \fBpthread_cond_timedwait\fP function returns +the following error codes on error: +.RS +.TP +\fBETIMEDOUT\fP +The condition variable was not signaled +until the timeout specified by \fIabstime\fP. +.TP +\fBEINTR\fP +\fBpthread_cond_timedwait\fP was interrupted by a signal. +.RE +.P +The \fBpthread_cond_destroy\fP function returns +the following error code on error: +.RS +.TP +\fBEBUSY\fP +Some threads are currently waiting on \fIcond\fP. +.RE +. +. +.SH "SEE ALSO" +\fBpthread_condattr_init\fP(3), +\fBpthread_mutex_lock\fP(3), +\fBpthread_mutex_unlock\fP(3), +\fBgettimeofday\fP(2), +\fBnanosleep\fP(2). +. +. +.SH EXAMPLE +Consider two shared variables \fIx\fP and \fIy\fP, +protected by the mutex \fImut\fP, +and a condition variable \fIcond\fP +that is to be signaled +whenever \fIx\fP becomes greater than \fIy\fP. +.P +.RS +.ft 3 +.nf +.sp +int x,y; +pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; +pthread_cond_t cond = PTHREAD_COND_INITIALIZER; +.ft +.P +.RE +.fi +.P +Waiting until \fIx\fP is greater than \fIy\fP is performed as follows: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +while (x <= y) { + pthread_cond_wait(&cond, &mut); +} +/* operate on x and y */ +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi +.P +Modifications on \fIx\fP and \fIy\fP +that may cause \fIx\fP to become greater than \fIy\fP +should signal the condition if needed: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +/* modify x and y */ +if (x > y) pthread_cond_broadcast(&cond); +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi +.P +If it can be proved that at most one waiting thread needs to be waken up +(for instance, +if there are only two threads communicating through \fIx\fP and \fIy\fP), +\fBpthread_cond_signal\fP can be used as +a slightly more efficient alternative to \fBpthread_cond_broadcast\fP. +In doubt, +use \fBpthread_cond_broadcast\fP. +.P +To wait for \fIx\fP to become greater than \fIy\fP +with a timeout of 5 seconds, +do: +.P +.RS +.ft 3 +.nf +.sp +struct timeval now; +struct timespec timeout; +int retcode; +\& +pthread_mutex_lock(&mut); +gettimeofday(&now); +timeout.tv_sec = now.tv_sec + 5; +timeout.tv_nsec = now.tv_usec * 1000; +retcode = 0; +while (x <= y && retcode != ETIMEDOUT) { + retcode = pthread_cond_timedwait(&cond, &mut, &timeout); +} +if (retcode == ETIMEDOUT) { + /* timeout occurred */ +} else { + /* operate on x and y */ +} +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi diff --git a/man3/pthread_condattr_init.3 b/man3/pthread_condattr_init.3 new file mode 100644 index 0000000..bed354c --- /dev/null +++ b/man3/pthread_condattr_init.3 @@ -0,0 +1,48 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_condattr_init 3 2023-10-31 "Linux man-pages 6.7" +. +. +.SH NAME +pthread_condattr_init, +pthread_condattr_destroy +\- +condition creation attributes +. +. +.SH SYNOPSIS +.B #include +.P +.BI "int pthread_condattr_init(pthread_condattr_t *" attr ");" +.BI "int pthread_condattr_destroy(pthread_condattr_t *" attr ");" +. +. +.SH DESCRIPTION +Condition attributes can be specified at condition creation time, +by passing a condition attribute object +as second argument to \fBpthread_cond_init\fP(3). +Passing \fBNULL\fP is equivalent to +passing a condition attribute object +with all attributes set to their default values. +.P +The LinuxThreads implementation supports no attributes for conditions. +The functions on condition attributes are +included only for compliance with the POSIX standard. +.P +\fBpthread_condattr_init\fP +initializes the condition attribute object \fIattr\fP +and fills it with default values for the attributes. +\fBpthread_condattr_destroy\fP destroys a condition attribute object, +which must not be reused until it is reinitialized. +Both functions do nothing in the LinuxThreads implementation. +. +. +.SH "RETURN VALUE" +\fBpthread_condattr_init\fP and \fBpthread_condattr_destroy\fP always return 0. +. +. +.SH "SEE ALSO" +\fBpthread_cond_init\fP(3). diff --git a/man3/pthread_create.3 b/man3/pthread_create.3 index 268bfa0..beba117 100644 --- a/man3/pthread_create.3 +++ b/man3/pthread_create.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_create 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_create 3 2024-02-12 "Linux man-pages 6.7" .SH NAME pthread_create \- create a new thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_create(pthread_t *restrict " thread , .BI " const pthread_attr_t *restrict " attr , .BI " void *(*" start_routine ")(void *)," @@ -28,7 +28,7 @@ The new thread starts execution by invoking .I arg is passed as the sole argument of .IR start_routine (). -.PP +.P The new thread terminates in one of the following ways: .IP \[bu] 3 It calls @@ -53,7 +53,7 @@ Any of the threads in the process calls or the main thread performs a return from .IR main (). This causes the termination of all threads in the process. -.PP +.P The .I attr argument points to a @@ -67,14 +67,14 @@ If .I attr is NULL, then the thread is created with default attributes. -.PP +.P Before returning, a successful call to .BR pthread_create () stores the ID of the new thread in the buffer pointed to by .IR thread ; this identifier is used to refer to the thread in subsequent calls to other pthreads functions. -.PP +.P The new thread inherits a copy of the creating thread's signal mask .RB ( pthread_sigmask (3)). The set of pending signals for the new thread is empty @@ -82,10 +82,10 @@ The set of pending signals for the new thread is empty The new thread does not inherit the creating thread's alternate signal stack .RB ( sigaltstack (2)). -.PP +.P The new thread inherits the calling thread's floating-point environment .RB ( fenv (3)). -.PP +.P The initial value of the new thread's CPU-time clock is 0 (see .BR pthread_getcpuclockid (3)). @@ -148,7 +148,6 @@ T{ .BR pthread_create () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -165,7 +164,7 @@ after a call to .BR pthread_create (), it is indeterminate which thread\[em]the caller or the new thread\[em]will next execute. -.PP +.P A thread may either be .I joinable or @@ -185,7 +184,7 @@ By default, a new thread is created in a joinable state, unless .I attr was set to create the thread in a detached state (using .BR pthread_attr_setdetachstate (3)). -.PP +.P Under the NPTL threading implementation, if the .B RLIMIT_STACK soft resource limit @@ -201,23 +200,8 @@ in order to obtain a stack size other than the default. If the .B RLIMIT_STACK resource limit is set to "unlimited", -a per-architecture value is used for the stack size. -Here is the value for a few architectures: -.RS -.TS -allbox; -lb lb -l r. -Architecture Default stack size -i386 2 MB -IA-64 32 MB -PowerPC 4 MB -S/390 2 MB -Sparc-32 2 MB -Sparc-64 4 MB -x86_64 2 MB -.TE -.RE +a per-architecture value is used for the stack size: +2 MB on most architectures; 4 MB on POWER and Sparc-64. .SH BUGS In the obsolete LinuxThreads implementation, each of the threads in a process has a different process ID. @@ -228,12 +212,12 @@ and is the source of many other nonconformances to the standard; see The program below demonstrates the use of .BR pthread_create (), as well as a number of other functions in the pthreads API. -.PP +.P In the following run, on a system providing the NPTL threading implementation, the stack size defaults to the value given by the "stack size" resource limit: -.PP +.P .in +4n .EX .RB "$" " ulimit \-s" @@ -247,11 +231,11 @@ Joined with thread 2; returned value was SALUT Joined with thread 3; returned value was SERVUS .EE .in -.PP +.P In the next run, the program explicitly sets a stack size of 1\ MB (using .BR pthread_attr_setstacksize (3)) for the created threads: -.PP +.P .in +4n .EX .RB "$" " ./a.out \-s 0x100000 hola salut servus" diff --git a/man3/pthread_detach.3 b/man3/pthread_detach.3 index aba9f05..25b588a 100644 --- a/man3/pthread_detach.3 +++ b/man3/pthread_detach.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_detach 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_detach 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_detach \- detach a thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_detach(pthread_t " thread ); .fi .SH DESCRIPTION @@ -25,7 +25,7 @@ as detached. When a detached thread terminates, its resources are automatically released back to the system without the need for another thread to join with the terminated thread. -.PP +.P Attempting to detach an already detached thread results in unspecified behavior. .SH RETURN VALUE @@ -57,7 +57,6 @@ T{ .BR pthread_detach () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -66,21 +65,21 @@ POSIX.1-2001. Once a thread has been detached, it can't be joined with .BR pthread_join (3) or be made joinable again. -.PP +.P A new thread can be created in a detached state using .BR pthread_attr_setdetachstate (3) to set the detached attribute of the .I attr argument of .BR pthread_create (3). -.PP +.P The detached attribute merely determines the behavior of the system when the thread terminates; it does not prevent the thread from being terminated if the process terminates using .BR exit (3) (or equivalently, if the main thread returns). -.PP +.P Either .BR pthread_join (3) or @@ -91,7 +90,7 @@ so that system resources for the thread can be released. actions has not been done will be freed when the process terminates.) .SH EXAMPLES The following statement detaches the calling thread: -.PP +.P .in +4n .EX pthread_detach(pthread_self()); diff --git a/man3/pthread_equal.3 b/man3/pthread_equal.3 index 976e273..5046d8e 100644 --- a/man3/pthread_equal.3 +++ b/man3/pthread_equal.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_equal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_equal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_equal \- compare thread IDs .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_equal(pthread_t " t1 ", pthread_t " t2 ); .fi .SH DESCRIPTION @@ -40,7 +40,6 @@ T{ .BR pthread_equal () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_exit.3 b/man3/pthread_exit.3 index 4f317a9..edd6f90 100644 --- a/man3/pthread_exit.3 +++ b/man3/pthread_exit.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_exit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_exit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_exit \- terminate calling thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[noreturn]] void pthread_exit(void *" retval ); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ function terminates the calling thread and returns a value via that (if the thread is joinable) is available to another thread in the same process that calls .BR pthread_join (3). -.PP +.P Any clean-up handlers established by .BR pthread_cleanup_push (3) that have not yet been popped, @@ -34,14 +34,14 @@ If the thread has any thread-specific data, then, after the clean-up handlers have been executed, the corresponding destructor functions are called, in an unspecified order. -.PP +.P When a thread terminates, process-shared resources (e.g., mutexes, condition variables, semaphores, and file descriptors) are not released, and functions registered using .BR atexit (3) are not called. -.PP +.P After the last thread in a process terminates, the process terminates as by calling .BR exit (3) @@ -68,7 +68,6 @@ T{ .BR pthread_exit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -78,13 +77,13 @@ Performing a return from the start function of any thread other than the main thread results in an implicit call to .BR pthread_exit (), using the function's return value as the thread's exit status. -.PP +.P To allow other threads to continue execution, the main thread should terminate by calling .BR pthread_exit () rather than .BR exit (3). -.PP +.P The value pointed to by .I retval should not be located on the calling thread's stack, diff --git a/man3/pthread_getattr_default_np.3 b/man3/pthread_getattr_default_np.3 index a88961a..ac8ee10 100644 --- a/man3/pthread_getattr_default_np.3 +++ b/man3/pthread_getattr_default_np.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_getattr_default_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_getattr_default_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_getattr_default_np, pthread_setattr_default_np, \- get or set default thread-creation attributes @@ -14,7 +14,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_getattr_default_np(pthread_attr_t *" attr ); .BI "int pthread_setattr_default_np(const pthread_attr_t *" attr ); .fi @@ -39,7 +39,7 @@ attribute must not be set in the object. Setting the .I stack size attribute to zero means leave the default stack size unchanged. -.PP +.P The .BR pthread_getattr_default_np () function initializes the thread attributes object referred to by @@ -73,7 +73,6 @@ T{ .BR pthread_setattr_default_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in their names. @@ -85,7 +84,7 @@ The program below uses to fetch the default thread-creation attributes and then displays various settings from the returned thread attributes object. When running the program, we see the following output: -.PP +.P .in +4n .EX $ \fB./a.out\fP @@ -122,12 +121,12 @@ display_pthread_attr(pthread_attr_t *attr) s = pthread_attr_getstacksize(attr, &stacksize); if (s != 0) errc(EXIT_FAILURE, s, "pthread_attr_getstacksize"); - printf("Stack size: %zd\en", stacksize); + printf("Stack size: %zu\en", stacksize); \& s = pthread_attr_getguardsize(attr, &guardsize); if (s != 0) errc(EXIT_FAILURE, s, "pthread_attr_getguardsize"); - printf("Guard size: %zd\en", guardsize); + printf("Guard size: %zu\en", guardsize); \& s = pthread_attr_getschedpolicy(attr, &policy); if (s != 0) diff --git a/man3/pthread_getattr_np.3 b/man3/pthread_getattr_np.3 index be1fb19..02a621f 100644 --- a/man3/pthread_getattr_np.3 +++ b/man3/pthread_getattr_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_getattr_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_getattr_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_getattr_np \- get attributes of created thread .SH LIBRARY @@ -14,7 +14,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_getattr_np(pthread_t " thread ", pthread_attr_t *" attr ); .fi .SH DESCRIPTION @@ -24,7 +24,7 @@ function initializes the thread attributes object referred to by .I attr so that it contains actual attribute values describing the running thread .IR thread . -.PP +.P The returned attribute values may differ from the corresponding attribute values passed in the .I attr @@ -42,12 +42,12 @@ and the guard size, which the implementation may round upward to a multiple of the page size, or ignore (i.e., treat as 0), if the application is allocating its own stack. -.PP +.P Furthermore, if the stack address attribute was not set in the thread attributes object used to create the thread, then the returned thread attributes object will report the actual stack address that the implementation selected for the thread. -.PP +.P When the thread attributes object returned by .BR pthread_getattr_np () is no longer required, it should be destroyed using @@ -60,7 +60,7 @@ on error, it returns a nonzero error number. .B ENOMEM .\" Can happen (but unlikely) while trying to allocate memory for cpuset Insufficient memory. -.PP +.P In addition, if .I thread refers to the main thread, then @@ -89,7 +89,6 @@ T{ .BR pthread_getattr_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in the name. @@ -105,10 +104,10 @@ and stack size attributes. Command-line arguments can be used to set these attributes to values other than the default when creating the thread. The shell sessions below demonstrate the use of the program. -.PP +.P In the first run, on an x86-32 system, a thread is created using default attributes: -.PP +.P .in +4n .EX .RB "$" " ulimit \-s" " # No stack limit ==> default stack size is 2 MB" @@ -120,11 +119,11 @@ Attributes of created thread: Stack size = 0x201000 (2101248) bytes .EE .in -.PP +.P In the following run, we see that if a guard size is specified, it is rounded up to the next multiple of the system page size (4096 bytes on x86-32): -.PP +.P .in +4n .EX .RB "$" " ./a.out \-g 4097" @@ -153,10 +152,10 @@ Attributes of created thread: .\" Stack size = 0x8000 (32768) bytes .\".fi .\".in -.PP +.P In the last run, the program manually allocates a stack for the thread. In this case, the guard size attribute is ignored. -.PP +.P .in +4n .EX .RB "$" " ./a.out \-g 4096 \-s 0x8000 \-a" @@ -273,7 +272,7 @@ get_thread_attributes_from_cl(int argc, char *argv[], if (argc > optind) usage(argv[0], "Extraneous command\-line arguments\en"); \& - if (stack_size >= 0 || guard_size > 0) { + if (stack_size != -1 || guard_size > 0) { ret_attrp = attrp; \& s = pthread_attr_init(attrp); @@ -281,7 +280,7 @@ get_thread_attributes_from_cl(int argc, char *argv[], errc(EXIT_FAILURE, s, "pthread_attr_init"); } \& - if (stack_size >= 0) { + if (stack_size != -1) { if (!allocate_stack) { s = pthread_attr_setstacksize(attrp, stack_size); if (s != 0) @@ -299,7 +298,7 @@ get_thread_attributes_from_cl(int argc, char *argv[], } } \& - if (guard_size >= 0) { + if (guard_size != -1) { s = pthread_attr_setguardsize(attrp, guard_size); if (s != 0) errc(EXIT_FAILURE, s, "pthread_attr_setstacksize"); diff --git a/man3/pthread_getcpuclockid.3 b/man3/pthread_getcpuclockid.3 index 127d662..872134c 100644 --- a/man3/pthread_getcpuclockid.3 +++ b/man3/pthread_getcpuclockid.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_getcpuclockid 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_getcpuclockid 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_getcpuclockid \- retrieve ID of a thread's CPU time clock .SH LIBRARY @@ -14,7 +14,7 @@ POSIX threads library .nf .B #include .B #include -.PP +.P .BI "int pthread_getcpuclockid(pthread_t " thread ", clockid_t *" clockid ); .fi .SH DESCRIPTION @@ -59,7 +59,6 @@ T{ .BR pthread_getcpuclockid () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -82,7 +81,7 @@ The program below creates a thread and then uses to retrieve the total process CPU time, and the per-thread CPU time consumed by the two threads. The following shell session shows an example run: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man3/pthread_join.3 b/man3/pthread_join.3 index 9284d85..f063a79 100644 --- a/man3/pthread_join.3 +++ b/man3/pthread_join.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_join 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_join 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_join \- join with a terminated thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_join(pthread_t " thread ", void **" retval ); .fi .SH DESCRIPTION @@ -28,7 +28,7 @@ returns immediately. The thread specified by .I thread must be joinable. -.PP +.P If .I retval is not NULL, then @@ -42,7 +42,7 @@ If the target thread was canceled, then .B PTHREAD_CANCELED is placed in the location pointed to by .IR retval . -.PP +.P If multiple threads simultaneously try to join with the same thread, the results are undefined. If the thread calling @@ -91,7 +91,6 @@ T{ .BR pthread_join () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -103,10 +102,10 @@ the caller is guaranteed that the target thread has terminated. The caller may then choose to do any clean-up that is required after termination of the thread (e.g., freeing memory or other resources that were allocated to the target thread). -.PP +.P Joining with a thread that has previously been joined results in undefined behavior. -.PP +.P Failure to join with a thread that is joinable (i.e., one that is not detached), produces a "zombie thread". @@ -114,13 +113,13 @@ Avoid doing this, since each zombie thread consumes some system resources, and when enough zombie threads have accumulated, it will no longer be possible to create new threads (or processes). -.PP +.P There is no pthreads analog of .IR "waitpid(\-1,\ &status,\ 0)" , that is, "join with any terminated thread". If you believe you need this functionality, you probably need to rethink your application design. -.PP +.P All of the threads in a process are peers: any thread can join with any other thread in the process. .SH EXAMPLES diff --git a/man3/pthread_key_create.3 b/man3/pthread_key_create.3 new file mode 100644 index 0000000..1e7d680 --- /dev/null +++ b/man3/pthread_key_create.3 @@ -0,0 +1,178 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_key_create 3 2024-02-26 "Linux man-pages 6.7" +. +. +.SH NAME +pthread_key_create, +pthread_key_delete, +pthread_setspecific, +pthread_getspecific +\- +management of thread-specific data +. +. +.SH SYNOPSIS +.B #include +.P +.BI "int pthread_key_create(pthread_key_t *" key ", void (*" destr_function ") (void *));" +.BI "int pthread_key_delete(pthread_key_t " key ");" +.BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ");" +.BI "void * pthread_getspecific(pthread_key_t " key ");" +. +. +.SH DESCRIPTION +Programs often need global or static variables +that have different values in different threads. +Since threads share one memory space, +this cannot be achieved with regular variables. +Thread-specific data is the POSIX threads answer to this need. +.P +Each thread possesses a private memory block, +the thread-specific data area, +or TSD area for short. +This area is indexed by TSD keys. +The TSD area associates values of type \fBvoid *\fP to TSD keys. +TSD keys are common to all threads, +but the value associated with a given TSD key +can be different in each thread. +.P +For concreteness, +the TSD areas can be viewed as arrays of \fBvoid *\fP pointers, +TSD keys as integer indices into these arrays, +and the value of a TSD key +as the value of the corresponding array element in the calling thread. +.P +When a thread is created, +its TSD area initially associates \fBNULL\fP with all keys. +.P +\fBpthread_key_create\fP allocates a new TSD key. +The key is stored in the location pointed to by \fIkey\fP. +There is a limit of \fBPTHREAD_KEYS_MAX\fP +on the number of keys allocated at a given time. +The value initially associated with the returned key +is \fBNULL\fP in all currently executing threads. +.P +The \fIdestr_function\fP argument, +if not \fBNULL\fP, +specifies a destructor function associated with the key. +When a thread terminates via \fBpthread_exit\fP or by cancelation, +\fIdestr_function\fP is called with arguments +the value associated with the key in that thread. +The \fIdestr_function\fP is not called if that value is \fBNULL\fP. +The order in which destructor functions are called at thread termination time +is unspecified. +.P +Before the destructor function is called, +the \fBNULL\fP value is associated with the key in the current thread. +A destructor function might, +however, +re-associate non-\fBNULL\fP values to that key or some other key. +To deal with this, +if after all the destructors have been called +for all non-\fBNULL\fP values, +there are still some non-\fBNULL\fP values with associated destructors, +then the process is repeated. +The glibc implementation stops the process +after \fBPTHREAD_DESTRUCTOR_ITERATIONS\fP iterations, +even if some non-\fBNULL\fP values with associated descriptors remain. +Other implementations may loop indefinitely. +.P +\fBpthread_key_delete\fP deallocates a TSD key. +It does not check +whether non-\fBNULL\fP values are associated with that key +in the currently executing threads, +nor call the destructor function associated with the key. +.P +\fBpthread_setspecific\fP changes the value +associated with \fIkey\fP in the calling thread, +storing the given \fIpointer\fP instead. +.P +\fBpthread_getspecific\fP returns the value +currently associated with \fIkey\fP in the calling thread. +. +. +.SH "RETURN VALUE" +\fBpthread_key_create\fP, +\fBpthread_key_delete\fP, +and \fBpthread_setspecific\fP +return 0 on success and a non-zero error code on failure. +If successful, +\fBpthread_key_create\fP stores the newly allocated key +in the location pointed to by its \fIkey\fP argument. +.P +\fBpthread_getspecific\fP returns +the value associated with \fIkey\fP on success, +and \fBNULL\fP on error. +. +. +.SH ERRORS +\fBpthread_key_create\fP returns the following error code on error: +.RS +.TP +\fBEAGAIN\fP +\fBPTHREAD_KEYS_MAX\fP keys are already allocated. +.RE +.P +\fBpthread_key_delete\fP and \fBpthread_setspecific\fP return +the following error code on error: +.RS +.TP +\fBEINVAL\fP +\fIkey\fP is not a valid, allocated TSD key. +.RE +.P +\fBpthread_getspecific\fP returns \fBNULL\fP if \fIkey\fP is not a valid, +allocated TSD key. +. +. +.SH "SEE ALSO" +pthread_create(3), pthread_exit(3), pthread_testcancel(3). +. +. +.SH EXAMPLE +The following code fragment +allocates a thread-specific array of 100 characters, +with automatic reclamation at thread exit: +.P +.RS +.ft 3 +.nf +.sp +/* Key for the thread-specific buffer */ +static pthread_key_t buffer_key; +\& +/* Once-only initialisation of the key */ +static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT; +\& +/* Allocate the thread-specific buffer */ +void buffer_alloc(void) +{ + pthread_once(&buffer_key_once, buffer_key_alloc); + pthread_setspecific(buffer_key, malloc(100)); +} +\& +/* Return the thread-specific buffer */ +char * get_buffer(void) +{ + return (char *) pthread_getspecific(buffer_key); +} +\& +/* Allocate the key */ +static void buffer_key_alloc() +{ + pthread_key_create(&buffer_key, buffer_destroy); +} +\& +/* Free the thread-specific buffer */ +static void buffer_destroy(void * buf) +{ + free(buf); +} +.ft +.P +.RE +.fi diff --git a/man3/pthread_kill.3 b/man3/pthread_kill.3 index 0501c4f..659b0db 100644 --- a/man3/pthread_kill.3 +++ b/man3/pthread_kill.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_kill 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_kill 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_kill \- send a signal to a thread .SH LIBRARY @@ -13,15 +13,15 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_kill(pthread_t " thread ", int " sig ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_kill (): .nf _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500 @@ -36,7 +36,7 @@ to a thread in the same process as the caller. The signal is asynchronously directed to .IR thread . -.PP +.P If .I sig is 0, then no signal is sent, but error checking is still performed. @@ -63,7 +63,6 @@ T{ .BR pthread_kill () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The glibc implementation of .BR pthread_kill () @@ -74,7 +73,7 @@ used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P POSIX.1-2008 recommends that if an implementation detects the use of a thread ID after the end of its lifetime, .BR pthread_kill () diff --git a/man3/pthread_kill_other_threads_np.3 b/man3/pthread_kill_other_threads_np.3 index aec544d..b924273 100644 --- a/man3/pthread_kill_other_threads_np.3 +++ b/man3/pthread_kill_other_threads_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_kill_other_threads_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_kill_other_threads_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_kill_other_threads_np \- terminate all other threads in process .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .B void pthread_kill_other_threads_np(void); .fi .SH DESCRIPTION @@ -40,7 +40,6 @@ T{ .BR pthread_kill_other_threads_np () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS In the NPTL threading implementation, .BR pthread_kill_other_threads_np () diff --git a/man3/pthread_mutex_consistent.3 b/man3/pthread_mutex_consistent.3 index 0f9cda3..54cdc51 100644 --- a/man3/pthread_mutex_consistent.3 +++ b/man3/pthread_mutex_consistent.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_mutex_consistent 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_mutex_consistent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_mutex_consistent \- make a robust mutex consistent .SH LIBRARY @@ -12,15 +12,15 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_mutex_consistent(pthread_mutex_t *" mutex ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_mutex_consistent (): .nf _POSIX_C_SOURCE >= 200809L @@ -49,19 +49,19 @@ POSIX.1-2008. .SH HISTORY glibc 2.12. POSIX.1-2008. -.PP +.P Before the addition of .BR pthread_mutex_consistent () to POSIX, glibc defined the following equivalent nonstandard function if .B _GNU_SOURCE was defined: -.PP +.P .nf .B [[deprecated]] .BI "int pthread_mutex_consistent_np(const pthread_mutex_t *" mutex ); .fi -.PP +.P This GNU-specific API, which first appeared in glibc 2.4, is nowadays obsolete and should not be used in new programs; since glibc 2.34 it has been marked as deprecated. diff --git a/man3/pthread_mutex_init.3 b/man3/pthread_mutex_init.3 new file mode 100644 index 0000000..8d9abf9 --- /dev/null +++ b/man3/pthread_mutex_init.3 @@ -0,0 +1,241 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutex_init 3 2024-02-26 "Linux man-pages 6.7" +. +. +.SH NAME +pthread_mutex_init, +pthread_mutex_lock, +pthread_mutex_trylock, +pthread_mutex_unlock, +pthread_mutex_destroy +\- +operations on mutexes +. +. +.SH SYNOPSIS +.B #include +.P +.BI "pthread_mutex_t " fastmutex " = PTHREAD_MUTEX_INITIALIZER;" +.BI "pthread_mutex_t " recmutex " = PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP;" +.BI "pthread_mutex_t " errchkmutex " = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;" +.P +.BI "int pthread_mutex_init(pthread_mutex_t *" mutex ", const pthread_mutexattr_t *" mutexattr ");" +.BI "int pthread_mutex_lock(pthread_mutex_t *" mutex ");" +.BI "int pthread_mutex_trylock(pthread_mutex_t *" mutex ");" +.BI "int pthread_mutex_unlock(pthread_mutex_t *" mutex ");" +.BI "int pthread_mutex_destroy(pthread_mutex_t *" mutex ");" +. +. +.SH DESCRIPTION +A mutex is a MUTual EXclusion device, +and is useful for +protecting shared data structures from concurrent modifications, +and implementing critical sections and monitors. +.P +A mutex has two possible states: +unlocked (not owned by any thread), +and locked (owned by one thread). +A mutex can never be owned by two different threads simultaneously. +A thread attempting to lock a mutex +that is already locked by another thread +is suspended until the owning thread unlocks the mutex first. +.P +\fBpthread_mutex_init\fP initializes the mutex object pointed to by \fImutex\fP +according to the mutex attributes specified in \fImutexattr\fP. +If \fImutexattr\fP is \fBNULL\fP, +default attributes are used instead. +.P +The LinuxThreads implementation supports only one mutex attributes, +the \fImutex kind\fP, +which is either ``fast'', +``recursive'', +or ``error checking''. +The kind of a mutex determines +whether it can be locked again by a thread that already owns it. +The default kind is ``fast''. +See \fBpthread_mutexattr_init\fP(3) for more information on mutex attributes. +.P +Variables of type \fBpthread_mutex_t\fP can also be initialized statically, +using the constants +\fBPTHREAD_MUTEX_INITIALIZER\fP +(for fast mutexes), +\fBPTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP\fP +(for recursive mutexes), +and \fBPTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP\fP +(for error checking mutexes). +.P +\fBpthread_mutex_lock\fP locks the given mutex. +If the mutex is currently unlocked, +it becomes locked and owned by the calling thread, +and \fBpthread_mutex_lock\fP returns immediately. +If the mutex is already locked by another thread, +\fBpthread_mutex_lock\fP suspends the calling thread +until the mutex is unlocked. +.P +If the mutex is already locked by the calling thread, +the behavior of \fBpthread_mutex_lock\fP depends on the kind of the mutex. +If the mutex is of the ``fast'' kind, +the calling thread is suspended until the mutex is unlocked, +thus effectively causing the calling thread to deadlock. +If the mutex is of the ``error checking'' kind, +\fBpthread_mutex_lock\fP returns immediately with the error code \fBEDEADLK\fP. +If the mutex is of the ``recursive'' kind, +\fBpthread_mutex_lock\fP succeeds and returns immediately, +recording the number of times the calling thread has locked the mutex. +An equal number of \fBpthread_mutex_unlock\fP operations +must be performed before the mutex returns to the unlocked state. +.P +\fBpthread_mutex_trylock\fP behaves identically to \fBpthread_mutex_lock\fP, +except that it does not block the calling thread +if the mutex is already locked by another thread +(or by the calling thread in the case of a ``fast'' mutex). +Instead, +\fBpthread_mutex_trylock\fP returns immediately +with the error code \fBEBUSY\fP. +.P +\fBpthread_mutex_unlock\fP unlocks the given mutex. +The mutex is assumed to be locked and owned by the calling thread +on entrance to \fBpthread_mutex_unlock\fP. +If the mutex is of the ``fast'' kind, +\fBpthread_mutex_unlock\fP always returns it to the unlocked state. +If it is of the ``recursive'' kind, +it decrements the locking count of the mutex +(number of \fBpthread_mutex_lock\fP operations +performed on it by the calling thread), +and only when this count reaches zero is the mutex actually unlocked. +.P +On ``error checking'' and ``recursive'' mutexes, +\fBpthread_mutex_unlock\fP actually checks at run-time +that the mutex is locked on entrance, +and that it was locked by the same thread +that is now calling \fBpthread_mutex_unlock\fP. +If these conditions are not met, +an error code is returned and the mutex remains unchanged. +``Fast'' mutexes perform no such checks, +thus allowing a locked mutex to be +unlocked by a thread other than its owner. +This is non-portable behavior and must not be relied upon. +.P +\fBpthread_mutex_destroy\fP destroys a mutex object, +freeing the resources it might hold. +The mutex must be unlocked on entrance. +In the LinuxThreads implementation, +no resources are associated with mutex objects, +thus \fBpthread_mutex_destroy\fP actually does nothing +except checking that the mutex is unlocked. +. +. +.SH CANCELLATION +None of the mutex functions is a cancelation point, +not even \fBpthread_mutex_lock\fP, +in spite of the fact that it can suspend a thread for arbitrary durations. +This way, +the status of mutexes at cancelation points is predictable, +allowing cancelation handlers +to unlock precisely those mutexes that need to be unlocked +before the thread stops executing. +Consequently, +threads using deferred cancelation +should never hold a mutex for extended periods of time. +. +. +.SH "ASYNC-SIGNAL SAFETY" +The mutex functions are not async-signal safe. +What this means is that they should not be called from a signal handler. +In particular, +calling \fBpthread_mutex_lock\fP or \fBpthread_mutex_unlock\fP +from a signal handler +may deadlock the calling thread. +. +. +.SH "RETURN VALUE" +\fBpthread_mutex_init\fP always returns 0. +The other mutex functions +return 0 on success and a non-zero error code on error. +. +. +.SH ERRORS +The \fBpthread_mutex_lock\fP function returns +the following error code on error: +.RS +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.TP +\fBEDEADLK\fP +The mutex is already locked by the calling thread +(``error checking'' mutexes only). +.RE +.P +The \fBpthread_mutex_trylock\fP function returns +the following error codes on error: +.RS +.TP +\fBEBUSY\fP +The mutex could not be acquired because it was currently locked. +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.RE +.P +The \fBpthread_mutex_unlock\fP function returns +the following error code on error: +.RS +.TP +\fBEINVAL\fP +The mutex has not been properly initialized. +.TP +\fBEPERM\fP +The calling thread does not own the mutex +(``error checking'' mutexes only). +.RE +.P +The \fBpthread_mutex_destroy\fP function returns +the following error code on error: +.RS +.TP +\fBEBUSY\fP +The mutex is currently locked. +.RE +. +. +.SH "SEE ALSO" +\fBpthread_mutexattr_init\fP(3), +\fBpthread_mutexattr_setkind_np\fP(3), +\fBpthread_cancel\fP(3). +. +. +.SH EXAMPLE +A shared global variable \fIx\fP can be protected by a mutex as follows: +.P +.RS +.ft 3 +.nf +.sp +int x; +pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER; +.ft +.P +.RE +.fi +.P +All accesses and modifications to \fIx\fP +should be bracketed by calls to +\fBpthread_mutex_lock\fP and \fBpthread_mutex_unlock\fP +as follows: +.P +.RS +.ft 3 +.nf +.sp +pthread_mutex_lock(&mut); +/* operate on x */ +pthread_mutex_unlock(&mut); +.ft +.P +.RE +.fi diff --git a/man3/pthread_mutexattr_getpshared.3 b/man3/pthread_mutexattr_getpshared.3 index b2abac1..47fe8dd 100644 --- a/man3/pthread_mutexattr_getpshared.3 +++ b/man3/pthread_mutexattr_getpshared.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_mutexattr_getpshared 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_mutexattr_getpshared 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_mutexattr_getpshared, pthread_mutexattr_setpshared \- get/set process-shared mutex attribute @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .B int pthread_mutexattr_getpshared( .BI " const pthread_mutexattr_t *restrict " attr , .BI " int *restrict " pshared ); @@ -24,7 +24,7 @@ These functions get and set the process-shared attribute in a mutex attributes object. This attribute must be appropriately set to ensure correct, efficient operation of a mutex created using this attributes object. -.PP +.P The process-shared attribute can have one of the following values: .TP .B PTHREAD_PROCESS_PRIVATE @@ -36,21 +36,21 @@ This is the default value for the process-shared mutex attribute. Mutexes created with this attributes object can be shared between any threads that have access to the memory containing the object, including threads in different processes. -.PP +.P .BR pthread_mutexattr_getpshared () places the value of the process-shared attribute of the mutex attributes object referred to by .I attr in the location pointed to by .IR pshared . -.PP +.P .BR pthread_mutexattr_setpshared () sets the value of the process-shared attribute of the mutex attributes object referred to by .I attr to the value specified in .BR pshared . -.PP +.P If .I attr does not refer to an initialized mutex attributes object, diff --git a/man3/pthread_mutexattr_init.3 b/man3/pthread_mutexattr_init.3 index 55d2530..4b09f5b 100644 --- a/man3/pthread_mutexattr_init.3 +++ b/man3/pthread_mutexattr_init.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_mutexattr_init 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_mutexattr_init 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_mutexattr_init, pthread_mutexattr_destroy \- initialize and destroy a mutex attributes object @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_mutexattr_init(pthread_mutexattr_t *" attr ");" .BI "int pthread_mutexattr_destroy(pthread_mutexattr_t *" attr ");" .fi @@ -22,16 +22,16 @@ The function initializes the mutex attributes object pointed to by .I attr with default values for all attributes defined by the implementation. -.PP +.P The results of initializing an already initialized mutex attributes object are undefined. -.PP +.P The .BR pthread_mutexattr_destroy () function destroys a mutex attribute object (making it uninitialized). Once a mutex attributes object has been destroyed, it can be reinitialized with .BR pthread_mutexattr_init (). -.PP +.P The results of destroying an uninitialized mutex attributes object are undefined. .SH RETURN VALUE diff --git a/man3/pthread_mutexattr_setkind_np.3 b/man3/pthread_mutexattr_setkind_np.3 new file mode 100644 index 0000000..ca6a64e --- /dev/null +++ b/man3/pthread_mutexattr_setkind_np.3 @@ -0,0 +1,52 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_mutexattr_setkind_np 3 2023-10-31 "Linux man-pages 6.7" +. +. +.SH NAME +pthread_mutexattr_setkind_np, +pthread_mutexattr_getkind_np +\- +deprecated mutex creation attributes +. +. +.SH SYNOPSIS +.B #include +.P +.BI "int pthread_mutexattr_setkind_np(pthread_mutexattr_t *" attr ", int " kind ");" +.BI "int pthread_mutexattr_getkind_np(const pthread_mutexattr_t *" attr ", int *" kind ");" +. +. +.SH DESCRIPTION +These functions are deprecated, +use \fBpthread_mutexattr_settype\fP(3) +and \fBpthread_mutexattr_gettype\fP(3) +instead. +. +. +.SH "RETURN VALUE" +\fBpthread_mutexattr_getkind_np\fP always returns 0. +.P +\fBpthread_mutexattr_setkind_np\fP +returns 0 on success and a non-zero error code on error. +. +. +.SH ERRORS +On error, +\fBpthread_mutexattr_setkind_np\fP returns the following error code: +.TP +\fBEINVAL\fP +\fIkind\fP is neither +\fBPTHREAD_MUTEX_FAST_NP\fP +nor +\fBPTHREAD_MUTEX_RECURSIVE_NP\fP +nor +\fBPTHREAD_MUTEX_ERRORCHECK_NP\fP. +. +. +.SH "SEE ALSO" +\fBpthread_mutexattr_settype\fP(3), +\fBpthread_mutexattr_gettype\fP(3). diff --git a/man3/pthread_mutexattr_setrobust.3 b/man3/pthread_mutexattr_setrobust.3 index 3612e15..802b400 100644 --- a/man3/pthread_mutexattr_setrobust.3 +++ b/man3/pthread_mutexattr_setrobust.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_mutexattr_setrobust 3 2023-05-03 "Linux man-pages 6.05.01" +.TH pthread_mutexattr_setrobust 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_mutexattr_getrobust, pthread_mutexattr_setrobust \- get and set the robustness attribute of a mutex attributes object @@ -13,18 +13,18 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_mutexattr_getrobust(const pthread_mutexattr_t *" attr , .BI " int *" robustness ");" .BI "int pthread_mutexattr_setrobust(pthread_mutexattr_t *" attr , .BI " int " robustness ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_mutexattr_getrobust (), .BR pthread_mutexattr_setrobust (): .nf @@ -47,7 +47,7 @@ the mutex attributes object referred to by .I attr to the value specified in .IR *robustness . -.PP +.P The robustness attribute specifies the behavior of the mutex when the owning thread dies without unlocking the mutex. The following values are valid for @@ -94,7 +94,7 @@ further .BR pthread_mutex_lock (3) operations on this mutex will still return .BR EOWNERDEAD . -.PP +.P Note that the .I attr argument of @@ -107,7 +107,7 @@ otherwise the behavior is undefined. .SH RETURN VALUE On success, these functions return 0. On error, they return a positive error number. -.PP +.P In the glibc implementation, .BR pthread_mutexattr_getrobust () always return zero. @@ -136,7 +136,7 @@ POSIX.1-2008. .SH HISTORY glibc 2.12. POSIX.1-2008. -.PP +.P Before the addition of .BR pthread_mutexattr_getrobust () and @@ -145,7 +145,7 @@ to POSIX, glibc defined the following equivalent nonstandard functions if .B _GNU_SOURCE was defined: -.PP +.P .nf .B [[deprecated]] .BI "int pthread_mutexattr_getrobust_np(const pthread_mutexattr_t *" attr , @@ -154,13 +154,13 @@ was defined: .BI "int pthread_mutexattr_setrobust_np(const pthread_mutexattr_t *" attr , .BI " int " robustness ");" .fi -.PP +.P Correspondingly, the constants .B PTHREAD_MUTEX_STALLED_NP and .B PTHREAD_MUTEX_ROBUST_NP were also defined. -.PP +.P These GNU-specific APIs, which first appeared in glibc 2.4, are nowadays obsolete and should not be used in new programs; since glibc 2.34 these APIs are marked as deprecated. @@ -173,9 +173,9 @@ The main thread subsequently acquires the mutex successfully and gets the error .BR EOWNERDEAD , after which it makes the mutex consistent. -.PP +.P The following shell session shows what we see when running this program: -.PP +.P .in +4n .EX $ \fB./a.out\fP diff --git a/man3/pthread_once.3 b/man3/pthread_once.3 new file mode 100644 index 0000000..852dffa --- /dev/null +++ b/man3/pthread_once.3 @@ -0,0 +1,44 @@ +.\" Copyright, Xavier Leroy +.\" Copyright 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_once 3 2023-10-31 "Linux man-pages 6.7" +. +. +.SH NAME +pthread_once +\- +once-only initialization +. +. +.SH SYNOPSIS +.B #include +.P +.BI "pthread_once_t " once_control " = PTHREAD_ONCE_INIT;" +.P +.BI "int pthread_once(pthread_once_t *" once_control ", void (*" init_routine ") (void));" +. +. +.SH DESCRIPTION +The purpose of \fBpthread_once\fP is +to ensure that a piece of initialization code is executed at most once. +The \fIonce_control\fP argument points to a static or extern variable +statically initialized to \fBPTHREAD_ONCE_INIT\fP. +.P +The first time \fBpthread_once\fP is called +with a given \fIonce_control\fP argument, +it calls \fIinit_routine\fP with no argument +and changes the value of the \fIonce_control\fP variable +to record that initialization has been performed. +Subsequent calls to \fBpthread_once\fP +with the same \fBonce_control\fP argument +do nothing. +. +. +.SH "RETURN VALUE" +\fBpthread_once\fP always returns 0. +. +. +.SH ERRORS +None. diff --git a/man3/pthread_rwlockattr_setkind_np.3 b/man3/pthread_rwlockattr_setkind_np.3 index d068119..f2998ca 100644 --- a/man3/pthread_rwlockattr_setkind_np.3 +++ b/man3/pthread_rwlockattr_setkind_np.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_rwlockattr_setkind_np 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_rwlockattr_setkind_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_rwlockattr_setkind_np, pthread_rwlockattr_getkind_np \- set/get the read-write lock kind of the thread read-write lock attribute object @@ -12,19 +12,19 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_rwlockattr_setkind_np(pthread_rwlockattr_t *" attr , .BI " int " pref ); .B int pthread_rwlockattr_getkind_np( .BI " const pthread_rwlockattr_t *restrict " attr , .BI " int *restrict " pref ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_rwlockattr_setkind_np (), .BR pthread_rwlockattr_getkind_np (): .nf @@ -89,7 +89,7 @@ read locks thus avoiding deadlocks. Setting the lock kind to this avoids writer starvation as long as any read locking is not done in a recursive fashion. -.PP +.P The .BR pthread_rwlockattr_getkind_np () function returns the value of the lock kind attribute of the diff --git a/man3/pthread_self.3 b/man3/pthread_self.3 index 6c2d58e..7d703dd 100644 --- a/man3/pthread_self.3 +++ b/man3/pthread_self.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_self 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_self 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_self \- obtain ID of the calling thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .B pthread_t pthread_self(void); .fi .SH DESCRIPTION @@ -43,7 +43,6 @@ T{ .BR pthread_self () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -59,15 +58,15 @@ can't portably be compared using the C equality operator (\fB==\fP); use .BR pthread_equal (3) instead. -.PP +.P Thread identifiers should be considered opaque: any attempt to use a thread ID other than in pthreads calls is nonportable and can lead to unspecified results. -.PP +.P Thread IDs are guaranteed to be unique only within a process. A thread ID may be reused after a terminated thread has been joined, or a detached thread has terminated. -.PP +.P The thread ID returned by .BR pthread_self () is not the same thing as the kernel thread ID returned by a call to diff --git a/man3/pthread_setaffinity_np.3 b/man3/pthread_setaffinity_np.3 index 112317d..cf91c59 100644 --- a/man3/pthread_setaffinity_np.3 +++ b/man3/pthread_setaffinity_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_setaffinity_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_setaffinity_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_setaffinity_np, pthread_getaffinity_np \- set/get CPU affinity of a thread @@ -15,7 +15,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_setaffinity_np(pthread_t " thread ", size_t " cpusetsize , .BI " const cpu_set_t *" cpuset ); .BI "int pthread_getaffinity_np(pthread_t " thread ", size_t " cpusetsize , @@ -33,20 +33,20 @@ If the call is successful, and the thread is not currently running on one of the CPUs in .IR cpuset , then it is migrated to one of those CPUs. -.PP +.P The .BR pthread_getaffinity_np () function returns the CPU affinity mask of the thread .I thread in the buffer pointed to by .IR cpuset . -.PP +.P For more details on CPU affinity masks, see .BR sched_setaffinity (2). For a description of a set of macros that can be used to manipulate and inspect CPU sets, see .BR CPU_SET (3). -.PP +.P The argument .I cpusetsize is the length (in bytes) of the buffer pointed to by @@ -109,13 +109,12 @@ T{ .BR pthread_getaffinity_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in the names. .SH HISTORY glibc 2.3.4. -.PP +.P In glibc 2.3.3 only, versions of these functions were provided that did not have a .I cpusetsize @@ -135,13 +134,13 @@ runs if the "cpuset" mechanism described in is being used. These restrictions on the actual set of CPUs on which the thread will run are silently imposed by the kernel. -.PP +.P These functions are implemented on top of the .BR sched_setaffinity (2) and .BR sched_getaffinity (2) system calls. -.PP +.P A new thread created by .BR pthread_create (3) inherits a copy of its creator's CPU affinity mask. @@ -153,7 +152,7 @@ to set its CPU affinity mask to include CPUs 0 to 7 and then calls .BR pthread_getaffinity_np () to check the resulting CPU affinity mask of the thread. -.PP +.P .\" SRC BEGIN (pthread_setaffinity_np.c) .EX #define _GNU_SOURCE diff --git a/man3/pthread_setcancelstate.3 b/man3/pthread_setcancelstate.3 index 5fd0d27..40b0a6e 100644 --- a/man3/pthread_setcancelstate.3 +++ b/man3/pthread_setcancelstate.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_setcancelstate 3 2023-07-30 "Linux man-pages 6.05.01" +.TH pthread_setcancelstate 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_setcancelstate, pthread_setcanceltype \- set cancelability state and type @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_setcancelstate(int " state ", int *" oldstate ); .BI "int pthread_setcanceltype(int " type ", int *" oldtype ); .fi @@ -42,7 +42,7 @@ will respond to a cancelation request. The thread is not cancelable. If a cancelation request is received, it is blocked until cancelability is enabled. -.PP +.P The .BR pthread_setcanceltype () sets the cancelability type of the calling thread to the value @@ -72,7 +72,7 @@ The thread can be canceled at any time. (Typically, it will be canceled immediately upon receiving a cancelation request, but the system doesn't guarantee this.) -.PP +.P The set-and-get operation performed by each of these functions is atomic with respect to other threads in the process calling the same function. @@ -87,7 +87,7 @@ can fail with the following error: .B EINVAL Invalid value for .IR state . -.PP +.P The .BR pthread_setcanceltype () can fail with the following error: @@ -124,7 +124,6 @@ T} Async-cancel safety T{ AC-Safe T} .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -133,7 +132,7 @@ POSIX.1-2001. .SH NOTES For details of what happens when a thread is canceled, see .BR \%pthread_cancel (3). -.PP +.P Briefly disabling cancelability is useful if a thread performs some critical action that must not be interrupted by a cancelation request. @@ -159,7 +158,7 @@ Furthermore, some internal data structures family of functions) may be left in an inconsistent state if cancelation occurs in the middle of the function call. Consequently, clean-up handlers cease to be useful. -.PP +.P Functions that can be safely asynchronously canceled are called .IR "async-cancel-safe functions" . POSIX.1-2001 and POSIX.1-2008 require only that @@ -170,7 +169,7 @@ and be async-cancel-safe. In general, other library functions can't be safely called from an asynchronously cancelable thread. -.PP +.P One of the few circumstances in which asynchronous cancelability is useful is for cancelation of a thread that is in a pure compute-bound loop. .SS Portability notes diff --git a/man3/pthread_setconcurrency.3 b/man3/pthread_setconcurrency.3 index 642208f..0c2ffd0 100644 --- a/man3/pthread_setconcurrency.3 +++ b/man3/pthread_setconcurrency.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_setconcurrency 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_setconcurrency 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_setconcurrency, pthread_getconcurrency \- set/get the concurrency level @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_setconcurrency(int " new_level ); .BI "int pthread_getconcurrency(" void ); .fi @@ -27,12 +27,12 @@ The implementation takes this only as a hint: POSIX.1 does not specify the level of concurrency that should be provided as a result of calling .BR pthread_setconcurrency (). -.PP +.P Specifying .I new_level as 0 instructs the implementation to manage the concurrency level as it deems appropriate. -.PP +.P .BR pthread_getconcurrency () returns the current value of the concurrency level for this process. .SH RETURN VALUE @@ -40,7 +40,7 @@ On success, .BR pthread_setconcurrency () returns 0; on error, it returns a nonzero error number. -.PP +.P .BR pthread_getconcurrency () always succeeds, returning the concurrency level set by a previous call to .BR pthread_setconcurrency (), @@ -54,7 +54,7 @@ can fail with the following error: .B EINVAL .I new_level is negative. -.PP +.P POSIX.1 also documents an .B EAGAIN error ("the value specified by @@ -75,7 +75,6 @@ T{ .BR pthread_getconcurrency () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -83,14 +82,14 @@ glibc 2.1. POSIX.1-2001. .SH NOTES The default concurrency level is 0. -.PP +.P Concurrency levels are meaningful only for M:N threading implementations, where at any moment a subset of a process's set of user-level threads may be bound to a smaller number of kernel-scheduling entities. Setting the concurrency level allows the application to give the system a hint as to the number of kernel-scheduling entities that should be provided for efficient execution of the application. -.PP +.P Both LinuxThreads and NPTL are 1:1 threading implementations, so setting the concurrency level has no meaning. In other words, diff --git a/man3/pthread_setname_np.3 b/man3/pthread_setname_np.3 index 5d9a711..4ff9f06 100644 --- a/man3/pthread_setname_np.3 +++ b/man3/pthread_setname_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_setname_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_setname_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_setname_np, pthread_getname_np \- set/get the name of a thread .SH LIBRARY @@ -14,7 +14,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_setname_np(pthread_t " thread ", const char *" name ); .BI "int pthread_getname_np(pthread_t " thread ", char " name [. size "], \ size_t " size ); @@ -36,7 +36,7 @@ The argument specifies the thread whose name is to be changed; .I name specifies the new name. -.PP +.P The .BR pthread_getname_np () function can be used to retrieve the name of the thread. @@ -65,7 +65,7 @@ function can fail with the following error: The length of the string specified pointed to by .I name exceeds the allowed limit. -.PP +.P The .BR pthread_getname_np () function can fail with the following error: @@ -76,7 +76,7 @@ The buffer specified by and .I size is too small to hold the thread name. -.PP +.P If either of these functions fails to open .IR /proc/self/task/ tid /comm , then the call may fail with one of the errors described in @@ -96,7 +96,6 @@ T{ .BR pthread_getname_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in the names. @@ -117,9 +116,9 @@ The program below demonstrates the use of .BR pthread_setname_np () and .BR pthread_getname_np (). -.PP +.P The following shell session shows a sample run of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man3/pthread_setschedparam.3 b/man3/pthread_setschedparam.3 index 62a5832..5fdb307 100644 --- a/man3/pthread_setschedparam.3 +++ b/man3/pthread_setschedparam.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_setschedparam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_setschedparam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_setschedparam, pthread_getschedparam \- set/get scheduling policy and parameters of a thread @@ -14,7 +14,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_setschedparam(pthread_t " thread ", int " policy , .BI " const struct sched_param *" param ); .BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy , @@ -25,7 +25,7 @@ The .BR pthread_setschedparam () function sets the scheduling policy and parameters of the thread .IR thread . -.PP +.P .I policy specifies the new scheduling policy for .IR thread . @@ -36,13 +36,13 @@ and their semantics, are described in .\" FIXME . pthread_setschedparam() places no restriction on the policy, .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013 -.PP +.P The structure pointed to by .I param specifies the new scheduling parameters for .IR thread . Scheduling parameters are maintained in the following structure: -.PP +.P .in +4n .EX struct sched_param { @@ -50,12 +50,12 @@ struct sched_param { }; .EE .in -.PP +.P As can be seen, only one scheduling parameter is supported. For details of the permitted ranges for scheduling priorities in each scheduling policy, see .BR sched (7). -.PP +.P The .BR pthread_getschedparam () function returns the scheduling policy and parameters of the thread @@ -98,7 +98,7 @@ Both of these functions can fail with the following error: No thread with the ID .I thread could be found. -.PP +.P .BR pthread_setschedparam () may additionally fail with the following errors: .TP @@ -112,7 +112,7 @@ does not make sense for the .B EPERM The caller does not have appropriate privileges to set the specified scheduling policy and parameters. -.PP +.P POSIX.1 also documents an .B ENOTSUP ("attempt was made to set the policy or scheduling parameters @@ -133,7 +133,6 @@ T{ .BR pthread_getschedparam () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -152,7 +151,7 @@ and .BR pthread_getschedparam (), as well as the use of a number of other scheduling-related pthreads functions. -.PP +.P In the following run, the main thread sets its scheduling policy to .B SCHED_FIFO with a priority of 10, @@ -168,7 +167,7 @@ meaning that threads created using this attributes object should take their scheduling attributes from the thread attributes object. The program then creates a thread using the thread attributes object, and that thread displays its scheduling policy and priority. -.PP +.P .in +4n .EX $ \fBsu\fP # Need privilege to set real\-time scheduling policies @@ -185,17 +184,17 @@ Scheduler attributes of new thread policy=SCHED_RR, priority=20 .EE .in -.PP +.P In the above output, one can see that the scheduling policy and priority were taken from the values specified in the thread attributes object. -.PP +.P The next run is the same as the previous, except that the inherit scheduler attribute is set to .BR PTHREAD_INHERIT_SCHED , meaning that threads created using the thread attributes object should ignore the scheduling attributes specified in the attributes object and instead take their scheduling attributes from the creating thread. -.PP +.P .in +4n .EX # \fB./a.out \-mf10 \-ar20 \-i i\fP @@ -210,11 +209,11 @@ Scheduler attributes of new thread policy=SCHED_FIFO, priority=10 .EE .in -.PP +.P In the above output, one can see that the scheduling policy and priority were taken from the creating thread, rather than the thread attributes object. -.PP +.P Note that if we had omitted the .I \-i\~i option, the output would have been the same, since @@ -235,6 +234,7 @@ is the default for the inherit scheduler attribute. #define handle_error_en(en, msg) \e do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) \& +[[noreturn]] static void usage(char *prog_name, char *msg) { @@ -270,7 +270,7 @@ get_policy(char p, int *policy) } \& static void -display_sched_attr(int policy, struct sched_param *param) +display_sched_attr(int policy, const struct sched_param *param) { printf(" policy=%s, priority=%d\en", (policy == SCHED_FIFO) ? "SCHED_FIFO" : diff --git a/man3/pthread_setschedprio.3 b/man3/pthread_setschedprio.3 index 64bcb57..acc752d 100644 --- a/man3/pthread_setschedprio.3 +++ b/man3/pthread_setschedprio.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_setschedprio 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_setschedprio 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_setschedprio \- set scheduling priority of a thread .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_setschedprio(pthread_t " thread ", int " prio ); .fi .SH DESCRIPTION @@ -54,7 +54,7 @@ to set the specified priority. No thread with the ID .I thread could be found. -.PP +.P POSIX.1 also documents an .B ENOTSUP ("attempt was made to set the priority @@ -74,7 +74,6 @@ T{ .BR pthread_setschedprio () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_sigmask.3 b/man3/pthread_sigmask.3 index 724f1e9..fb923a8 100644 --- a/man3/pthread_sigmask.3 +++ b/man3/pthread_sigmask.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_sigmask 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_sigmask 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_sigmask \- examine and change mask of blocked signals .SH LIBRARY @@ -13,16 +13,16 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_sigmask(int " how ", const sigset_t *" set \ ", sigset_t *" oldset ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_sigmask (): .nf _POSIX_C_SOURCE >= 199506L || _XOPEN_SOURCE >= 500 @@ -35,7 +35,7 @@ function is just like with the difference that its use in multithreaded programs is explicitly specified by POSIX.1. Other differences are noted in this page. -.PP +.P For a description of the arguments and operation of this function, see .BR sigprocmask (2). .SH RETURN VALUE @@ -60,14 +60,13 @@ T{ .BR pthread_sigmask () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. .SH NOTES A new thread inherits a copy of its creator's signal mask. -.PP +.P The glibc .BR pthread_sigmask () function silently ignores attempts to block the two real-time signals that @@ -80,7 +79,7 @@ The program below blocks some signals in the main thread, and then creates a dedicated thread to fetch those signals via .BR sigwait (3). The following shell session demonstrates its use: -.PP +.P .in +4n .EX .RB "$" " ./a.out &" diff --git a/man3/pthread_sigqueue.3 b/man3/pthread_sigqueue.3 index 5873696..62a1b18 100644 --- a/man3/pthread_sigqueue.3 +++ b/man3/pthread_sigqueue.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_sigqueue 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_sigqueue 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_sigqueue \- queue a signal and data to a thread .SH LIBRARY @@ -13,16 +13,16 @@ POSIX threads library .nf .B #include .B #include -.PP +.P .BI "int pthread_sigqueue(pthread_t " thread ", int " sig , .BI " const union sigval " value ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_sigqueue (): .nf _GNU_SOURCE @@ -35,7 +35,7 @@ function performs a similar task to but, rather than sending a signal to a process, it sends a signal to a thread in the same process as the calling thread. -.PP +.P The .I thread argument is the ID of a thread in the same process as the caller. @@ -85,7 +85,6 @@ T{ .BR pthread_sigqueue () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The glibc implementation of .BR pthread_sigqueue () diff --git a/man3/pthread_spin_init.3 b/man3/pthread_spin_init.3 index 87ad2e8..57ccb88 100644 --- a/man3/pthread_spin_init.3 +++ b/man3/pthread_spin_init.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_spin_init 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_spin_init 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_spin_init, pthread_spin_destroy \- initialize or destroy a spin lock .SH LIBRARY @@ -11,16 +11,16 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_spin_init(pthread_spinlock_t *" lock ", int " pshared ");" .BI "int pthread_spin_destroy(pthread_spinlock_t *" lock ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_spin_init (), .BR pthread_spin_destroy (): .nf @@ -33,7 +33,7 @@ instead of spin locks. Spin locks are primarily useful in conjunction with real-time scheduling policies. See NOTES. -.PP +.P The .BR pthread_spin_init () function allocates any resources required for the use of @@ -56,12 +56,12 @@ The spin lock may be operated on by any thread in any process that has access to the memory containing the lock (i.e., the lock may be in a shared memory object that is shared among multiple processes). -.PP +.P Calling .BR pthread_spin_init () on a spin lock that has already been initialized results in undefined behavior. -.PP +.P The .BR pthread_spin_destroy () function destroys a previously initialized spin lock, @@ -69,13 +69,13 @@ freeing any resources that were allocated for that lock. Destroying a spin lock that has not been previously been initialized or destroying a spin lock while another thread holds the lock results in undefined behavior. -.PP +.P Once a spin lock has been destroyed, performing any operation on the lock other than once more initializing it with .BR pthread_spin_init () results in undefined behavior. -.PP +.P The result of performing operations such as .BR pthread_spin_lock (3), .BR pthread_spin_unlock (3), @@ -108,7 +108,7 @@ POSIX.1-2008. .SH HISTORY glibc 2.2. POSIX.1-2001. -.PP +.P Support for process-shared spin locks is a POSIX option. The option is supported in the glibc implementation. .SH NOTES @@ -124,10 +124,10 @@ The problem is that if a thread operating under such a policy is scheduled off the CPU while it holds a spin lock, then other threads will waste time spinning on the lock until the lock holder is once more rescheduled and releases the lock. -.PP +.P If threads create a deadlock situation while employing spin locks, those threads will spin forever consuming CPU time. -.PP +.P User-space spin locks are .I not applicable as a general locking solution. diff --git a/man3/pthread_spin_lock.3 b/man3/pthread_spin_lock.3 index 4c9bcf1..65e4d45 100644 --- a/man3/pthread_spin_lock.3 +++ b/man3/pthread_spin_lock.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_spin_lock 3 2023-03-30 "Linux man-pages 6.05.01" +.TH pthread_spin_lock 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_spin_lock, pthread_spin_trylock, pthread_spin_unlock \- lock and unlock a spin lock @@ -12,17 +12,17 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int pthread_spin_lock(pthread_spinlock_t *" lock ); .BI "int pthread_spin_trylock(pthread_spinlock_t *" lock ); .BI "int pthread_spin_unlock(pthread_spinlock_t *" lock ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR pthread_spin_lock (), .BR pthread_spin_trylock (): .nf @@ -38,14 +38,14 @@ the calling thread acquires the lock immediately. If the spin lock is currently locked by another thread, the calling thread spins, testing the lock until it becomes available, at which point the calling thread acquires the lock. -.PP +.P Calling .BR pthread_spin_lock () on a lock that is already held by the caller or a lock that has not been initialized with .BR pthread_spin_init (3) results in undefined behavior. -.PP +.P The .BR pthread_spin_trylock () function is like @@ -55,14 +55,14 @@ except that if the spin lock referred to by is currently locked, then, instead of spinning, the call returns immediately with the error .BR EBUSY . -.PP +.P The .BR pthread_spin_unlock () function unlocks the spin lock referred to .IR lock . If any threads are spinning on the lock, one of those threads will then acquire the lock. -.PP +.P Calling .BR pthread_spin_unlock () on a lock that is not held by the caller results in undefined behavior. @@ -76,7 +76,7 @@ may fail with the following errors: .B EDEADLOCK .\" Not detected in glibc The system detected a deadlock condition. -.PP +.P .BR pthread_spin_trylock () fails with the following errors: .TP @@ -90,7 +90,7 @@ POSIX.1-2001. .SH CAVEATS Applying any of the functions described on this page to an uninitialized spin lock results in undefined behavior. -.PP +.P Carefully read NOTES in .BR pthread_spin_init (3). .SH SEE ALSO diff --git a/man3/pthread_testcancel.3 b/man3/pthread_testcancel.3 index 9188ede..796c7a3 100644 --- a/man3/pthread_testcancel.3 +++ b/man3/pthread_testcancel.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_testcancel 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_testcancel 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_testcancel \- request delivery of any pending cancelation request .SH LIBRARY @@ -13,7 +13,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .B void pthread_testcancel(void); .fi .SH DESCRIPTION @@ -22,7 +22,7 @@ Calling creates a cancelation point within the calling thread, so that a thread that is otherwise executing code that contains no cancelation points will respond to a cancelation request. -.PP +.P If cancelability is disabled (using .BR pthread_setcancelstate (3)), or no cancelation request is pending, @@ -49,7 +49,6 @@ T{ .BR pthread_testcancel () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/pthread_tryjoin_np.3 b/man3/pthread_tryjoin_np.3 index 1a0643d..59d622e 100644 --- a/man3/pthread_tryjoin_np.3 +++ b/man3/pthread_tryjoin_np.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_tryjoin_np 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_tryjoin_np 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_tryjoin_np, pthread_timedjoin_np \- try to join with a terminated thread @@ -15,7 +15,7 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int pthread_tryjoin_np(pthread_t " thread ", void **" retval ); .BI "int pthread_timedjoin_np(pthread_t " thread ", void **" retval , .BI " const struct timespec *" abstime ); @@ -24,7 +24,7 @@ POSIX threads library These functions operate in the same way as .BR pthread_join (3), except for the differences described on this page. -.PP +.P The .BR pthread_tryjoin_np () function performs a nonblocking join with the thread @@ -36,7 +36,7 @@ If has not yet terminated, then instead of blocking, as is done by .BR pthread_join (3), the call returns an error. -.PP +.P The .BR pthread_timedjoin_np () function performs a join-with-timeout. @@ -72,7 +72,7 @@ can in addition fail with the following error: .B EBUSY .I thread had not yet terminated at the time of the call. -.PP +.P .BR pthread_timedjoin_np () can in addition fail with the following errors: .TP @@ -88,7 +88,7 @@ is greater than 1e9). The call timed out before .I thread terminated. -.PP +.P .BR pthread_timedjoin_np () never returns the error .BR EINTR . @@ -107,7 +107,6 @@ T{ .BR pthread_timedjoin_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU; hence the suffix "_np" (nonportable) in the names. @@ -127,7 +126,7 @@ Consequently, the timeout is unaffected by discontinuous changes to the clock. .SH EXAMPLES The following code waits to join for up to 5 seconds: -.PP +.P .in +4n .EX struct timespec ts; diff --git a/man3/pthread_yield.3 b/man3/pthread_yield.3 index 95bb580..34d2bad 100644 --- a/man3/pthread_yield.3 +++ b/man3/pthread_yield.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthread_yield 3 2023-07-20 "Linux man-pages 6.05.01" +.TH pthread_yield 3 2023-10-31 "Linux man-pages 6.7" .SH NAME pthread_yield \- yield the processor .SH LIBRARY @@ -13,13 +13,13 @@ POSIX threads library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .B [[deprecated]] int pthread_yield(void); .fi .SH DESCRIPTION .BR Note : This function is deprecated; see below. -.PP +.P .BR pthread_yield () causes the calling thread to relinquish the CPU. The thread is placed at the end of the run queue for its static @@ -49,7 +49,6 @@ T{ .BR pthread_yield () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On Linux, this function is implemented as a call to .BR sched_yield (2). diff --git a/man3/ptsname.3 b/man3/ptsname.3 index b57f057..e7887e9 100644 --- a/man3/ptsname.3 +++ b/man3/ptsname.3 @@ -5,7 +5,7 @@ .\" .\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS .\" -.TH ptsname 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ptsname 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ptsname, ptsname_r \- get the name of the slave pseudoterminal .SH LIBRARY @@ -14,16 +14,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *ptsname(int " fd ); .BI "int ptsname_r(int " fd ", char " buf [. buflen "], size_t " buflen ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ptsname (): .nf Since glibc 2.24: @@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see glibc 2.23 and earlier: _XOPEN_SOURCE .fi -.PP +.P .BR ptsname_r (): .nf _GNU_SOURCE @@ -43,7 +43,7 @@ The function returns the name of the slave pseudoterminal device corresponding to the master referred to by the file descriptor .IR fd . -.PP +.P The .BR ptsname_r () function is the reentrant equivalent of @@ -62,7 +62,7 @@ returns a pointer to a string in static storage which will be overwritten by subsequent calls. This pointer must not be freed. On failure, NULL is returned. -.PP +.P On success, .BR ptsname_r () returns 0. @@ -108,7 +108,6 @@ T{ .BR ptsname_r () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS A version of .BR ptsname_r () @@ -122,7 +121,7 @@ Avoid using this function in portable programs. .TP .BR ptsname (): POSIX.1-2008. -.PP +.P .BR ptsname_r () is a Linux extension, that is proposed for inclusion .\" FIXME . for later review when Issue 8 is one day released @@ -134,7 +133,7 @@ in the next major revision of POSIX.1 (Issue 8). .BR ptsname (): POSIX.1-2001. glibc 2.1. -.PP +.P .BR ptsname () is part of the UNIX 98 pseudoterminal support (see .BR pts (4)). diff --git a/man3/putenv.3 b/man3/putenv.3 index da15b2e..c63d5e4 100644 --- a/man3/putenv.3 +++ b/man3/putenv.3 @@ -14,7 +14,7 @@ .\" Modified Mon Oct 11 11:11:11 1999 by Andries Brouwer (aeb@cwi.nl) .\" Modified Wed Nov 10 00:02:26 1999 by Andries Brouwer (aeb@cwi.nl) .\" Modified Sun May 20 22:17:20 2001 by Andries Brouwer (aeb@cwi.nl) -.TH putenv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH putenv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME putenv \- change or add an environment variable .SH LIBRARY @@ -23,16 +23,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int putenv(char *" string ); .\" Not: const char * .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR putenv (): .nf _XOPEN_SOURCE @@ -77,17 +77,16 @@ T{ .BR putenv () T} Thread safety MT-Unsafe const:env .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr2, 4.3BSD-Reno. -.PP +.P The .BR putenv () function is not required to be reentrant, and the one in glibc 2.0 is not, but the glibc 2.1 version is. -.\" .LP +.\" .P .\" Description for libc4, libc5, glibc: .\" If the argument \fIstring\fP is of the form \fIname\fP, .\" and does not contain an \[aq]=\[aq] character, then the variable \fIname\fP @@ -100,7 +99,7 @@ one in glibc 2.0 is not, but the glibc 2.1 version is. .\" then it will be freed. .\" In no case will the old storage associated .\" to the environment variable itself be freed. -.PP +.P Since glibc 2.1.2, the glibc implementation conforms to SUSv2: the pointer \fIstring\fP given to .BR putenv () @@ -116,23 +115,23 @@ However, from glibc 2.0 to glibc 2.1.1, it differs: a copy of the string is used. On the one hand this causes a memory leak, and on the other hand it violates SUSv2. -.PP +.P The 4.3BSD-Reno version, like glibc 2.0, uses a copy; this is fixed in all modern BSDs. -.PP +.P SUSv2 removes the \fIconst\fP from the prototype, and so does glibc 2.1.3. -.PP +.P The GNU C library implementation provides a nonstandard extension. If .I string does not include an equal sign: -.PP +.P .in +4n .EX putenv("NAME"); .EE .in -.PP +.P then the named variable is removed from the caller's environment. .SH SEE ALSO .BR clearenv (3), diff --git a/man3/putgrent.3 b/man3/putgrent.3 index e1b955c..1de2084 100644 --- a/man3/putgrent.3 +++ b/man3/putgrent.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH putgrent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH putgrent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME putgrent \- write a group database entry to a file .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int putgrent(const struct group *restrict " grp \ ", FILE *restrict " stream ); .fi @@ -27,11 +27,11 @@ The function writes the content of the provided into the .IR stream . The list of group members must be NULL-terminated or NULL-initialized. -.PP +.P The .I struct group is defined as follows: -.PP +.P .in +4n .EX struct group { @@ -58,7 +58,6 @@ T{ .BR putgrent () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH SEE ALSO diff --git a/man3/putpwent.3 b/man3/putpwent.3 index d1755f8..645e8be 100644 --- a/man3/putpwent.3 +++ b/man3/putpwent.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:43:46 1993 by Rik Faith (faith@cs.unc.edu) -.TH putpwent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH putpwent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME putpwent \- write a password file entry .SH LIBRARY @@ -19,16 +19,16 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "int putpwent(const struct passwd *restrict " p \ ", FILE *restrict " stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR putpwent (): .nf Since glibc 2.19: @@ -41,9 +41,9 @@ The .BR putpwent () function writes a password entry from the structure \fIp\fP in the file associated with \fIstream\fP. -.PP +.P The \fIpasswd\fP structure is defined in \fI\fP as follows: -.PP +.P .in +4n .EX struct passwd { @@ -82,7 +82,6 @@ T{ .BR putpwent () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/puts.3 b/man3/puts.3 index a113df5..dd50c52 100644 --- a/man3/puts.3 +++ b/man3/puts.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Sat Jul 24 18:42:59 1993 by Rik Faith (faith@cs.unc.edu) -.TH puts 3 2023-07-20 "Linux man-pages 6.05.01" +.TH puts 3 2023-10-31 "Linux man-pages 6.7" .SH NAME fputc, fputs, putc, putchar, puts \- output of characters and strings .SH LIBRARY @@ -13,11 +13,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int fputc(int " c ", FILE *" stream ); .BI "int putc(int " c ", FILE *" stream ); .BI "int putchar(int " c ); -.PP +.P .BI "int fputs(const char *restrict " s ", FILE *restrict " stream ); .BI "int puts(const char *" s ); .fi @@ -29,37 +29,37 @@ cast to an .IR "unsigned char" , to .IR stream . -.PP +.P .BR putc () is equivalent to .BR fputc () except that it may be implemented as a macro which evaluates .I stream more than once. -.PP +.P .BI "putchar(" c ) is equivalent to .BI "putc(" c ", " stdout ) \fR. -.PP +.P .BR fputs () writes the string .I s to .IR stream , without its terminating null byte (\[aq]\e0\[aq]). -.PP +.P .BR puts () writes the string .I s and a trailing newline to .IR stdout . -.PP +.P Calls to the functions described here can be mixed with each other and with calls to other output functions from the .I stdio library for the same output stream. -.PP +.P For nonlocking counterparts, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -74,7 +74,7 @@ cast to an or .B EOF on error. -.PP +.P .BR puts () and .BR fputs () @@ -99,7 +99,6 @@ T{ .BR puts () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/putwchar.3 b/man3/putwchar.3 index e544681..af64cba 100644 --- a/man3/putwchar.3 +++ b/man3/putwchar.3 @@ -10,7 +10,7 @@ .\" http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH putwchar 3 2023-07-20 "Linux man-pages 6.05.01" +.TH putwchar 3 2023-10-31 "Linux man-pages 6.7" .SH NAME putwchar \- write a wide character to standard output .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wint_t putwchar(wchar_t " wc ); .fi .SH DESCRIPTION @@ -45,7 +45,7 @@ and returns .BR WEOF . Otherwise, it returns .IR wc . -.PP +.P For a nonlocking counterpart, see .BR unlocked_stdio (3). .SH RETURN VALUE @@ -70,7 +70,6 @@ T{ .BR putwchar () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -82,7 +81,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P It is reasonable to expect that .BR putwchar () will actually write diff --git a/man3/qecvt.3 b/man3/qecvt.3 index aa19f81..a9aeed8 100644 --- a/man3/qecvt.3 +++ b/man3/qecvt.3 @@ -6,7 +6,7 @@ .\" This replaces an earlier man page written by Walter Harms .\" . .\" -.TH qecvt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH qecvt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME qecvt, qfcvt, qgcvt \- convert a floating-point number to a string .SH LIBRARY @@ -15,19 +15,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] char *qecvt(long double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign ); .BI "[[deprecated]] char *qfcvt(long double " number ", int " ndigits , .BI " int *restrict " decpt ", int *restrict " sign ); .BI "[[deprecated]] char *qgcvt(long double " number ", int " ndigit ", char *" buf ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR qecvt (), .BR qfcvt (), .BR qgcvt (): @@ -93,13 +93,12 @@ T{ .BR qgcvt () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY SVr4, SunOS, GNU. .\" Not supported by libc4 and libc5. -.PP +.P These functions are obsolete. Instead, .BR snprintf (3) diff --git a/man3/qsort.3 b/man3/qsort.3 index 09737a2..6959a9a 100644 --- a/man3/qsort.3 +++ b/man3/qsort.3 @@ -15,7 +15,7 @@ .\" and Ben Bacarisse .\" Document qsort_r() .\" -.TH qsort 3 2023-07-20 "Linux man-pages 6.05.01" +.TH qsort 3 2023-10-31 "Linux man-pages 6.7" .SH NAME qsort, qsort_r \- sort an array .SH LIBRARY @@ -24,7 +24,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void qsort(void " base [. size " * ." nmemb "], size_t " nmemb ", \ size_t " size , .BI " int (*" compar ")(const void [." size "], \ @@ -35,12 +35,12 @@ size_t " size , const void [." size "], void *)," .BI " void *" arg ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR qsort_r (): .nf _GNU_SOURCE @@ -52,17 +52,17 @@ function sorts an array with \fInmemb\fP elements of size \fIsize\fP. The \fIbase\fP argument points to the start of the array. -.PP +.P The contents of the array are sorted in ascending order according to a comparison function pointed to by \fIcompar\fP, which is called with two arguments that point to the objects being compared. -.PP +.P The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted array is undefined. -.PP +.P The .BR qsort_r () function is identical to @@ -96,7 +96,6 @@ T{ .BR qsort_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR qsort () @@ -115,10 +114,10 @@ as shown in the example below. .SH EXAMPLES For one example of use, see the example under .BR bsearch (3). -.PP +.P Another example is the following program, which sorts the strings given in its command-line arguments: -.PP +.P .\" SRC BEGIN (qsort.c) .EX #include diff --git a/man3/raise.3 b/man3/raise.3 index 49d2d96..9fb5c72 100644 --- a/man3/raise.3 +++ b/man3/raise.3 @@ -7,7 +7,7 @@ .\" Modified Sat Jul 24 18:40:56 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 1995 by Mike Battersby (mib@deakin.edu.au) .\" -.TH raise 3 2023-07-20 "Linux man-pages 6.05.01" +.TH raise 3 2023-10-31 "Linux man-pages 6.7" .SH NAME raise \- send a signal to the caller .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int raise(int " sig ); .fi .SH DESCRIPTION @@ -24,21 +24,21 @@ The .BR raise () function sends a signal to the calling process or thread. In a single-threaded program it is equivalent to -.PP +.P .in +4n .EX kill(getpid(), sig); .EE .in -.PP +.P In a multithreaded program it is equivalent to -.PP +.P .in +4n .EX pthread_kill(pthread_self(), sig); .EE .in -.PP +.P If the signal causes a handler to be called, .BR raise () will return only after the signal handler has returned. @@ -59,12 +59,11 @@ T{ .BR raise () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C89. -.PP +.P Since glibc 2.3.3, .BR raise () is implemented by calling diff --git a/man3/rand.3 b/man3/rand.3 index 6146ce9..681a5f7 100644 --- a/man3/rand.3 +++ b/man3/rand.3 @@ -19,7 +19,7 @@ .\" Modified 2003-11-15, aeb, added rand_r .\" 2010-09-13, mtk, added example program .\" -.TH rand 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rand 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rand, rand_r, srand \- pseudo-random number generator .SH LIBRARY @@ -28,18 +28,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int rand(void); .BI "void srand(unsigned int " seed ); -.PP +.P .BI "[[deprecated]] int rand_r(unsigned int *" seedp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR rand_r (): .nf Since glibc 2.24: @@ -53,7 +53,7 @@ The function returns a pseudo-random integer in the range 0 to .B RAND_MAX inclusive (i.e., the mathematical range [0,\ \fBRAND_MAX\fR]). -.PP +.P The .BR srand () function sets its argument as the seed for a new @@ -62,11 +62,11 @@ sequence of pseudo-random integers to be returned by These sequences are repeatable by calling .BR srand () with the same seed value. -.PP +.P If no seed value is provided, the .BR rand () function is automatically seeded with a value of 1. -.PP +.P The function .BR rand () is not reentrant, since it @@ -77,7 +77,7 @@ In order to get reproducible behavior in a threaded application, this state must be made explicit; this can be done using the reentrant function .BR rand_r (). -.PP +.P Like .BR rand (), .BR rand_r () @@ -93,7 +93,7 @@ is called with the same initial value for the integer pointed to by .IR seedp , and that value is not modified between calls, then the same pseudo-random sequence will result. -.PP +.P The value pointed to by the .I seedp argument of @@ -130,7 +130,6 @@ T{ .BR srand () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The versions of .BR rand () @@ -175,7 +174,7 @@ POSIX.1-2001 gives the following example of an implementation of and .BR srand (), possibly useful when one needs the same sequence on two different machines. -.PP +.P .in +4n .EX static unsigned long next = 1; @@ -191,7 +190,7 @@ void mysrand(unsigned int seed) { } .EE .in -.PP +.P The following program can be used to display the pseudo-random sequence produced by .BR rand () @@ -199,7 +198,7 @@ when given a particular seed. When the seed is .IR \-1 , the program uses a random seed. -.PP +.P .in +4n .\" SRC BEGIN (rand.c) .EX diff --git a/man3/random.3 b/man3/random.3 index 9c69344..3d1c4dd 100644 --- a/man3/random.3 +++ b/man3/random.3 @@ -11,7 +11,7 @@ .\" Modified Sat Jul 24 18:13:39 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Aug 20 21:47:07 2000, aeb .\" -.TH random 3 2023-07-20 "Linux man-pages 6.05.01" +.TH random 3 2023-10-31 "Linux man-pages 6.7" .SH NAME random, srandom, initstate, setstate \- random number generator .SH LIBRARY @@ -20,19 +20,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B long random(void); .BI "void srandom(unsigned int " seed ); -.PP +.P .BI "char *initstate(unsigned int " seed ", char " state [. n "], size_t " n ); .BI "char *setstate(char *" state ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR random (), .BR srandom (), .BR initstate (), @@ -52,7 +52,7 @@ return successive pseudo-random numbers in the range from 0 to 2\[ha]31\ \-\ 1. The period of this random number generator is very large, approximately .IR "16\ *\ ((2\[ha]31)\ \-\ 1)" . -.PP +.P The .BR srandom () function sets its argument as the seed for a new @@ -66,7 +66,7 @@ If no seed value is provided, the .BR random () function is automatically seeded with a value of 1. -.PP +.P The .BR initstate () function allows a state array \fIstate\fP to @@ -85,7 +85,7 @@ Using less than 8 bytes results in an error. \fIseed\fP is the seed for the initialization, which specifies a starting point for the random number sequence, and provides for restarting at the same point. -.PP +.P The .BR setstate () function changes the state array used by the @@ -109,14 +109,14 @@ function returns a value between 0 and The .BR srandom () function returns no value. -.PP +.P The .BR initstate () function returns a pointer to the previous state array. On failure, it returns NULL, and .I errno is set to indicate the error. -.PP +.P On success, .BR setstate () returns a pointer to the previous state array. @@ -152,7 +152,6 @@ T{ .BR setstate () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -164,7 +163,7 @@ Random-number generation is a complex topic. William T.\& Vetterling; New York: Cambridge University Press, 2007, 3rd ed.) provides an excellent discussion of practical random-number generation issues in Chapter 7 (Random Numbers). -.PP +.P For a more theoretical discussion which also covers many practical issues in depth, see Chapter 3 (Random Numbers) in Donald E.\& Knuth's .IR "The Art of Computer Programming" , diff --git a/man3/random_r.3 b/man3/random_r.3 index c812c2f..f1647f8 100644 --- a/man3/random_r.3 +++ b/man3/random_r.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH random_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH random_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME random_r, srandom_r, initstate_r, setstate_r \- reentrant random number generator @@ -14,23 +14,23 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int random_r(struct random_data *restrict " buf , .BI " int32_t *restrict " result ); .BI "int srandom_r(unsigned int " seed ", struct random_data *" buf ); -.PP +.P .BI "int initstate_r(unsigned int " seed ", \ char " statebuf "[restrict ." statelen ], .BI " size_t " statelen ", struct random_data *restrict " buf ); .BI "int setstate_r(char *restrict " statebuf , .BI " struct random_data *restrict " buf ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR random_r (), .BR srandom_r (), .BR initstate_r (), @@ -45,7 +45,7 @@ of the functions described in .BR random (3). They are suitable for use in multithreaded programs where each thread needs to obtain an independent, reproducible sequence of random numbers. -.PP +.P The .BR random_r () function is like @@ -58,7 +58,7 @@ which must have been previously initialized by .BR initstate_r (). The generated random number is returned in the argument .IR result . -.PP +.P The .BR srandom_r () function is like @@ -69,7 +69,7 @@ whose state is maintained in the object pointed to by which must have been previously initialized by .BR initstate_r (), instead of the seed associated with the global state variable. -.PP +.P The .BR initstate_r () function is like @@ -97,7 +97,7 @@ should typically be allocated as a static variable, or allocated on the heap using .BR malloc (3) or similar.) -.PP +.P The .BR setstate_r () function is like @@ -155,7 +155,6 @@ T{ .BR setstate_r () T} Thread safety MT-Safe race:buf .TE -.sp 1 .SH STANDARDS GNU. .\" These functions appear to be on Tru64, but don't seem to be on diff --git a/man3/rcmd.3 b/man3/rcmd.3 index 765e85a..012dc62 100644 --- a/man3/rcmd.3 +++ b/man3/rcmd.3 @@ -13,7 +13,7 @@ .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH rcmd 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rcmd 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rcmd, rresvport, iruserok, ruserok, rcmd_af, rresvport_af, iruserok_af, ruserok_af \- routines for returning a @@ -24,27 +24,27 @@ Standard C library .SH SYNOPSIS .nf .BR "#include " "/* Or on some systems */" -.PP +.P .BI "int rcmd(char **restrict " ahost ", unsigned short " inport , .BI " const char *restrict " locuser , .BI " const char *restrict " remuser , .BI " const char *restrict " cmd ", int *restrict " fd2p ); -.PP +.P .BI "int rresvport(int *" port ); -.PP +.P .BI "int iruserok(uint32_t " raddr ", int " superuser , .BI " const char *" ruser ", const char *" luser ); .BI "int ruserok(const char *" rhost ", int " superuser , .BI " const char *" ruser ", const char *" luser ); -.PP +.P .BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport , .BI " const char *restrict " locuser , .BI " const char *restrict " remuser , .BI " const char *restrict " cmd ", int *restrict " fd2p , .BI " sa_family_t " af ); -.PP +.P .BI "int rresvport_af(int *" port ", sa_family_t " af ); -.PP +.P .BI "int iruserok_af(const void *restrict " raddr ", int " superuser , .BI " const char *restrict " ruser ", const char *restrict " luser , .BI " sa_family_t " af ); @@ -52,13 +52,13 @@ Standard C library .BI " const char *" ruser ", const char *" luser , .BI " sa_family_t " af ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE .ad l -.PP +.P .BR rcmd (), .BR rcmd_af (), .BR rresvport (), @@ -110,7 +110,7 @@ is set to the standard name of the host and a connection is established to a server residing at the well-known Internet port .IR inport . -.PP +.P If the connection succeeds, a socket in the Internet domain of type .B SOCK_STREAM @@ -139,7 +139,7 @@ command) will be made the same as the and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data. -.PP +.P The protocol is described in detail in .BR rshd (8). .SS rresvport() @@ -182,7 +182,7 @@ If that lookup is not done, or is unsuccessful, the .I .rhosts in the local user's home directory is checked to see if the request for service is allowed. -.PP +.P If this file does not exist, is not a regular file, is owned by anyone other than the user or the superuser, is writable by anyone other than the owner, or is hardlinked anywhere, the check automatically fails. @@ -198,7 +198,7 @@ return \-1. If the local domain (as obtained from .BR gethostname (2)) is the same as the remote domain, only the machine name need be specified. -.PP +.P If the IP address of the remote host is known, .BR iruserok () should be used in preference to @@ -226,7 +226,7 @@ The function returns a valid socket descriptor on success. It returns \-1 on error and prints a diagnostic message on the standard error. -.PP +.P The .BR rresvport () function @@ -237,7 +237,7 @@ to indicate the error. The error code .B EAGAIN is overloaded to mean: "All network ports in use". -.PP +.P For information on the return from .BR ruserok () and @@ -272,7 +272,6 @@ T{ .BR ruserok_af () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY @@ -285,7 +284,7 @@ BSD. .TQ .BR ruserok_af () glibc 2.2. -.PP +.P Solaris, 4.2BSD. The "_af" variants are more recent additions, and are not present on as wide a range of systems. diff --git a/man3/re_comp.3 b/man3/re_comp.3 index 3cb4450..038dc96 100644 --- a/man3/re_comp.3 +++ b/man3/re_comp.3 @@ -5,7 +5,7 @@ .\" .\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@@ee.surrey.ac.uk) .\" -.TH re_comp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH re_comp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME re_comp, re_exec \- BSD regex functions .SH LIBRARY @@ -16,7 +16,7 @@ Standard C library .B #define _REGEX_RE_COMP .B #include .B #include -.PP +.P .BI "[[deprecated]] char *re_comp(const char *" regex ); .BI "[[deprecated]] int re_exec(const char *" string ); .fi @@ -32,7 +32,7 @@ If is NULL, no operation is performed and the pattern buffer's contents are not altered. -.PP +.P .BR re_exec () is used to assess whether the null-terminated string pointed to by .I string @@ -43,7 +43,7 @@ matches the previously compiled returns NULL on successful compilation of .I regex otherwise it returns a pointer to an appropriate error message. -.PP +.P .BR re_exec () returns 1 for a successful match, zero for failure. .SH ATTRIBUTES @@ -61,12 +61,11 @@ T{ .BR re_exec () T} Thread safety MT-Unsafe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY 4.3BSD. -.PP +.P These functions are obsolete; the functions documented in .BR regcomp (3) should be used instead. diff --git a/man3/readdir.3 b/man3/readdir.3 index 2e0ea09..9b61aaf 100644 --- a/man3/readdir.3 +++ b/man3/readdir.3 @@ -14,7 +14,7 @@ .\" 2007-07-30 Ulrich Drepper , mtk: .\" Rework discussion of nonstandard structure fields. .\" -.TH readdir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH readdir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME readdir \- read a directory .SH LIBRARY @@ -23,7 +23,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "struct dirent *readdir(DIR *" dirp ); .fi .SH DESCRIPTION @@ -34,11 +34,11 @@ representing the next directory entry in the directory stream pointed to by \fIdirp\fP. It returns NULL on reaching the end of the directory stream or if an error occurred. -.PP +.P In the glibc implementation, the .I dirent structure is defined as follows: -.PP +.P .in +4n .EX struct dirent { @@ -51,7 +51,7 @@ struct dirent { }; .EE .in -.PP +.P The only fields in the .I dirent structure that are mandated by POSIX.1 are @@ -60,7 +60,7 @@ and .IR d_ino . The other fields are unstandardized, and not present on all systems; see NOTES below for some further details. -.PP +.P The fields of the .I dirent structure are as follows: @@ -139,7 +139,7 @@ All applications must properly handle a return of .I d_name This field contains the null terminated filename. .IR "See NOTES" . -.PP +.P The data returned by .BR readdir () may be overwritten by subsequent calls to @@ -154,7 +154,7 @@ structure. (This structure may be statically allocated; do not attempt to .BR free (3) it.) -.PP +.P If the end of the directory stream is reached, NULL is returned and .I errno is not changed. @@ -186,8 +186,7 @@ T{ .BR readdir () T} Thread safety MT-Unsafe race:dirstream .TE -.sp 1 -.PP +.P In the current POSIX.1 specification (POSIX.1-2008), .BR readdir () is not required to be thread-safe. @@ -235,7 +234,7 @@ structure definition shown above is taken from the glibc headers, and shows the .I d_name field with a fixed size. -.PP +.P .IR Warning : applications should avoid any dependence on the size of the .I d_name @@ -245,7 +244,7 @@ POSIX defines it as a character array of unspecified size, with at most .B NAME_MAX characters preceding the terminating null byte (\[aq]\e0\[aq]). -.PP +.P POSIX.1 explicitly notes that this field should not be used as an lvalue. The standard also notes that the use of .I sizeof(d_name) @@ -259,15 +258,15 @@ By implication, the use to capture the size of the record including the size of .I d_name is also incorrect. -.PP +.P Note that while the call -.PP +.P .in +4n .EX fpathconf(fd, _PC_NAME_MAX) .EE .in -.PP +.P returns the value 255 for most filesystems, on some filesystems (e.g., CIFS, Windows SMB servers), the null-terminated filename that is (correctly) returned in @@ -285,7 +284,7 @@ POSIX.1-2001, SVr4, 4.3BSD. .SH NOTES A directory stream is opened using .BR opendir (3). -.PP +.P The order in which filenames are read by successive calls to .BR readdir () depends on the filesystem implementation; diff --git a/man3/readdir_r.3 b/man3/readdir_r.3 index f853e51..f90a70b 100644 --- a/man3/readdir_r.3 +++ b/man3/readdir_r.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH readdir_r 3 2023-07-20 "Linux man-pages 6.05.01" +.TH readdir_r 3 2023-10-31 "Linux man-pages 6.7" .SH NAME readdir_r \- read a directory .SH LIBRARY @@ -13,17 +13,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int readdir_r(DIR *restrict " dirp , .BI " struct dirent *restrict " entry , .BI " struct dirent **restrict " result ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR readdir_r (): .nf _POSIX_C_SOURCE @@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see This function is deprecated; use .BR readdir (3) instead. -.PP +.P The .BR readdir_r () function was invented as a reentrant version of @@ -46,13 +46,13 @@ For details of the .I dirent structure, see .BR readdir (3). -.PP +.P A pointer to the returned buffer is placed in .IR *result ; if the end of the directory stream was encountered, then NULL is instead returned in .IR *result . -.PP +.P It is recommended that applications use .BR readdir (3) instead of @@ -137,7 +137,6 @@ T{ .BR readdir_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/realpath.3 b/man3/realpath.3 index 3f25e60..dc1ec7f 100644 --- a/man3/realpath.3 +++ b/man3/realpath.3 @@ -6,7 +6,7 @@ .\" Rewritten old page, 990824, aeb@cwi.nl .\" 2004-12-14, mtk, added discussion of resolved_path == NULL .\" -.TH realpath 3 2023-07-20 "Linux man-pages 6.05.01" +.TH realpath 3 2023-10-31 "Linux man-pages 6.7" .SH NAME realpath \- return the canonicalized absolute pathname .SH LIBRARY @@ -16,16 +16,16 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "char *realpath(const char *restrict " path , .BI " char *restrict " resolved_path ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR realpath (): .nf _XOPEN_SOURCE >= 500 @@ -53,7 +53,7 @@ The resulting path will have no symbolic link, or .I "/../" components. -.PP +.P If .I resolved_path is specified as NULL, then @@ -74,7 +74,7 @@ If there is no error, .BR realpath () returns a pointer to the .IR resolved_path . -.PP +.P Otherwise, it returns NULL, the contents of the array .I resolved_path @@ -130,7 +130,6 @@ T{ .BR realpath () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS GNU extensions If the call fails with either @@ -147,12 +146,12 @@ that is not readable or does not exist is returned in POSIX.1-2008. .SH HISTORY 4.4BSD, POSIX.1-2001, Solaris. -.PP +.P POSIX.1-2001 says that the behavior if .I resolved_path is NULL is implementation-defined. POSIX.1-2008 specifies the behavior described in this page. -.PP +.P In 4.4BSD and Solaris, the limit on the pathname length is .B MAXPATHLEN (found in \fI\fP). @@ -164,7 +163,7 @@ as found in \fI\fP or provided by the .BR pathconf (3) function. A typical source fragment would be -.PP +.P .in +4n .EX #ifdef PATH_MAX @@ -176,9 +175,9 @@ A typical source fragment would be #endif .EE .in -.PP +.P (But see the BUGS section.) -.\".PP +.\".P .\" 2012-05-05, According to Casper Dik, the statement about .\" Solaris was not true at least as far back as 1997, and .\" may never have been true. @@ -217,7 +216,7 @@ The .I "resolved_path\ ==\ NULL" feature, not standardized in POSIX.1-2001, but standardized in POSIX.1-2008, allows this design problem to be avoided. -.\" .LP +.\" .P .\" The libc4 and libc5 implementation contained a buffer overflow .\" (fixed in libc-5.4.13). .\" Thus, set-user-ID programs like diff --git a/man3/recno.3 b/man3/recno.3 index a4a38d2..afc4e72 100644 --- a/man3/recno.3 +++ b/man3/recno.3 @@ -5,7 +5,7 @@ .\" .\" @(#)recno.3 8.5 (Berkeley) 8/18/94 .\" -.TH recno 3 2022-12-04 "Linux man-pages 6.05.01" +.TH recno 3 2023-10-31 "Linux man-pages 6.7" .UC 7 .SH NAME recno \- record number database access method @@ -26,7 +26,7 @@ Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the .I libdb library instead. -.PP +.P The routine .BR dbopen (3) is the library interface to database files. @@ -34,7 +34,7 @@ One of the supported file formats is record number files. The general description of the database access methods is in .BR dbopen (3), this manual page describes only the recno-specific information. -.PP +.P The record number data structure is either variable or fixed-length records stored in a flat-file format, accessed by the logical record number. @@ -43,13 +43,13 @@ one through four, and the deletion of record number one causes record number five to be renumbered to record number four, as well as the cursor, if positioned after record number one, to shift down one record. -.PP +.P The recno access-method-specific data structure provided to .BR dbopen (3) is defined in the .I include file as follows: -.PP +.P .in +4n .EX typedef struct { @@ -63,7 +63,7 @@ typedef struct { } RECNOINFO; .EE .in -.PP +.P The elements of this structure are defined as follows: .TP .I flags @@ -151,7 +151,7 @@ is non-NULL, it specifies the name of the btree file, as if specified as the filename for a .BR dbopen (3) of a btree file. -.PP +.P The data part of the key/data pair used by the .I recno access method @@ -169,12 +169,12 @@ the implementation. The .I size field of the key should be the size of that type. -.PP +.P Because there can be no metadata associated with the underlying recno access method files, any changes made to the default values (e.g., fixed record length or byte separator value) must be explicitly specified each time the file is opened. -.PP +.P In the interface specified by .BR dbopen (3), using the @@ -201,7 +201,7 @@ Only big and little endian byte order is supported. .BR dbopen (3), .BR hash (3), .BR mpool (3) -.PP +.P .IR "Document Processing in a Relational Database System" , Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman, Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982. diff --git a/man3/regex.3 b/man3/regex.3 index fe6a6b3..fb641ef 100644 --- a/man3/regex.3 +++ b/man3/regex.3 @@ -10,7 +10,7 @@ .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) .\" .\" show the synopsis section nicely -.TH regex 3 2023-07-20 "Linux man-pages 6.05.01" +.TH regex 3 2023-10-31 "Linux man-pages 6.7" .SH NAME regcomp, regexec, regerror, regfree \- POSIX regex functions .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex , .BI " int " cflags ); .BI "int regexec(const regex_t *restrict " preg \ @@ -27,21 +27,21 @@ Standard C library .BI " size_t " nmatch ", \ regmatch_t " pmatch "[_Nullable restrict ." nmatch ], .BI " int " eflags ); -.PP +.P .BI "size_t regerror(int " errcode ", const regex_t *_Nullable restrict " preg , .BI " char " errbuf "[_Nullable restrict ." errbuf_size ], .BI " size_t " errbuf_size ); .BI "void regfree(regex_t *" preg ); -.PP +.P .B typedef struct { .B " size_t re_nsub;" .B } regex_t; -.PP +.P .B typedef struct { .B " regoff_t rm_so;" .B " regoff_t rm_eo;" .B } regmatch_t; -.PP +.P .BR typedef " /* ... */ " regoff_t; .fi .SH DESCRIPTION @@ -51,7 +51,7 @@ is used to compile a regular expression into a form that is suitable for subsequent .BR regexec () searches. -.PP +.P On success, the pattern buffer at .I *preg is initialized. @@ -59,7 +59,7 @@ is initialized. is a null-terminated string. The locale must be the same when running .BR regexec (). -.PP +.P After .BR regcomp () succeeds, @@ -74,7 +74,7 @@ passed as to .BR regexec () is sufficient to capture all matches. -.PP +.P .I cflags is the bitwise OR @@ -205,12 +205,12 @@ unused elements of .I pmatch are filled with .BR \-1 s. -.PP +.P Each returned valid .RB (non- \-1 ) match corresponds to the range .RI [ "string + rm_so" , " string + rm_eo" ). -.PP +.P .I regoff_t is a signed integer type capable of storing the largest value that can be stored in either an @@ -225,14 +225,14 @@ is used to turn the error codes that can be returned by both and .BR regexec () into error message strings. -.PP +.P If .I preg isn't a null pointer, .I errcode must be the latest error returned from an operation on .IR preg . -.PP +.P If .I errbuf_size isn't 0, up to @@ -251,12 +251,12 @@ must have been initialized via .SH RETURN VALUE .BR regcomp () returns zero for a successful compilation or an error code for failure. -.PP +.P .BR regexec () returns zero for a successful match or .B REG_NOMATCH for failure. -.PP +.P .BR regerror () returns the size of the buffer required to hold the string. .SH ERRORS @@ -333,12 +333,11 @@ T{ .BR regfree () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Prior to POSIX.1-2008, .I regoff_t was required to be @@ -353,7 +352,7 @@ is only required to be initialized if .B REG_NOSUB wasn't specified, but all known implementations initialize it regardless. .\" glibc, musl, 4.4BSD, illumos -.PP +.P Both .I regex_t and @@ -407,6 +406,6 @@ int main(void) .SH SEE ALSO .BR grep (1), .BR regex (7) -.PP +.P The glibc manual section, .I "Regular Expressions" diff --git a/man3/remainder.3 b/man3/remainder.3 index df97879..774b355 100644 --- a/man3/remainder.3 +++ b/man3/remainder.3 @@ -15,7 +15,7 @@ .\" (walter.harms@informatik.uni-oldenburg.de) .\" Modified 2003-11-18, 2004-10-05 aeb .\" -.TH remainder 3 2023-07-20 "Linux man-pages 6.05.01" +.TH remainder 3 2023-10-31 "Linux man-pages 6.7" .SH NAME drem, dremf, dreml, remainder, remainderf, remainderl \- \ floating-point remainder function @@ -25,22 +25,22 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double remainder(double " x ", double " y ); .BI "float remainderf(float " x ", float " y ); .BI "long double remainderl(long double " x ", long double " y ); -.PP +.P /* Obsolete synonyms */ .BI "[[deprecated]] double drem(double " x ", double " y ); .BI "[[deprecated]] float dremf(float " x ", float " y ); .BI "[[deprecated]] long double dreml(long double " x ", long double " y ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR remainder (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -49,7 +49,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR remainderf (), .BR remainderl (): .nf @@ -57,7 +57,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR drem (), .BR dremf (), .BR dreml (): @@ -83,10 +83,10 @@ If the absolute value of is 0.5, .I n is chosen to be even. -.PP +.P These functions are unaffected by the current rounding mode (see .BR fenv (3)). -.PP +.P The .BR drem () function does precisely the same thing. @@ -96,13 +96,13 @@ functions return the floating-point remainder, \fIx\fP\-\fIn\fP*\fIy\fP. If the return value is 0, it has the sign of .IR x . -.PP +.P If .I x or .I y is a NaN, a NaN is returned. -.PP +.P If .I x is an infinity, @@ -111,7 +111,7 @@ and is not a NaN, a domain error occurs, and a NaN is returned. -.PP +.P If .I y is zero, @@ -127,7 +127,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity and \fIy\fP is not a NaN @@ -169,7 +169,6 @@ T{ .BR remainderl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .\" IEC 60559. .TP @@ -207,16 +206,16 @@ Tru64, glibc2. Before glibc 2.15, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6779 the call -.PP +.P .in +4n .EX remainder(nan(""), 0); .EE .in -.PP +.P returned a NaN, as expected, but wrongly caused a domain error. Since glibc 2.15, a silent NaN (i.e., no domain error) is returned. -.PP +.P Before glibc 2.15, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6783 .I errno diff --git a/man3/remove.3 b/man3/remove.3 index d814d71..48ca0a6 100644 --- a/man3/remove.3 +++ b/man3/remove.3 @@ -9,7 +9,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH remove 3 2023-07-20 "Linux man-pages 6.05.01" +.TH remove 3 2023-10-31 "Linux man-pages 6.7" .SH NAME remove \- remove a file or directory .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int remove(const char *" pathname ); .fi .SH DESCRIPTION @@ -29,18 +29,18 @@ It calls for files, and .BR rmdir (2) for directories. -.PP +.P If the removed name was the last link to a file and no processes have the file open, the file is deleted and the space it was using is made available for reuse. -.PP +.P If the name was the last link to a file, but any processes still have the file open, the file will remain in existence until the last file descriptor referring to it is closed. -.PP +.P If the name referred to a symbolic link, the link is removed. -.PP +.P If the name referred to a socket, FIFO, or device, the name is removed, but processes which have the object open may continue to use it. .SH RETURN VALUE @@ -67,7 +67,6 @@ T{ .BR remove () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/remquo.3 b/man3/remquo.3 index 4fd76ea..8dcfec0 100644 --- a/man3/remquo.3 +++ b/man3/remquo.3 @@ -8,7 +8,7 @@ .\" based on glibc infopages .\" polished, aeb .\" -.TH remquo 3 2023-07-20 "Linux man-pages 6.05.01" +.TH remquo 3 2023-10-31 "Linux man-pages 6.7" .SH NAME remquo, remquof, remquol \- remainder and part of quotient .SH LIBRARY @@ -17,17 +17,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double remquo(double " x ", double " y ", int *" quo ); .BI "float remquof(float " x ", float " y ", int *" quo ); .BI "long double remquol(long double " x ", long double " y ", int *" quo ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR remquo (), .BR remquof (), .BR remquol (): @@ -44,17 +44,17 @@ A few bits of the quotient are stored via the .I quo pointer. The remainder is returned as the function result. -.PP +.P The value of the remainder is the same as that computed by the .BR remainder (3) function. -.PP +.P The value stored via the .I quo pointer has the sign of .I x\~/\~y and agrees with the quotient in at least the low order 3 bits. -.PP +.P For example, \fIremquo(29.0,\ 3.0)\fP returns \-1.0 and might store 2. Note that the actual quotient might not fit in an integer. .\" A possible application of this function might be the computation @@ -66,13 +66,13 @@ Note that the actual quotient might not fit in an integer. On success, these functions return the same value as the analogous functions described in .BR remainder (3). -.PP +.P If .I x or .I y is a NaN, a NaN is returned. -.PP +.P If .I x is an infinity, @@ -81,7 +81,7 @@ and is not a NaN, a domain error occurs, and a NaN is returned. -.PP +.P If .I y is zero, @@ -95,7 +95,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity or \fIy\fP is 0, \ @@ -106,7 +106,7 @@ and the other argument is not a NaN An invalid floating-point exception .RB ( FE_INVALID ) is raised. -.PP +.P These functions do not set .IR errno . .\" FIXME . Is it intentional that these functions do not set errno? @@ -127,7 +127,6 @@ T{ .BR remquol () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/resolver.3 b/man3/resolver.3 index 416951f..f44c51b 100644 --- a/man3/resolver.3 +++ b/man3/resolver.3 @@ -11,7 +11,7 @@ .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) .\" Modified 2004-10-31 by aeb .\" -.TH resolver 3 2023-07-20 "Linux man-pages 6.05.01" +.TH resolver 3 2023-10-31 "Linux man-pages 6.7" .SH NAME res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, res_nclose, @@ -26,71 +26,71 @@ Resolver library .B #include .B #include .B #include -.PP +.P .B struct __res_state; .B typedef struct __res_state *res_state; -.PP +.P .BI "int res_ninit(res_state " statep ); -.PP +.P .BI "void res_nclose(res_state " statep ); -.PP +.P .BI "int res_nquery(res_state " statep , .BI " const char *" dname ", int " class ", int " type , .BI " unsigned char " answer [. anslen "], int " anslen ); -.PP +.P .BI "int res_nsearch(res_state " statep , .BI " const char *" dname ", int " class ", int " type , .BI " unsigned char " answer [. anslen "], int " anslen ); -.PP +.P .BI "int res_nquerydomain(res_state " statep , .BI " const char *" name ", const char *" domain , .BI " int " class ", int " type ", unsigned char " answer [. anslen ], .BI " int " anslen ); -.PP +.P .BI "int res_nmkquery(res_state " statep , .BI " int " op ", const char *" dname ", int " class , .BI " int " type ", const unsigned char " data [. datalen "], \ int " datalen , .BI " const unsigned char *" newrr , .BI " unsigned char " buf [. buflen "], int " buflen ); -.PP +.P .BI "int res_nsend(res_state " statep , .BI " const unsigned char " msg [. msglen "], int " msglen , .BI " unsigned char " answer [. anslen "], int " anslen ); -.PP +.P .BI "int dn_comp(const char *" exp_dn ", unsigned char " comp_dn [. length ], .BI " int " length ", unsigned char **" dnptrs , .BI " unsigned char **" lastdnptr ); -.PP +.P .BI "int dn_expand(const unsigned char *" msg , .BI " const unsigned char *" eomorig , .BI " const unsigned char *" comp_dn ", char " exp_dn [. length ], .BI " int " length ); -.PP +.P .B [[deprecated]] extern struct __res_state _res; -.PP +.P .B [[deprecated]] int res_init(void); -.PP +.P .B [[deprecated]] .BI "int res_query(const char *" dname ", int " class ", int " type , .BI " unsigned char " answer [. anslen "], int " anslen ); -.PP +.P .B [[deprecated]] .BI "int res_search(const char *" dname ", int " class ", int " type , .BI " unsigned char " answer [. anslen "], int " anslen ); -.PP +.P .B [[deprecated]] .BI "int res_querydomain(const char *" name ", const char *" domain , .BI " int " class ", int " type ", unsigned char " answer [. anslen ], .BI " int " anslen ); -.PP +.P .B [[deprecated]] .BI "int res_mkquery(int " op ", const char *" dname ", int " class , .BI " int " type ", const unsigned char " data [. datalen "], \ int " datalen , .BI " const unsigned char *" newrr , .BI " unsigned char " buf [. buflen "], int " buflen ); -.PP +.P .B [[deprecated]] .BI "int res_send(const unsigned char " msg [. msglen "], int " msglen , .BI " unsigned char " answer [. anslen "], int " anslen ); @@ -99,10 +99,10 @@ int " datalen , .B Note: This page is incomplete (various resolver functions provided by glibc are not described) and likely out of date. -.PP +.P The functions described below make queries to and interpret the responses from Internet domain name servers. -.PP +.P The API consists of a set of more modern, reentrant functions and an older set of nonreentrant functions that have been superseded. The traditional resolver interfaces such as @@ -118,7 +118,7 @@ BIND 8.2 introduced a set of new interfaces and so on, which take a .I res_state as their first argument, so you can use a per-thread resolver state. -.PP +.P The .BR res_ninit () and @@ -144,7 +144,7 @@ to free memory allocated by .BR res_ninit () and subsequent calls to .BR res_nquery (). -.PP +.P The .BR res_nquery () and @@ -154,7 +154,7 @@ fully qualified domain name \fIname\fP of specified \fItype\fP and \fIclass\fP. The reply is left in the buffer \fIanswer\fP of length \fIanslen\fP supplied by the caller. -.PP +.P The .BR res_nsearch () and @@ -170,7 +170,7 @@ and .B RES_DNSRCH (see description of \fI_res\fP options below). -.PP +.P The .BR res_nquerydomain () and @@ -178,10 +178,10 @@ and functions make a query using .BR res_nquery ()/ res_query () on the concatenation of \fIname\fP and \fIdomain\fP. -.PP +.P The following functions are lower-level routines used by .BR res_nquery ()/ res_query (). -.PP +.P The .BR res_nmkquery () and @@ -203,9 +203,9 @@ since it has not been supported by DNS servers for a very long time. .TP .B NS_NOTIFY_OP Notify secondary of SOA (Start of Authority) change. -.PP +.P \fInewrr\fP is currently unused. -.PP +.P The .BR res_nsend () and @@ -216,7 +216,7 @@ which is of length \fIanslen\fP. They will call .BR res_ninit ()/ res_init () if it has not already been called. -.PP +.P The .BR dn_comp () function compresses the domain name \fIexp_dn\fP @@ -229,7 +229,7 @@ The limit of the array is specified by \fIlastdnptr\fP. If \fIdnptr\fP is NULL, domain names are not compressed. If \fIlastdnptr\fP is NULL, the list of labels is not updated. -.PP +.P The .BR dn_expand () function expands the compressed domain name @@ -238,7 +238,7 @@ function expands the compressed domain name The compressed name is contained in a query or reply message, and \fImsg\fP points to the beginning of the message. -.PP +.P The resolver routines use configuration and state information contained in a .I __res_state @@ -427,7 +427,7 @@ and .BR res_init () functions return 0 on success, or \-1 if an error occurs. -.PP +.P The .BR res_nquery (), .BR res_query (), @@ -442,14 +442,14 @@ and .BR res_send () functions return the length of the response, or \-1 if an error occurs. -.PP +.P The .BR dn_comp () and .BR dn_expand () functions return the length of the compressed name, or \-1 if an error occurs. -.PP +.P In the case of an error return from .BR res_nquery (), .BR res_query (), @@ -496,7 +496,6 @@ T{ .BR dn_expand () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -507,6 +506,6 @@ None. .BR resolver (5), .BR hostname (7), .BR named (8) -.PP +.P The GNU C library source file .IR resolv/README . diff --git a/man3/rewinddir.3 b/man3/rewinddir.3 index 61221ba..fbc8b1a 100644 --- a/man3/rewinddir.3 +++ b/man3/rewinddir.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sat Jul 24 18:29:11 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl) -.TH rewinddir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rewinddir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rewinddir \- reset directory stream .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "void rewinddir(DIR *" dirp ); .fi .SH DESCRIPTION @@ -47,7 +47,6 @@ T{ .BR rewinddir () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/rexec.3 b/man3/rexec.3 index 7f94d27..ca680d3 100644 --- a/man3/rexec.3 +++ b/man3/rexec.3 @@ -11,7 +11,7 @@ .\" .\" 2013-06-21, mtk, Converted from mdoc to man macros .\" -.TH rexec 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rexec 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rexec, rexec_af \- return stream to a remote command .SH LIBRARY @@ -20,19 +20,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B [[deprecated]] .BI "int rexec(char **restrict " ahost ", int " inport , .BI " const char *restrict " user ", const char *restrict " passwd , .BI " const char *restrict " cmd ", int *restrict " fd2p ); -.PP +.P .B [[deprecated]] .BI "int rexec_af(char **restrict " ahost ", int " inport , .BI " const char *restrict " user ", const char *restrict " passwd , .BI " const char *restrict " cmd ", int *restrict " fd2p , .BI " sa_family_t " af ); .fi -.PP +.P .BR rexec (), .BR rexec_af (): .nf @@ -44,7 +44,7 @@ Standard C library .SH DESCRIPTION This interface is obsoleted by .BR rcmd (3). -.PP +.P The .BR rexec () function @@ -63,7 +63,7 @@ the environment and then the file in user's home directory are searched for appropriate information. If all this fails, the user is prompted for the information. -.PP +.P The port .I inport specifies which well-known DARPA Internet port to use for @@ -74,7 +74,7 @@ the connection; the call will return a pointer to a structure that contains the necessary port. The protocol for connection is described in detail in .BR rexecd (8). -.PP +.P If the connection succeeds, a socket in the Internet domain of type .B SOCK_STREAM @@ -138,7 +138,6 @@ T{ .BR rexec_af () T} Thread safety MT-Unsafe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -152,7 +151,7 @@ glibc 2.2. The .BR rexec () function sends the unencrypted password across the network. -.PP +.P The underlying service is considered a big security hole and therefore not enabled on many sites; see .BR rexecd (8) diff --git a/man3/rint.3 b/man3/rint.3 index 945f48b..812d6ae 100644 --- a/man3/rint.3 +++ b/man3/rint.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH rint 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rint 3 2023-10-31 "Linux man-pages 6.7" .SH NAME nearbyint, nearbyintf, nearbyintl, rint, rintf, rintl \- round to nearest integer @@ -15,28 +15,28 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double nearbyint(double " x ); .BI "float nearbyintf(float " x ); .BI "long double nearbyintl(long double " x ); -.PP +.P .BI "double rint(double " x ); .BI "float rintf(float " x ); .BI "long double rintl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR nearbyint (), .BR nearbyintf (), .BR nearbyintl (): .nf _POSIX_C_SOURCE >= 200112L || _ISOC99_SOURCE .fi -.PP +.P .BR rint (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR rintf (), .BR rintl (): .nf @@ -68,7 +68,7 @@ exception. When the current rounding direction is to nearest, these functions round halfway cases to the even integer in accordance with IEEE-754. -.PP +.P The .BR rint (), .BR rintf (), @@ -83,7 +83,7 @@ checkable via when the result differs in value from the argument. .SH RETURN VALUE These functions return the rounded integer value. -.PP +.P If .I x is integral, +0, \-0, NaN, or infinite, @@ -111,7 +111,6 @@ T{ .BR rintl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -133,7 +132,7 @@ the maximum value of the exponent is 127 (respectively, 1023), and the number of mantissa bits including the implicit bit is 24 (respectively, 53).) -.PP +.P If you want to store the rounded value in an integer type, you probably want to use one of the functions described in .BR lrint (3) diff --git a/man3/round.3 b/man3/round.3 index 591875f..4e27fd6 100644 --- a/man3/round.3 +++ b/man3/round.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH round 3 2023-07-20 "Linux man-pages 6.05.01" +.TH round 3 2023-10-31 "Linux man-pages 6.7" .SH NAME round, roundf, roundl \- round to nearest integer, away from zero .SH LIBRARY @@ -14,17 +14,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double round(double " x ); .BI "float roundf(float " x ); .BI "long double roundl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR round (), .BR roundf (), .BR roundl (): @@ -40,7 +40,7 @@ direction, see .BR fenv (3)), instead of to the nearest even integer like .BR rint (3). -.PP +.P For example, .I round(0.5) is 1.0, and @@ -48,7 +48,7 @@ is 1.0, and is \-1.0. .SH RETURN VALUE These functions return the rounded integer value. -.PP +.P If .I x is integral, +0, \-0, NaN, or infinite, @@ -73,7 +73,6 @@ T{ .BR roundl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -97,7 +96,7 @@ the maximum value of the exponent is 127 (respectively, 1023), and the number of mantissa bits including the implicit bit is 24 (respectively, 53).) -.PP +.P If you want to store the rounded value in an integer type, you probably want to use one of the functions described in .BR lround (3) diff --git a/man3/roundup.3 b/man3/roundup.3 index d21949e..bcde64a 100644 --- a/man3/roundup.3 +++ b/man3/roundup.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH roundup 3 2023-03-30 "Linux man-pages 6.05.01" +.TH roundup 3 2023-10-31 "Linux man-pages 6.7" .SH NAME roundup \- round up in steps .SH LIBRARY @@ -11,7 +11,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI roundup( x ", " step ); .fi .SH DESCRIPTION @@ -21,11 +21,11 @@ to the nearest multiple of .I step that is not less than .IR x . -.PP +.P It is typically used for rounding up a pointer to align it or increasing a buffer to be allocated. -.PP +.P This API is not designed to be generic, and doesn't work in some cases that are not important for the typical use cases described above. @@ -36,13 +36,13 @@ This macro returns the rounded value. None. .SH CAVEATS The arguments may be evaluated more than once. -.PP +.P .I x should be nonnegative, and .I step should be positive. -.PP +.P If .I x + step would overflow or wrap around, diff --git a/man3/rpc.3 b/man3/rpc.3 index 4923e8a..b5d238c 100644 --- a/man3/rpc.3 +++ b/man3/rpc.3 @@ -9,7 +9,7 @@ .\" .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax .\" -.TH rpc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rpc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rpc \- library routines for remote procedure calls .SH LIBRARY @@ -22,28 +22,28 @@ First, the client calls a procedure to send a data packet to the server. Upon receipt of the packet, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. -.\" .LP +.\" .P .\" We don't have an rpc_secure.3 page at the moment -- MTK, 19 Sep 05 .\" Routines that are used for Secure RPC (DES authentication) are described in .\" .BR rpc_secure (3). .\" Secure RPC can be used only if DES encryption is available. -.PP +.P To take use of these routines, include the header file .IR "" . -.PP +.P The prototypes below make use of the following types: -.PP +.P .RS 4 .EX .BI "typedef int " bool_t ; -.PP +.P .BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *, ...);" -.PP +.P .BI "typedef bool_t (*" resultproc_t ")(caddr_t " resp , .BI " struct sockaddr_in *" raddr ); .EE .RE -.PP +.P See the header files for the declarations of the .IR AUTH , .IR CLIENT , @@ -51,7 +51,7 @@ See the header files for the declarations of the and .I XDR types. -.PP +.P .nf .BI "void auth_destroy(AUTH *" auth ); .fi @@ -63,7 +63,7 @@ The use of .I auth is undefined after calling .BR auth_destroy (). -.PP +.P .nf .B AUTH *authnone_create(void); .fi @@ -72,7 +72,7 @@ Create and return an RPC authentication handle that passes nonusable authentication information with each remote procedure call. This is the default authentication used by RPC. -.PP +.P .nf .BI "AUTH *authunix_create(char *" host ", uid_t " uid ", gid_t " gid , .BI " int " len ", gid_t " aup_gids [. len ]); @@ -92,7 +92,7 @@ and .I aup_gids refer to a counted array of groups to which the user belongs. It is easy to impersonate a user. -.PP +.P .nf .B AUTH *authunix_create_default(void); .fi @@ -100,7 +100,7 @@ It is easy to impersonate a user. Calls .BR authunix_create () with the appropriate parameters. -.PP +.P .nf .BI "int callrpc(char *" host ", unsigned long " prognum , .BI " unsigned long " versnum ", unsigned long " procnum , @@ -136,7 +136,7 @@ uses UDP/IP as a transport; see .BR clntudp_create () for restrictions. You do not have control of timeouts or authentication using this routine. -.PP +.P .nf .BI "enum clnt_stat clnt_broadcast(unsigned long " prognum , .BI " unsigned long " versnum ", unsigned long " procnum , @@ -177,7 +177,7 @@ waits for more replies; otherwise it returns with appropriate status. Warning: broadcast sockets are limited in size to the maximum transfer unit of the data link. For ethernet, this value is 1500 bytes. -.PP +.P .nf .BI "enum clnt_stat clnt_call(CLIENT *" clnt ", unsigned long " procnum , .BI " xdrproc_t " inproc ", char *" in , @@ -202,7 +202,7 @@ is used to encode the procedure's parameters, and is used to decode the procedure's results; .I tout is the time allowed for results to come back. -.PP +.P .nf .BI "clnt_destroy(CLIENT *" clnt ); .fi @@ -218,7 +218,7 @@ is undefined after calling .BR clnt_destroy (). If the RPC library opened the associated socket, it will close it also. Otherwise, the socket remains open. -.PP +.P .nf .BI "CLIENT *clnt_create(const char *" host ", unsigned long " prog , .BI " unsigned long " vers ", const char *" proto ); @@ -238,7 +238,7 @@ Warning: using UDP has its shortcomings. Since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. -.PP +.P .nf .BI "bool_t clnt_control(CLIENT *" cl ", int " req ", char *" info ); .fi @@ -285,7 +285,7 @@ The following operations are valid for UDP only: The retry timeout is the time that "UDP RPC" waits for the server to reply before retransmitting the request. -.PP +.P .nf .BI "clnt_freeres(CLIENT * " clnt ", xdrproc_t " outproc ", char *" out ); .fi @@ -299,7 +299,7 @@ is the address of the results, and is the XDR routine describing the results. This routine returns one if the results were successfully freed, and zero otherwise. -.PP +.P .nf .BI "void clnt_geterr(CLIENT *" clnt ", struct rpc_err *" errp ); .fi @@ -307,7 +307,7 @@ and zero otherwise. A macro that copies the error structure out of the client handle to the structure at address .IR errp . -.PP +.P .nf .BI "void clnt_pcreateerror(const char *" s ); .fi @@ -324,7 +324,7 @@ Used when a or .BR clntudp_create () call fails. -.PP +.P .nf .BI "void clnt_perrno(enum clnt_stat " stat ); .fi @@ -334,7 +334,7 @@ to the condition indicated by .IR stat . Used after .BR callrpc (). -.PP +.P .nf .BI "clnt_perror(CLIENT *" clnt ", const char *" s ); .fi @@ -347,7 +347,7 @@ The message is prepended with string and a colon. Used after .BR clnt_call (). -.PP +.P .nf .BI "char *clnt_spcreateerror(const char *" s ); .fi @@ -357,7 +357,7 @@ Like except that it returns a string instead of printing to the standard error. .IP Bugs: returns pointer to static data that is overwritten on each call. -.PP +.P .nf .BI "char *clnt_sperrno(enum clnt_stat " stat ); .fi @@ -385,7 +385,7 @@ and .BR clnt_sperrno () returns pointer to static data, but the result will not get overwritten on each call. -.PP +.P .nf .BI "char *clnt_sperror(CLIENT *" rpch ", const char *" s ); .fi @@ -397,7 +397,7 @@ except that (like it returns a string instead of printing to standard error. .IP Bugs: returns pointer to static data that is overwritten on each call. -.PP +.P .nf .BI "CLIENT *clntraw_create(unsigned long " prognum \ ", unsigned long " versnum ); @@ -414,7 +414,7 @@ corresponding RPC server should live in the same address space; see This allows simulation of RPC and acquisition of RPC overheads, such as round trip times, without any kernel interference. This routine returns NULL if it fails. -.PP +.P .nf .BI "CLIENT *clnttcp_create(struct sockaddr_in *" addr , .BI " unsigned long " prognum ", unsigned long " versnum , @@ -450,7 +450,7 @@ and .IR recvsz ; values of zero choose suitable defaults. This routine returns NULL if it fails. -.PP +.P .nf .BI "CLIENT *clntudp_create(struct sockaddr_in *" addr , .BI " unsigned long " prognum ", unsigned long " versnum , @@ -485,7 +485,7 @@ The total time for the call to time out is specified by Warning: since UDP-based RPC messages can hold only up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take large arguments or return huge results. -.PP +.P .nf .BI "CLIENT *clntudp_bufcreate(struct sockaddr_in *" addr , .BI " unsigned long " prognum ", unsigned long " versnum , @@ -520,7 +520,7 @@ The total time for the call to time out is specified by .IP This allows the user to specify the maximum packet size for sending and receiving UDP-based RPC messages. -.PP +.P .nf .BI "void get_myaddress(struct sockaddr_in *" addr ); .fi @@ -531,7 +531,7 @@ without consulting the library routines that deal with .IR /etc/hosts . The port number is always set to .BR htons(PMAPPORT) . -.PP +.P .nf .BI "struct pmaplist *pmap_getmaps(struct sockaddr_in *" addr ); .fi @@ -545,7 +545,7 @@ This routine can return NULL. The command .I rpcinfo\~\-p uses this routine. -.PP +.P .nf .BI "unsigned short pmap_getport(struct sockaddr_in *" addr , .BI " unsigned long " prognum ", unsigned long " versnum , @@ -574,7 +574,7 @@ service. In the latter case, the global variable .I rpc_createerr contains the RPC status. -.PP +.P .nf .BI "enum clnt_stat pmap_rmtcall(struct sockaddr_in *" addr , .BI " unsigned long " prognum ", unsigned long " versnum , @@ -602,7 +602,7 @@ and This procedure should be used for a \[lq]ping\[rq] and nothing else. See also .BR clnt_broadcast (). -.PP +.P .nf .BI "bool_t pmap_set(unsigned long " prognum ", unsigned long " versnum , .BI " int " protocol ", unsigned short " port ); @@ -626,7 +626,7 @@ or This routine returns one if it succeeds, zero otherwise. Automatically done by .BR svc_register (). -.PP +.P .nf .BI "bool_t pmap_unset(unsigned long " prognum ", unsigned long " versnum ); .fi @@ -641,7 +641,7 @@ on the machine's .B portmap service. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "int registerrpc(unsigned long " prognum ", unsigned long " versnum , .BI " unsigned long " procnum ", char *(*" procname ")(char *)," @@ -671,7 +671,7 @@ Warning: remote procedures registered in this form are accessed using the UDP/IP transport; see .BR svcudp_create () for restrictions. -.PP +.P .nf .BI "struct rpc_createerr " rpc_createerr ; .fi @@ -681,7 +681,7 @@ that does not succeed. Use the routine .BR clnt_pcreateerror () to print the reason why. -.PP +.P .nf .BI "void svc_destroy(SVCXPRT *" xprt ); .fi @@ -695,7 +695,7 @@ itself. Use of .I xprt is undefined after calling this routine. -.PP +.P .nf .BI "fd_set " svc_fdset ; .fi @@ -712,7 +712,7 @@ This variable is read-only (do not pass its address to yet it may change after calls to .BR svc_getreqset () or any creation routines. -.PP +.P .nf .BI "int " svc_fds ; .fi @@ -722,7 +722,7 @@ Similar to but limited to 32 file descriptors. This interface is obsoleted by .BR svc_fdset . -.PP +.P .nf .BI "svc_freeargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); .fi @@ -732,7 +732,7 @@ system when it decoded the arguments to a service procedure using .BR svc_getargs (). This routine returns 1 if the results were successfully freed, and zero otherwise. -.PP +.P .nf .BI "svc_getargs(SVCXPRT *" xprt ", xdrproc_t " inproc ", char *" in ); .fi @@ -746,7 +746,7 @@ is the address where the arguments will be placed; .I inproc is the XDR routine used to decode the arguments. This routine returns one if decoding succeeds, and zero otherwise. -.PP +.P .nf .BI "struct sockaddr_in *svc_getcaller(SVCXPRT *" xprt ); .fi @@ -754,7 +754,7 @@ This routine returns one if decoding succeeds, and zero otherwise. The approved way of getting the network address of the caller of a procedure associated with the RPC service transport handle, .IR xprt . -.PP +.P .nf .BI "void svc_getreqset(fd_set *" rdfds ); .fi @@ -771,7 +771,7 @@ is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfds have been serviced. -.PP +.P .nf .BI "void svc_getreq(int " rdfds ); .fi @@ -781,7 +781,7 @@ Similar to but limited to 32 file descriptors. This interface is obsoleted by .BR svc_getreqset (). -.PP +.P .nf .BI "bool_t svc_register(SVCXPRT *" xprt ", unsigned long " prognum , .BI " unsigned long " versnum , @@ -827,7 +827,7 @@ dispatch(struct svc_req *request, SVCXPRT *xprt); The .BR svc_register () routine returns one if it succeeds, and zero otherwise. -.PP +.P .nf .B "void svc_run(void);" .fi @@ -840,7 +840,7 @@ when one arrives. This procedure is usually waiting for a .BR select (2) system call to return. -.PP +.P .nf .BI "bool_t svc_sendreply(SVCXPRT *" xprt ", xdrproc_t " outproc \ ", char *" out ); @@ -856,7 +856,7 @@ is the XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "void svc_unregister(unsigned long " prognum ", unsigned long " versnum ); .fi @@ -866,14 +866,14 @@ Remove all mapping of the double to dispatch routines, and of the triple .RI [ prognum , versnum , * ] to port number. -.PP +.P .nf .BI "void svcerr_auth(SVCXPRT *" xprt ", enum auth_stat " why ); .fi .IP Called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error. -.PP +.P .nf .BI "void svcerr_decode(SVCXPRT *" xprt ); .fi @@ -882,21 +882,21 @@ Called by a service dispatch routine that cannot successfully decode its parameters. See also .BR svc_getargs (). -.PP +.P .nf .BI "void svcerr_noproc(SVCXPRT *" xprt ); .fi .IP Called by a service dispatch routine that does not implement the procedure number that the caller requests. -.PP +.P .nf .BI "void svcerr_noprog(SVCXPRT *" xprt ); .fi .IP Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. -.PP +.P .nf .BI "void svcerr_progvers(SVCXPRT *" xprt ", unsigned long " low_vers , .BI " unsigned long " high_vers ); @@ -905,7 +905,7 @@ Service implementors usually do not need this routine. Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. -.PP +.P .nf .BI "void svcerr_systemerr(SVCXPRT *" xprt ); .fi @@ -914,7 +914,7 @@ Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. -.PP +.P .nf .BI "void svcerr_weakauth(SVCXPRT *" xprt ); .fi @@ -923,7 +923,7 @@ Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .BR "svcerr_auth(xprt, AUTH_TOOWEAK)" . -.PP +.P .nf .BI "SVCXPRT *svcfd_create(int " fd ", unsigned int " sendsize , .BI " unsigned int " recvsize ); @@ -937,7 +937,7 @@ and .I recvsize indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. -.PP +.P .nf .B SVCXPRT *svcraw_create(void); .fi @@ -950,7 +950,7 @@ so the corresponding RPC client should live in the same address space; see This routine allows simulation of RPC and acquisition of RPC overheads (such as round trip times), without any kernel interference. This routine returns NULL if it fails. -.PP +.P .nf .BI "SVCXPRT *svctcp_create(int " sock ", unsigned int " send_buf_size , .BI " unsigned int " recv_buf_size ); @@ -974,7 +974,7 @@ This routine returns NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers; values of zero choose suitable defaults. -.PP +.P .nf .BI "SVCXPRT *svcudp_bufcreate(int " sock ", unsigned int " sendsize , .BI " unsigned int " recosize ); @@ -998,7 +998,7 @@ This routine returns NULL if it fails. .IP This allows the user to specify the maximum packet size for sending and receiving UDP-based RPC messages. -.PP +.P .nf .BI "SVCXPRT *svcudp_create(int " sock ); .fi @@ -1007,7 +1007,7 @@ This call is equivalent to .I svcudp_bufcreate(sock,SZ,SZ) for some default size .IR SZ . -.PP +.P .nf .BI "bool_t xdr_accepted_reply(XDR *" xdrs ", struct accepted_reply *" ar ); .fi @@ -1015,7 +1015,7 @@ for some default size Used for encoding RPC reply messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package. -.PP +.P .nf .BI "bool_t xdr_authunix_parms(XDR *" xdrs ", struct authunix_parms *" aupp ); .fi @@ -1024,7 +1024,7 @@ Used for describing UNIX credentials. This routine is useful for users who wish to generate these credentials without using the RPC authentication package. -.PP +.P .nf .BI "void xdr_callhdr(XDR *" xdrs ", struct rpc_msg *" chdr ); .fi @@ -1032,7 +1032,7 @@ authentication package. Used for describing RPC call header messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package. -.PP +.P .nf .BI "bool_t xdr_callmsg(XDR *" xdrs ", struct rpc_msg *" cmsg ); .fi @@ -1040,7 +1040,7 @@ RPC-style messages without using the RPC package. Used for describing RPC call messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package. -.PP +.P .nf .BI "bool_t xdr_opaque_auth(XDR *" xdrs ", struct opaque_auth *" ap ); .fi @@ -1048,7 +1048,7 @@ messages without using the RPC package. Used for describing RPC authentication information messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package. -.PP +.P .nf .BI "bool_t xdr_pmap(XDR *" xdrs ", struct pmap *" regs ); .fi @@ -1060,7 +1060,7 @@ This routine is useful for users who wish to generate these parameters without using the .B pmap interface. -.PP +.P .nf .BI "bool_t xdr_pmaplist(XDR *" xdrs ", struct pmaplist **" rp ); .fi @@ -1070,7 +1070,7 @@ This routine is useful for users who wish to generate these parameters without using the .B pmap interface. -.PP +.P .nf .BI "bool_t xdr_rejected_reply(XDR *" xdrs ", struct rejected_reply *" rr ); .fi @@ -1078,7 +1078,7 @@ interface. Used for describing RPC reply messages. This routine is useful for users who wish to generate RPC-style messages without using the RPC package. -.PP +.P .nf .BI "bool_t xdr_replymsg(XDR *" xdrs ", struct rpc_msg *" rmsg ); .fi @@ -1086,7 +1086,7 @@ RPC-style messages without using the RPC package. Used for describing RPC reply messages. This routine is useful for users who wish to generate RPC style messages without using the RPC package. -.PP +.P .nf .BI "void xprt_register(SVCXPRT *" xprt ); .fi @@ -1096,7 +1096,7 @@ they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. -.PP +.P .nf .BI "void xprt_unregister(SVCXPRT *" xprt ); .fi @@ -1181,12 +1181,11 @@ T{ .BR xprt_unregister () T} Thread safety MT-Safe .TE -.sp 1 .SH SEE ALSO .\" We don't have an rpc_secure.3 page in the set at the moment -- MTK, 19 Sep 05 .\" .BR rpc_secure (3), .BR xdr (3) -.PP +.P The following manuals: .RS Remote Procedure Calls: Protocol Specification @@ -1196,7 +1195,7 @@ Remote Procedure Call Programming Guide rpcgen Programming Guide .br .RE -.PP +.P .IR "RPC: Remote Procedure Call Protocol Specification" , RFC\ 1050, Sun Microsystems, Inc., USC-ISI. diff --git a/man3/rpmatch.3 b/man3/rpmatch.3 index ac3fa09..dac2474 100644 --- a/man3/rpmatch.3 +++ b/man3/rpmatch.3 @@ -27,7 +27,7 @@ .\" .\" 2006-05-19, mtk, various edits and example program .\" -.TH rpmatch 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rpmatch 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rpmatch \- determine if the answer to a question is affirmative or negative .SH LIBRARY @@ -36,15 +36,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int rpmatch(const char *" response ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR rpmatch (): .nf Since glibc 2.19: @@ -56,14 +56,14 @@ Feature Test Macro Requirements for glibc (see .BR rpmatch () handles a user response to yes or no questions, with support for internationalization. -.PP +.P .I response should be a null-terminated string containing a user-supplied response, perhaps obtained with .BR fgets (3) or .BR getline (3). -.PP +.P The user's language preference is taken into account per the environment variables .BR LANG , @@ -73,7 +73,7 @@ and if the program has called .BR setlocale (3) to effect their changes. -.PP +.P Regardless of the locale, responses matching .B \[ha][Yy] are always accepted as affirmative, and those matching @@ -92,7 +92,7 @@ is unrecognized. A return value of \-1 may indicate either an invalid input, or some other error. It is incorrect to only test if the return value is nonzero. -.PP +.P .BR rpmatch () can fail for any of the reasons that .BR regcomp (3) @@ -119,7 +119,6 @@ T{ .BR rpmatch () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -139,7 +138,7 @@ being the proper way to distinguish between binary answers. The following program displays the results when .BR rpmatch () is applied to the string given in the program's command-line argument. -.PP +.P .\" SRC BEGIN (rpmatch.c) .EX #define _DEFAULT_SOURCE diff --git a/man3/rtime.3 b/man3/rtime.3 index a866d0b..4d1a4a0 100644 --- a/man3/rtime.3 +++ b/man3/rtime.3 @@ -8,7 +8,7 @@ .\" .\" Slightly polished, aeb, 2003-04-06 .\" -.TH rtime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH rtime 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rtime \- get time from a remote machine .SH LIBRARY @@ -17,20 +17,20 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int rtime(struct sockaddr_in *" addrp ", struct rpc_timeval *" timep , .BI " struct rpc_timeval *" timeout ); .fi .SH DESCRIPTION This function uses the Time Server Protocol as described in RFC\ 868 to obtain the time from a remote machine. -.PP +.P The Time Server Protocol gives the time in seconds since 00:00:00 UTC, 1 Jan 1900, and this function subtracts the appropriate constant in order to convert the result to seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P When .I timeout is non-NULL, the udp/time socket (port 37) is used. @@ -70,23 +70,22 @@ T{ .BR rtime () T} Thread safety MT-Safe .TE -.sp 1 .SH NOTES Only IPv4 is supported. -.PP +.P Some .I in.timed versions support only TCP. Try the example program with .I use_tcp set to 1. -.\" .PP +.\" .P .\" Libc5 uses the prototype -.\" .PP +.\" .P .\" .nf .\" int rtime(struct sockaddr_in *, struct timeval *, struct timeval *); .\" .fi -.\" .PP +.\" .P .\" and requires .\" .I .\" instead of @@ -100,11 +99,11 @@ You may check that the time entry within .I /etc/inetd.conf is not commented out. -.PP +.P The program connects to a computer called "linux". Using "localhost" does not work. The result is the localtime of the computer "linux". -.PP +.P .\" SRC BEGIN (rtime.c) .EX #include diff --git a/man3/rtnetlink.3 b/man3/rtnetlink.3 index 7033d4b..b0f9f43 100644 --- a/man3/rtnetlink.3 +++ b/man3/rtnetlink.3 @@ -4,7 +4,7 @@ .\" .\" $Id: rtnetlink.3,v 1.2 1999/05/18 10:35:10 freitag Exp $ .\" -.TH rtnetlink 3 2023-07-15 "Linux man-pages 6.05.01" +.TH rtnetlink 3 2023-10-31 "Linux man-pages 6.7" .SH NAME rtnetlink \- macros to manipulate rtnetlink messages .SH LIBRARY @@ -16,18 +16,18 @@ Standard C library .B #include .B #include .B #include -.PP +.P .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type \ ", NETLINK_ROUTE);" -.PP +.P .BI "int RTA_OK(struct rtattr *" rta ", int " rtabuflen ); -.PP +.P .BI "void *RTA_DATA(struct rtattr *" rta ); .BI "unsigned int RTA_PAYLOAD(struct rtattr *" rta ); -.PP +.P .BI "struct rtattr *RTA_NEXT(struct rtattr *" rta \ ", unsigned int " rtabuflen ); -.PP +.P .BI "unsigned int RTA_LENGTH(unsigned int " length ); .BI "unsigned int RTA_SPACE(unsigned int "length ); .fi @@ -38,7 +38,7 @@ messages consist of a .BR netlink (7) message header and appended attributes. The attributes should be manipulated only using the macros provided here. -.PP +.P .BI RTA_OK( rta ", " attrlen ) returns true if .I rta @@ -49,13 +49,13 @@ When not true then you must assume there are no more attributes in the message, even if .I attrlen is nonzero. -.PP +.P .BI RTA_DATA( rta ) returns a pointer to the start of this attribute's data. -.PP +.P .BI RTA_PAYLOAD( rta ) returns the length of this attribute's data. -.PP +.P .BI RTA_NEXT( rta ", " attrlen ) gets the next attribute after .IR rta . @@ -64,12 +64,12 @@ Calling this macro will update You should use .B RTA_OK to check the validity of the returned pointer. -.PP +.P .BI RTA_LENGTH( len ) returns the length which is required for .I len bytes of data plus the header. -.PP +.P .BI RTA_SPACE( len ) returns the amount of space which will be needed in a message with .I len @@ -81,7 +81,7 @@ This manual page is incomplete. .SH EXAMPLES .\" FIXME . ? would be better to use libnetlink in the EXAMPLE code here Creating a rtnetlink message to set the MTU of a device: -.PP +.P .in +4n .EX #include diff --git a/man3/scalb.3 b/man3/scalb.3 index 5513a27..f99fd2d 100644 --- a/man3/scalb.3 +++ b/man3/scalb.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH scalb 3 2023-07-20 "Linux man-pages 6.05.01" +.TH scalb 3 2023-10-31 "Linux man-pages 6.7" .SH NAME scalb, scalbf, scalbl \- multiply floating-point number by integral power of radix (OBSOLETE) @@ -15,17 +15,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] double scalb(double " x ", double " exp ); .BI "[[deprecated]] float scalbf(float " x ", float " exp ); .BI "[[deprecated]] long double scalbl(long double " x ", long double " exp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR scalb (): .nf _XOPEN_SOURCE >= 500 @@ -33,7 +33,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR scalbf (), .BR scalbl (): .nf @@ -50,11 +50,11 @@ by to the power of .IR exp , that is: -.PP +.P .nf x * FLT_RADIX ** exp .fi -.PP +.P The definition of .B FLT_RADIX can be obtained by including @@ -67,13 +67,13 @@ On success, these functions return .B FLT_RADIX ** .IR exp . -.PP +.P If .I x or .I exp is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity (negative infinity), @@ -81,13 +81,13 @@ and .I exp is not negative infinity, positive infinity (negative infinity) is returned. -.PP +.P If .I x is +0 (\-0), and .I exp is not positive infinity, +0 (\-0) is returned. -.PP +.P If .I x is zero, and @@ -95,7 +95,7 @@ is zero, and is positive infinity, a domain error occurs, and a NaN is returned. -.PP +.P If .I x is an infinity, @@ -104,7 +104,7 @@ and is negative infinity, a domain error occurs, and a NaN is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -114,7 +114,7 @@ or .BR HUGE_VALL , respectively, with a sign the same as .IR x . -.PP +.P If the result underflows, a range error occurs, and the functions return zero, with a sign the same as @@ -124,7 +124,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is 0, and \fIexp\fP is positive infinity, \ @@ -168,7 +168,6 @@ T{ .BR scalbl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY diff --git a/man3/scalbln.3 b/man3/scalbln.3 index 0651456..beeeff4 100644 --- a/man3/scalbln.3 +++ b/man3/scalbln.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH scalbln 3 2023-07-20 "Linux man-pages 6.05.01" +.TH scalbln 3 2023-10-31 "Linux man-pages 6.7" .SH NAME scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl \- multiply floating-point number by integral power of radix @@ -15,21 +15,21 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double scalbln(double " x ", long " exp ); .BI "float scalblnf(float " x ", long " exp ); .BI "long double scalblnl(long double " x ", long " exp ); -.PP +.P .BI "double scalbn(double " x ", int " exp ); .BI "float scalbnf(float " x ", int " exp ); .BI "long double scalbnl(long double " x ", int " exp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR scalbln (), .BR scalblnf (), .BR scalblnl (): @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L || /* Since glibc 2.19: */ _DEFAULT_SOURCE .fi -.PP +.P .BR scalbn (), .BR scalbnf (), .BR scalbnl (): @@ -55,11 +55,11 @@ by to the power of .IR exp , that is: -.PP +.P .nf x * FLT_RADIX ** exp .fi -.PP +.P The definition of .B FLT_RADIX can be obtained by including @@ -72,20 +72,20 @@ On success, these functions return .B FLT_RADIX ** .IR exp . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity (negative infinity), positive infinity (negative infinity) is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -95,7 +95,7 @@ or .BR HUGE_VALL , respectively, with a sign the same as .IR x . -.PP +.P If the result underflows, a range error occurs, and the functions return zero, with a sign the same as @@ -105,7 +105,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error, overflow @@ -142,7 +142,6 @@ T{ .BR scalblnl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/scandir.3 b/man3/scandir.3 index 1abda05..eeab256 100644 --- a/man3/scandir.3 +++ b/man3/scandir.3 @@ -21,7 +21,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH scandir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH scandir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME scandir, scandirat, alphasort, versionsort \- scan a directory for matching entries @@ -31,43 +31,43 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int scandir(const char *restrict " dirp , .BI " struct dirent ***restrict " namelist , .BI " int (*" filter ")(const struct dirent *)," .BI " int (*" compar ")(const struct dirent **," .B " const struct dirent **));" -.PP +.P .BI "int alphasort(const struct dirent **" a ", const struct dirent **" b ); .BI "int versionsort(const struct dirent **" a ", const struct dirent **" b ); -.PP +.P .BR "#include " " /* Definition of AT_* constants */" .B #include -.PP +.P .BI "int scandirat(int " dirfd ", const char *restrict " dirp , .BI " struct dirent ***restrict " namelist , .BI " int (*" filter ")(const struct dirent *)," .BI " int (*" compar ")(const struct dirent **," .B " const struct dirent **));" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR scandir (), .BR alphasort (): .nf /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200809L || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR versionsort (): .nf _GNU_SOURCE .fi -.PP +.P .BR scandirat (): .nf _GNU_SOURCE @@ -87,7 +87,7 @@ function \fIcompar\fP(), and collected in array \fInamelist\fP which is allocated via .BR malloc (3). If \fIfilter\fP is NULL, all entries are selected. -.PP +.P The .BR alphasort () and @@ -105,7 +105,7 @@ The function operates in exactly the same way as .BR scandir (), except for the differences described here. -.PP +.P If the pathname given in .I dirp is relative, then it is interpreted relative to the directory @@ -115,7 +115,7 @@ referred to by the file descriptor the calling process, as is done by .BR scandir () for a relative pathname). -.PP +.P If .I dirp is relative and @@ -127,13 +127,13 @@ then is interpreted relative to the current working directory of the calling process (like .BR scandir ()). -.PP +.P If .I dirp is absolute, then .I dirfd is ignored. -.PP +.P See .BR openat (2) for an explanation of the need for @@ -146,7 +146,7 @@ selected. On error, \-1 is returned, with .I errno set to indicate the error. -.PP +.P The .BR alphasort () and @@ -201,7 +201,6 @@ T{ .BR versionsort () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS .TP .BR alphasort () @@ -225,7 +224,7 @@ glibc 2.1. .TP .BR scandirat () glibc 2.15. -.\" .LP +.\" .P .\" The functions .\" .BR scandir () .\" and @@ -246,7 +245,7 @@ calls .BR strcoll (3); earlier it used .BR strcmp (3). -.PP +.P Before glibc 2.10, the two arguments of .BR alphasort () and diff --git a/man3/scanf.3 b/man3/scanf.3 index 7934509..3ac97c0 100644 --- a/man3/scanf.3 +++ b/man3/scanf.3 @@ -2,7 +2,7 @@ .\" Copyright 2022 Alejandro Colomar .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH scanf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH scanf 3 2023-12-09 "Linux man-pages 6.7" .SH NAME scanf, fscanf, vscanf, vfscanf \- input FILE format conversion .SH LIBRARY @@ -11,23 +11,23 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int scanf(const char *restrict " format ", ...);" .BI "int fscanf(FILE *restrict " stream , .BI " const char *restrict " format ", ...);" -.PP +.P .B #include -.PP +.P .BI "int vscanf(const char *restrict " format ", va_list " ap ); .BI "int vfscanf(FILE *restrict " stream , .BI " const char *restrict " format ", va_list " ap ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vscanf (), .BR vfscanf (): .nf @@ -36,7 +36,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION The .BR scanf () -family of functions scans input like +family of functions scans formatted input like .BR sscanf (3), but read from a .IR FILE . @@ -49,7 +49,7 @@ and parse them later with .BR sscanf (3) or more specialized functions such as .BR strtol (3). -.PP +.P The .BR scanf () function reads input from the standard input stream @@ -58,7 +58,7 @@ and .BR fscanf () reads input from the stream pointer .IR stream . -.PP +.P The .BR vfscanf () function is analogous to @@ -77,7 +77,7 @@ On success, these functions return the number of input items successfully matched and assigned; this can be fewer than provided for, or even zero, in the event of an early matching failure. -.PP +.P The value .B EOF is returned if the end of input is reached before either the first @@ -132,11 +132,27 @@ T{ .BR vfscanf () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. +.SH CAVEATS +These functions make it difficult to +distinguish newlines from other white space, +This is especially problematic with line-buffered input, +like the standard input stream. +.P +These functions can't report errors after the last +non-suppressed conversion specification. +.SH BUGS +It is impossible to accurately know +how many characters these functions have consumed from the input stream, +since they only report the number of successful conversions. +For example, +if the input is "123\en\ a", +.I scanf(\[dq]%d\ %d\[dq], &a, &b) +will consume the digits, the newline, and the space, but not the letter a. +This makes it difficult to recover from invalid input. .SH SEE ALSO .BR fgets (3), .BR getline (3), diff --git a/man3/sched_getcpu.3 b/man3/sched_getcpu.3 index eb34a11..ee7ff51 100644 --- a/man3/sched_getcpu.3 +++ b/man3/sched_getcpu.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sched_getcpu 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sched_getcpu 3 2024-01-01 "Linux man-pages 6.7" .SH NAME sched_getcpu \- determine CPU on which the calling thread is running .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B int sched_getcpu(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sched_getcpu (): .nf Since glibc 2.14: @@ -60,28 +60,27 @@ T{ .BR sched_getcpu () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY glibc 2.6. .SH NOTES The call -.PP +.P .in +4n .EX cpu = sched_getcpu(); .EE .in -.PP +.P is equivalent to the following .BR getcpu (2) call: -.PP +.P .in +4n .EX int c, s; -s = getcpu(&c, NULL, NULL); +s = getcpu(&c, NULL); cpu = (s == \-1) ? s : c; .EE .in diff --git a/man3/seekdir.3 b/man3/seekdir.3 index 4a3fa51..500a636 100644 --- a/man3/seekdir.3 +++ b/man3/seekdir.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sat Jul 24 18:25:21 1993 by Rik Faith (faith@cs.unc.edu) .\" -.TH seekdir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH seekdir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME seekdir \- set the position of the next readdir() call in the directory stream. @@ -19,15 +19,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void seekdir(DIR *" dirp ", long " loc ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR seekdir (): .nf _XOPEN_SOURCE @@ -63,7 +63,6 @@ T{ .BR seekdir () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_close.3 b/man3/sem_close.3 index 88adb87..c68c502 100644 --- a/man3/sem_close.3 +++ b/man3/sem_close.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_close 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_close 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_close \- close a named semaphore .SH LIBRARY @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_close(sem_t *" sem ); .fi .SH DESCRIPTION @@ -46,7 +46,6 @@ T{ .BR sem_close () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_destroy.3 b/man3/sem_destroy.3 index 524a318..f786906 100644 --- a/man3/sem_destroy.3 +++ b/man3/sem_destroy.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_destroy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_destroy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_destroy \- destroy an unnamed semaphore .SH LIBRARY @@ -12,24 +12,24 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_destroy(sem_t *" sem ); .fi .SH DESCRIPTION .BR sem_destroy () destroys the unnamed semaphore at the address pointed to by .IR sem . -.PP +.P Only a semaphore that has been initialized by .BR sem_init (3) should be destroyed using .BR sem_destroy (). -.PP +.P Destroying a semaphore that other processes or threads are currently blocked on (in .BR sem_wait (3)) produces undefined behavior. -.PP +.P Using a semaphore that has been destroyed produces undefined results, until the semaphore has been reinitialized using .BR sem_init (3). @@ -58,7 +58,6 @@ T{ .BR sem_destroy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_getvalue.3 b/man3/sem_getvalue.3 index 6e529ba..925a9bd 100644 --- a/man3/sem_getvalue.3 +++ b/man3/sem_getvalue.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_getvalue 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_getvalue 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_getvalue \- get the value of a semaphore .SH LIBRARY @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_getvalue(sem_t *restrict " sem ", int *restrict " sval ); .fi .SH DESCRIPTION @@ -21,7 +21,7 @@ places the current value of the semaphore pointed to .I sem into the integer pointed to by .IR sval . -.PP +.P If one or more processes or threads are blocked waiting to lock the semaphore with .BR sem_wait (3), @@ -60,7 +60,6 @@ T{ .BR sem_getvalue () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_init.3 b/man3/sem_init.3 index 5f9c352..0cae896 100644 --- a/man3/sem_init.3 +++ b/man3/sem_init.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_init 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_init 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_init \- initialize an unnamed semaphore .SH LIBRARY @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_init(sem_t *" sem ", int " pshared ", unsigned int " value ); .fi .SH DESCRIPTION @@ -22,12 +22,12 @@ initializes the unnamed semaphore at the address pointed to by The .I value argument specifies the initial value for the semaphore. -.PP +.P The .I pshared argument indicates whether this semaphore is to be shared between the threads of a process, or between processes. -.PP +.P If .I pshared has the value 0, @@ -35,7 +35,7 @@ then the semaphore is shared between the threads of a process, and should be located at some address that is visible to all threads (e.g., a global variable, or a variable allocated dynamically on the heap). -.PP +.P If .I pshared is nonzero, then the semaphore is shared between processes, @@ -52,7 +52,7 @@ can operate on the semaphore using .BR sem_post (3), .BR sem_wait (3), and so on. -.PP +.P Initializing a semaphore that has already been initialized results in undefined behavior. .SH RETURN VALUE @@ -87,12 +87,11 @@ T{ .BR sem_init () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Bizarrely, POSIX.1-2001 does not specify the value that should be returned by a successful call to .BR sem_init (). diff --git a/man3/sem_open.3 b/man3/sem_open.3 index 0845be9..660daa9 100644 --- a/man3/sem_open.3 +++ b/man3/sem_open.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_open 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_open 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_open \- initialize and open a named semaphore .SH LIBRARY @@ -14,7 +14,7 @@ POSIX threads library .BR "#include " " /* For O_* constants */" .BR "#include " " /* For mode constants */" .B #include -.PP +.P .BI "sem_t *sem_open(const char *" name ", int " oflag ); .BI "sem_t *sem_open(const char *" name ", int " oflag , .BI " mode_t " mode ", unsigned int " value ); @@ -28,7 +28,7 @@ For details of the construction of .IR name , see .BR sem_overview (7). -.PP +.P The .I oflag argument specifies flags that control the operation of the call. @@ -54,7 +54,7 @@ are specified in then an error is returned if a semaphore with the given .I name already exists. -.PP +.P If .B O_CREAT is specified in @@ -162,7 +162,6 @@ T{ .BR sem_open () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_post.3 b/man3/sem_post.3 index 5406484..1c06a81 100644 --- a/man3/sem_post.3 +++ b/man3/sem_post.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_post 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_post 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_post \- unlock a semaphore .SH LIBRARY @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_post(sem_t *" sem ); .fi .SH DESCRIPTION @@ -53,7 +53,6 @@ T{ .BR sem_post () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_unlink.3 b/man3/sem_unlink.3 index 434d145..dd8d402 100644 --- a/man3/sem_unlink.3 +++ b/man3/sem_unlink.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_unlink 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_unlink 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_unlink \- remove a named semaphore .SH LIBRARY @@ -12,7 +12,7 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_unlink(const char *" name ); .fi .SH DESCRIPTION @@ -54,7 +54,6 @@ T{ .BR sem_unlink () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sem_wait.3 b/man3/sem_wait.3 index b1302ca..aa4793c 100644 --- a/man3/sem_wait.3 +++ b/man3/sem_wait.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_wait 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sem_wait 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_wait, sem_timedwait, sem_trywait \- lock a semaphore .SH LIBRARY @@ -12,18 +12,18 @@ POSIX threads library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sem_wait(sem_t *" sem ); .BI "int sem_trywait(sem_t *" sem ); .BI "int sem_timedwait(sem_t *restrict " sem , .BI " const struct timespec *restrict " abs_timeout ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sem_timedwait (): .nf _POSIX_C_SOURCE >= 200112L @@ -38,7 +38,7 @@ If the semaphore currently has the value zero, then the call blocks until either it becomes possible to perform the decrement (i.e., the semaphore value rises above zero), or a signal handler interrupts the call. -.PP +.P .BR sem_trywait () is the same as .BR sem_wait (), @@ -48,7 +48,7 @@ then call returns an error set to .BR EAGAIN ) instead of blocking. -.PP +.P .BR sem_timedwait () is the same as .BR sem_wait (), @@ -62,7 +62,7 @@ argument points to a .BR timespec (3) structure that specifies an absolute timeout in seconds and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P If the timeout has already expired by the time of the call, and the semaphore could not be locked immediately, then @@ -71,7 +71,7 @@ fails with a timeout error .RI ( errno set to .BR ETIMEDOUT ). -.PP +.P If the operation can be performed immediately, then .BR sem_timedwait () never fails with a timeout error, regardless of the value of @@ -127,7 +127,6 @@ T{ .BR sem_timedwait () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -150,7 +149,7 @@ The second command-line argument specifies the length of the timeout, in seconds, for .BR sem_timedwait (). The following shows what happens on two different runs of the program: -.PP +.P .in +4n .EX .RB "$" " ./a.out 2 3" diff --git a/man3/setaliasent.3 b/man3/setaliasent.3 index 45fb548..acdad17 100644 --- a/man3/setaliasent.3 +++ b/man3/setaliasent.3 @@ -5,7 +5,7 @@ .\" .\" Polished a bit, added a little, aeb .\" -.TH setaliasent 3 2023-07-20 "Linux man-pages 6.05.01" +.TH setaliasent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME setaliasent, endaliasent, getaliasent, getaliasent_r, getaliasbyname, getaliasbyname_r \- read an alias entry @@ -15,16 +15,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "void setaliasent(void);" .B "void endaliasent(void);" -.PP +.P .B "struct aliasent *getaliasent(void);" .BI "int getaliasent_r(struct aliasent *restrict " result , .BI " char " buffer "[restrict ." buflen "], \ size_t " buflen , .BI " struct aliasent **restrict " res ); -.PP +.P .BI "struct aliasent *getaliasbyname(const char *" name ); .BI "int getaliasbyname_r(const char *restrict " name , .BI " struct aliasent *restrict " result , @@ -38,48 +38,48 @@ is the aliases database, that contains mail aliases. (To find out which databases are supported, try .IR "getent \-\-help" .) Six functions are provided to access the aliases database. -.PP +.P The .BR getaliasent () function returns a pointer to a structure containing the group information from the aliases database. The first time it is called it returns the first entry; thereafter, it returns successive entries. -.PP +.P The .BR setaliasent () function rewinds the file pointer to the beginning of the aliases database. -.PP +.P The .BR endaliasent () function closes the aliases database. -.PP +.P .BR getaliasent_r () is the reentrant version of the previous function. The requested structure is stored via the first argument but the programmer needs to fill the other arguments also. Not providing enough space causes the function to fail. -.PP +.P The function .BR getaliasbyname () takes the name argument and searches the aliases database. The entry is returned as a pointer to a .IR "struct aliasent" . -.PP +.P .BR getaliasbyname_r () is the reentrant version of the previous function. The requested structure is stored via the second argument but the programmer needs to fill the other arguments also. Not providing enough space causes the function to fail. -.PP +.P The .I "struct aliasent" is defined in .IR : -.PP +.P .in +4n .EX struct aliasent { @@ -125,12 +125,11 @@ T{ .BR getaliasbyname () T} Thread safety MT-Unsafe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY The NeXT system has similar routines: -.PP +.P .in +4n .EX #include @@ -145,7 +144,7 @@ alias_ent *alias_getbyname(char *name); The following example compiles with .IR "gcc example.c \-o example" . It will dump all names in the alias database. -.PP +.P .\" SRC BEGIN (setaliasent.c) .EX #include diff --git a/man3/setbuf.3 b/man3/setbuf.3 index ad998c3..89865e2 100644 --- a/man3/setbuf.3 +++ b/man3/setbuf.3 @@ -18,7 +18,7 @@ .\" Correction, 2000-03-03, Andreas Jaeger .\" Added return value for setvbuf, aeb, .\" -.TH setbuf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH setbuf 3 2024-02-26 "Linux man-pages 6.7" .SH NAME setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations .SH LIBRARY @@ -27,21 +27,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setvbuf(FILE *restrict " stream ", char " buf "[restrict ." size ], .BI " int " mode ", size_t " size ); -.PP +.P .BI "void setbuf(FILE *restrict " stream ", char *restrict " buf ); .BI "void setbuffer(FILE *restrict " stream ", char " buf "[restrict ." size ], .BI " size_t " size ); .BI "void setlinebuf(FILE *" stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setbuffer (), .BR setlinebuf (): .nf @@ -63,7 +63,7 @@ The function may be used to force the block out early. (See .BR fclose (3).) -.PP +.P Normally all files are block buffered. If a stream refers to a terminal (as .I stdout @@ -71,7 +71,7 @@ normally does), it is line buffered. The standard error stream .I stderr is always unbuffered by default. -.PP +.P The .BR setvbuf () function may be used on any open stream to change its buffer. @@ -89,7 +89,7 @@ line buffered .B _IOFBF fully buffered .RE -.PP +.P Except for unbuffered files, the .I buf argument should point to a buffer at least @@ -104,17 +104,17 @@ The .BR setvbuf () function may be used only after opening a stream and before any other operations have been performed on it. -.PP +.P The other three calls are, in effect, simply aliases for calls to .BR setvbuf (). The .BR setbuf () function is exactly equivalent to the call -.PP +.P .in +4n setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); .in -.PP +.P The .BR setbuffer () function is the same, except that the size of the buffer is up to the @@ -123,7 +123,7 @@ caller, rather than being determined by the default The .BR setlinebuf () function is exactly equivalent to the call: -.PP +.P .in +4n setvbuf(stream, NULL, _IOLBF, 0); .in @@ -137,7 +137,7 @@ is invalid or the request cannot be honored). It may set .I errno on failure. -.PP +.P The other functions do not return a value. .SH ATTRIBUTES For an explanation of the terms used in this section, see @@ -156,7 +156,6 @@ T{ .BR setvbuf () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR setbuf () @@ -194,15 +193,15 @@ in order to detect errors. .\" On 4.2BSD and 4.3BSD systems, .\" .BR setbuf () .\" always uses a suboptimal buffer size and should be avoided. -.\".PP +.\".P You must make sure that the space that .I buf points to still exists by the time .I stream is closed, which also happens at program termination. For example, the following is invalid: -.PP -.\" [[invalid]] SRC BEGIN (setbuf.c) +.P +.\" SRC BEGIN (setbuf.c) .EX #include \& diff --git a/man3/setenv.3 b/man3/setenv.3 index 0fe6521..d51f0f8 100644 --- a/man3/setenv.3 +++ b/man3/setenv.3 @@ -15,7 +15,7 @@ .\" Noted nonstandard behavior of setenv() if name contains '=' .\" 2005-08-12, mtk, glibc 2.3.4 fixed the "name contains '='" bug .\" -.TH setenv 3 2023-07-20 "Linux man-pages 6.05.01" +.TH setenv 3 2023-10-31 "Linux man-pages 6.7" .SH NAME setenv \- change or add an environment variable .SH LIBRARY @@ -24,16 +24,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setenv(const char *" name ", const char *" value ", int " overwrite ); .BI "int unsetenv(const char *" name ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setenv (), .BR unsetenv (): .nf @@ -73,7 +73,7 @@ and .I value (by contrast with .BR putenv (3)). -.PP +.P The .BR unsetenv () function deletes the variable @@ -116,12 +116,11 @@ T{ .BR unsetenv () T} Thread safety MT-Unsafe const:env .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P Prior to glibc 2.2.2, .BR unsetenv () was prototyped diff --git a/man3/setjmp.3 b/man3/setjmp.3 index 5133f89..18771aa 100644 --- a/man3/setjmp.3 +++ b/man3/setjmp.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH setjmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH setjmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME setjmp, sigsetjmp, longjmp, siglongjmp \- performing a nonlocal goto .SH LIBRARY @@ -12,22 +12,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setjmp(jmp_buf " env ); .BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs ); -.PP +.P .BI "[[noreturn]] void longjmp(jmp_buf " env ", int " val ); .BI "[[noreturn]] void siglongjmp(sigjmp_buf " env ", int " val ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR setjmp (): see NOTES. -.PP +.P .BR sigsetjmp (): .nf _POSIX_C_SOURCE @@ -42,7 +42,7 @@ function dynamically establishes the target to which control will later be transferred, and .BR longjmp () performs the transfer of execution. -.PP +.P The .BR setjmp () function saves various information about the calling environment @@ -55,7 +55,7 @@ for later use by In this case, .BR setjmp () returns 0. -.PP +.P The .BR longjmp () function uses the information saved in @@ -70,7 +70,7 @@ the values of some other registers and the process signal mask may be restored to their state at the time of the .BR setjmp () call. -.PP +.P Following a successful .BR longjmp (), execution continues as if @@ -89,7 +89,7 @@ and .BR siglongjmp () also perform nonlocal gotos, but provide predictable handling of the process signal mask. -.PP +.P If, and only if, the .I savesigs argument provided to @@ -112,7 +112,7 @@ or the nonzero value specified in .I val is returned. -.PP +.P The .BR longjmp () or @@ -139,7 +139,6 @@ T{ .BR siglongjmp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR setjmp () @@ -162,7 +161,7 @@ POSIX.1-2001, C89. .TQ .BR siglongjmp () POSIX.1-2001. -.PP +.P POSIX does not specify whether .BR setjmp () will save the signal mask @@ -239,7 +238,7 @@ and .IP \[bu] they are not declared as .IR volatile . -.PP +.P Analogous remarks apply for .BR siglongjmp (). .\" @@ -263,13 +262,13 @@ call. call should employ a unique .I jmp_buf variable.) -.PP +.P Adding further difficulty, the .BR setjmp () and .BR longjmp () calls may not even be in the same source code module. -.PP +.P In summary, nonlocal gotos can make programs harder to understand and maintain, and an alternative should be used if possible. .\" @@ -280,7 +279,7 @@ returns before .BR longjmp () is called, the behavior is undefined. Some kind of subtle or unsubtle chaos is sure to result. -.PP +.P If, in a multithreaded program, a .BR longjmp () call employs an @@ -298,7 +297,7 @@ in a different thread, the behavior is undefined. .\" (i.e., from a handler that was invoked in response to a signal that was .\" generated while another signal was already in the process of being .\" handled), the behavior is undefined. -.PP +.P POSIX.1-2008 Technical Corrigendum 2 adds .\" http://austingroupbugs.net/view.php?id=516#c1195 .BR longjmp () diff --git a/man3/setlocale.3 b/man3/setlocale.3 index d2b511e..50a36d8 100644 --- a/man3/setlocale.3 +++ b/man3/setlocale.3 @@ -10,7 +10,7 @@ .\" Modified Tue Aug 24 17:11:01 1999 by Andries Brouwer (aeb@cwi.nl) .\" Modified Tue Feb 6 03:31:55 2001 by Andries Brouwer (aeb@cwi.nl) .\" -.TH setlocale 3 2023-07-20 "Linux man-pages 6.05.01" +.TH setlocale 3 2024-02-25 "Linux man-pages 6.7" .SH NAME setlocale \- set the current locale .SH LIBRARY @@ -19,14 +19,14 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *setlocale(int " category ", const char *" locale ); .fi .SH DESCRIPTION The .BR setlocale () function is used to set or query the program's current locale. -.PP +.P If .I locale is not NULL, @@ -74,12 +74,12 @@ LC_TIME T{ Formatting of date and time values T} .TE -.PP +.P The categories marked with an asterisk in the above table are GNU extensions. For further information on these locale categories, see .BR locale (7). -.PP +.P The argument .I locale is a pointer to a character string containing the @@ -88,11 +88,11 @@ required setting of Such a string is either a well-known constant like "C" or "da_DK" (see below), or an opaque string that was returned by another call of .BR setlocale (). -.PP +.P If .I locale is an empty string, -.BR """""" , +.BR \[dq]\[dq] , each part of the locale that should be modified is set according to the environment variables. The details are implementation-dependent. @@ -110,21 +110,21 @@ If its value is not a valid locale specification, the locale is unchanged, and .BR setlocale () returns NULL. -.PP +.P The locale -.B """C""" +.B \[dq]C\[dq] or -.B """POSIX""" +.B \[dq]POSIX\[dq] is a portable locale; it exists on all conforming systems. -.PP +.P A locale name is typically of the form .IR language "[_" territory "][." codeset "][@" modifier "]," where .I language -is an ISO 639 language code, +is an ISO\~639 language code, .I territory -is an ISO 3166 country code, and +is an ISO\~3166 country code, and .I codeset is a character set or encoding identifier like .B "ISO\-8859\-1" @@ -132,22 +132,22 @@ or .BR "UTF\-8" . For a list of all supported locales, try "locale \-a" (see .BR locale (1)). -.PP +.P If .I locale is NULL, the current locale is only queried, not modified. -.PP +.P On startup of the main program, the portable -.B """C""" +.B \[dq]C\[dq] locale is selected as default. A program may be made portable to all locales by calling: -.PP +.P .in +4n .EX setlocale(LC_ALL, ""); .EE .in -.PP +.P after program initialization, and then: .IP \[bu] 3 using the values returned from a @@ -191,7 +191,6 @@ T{ .BR setlocale () T} Thread safety MT-Unsafe const:locale env .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SS Categories diff --git a/man3/setlogmask.3 b/man3/setlogmask.3 index 223b864..57fa9de 100644 --- a/man3/setlogmask.3 +++ b/man3/setlogmask.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH setlogmask 3 2023-07-20 "Linux man-pages 6.05.01" +.TH setlogmask 3 2023-11-01 "Linux man-pages 6.7" .SH NAME setlogmask \- set log priority mask .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setlogmask(int " mask ); .fi .SH DESCRIPTION @@ -24,13 +24,17 @@ Logging is enabled for the priorities that have the corresponding bit set in .IR mask . The initial mask is such that logging is enabled for all priorities. -.PP +.P The .BR setlogmask () function sets this logmask for the calling process, and returns the previous mask. -If the mask argument is 0, the current logmask is not modified. -.PP +If the +.I mask +argument is +.BR 0 , +the current logmask is not modified. +.P The eight priorities are .BR LOG_EMERG , .BR LOG_ALERT , @@ -70,13 +74,12 @@ T{ .BR setlogmask () T} Thread safety MT-Unsafe race:LogMask .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. .\" Note that the description in POSIX.1-2001 is flawed. -.PP +.P .BR LOG_UPTO () will be included in the next release of the POSIX specification (Issue 8). .\" FIXME . https://www.austingroupbugs.net/view.php?id=1033 diff --git a/man3/setnetgrent.3 b/man3/setnetgrent.3 index 8cc779f..ec6e6d6 100644 --- a/man3/setnetgrent.3 +++ b/man3/setnetgrent.3 @@ -6,7 +6,7 @@ .\" based on glibc infopages .\" polished - aeb .\" -.TH setnetgrent 3 2023-07-30 "Linux man-pages 6.05.01" +.TH setnetgrent 3 2023-10-31 "Linux man-pages 6.7" .SH NAME setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \- handle network group entries @@ -16,25 +16,25 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int setnetgrent(const char *" netgroup ); .B "void endnetgrent(void);" -.PP +.P .BI "int getnetgrent(char **restrict " host , .BI " char **restrict " user ", char **restrict " domain ); .BI "int getnetgrent_r(char **restrict " host , .BI " char **restrict " user ", char **restrict " domain , .BI " char " buf "[restrict ." buflen "], size_t " buflen ); -.PP +.P .BI "int innetgr(const char *" netgroup ", const char *" host , .BI " const char *" user ", const char *" domain ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR \%setnetgrent (), .BR \%endnetgrent (), .BR \%getnetgrent (), @@ -59,7 +59,7 @@ The functions described here allow access to the netgroup databases. The file .I /etc/nsswitch.conf defines what database is searched. -.PP +.P The .BR setnetgrent () call defines the netgroup that will be searched by subsequent @@ -79,7 +79,7 @@ To avoid this problem you can use the GNU function that stores the strings in the supplied buffer. To free all allocated buffers use .BR endnetgrent (). -.PP +.P In most cases you want to check only if the triplet .RI ( hostname ", " username ", " domainname ) is a member of a netgroup. @@ -134,7 +134,7 @@ MT-Unsafe race:netgrent race:netgrentbuf locale T} .TE -.sp 1 +.P In the above table, .I netgrent in diff --git a/man3/shm_open.3 b/man3/shm_open.3 index c5756c4..6d07292 100644 --- a/man3/shm_open.3 +++ b/man3/shm_open.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH shm_open 3 2023-07-20 "Linux man-pages 6.05.01" +.TH shm_open 3 2023-10-31 "Linux man-pages 6.7" .SH NAME shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects .SH LIBRARY @@ -14,7 +14,7 @@ Real-time library .B #include .BR "#include " " /* For mode constants */" .BR "#include " " /* For O_* constants */" -.PP +.P .BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); .BI "int shm_unlink(const char *" name ); .fi @@ -30,7 +30,7 @@ The function performs the converse operation, removing an object previously created by .BR shm_open (). -.PP +.P The operation of .BR shm_open () is analogous to that of @@ -51,7 +51,7 @@ followed by one or more characters, none of which are slashes. .\" case the subdirectory must exist under /dev/shm, and allow the .\" required permissions if a user wants to create a shared memory .\" object in that subdirectory. -.PP +.P .I oflag is a bit mask created by ORing together exactly one of .B O_RDONLY @@ -107,10 +107,10 @@ does not exist, are performed atomically. .TP .B O_TRUNC If the shared memory object already exists, truncate it to zero bytes. -.PP +.P Definitions of these flag values can be obtained by including .IR . -.PP +.P On successful completion .BR shm_open () returns a new file descriptor referring to the shared memory object. @@ -121,7 +121,7 @@ The flag (see .BR fcntl (2)) is set for the file descriptor. -.PP +.P The file descriptor is normally used in subsequent calls to .BR ftruncate (2) @@ -130,7 +130,7 @@ to After a call to .BR mmap (2) the file descriptor may be closed without affecting the memory mapping. -.PP +.P The operation of .BR shm_unlink () @@ -235,7 +235,6 @@ T{ .BR shm_unlink () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS POSIX leaves the behavior of the combination of .B O_RDONLY @@ -244,7 +243,7 @@ and unspecified. On Linux, this will successfully truncate an existing shared memory object\[em]this may not be so on other UNIX systems. -.PP +.P The POSIX shared memory object implementation on Linux makes use of a dedicated .BR tmpfs (5) @@ -255,7 +254,7 @@ POSIX.1-2008. .SH HISTORY glibc 2.2. POSIX.1-2001. -.PP +.P POSIX.1-2001 says that the group ownership of a newly created shared memory object is set to either the calling process's effective group ID or "a system default group ID". @@ -271,7 +270,7 @@ of a string that is placed into the shared memory by the "send" program. Once the data has been modified, the "send" program then prints the contents of the modified shared memory. An example execution of the two programs is the following: -.PP +.P .in +4n .EX $ \fB./pshm_ucase_bounce /myshm &\fP @@ -280,14 +279,14 @@ $ \fB./pshm_ucase_send /myshm hello\fP HELLO .EE .in -.PP +.P Further detail about these programs is provided below. .\" .SS Program source: pshm_ucase.h The following header file is included by both programs below. Its primary purpose is to define a structure that will be imposed on the memory object that is shared between the two programs. -.PP +.P .in +4n .\" SRC BEGIN (pshm_ucase.h) .EX @@ -325,12 +324,12 @@ match the size of the structure defined in the header file. It then maps the object into the process's address space, and initializes two POSIX semaphores inside the object to 0. -.PP +.P After the "send" program has posted the first of the semaphores, the "bounce" program upper cases the data that has been placed in the memory by the "send" program and then posts the second semaphore to tell the "send" program that it may now access the shared memory. -.PP +.P .in +4n .\" SRC BEGIN (pshm_ucase_bounce.c) .EX @@ -413,7 +412,7 @@ main(int argc, char *argv[]) The "send" program takes two command-line arguments: the pathname of a shared memory object previously created by the "bounce" program and a string that is to be copied into that object. -.PP +.P The program opens the shared memory object and maps the object into its address space. It then copies the data specified in its second argument @@ -423,7 +422,7 @@ which tells the "bounce" program that it can now access that data. After the "bounce" program posts the second semaphore, the "send" program prints the contents of the shared memory on standard output. -.PP +.P .in +4n .\" SRC BEGIN (pshm_ucase_send.c) .EX diff --git a/man3/siginterrupt.3 b/man3/siginterrupt.3 index 3f4c246..be7f093 100644 --- a/man3/siginterrupt.3 +++ b/man3/siginterrupt.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sun Jul 25 10:40:51 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Apr 14 16:20:34 1996 by Andries Brouwer (aeb@cwi.nl) -.TH siginterrupt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH siginterrupt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME siginterrupt \- allow signals to interrupt system calls .SH LIBRARY @@ -18,15 +18,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int siginterrupt(int " sig ", int " flag ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR siginterrupt (): .nf _XOPEN_SOURCE >= 500 @@ -43,12 +43,12 @@ If the \fIflag\fP argument is false (0), then system calls will be restarted if interrupted by the specified signal \fIsig\fP. This is the default behavior in Linux. -.PP +.P If the \fIflag\fP argument is true (1) and no data has been transferred, then a system call interrupted by the signal \fIsig\fP will return \-1 and \fIerrno\fP will be set to .BR EINTR . -.PP +.P If the \fIflag\fP argument is true (1) and data transfer has started, then the system call will be interrupted and will return the actual amount of data transferred. @@ -84,7 +84,6 @@ T} Thread safety T{ MT-Unsafe const:sigintr T} .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/signbit.3 b/man3/signbit.3 index 5dddad6..ad7a1f4 100644 --- a/man3/signbit.3 +++ b/man3/signbit.3 @@ -7,7 +7,7 @@ .\" .\" Based on glibc infopages, copyright Free Software Foundation .\" -.TH signbit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH signbit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME signbit \- test sign of a real floating-point number .SH LIBRARY @@ -16,15 +16,15 @@ Math library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int signbit(" x ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR signbit (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -35,7 +35,7 @@ is a generic macro which can work on all real floating-point types. It returns a nonzero value if the value of .I x has its sign bit set. -.PP +.P This is not the same as .IR "x < 0.0" , because IEEE 754 floating point allows zero to be signed. @@ -44,7 +44,7 @@ The comparison is false, but .I signbit(\-0.0) will return a nonzero value. -.PP +.P NaNs and infinities have a sign bit. .SH RETURN VALUE The @@ -68,12 +68,11 @@ T{ .BR signbit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C99. -.PP +.P This function is defined in IEC 559 (and the appendix with recommended functions in IEEE 754/IEEE 854). .SH SEE ALSO diff --git a/man3/significand.3 b/man3/significand.3 index 794955a..dbd6f7b 100644 --- a/man3/significand.3 +++ b/man3/significand.3 @@ -5,7 +5,7 @@ .\" .\" heavily based on glibc infopages, copyright Free Software Foundation .\" -.TH significand 3 2023-07-20 "Linux man-pages 6.05.01" +.TH significand 3 2024-03-12 "Linux man-pages 6.7" .SH NAME significand, significandf, significandl \- get mantissa of floating-point number @@ -15,17 +15,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double significand(double " x ); .BI "float significandf(float " x ); .BI "long double significandl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR significand (), .BR significandf (), .BR significandl (): @@ -36,15 +36,16 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION These functions return the mantissa of .I x -scaled to the range [1,2). +scaled to the range +.RB [ 1 ,\~ FLT_RADIX ). They are equivalent to -.PP +.P .in +4n .EX scalb(x, (double) \-ilogb(x)) .EE .in -.PP +.P This function exists mainly for use in certain standardized tests for IEEE 754 conformance. .SH ATTRIBUTES @@ -63,7 +64,6 @@ T{ .BR significandl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .TP diff --git a/man3/sigpause.3 b/man3/sigpause.3 index 492d9fa..062f069 100644 --- a/man3/sigpause.3 +++ b/man3/sigpause.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sigpause 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sigpause 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sigpause \- atomically release blocked signals and wait for interrupt .SH LIBRARY @@ -12,9 +12,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int sigpause(int " sigmask "); /* BSD (but see NOTES) */" -.PP +.P .BI "[[deprecated]] int sigpause(int " sig "); /* POSIX.1 / SysV / UNIX 95 */" .fi .SH DESCRIPTION @@ -22,7 +22,7 @@ Don't use this function. Use .BR sigsuspend (2) instead. -.PP +.P The function .BR sigpause () is designed to wait for some signal. @@ -51,7 +51,6 @@ T{ .BR sigpause () T} Thread safety MT-Safe .TE -.sp 1 .\" FIXME: The marking is different from that in the glibc manual, .\" marking in glibc manual is more detailed: .\" @@ -63,7 +62,7 @@ T} Thread safety MT-Safe .SH VERSIONS On Linux, this routine is a system call only on the Sparc (sparc64) architecture. -.PP +.P .\" Libc4 and libc5 know only about the BSD version. .\" glibc uses the BSD version if the @@ -84,7 +83,7 @@ _XOPEN_SOURCE >= 500 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) .IP \[bu] glibc 2.25 and earlier: _XOPEN_SOURCE -.PP +.P Since glibc 2.19, only the System V version is exposed by .IR ; applications that formerly used the BSD @@ -100,7 +99,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001. Obsoleted in POSIX.1-2008. -.PP +.P The classical BSD version of this function appeared in 4.2BSD. It sets the process's signal mask to .IR sigmask . diff --git a/man3/sigqueue.3 b/man3/sigqueue.3 index 98238a4..99ea60f 100644 --- a/man3/sigqueue.3 +++ b/man3/sigqueue.3 @@ -6,7 +6,7 @@ .\" added note on self-signaling, aeb, 2002-06-07 .\" added note on CAP_KILL, mtk, 2004-06-16 .\" -.TH sigqueue 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sigqueue 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sigqueue \- queue a signal and data to a process .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigqueue (): .nf _POSIX_C_SOURCE >= 199309L @@ -40,12 +40,12 @@ As with .BR kill (2), the null signal (0) can be used to check if a process with a given PID exists. -.PP +.P The .I value argument is used to specify an accompanying item of data (either an integer or a pointer value) to be sent with the signal, and has the following type: -.PP +.P .in +4n .EX union sigval { @@ -54,7 +54,7 @@ union sigval { }; .EE .in -.PP +.P If the receiving process has installed a handler for this signal using the .B SA_SIGINFO flag to @@ -111,7 +111,6 @@ T{ .BR sigqueue () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel differences On Linux, @@ -130,7 +129,7 @@ Inside the glibc wrapper, this argument, .IR uinfo , is initialized as follows: -.PP +.P .in +4n .EX uinfo.si_signo = sig; /* Argument supplied to sigqueue() */ diff --git a/man3/sigset.3 b/man3/sigset.3 index f7fad4d..2d393d6 100644 --- a/man3/sigset.3 +++ b/man3/sigset.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sigset 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sigset 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sigset, sighold, sigrelse, sigignore \- System V signal API .SH LIBRARY @@ -12,21 +12,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B typedef void (*sighandler_t)(int); -.PP +.P .BI "[[deprecated]] sighandler_t sigset(int " sig ", sighandler_t " disp ); -.PP +.P .BI "[[deprecated]] int sighold(int " sig ); .BI "[[deprecated]] int sigrelse(int " sig ); .BI "[[deprecated]] int sigignore(int " sig ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigset (), .BR sighold (), .BR sigrelse (), @@ -42,7 +42,7 @@ This API is obsolete: new applications should use the POSIX signal API .RB ( sigaction (2), .BR sigprocmask (2), etc.) -.PP +.P The .BR sigset () function modifies the disposition of the signal @@ -67,13 +67,13 @@ Add to the process's signal mask, but leave the disposition of .I sig unchanged. -.PP +.P If .I disp specifies the address of a signal handler, then .I sig is added to the process's signal mask during execution of the handler. -.PP +.P If .I disp was specified as a value other than @@ -81,25 +81,25 @@ was specified as a value other than then .I sig is removed from the process's signal mask. -.PP +.P The dispositions for .B SIGKILL and .B SIGSTOP cannot be changed. -.PP +.P The .BR sighold () function adds .I sig to the calling process's signal mask. -.PP +.P The .BR sigrelse () function removes .I sig from the calling process's signal mask. -.PP +.P The .BR sigignore () function sets the disposition of @@ -122,7 +122,7 @@ returns \-1, with .I errno set to indicate the error. (But see BUGS below.) -.PP +.P The .BR sighold (), .BR sigrelse (), @@ -138,14 +138,14 @@ see the ERRORS under .BR sigaction (2) and .BR sigprocmask (2). -.PP +.P For .BR sighold () and .BR sigrelse () see the ERRORS under .BR sigprocmask (2). -.PP +.P For .BR sigignore (), see the errors under @@ -167,7 +167,6 @@ T{ .BR sigignore () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .TP @@ -194,7 +193,7 @@ function provides reliable signal handling semantics (as when calling with .I sa_mask equal to 0). -.PP +.P On System V, the .BR signal () function provides unreliable semantics (as when calling @@ -212,7 +211,7 @@ unspecified. See .BR signal (2) for further details. -.PP +.P In order to wait for a signal, BSD and System V both provided a function named .BR sigpause (3), @@ -229,7 +228,7 @@ if .I disp was specified as a value other than .BR SIG_HOLD . -.PP +.P Before glibc 2.5, .BR sigset () does not correctly return the previous disposition of the signal diff --git a/man3/sigsetops.3 b/man3/sigsetops.3 index 4172dbc..7fc1140 100644 --- a/man3/sigsetops.3 +++ b/man3/sigsetops.3 @@ -9,7 +9,7 @@ .\" 2007-10-26 mdw added wording that a sigset_t must be initialized .\" prior to use .\" -.TH SIGSETOPS 3 2023-07-20 "Linux man-pages 6.05.01" +.TH SIGSETOPS 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sigemptyset, sigfillset, sigaddset, sigdelset, sigismember \- POSIX signal set operations @@ -19,21 +19,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigemptyset(sigset_t *" set ); .BI "int sigfillset(sigset_t *" set ); -.PP +.P .BI "int sigaddset(sigset_t *" set ", int " signum ); .BI "int sigdelset(sigset_t *" set ", int " signum ); -.PP +.P .BI "int sigismember(const sigset_t *" set ", int " signum ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigemptyset (), .BR sigfillset (), .BR sigaddset (), @@ -44,17 +44,17 @@ Feature Test Macro Requirements for glibc (see .fi .SH DESCRIPTION These functions allow the manipulation of POSIX signal sets. -.PP +.P .BR sigemptyset () initializes the signal set given by .I set to empty, with all signals excluded from the set. -.PP +.P .BR sigfillset () initializes .I set to full, including all signals. -.PP +.P .BR sigaddset () and .BR sigdelset () @@ -62,13 +62,13 @@ add and delete respectively signal .I signum from .IR set . -.PP +.P .BR sigismember () tests whether .I signum is a member of .IR set . -.PP +.P Objects of type .I sigset_t must be initialized by a call to either @@ -93,7 +93,7 @@ The results are undefined if this is not done. and .BR sigdelset () return 0 on success and \-1 on error. -.PP +.P .BR sigismember () returns 1 if .I signum @@ -102,7 +102,7 @@ is a member of 0 if .I signum is not a member, and \-1 on error. -.PP +.P On error, these functions set .I errno to indicate the error. @@ -132,7 +132,6 @@ T{ .BR sigandset () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS GNU If the @@ -140,7 +139,7 @@ If the feature test macro is defined, then \fI\fP exposes three other functions for manipulating signal sets: -.PP +.P .nf .BI "int sigisemptyset(const sigset_t *" set ); .BI "int sigorset(sigset_t *" dest ", const sigset_t *" left , @@ -148,12 +147,12 @@ sets: .BI "int sigandset(sigset_t *" dest ", const sigset_t *" left , .BI " const sigset_t *" right ); .fi -.PP +.P .BR sigisemptyset () returns 1 if .I set contains no signals, and 0 otherwise. -.PP +.P .BR sigorset () places the union of the sets .I left @@ -169,7 +168,7 @@ and in .IR dest . Both functions return 0 on success, and \-1 on failure. -.PP +.P These functions are nonstandard (a few other systems provide similar functions) and their use should be avoided in portable applications. .SH STANDARDS diff --git a/man3/sigvec.3 b/man3/sigvec.3 index c4529a8..d5ae4b0 100644 --- a/man3/sigvec.3 +++ b/man3/sigvec.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sigvec 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sigvec 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sigvec, sigblock, sigsetmask, siggetmask, sigmask \- BSD signal API .SH LIBRARY @@ -12,22 +12,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int sigvec(int " sig ", const struct sigvec *" vec , .BI " struct sigvec *" ovec ); -.PP +.P .BI "[[deprecated]] int sigmask(int " signum ); -.PP +.P .BI "[[deprecated]] int sigblock(int " mask ); .BI "[[deprecated]] int sigsetmask(int " mask ); .B [[deprecated]] int siggetmask(void); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .nf Since glibc 2.19: @@ -42,7 +42,7 @@ This API is obsolete: new applications should use the POSIX signal API .RB ( sigaction (2), .BR sigprocmask (2), etc.). -.PP +.P The .BR sigvec () function sets and/or gets the disposition of the signal @@ -67,17 +67,17 @@ without changing it, specify NULL for .IR vec , and a non-null pointer for .IR ovec . -.PP +.P The dispositions for .B SIGKILL and .B SIGSTOP cannot be changed. -.PP +.P The .I sigvec structure has the following form: -.PP +.P .in +4n .EX struct sigvec { @@ -87,7 +87,7 @@ struct sigvec { }; .EE .in -.PP +.P The .I sv_handler field specifies the disposition of the signal, and is either: @@ -96,7 +96,7 @@ the address of a signal handler function; meaning the default disposition applies for the signal; or .BR SIG_IGN , meaning that the signal is ignored. -.PP +.P If .I sv_handler specifies the address of a signal handler, then @@ -110,7 +110,7 @@ Attempts to block or .B SIGSTOP are silently ignored. -.PP +.P If .I sv_handler specifies the address of a signal handler, then the @@ -141,7 +141,7 @@ Handle the signal on the alternate signal stack .BR sigstack () function; the POSIX replacement is .BR sigaltstack (2)). -.PP +.P The .BR sigmask () macro constructs and returns a "signal mask" for @@ -151,7 +151,7 @@ For example, we can initialize the field given to .BR sigvec () using code such as the following: -.PP +.P .in +4n .EX vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT); @@ -159,7 +159,7 @@ vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT); handler execution */ .EE .in -.PP +.P The .BR sigblock () function adds the signals in @@ -173,7 +173,7 @@ Attempts to block or .B SIGSTOP are silently ignored. -.PP +.P The .BR sigsetmask () function sets the process's signal mask to the value given in @@ -181,7 +181,7 @@ function sets the process's signal mask to the value given in (like POSIX .IR sigprocmask(SIG_SETMASK) ), and returns the process's previous signal mask. -.PP +.P The .BR siggetmask () function returns the process's current signal mask. @@ -193,13 +193,13 @@ The function returns 0 on success; on error, it returns \-1 and sets .I errno to indicate the error. -.PP +.P The .BR sigblock () and .BR sigsetmask () functions return the previous signal mask. -.PP +.P The .BR sigmask () macro returns the signal mask for @@ -227,7 +227,6 @@ T{ .BR siggetmask () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -263,7 +262,7 @@ unspecified. See .BR signal (2) for further details. -.PP +.P In order to wait for a signal, BSD and System V both provided a function named .BR sigpause (3), diff --git a/man3/sigwait.3 b/man3/sigwait.3 index 38250ec..2ac7d0e 100644 --- a/man3/sigwait.3 +++ b/man3/sigwait.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sigwait 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sigwait 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sigwait \- wait for a signal .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigwait(const sigset_t *restrict " set ", int *restrict " sig ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigwait (): .nf Since glibc 2.26: @@ -40,7 +40,7 @@ The function accepts the signal (removes it from the pending list of signals), and returns the signal number in .IR sig . -.PP +.P The operation of .BR sigwait () is the same as @@ -78,12 +78,11 @@ T{ .BR sigwait () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .BR sigwait () is implemented using .BR sigtimedwait (2). -.PP +.P The glibc implementation of .BR sigwait () silently ignores attempts to wait for the two real-time signals that diff --git a/man3/sin.3 b/man3/sin.3 index 8ef99de..1038af0 100644 --- a/man3/sin.3 +++ b/man3/sin.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH sin 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sin, sinf, sinl \- sine function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double sin(double " x ); .BI "float sinf(float " x ); .BI "long double sinl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sinf (), .BR sinl (): .nf @@ -50,11 +50,11 @@ given in radians. .SH RETURN VALUE On success, these functions return the sine of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity or negative infinity, @@ -68,7 +68,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity @@ -95,12 +95,11 @@ T{ .BR sinl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/sincos.3 b/man3/sincos.3 index 79b920d..1093c3b 100644 --- a/man3/sincos.3 +++ b/man3/sincos.3 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH sincos 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sincos 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sincos, sincosf, sincosl \- calculate sin and cos simultaneously .SH LIBRARY @@ -15,7 +15,7 @@ Math library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void sincos(double " x ", double *" sin ", double *" cos ); .BI "void sincosf(float " x ", float *" sin ", float *" cos ); .BI "void sincosl(long double " x ", long double *" sin ", long double *" cos ); @@ -31,7 +31,7 @@ Using this function can be more efficient than two separate calls to .BR sin (3) and .BR cos (3). -.PP +.P If .I x is a NaN, @@ -39,7 +39,7 @@ a NaN is returned in .I *sin and .IR *cos . -.PP +.P If .I x is positive infinity or negative infinity, @@ -56,7 +56,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity @@ -83,7 +83,6 @@ T{ .BR sincosl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH HISTORY @@ -94,7 +93,7 @@ To see the performance advantage of it may be necessary to disable .BR gcc (1) built-in optimizations, using flags such as: -.PP +.P .in +4n .EX cc \-O \-lm \-fno\-builtin prog.c diff --git a/man3/sinh.3 b/man3/sinh.3 index bc9d17e..c9027d6 100644 --- a/man3/sinh.3 +++ b/man3/sinh.3 @@ -14,7 +14,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH sinh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sinh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sinh, sinhf, sinhl \- hyperbolic sine function .SH LIBRARY @@ -23,17 +23,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double sinh(double " x ); .BI "float sinhf(float " x ); .BI "long double sinhl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sinhf (), .BR sinhl (): .nf @@ -46,27 +46,27 @@ These functions return the hyperbolic sine of .IR x , which is defined mathematically as: -.PP +.P .nf sinh(x) = (exp(x) \- exp(\-x)) / 2 .fi .SH RETURN VALUE On success, these functions return the hyperbolic sine of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity (negative infinity), positive infinity (negative infinity) is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -85,7 +85,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Range error: result overflow @@ -111,12 +111,11 @@ T{ .BR sinhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/sleep.3 b/man3/sleep.3 index cf87069..ae70958 100644 --- a/man3/sleep.3 +++ b/man3/sleep.3 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" Modified Sat Jul 24 18:16:02 1993 by Rik Faith (faith@cs.unc.edu) -.TH sleep 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sleep 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sleep \- sleep for a specified number of seconds .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "unsigned int sleep(unsigned int " "seconds" ); .fi .SH DESCRIPTION @@ -40,7 +40,6 @@ T{ .BR sleep () T} Thread safety MT-Unsafe sig:SIGCHLD/linux .TE -.sp 1 .SH VERSIONS On Linux, .BR sleep () @@ -49,7 +48,7 @@ is implemented via See the .BR nanosleep (2) man page for a discussion of the clock used. -.PP +.P On some systems, .BR sleep () may be implemented using diff --git a/man3/slist.3 b/man3/slist.3 index 98ce859..396b9cb 100644 --- a/man3/slist.3 +++ b/man3/slist.3 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH SLIST 3 2023-05-03 "Linux man-pages 6.05.01" +.TH SLIST 3 2023-10-31 "Linux man-pages 6.7" .SH NAME SLIST_EMPTY, SLIST_ENTRY, @@ -31,45 +31,45 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B SLIST_ENTRY(TYPE); -.PP +.P .B SLIST_HEAD(HEADNAME, TYPE); .BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head ); .BI "void SLIST_INIT(SLIST_HEAD *" head ); -.PP +.P .BI "int SLIST_EMPTY(SLIST_HEAD *" head ); -.PP +.P .BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head , .BI " struct TYPE *" elm ", SLIST_ENTRY " NAME ); .BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm , .BI " struct TYPE *" elm ", SLIST_ENTRY " NAME ); -.PP +.P .BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head ); .BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME ); -.PP +.P .BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ); .\" .BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head , .\" .BI " SLIST_ENTRY " NAME ); -.\" .PP +.\" .P .\" .BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head , .\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var ); .\" .BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head , .\" .BI " SLIST_ENTRY " NAME ", struct TYPE *" temp_var ); -.PP +.P .BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm , .BI " SLIST_ENTRY " NAME ); .BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head , .BI " SLIST_ENTRY " NAME ); .\" .BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm , .\" .BI " SLIST_ENTRY " NAME ); -.\" .PP +.\" .P .\" .BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 , .\" .BI " SLIST_ENTRY " NAME ); .fi .SH DESCRIPTION These macros define and operate on doubly linked lists. -.PP +.P In the macro definitions, .I TYPE is the name of a user-defined structure, @@ -96,44 +96,44 @@ or at the head of the list. An .I SLIST_HEAD structure is declared as follows: -.PP +.P .in +4 .EX SLIST_HEAD(HEADNAME, TYPE) head; .EE .in -.PP +.P where .I struct HEADNAME is the structure to be defined, and .I struct TYPE is the type of the elements to be linked into the list. A pointer to the head of the list can later be declared as: -.PP +.P .in +4 .EX struct HEADNAME *headp; .EE .in -.PP +.P (The names .I head and .I headp are user selectable.) -.PP +.P .BR SLIST_ENTRY () declares a structure that connects the elements in the list. -.PP +.P .BR SLIST_HEAD_INITIALIZER () evaluates to an initializer for the list .IR head . -.PP +.P .BR SLIST_INIT () initializes the list referenced by .IR head . -.PP +.P .BR SLIST_EMPTY () evaluates to true if there are no elements in the list. .SS Insertion @@ -141,7 +141,7 @@ evaluates to true if there are no elements in the list. inserts the new element .I elm at the head of the list. -.PP +.P .BR SLIST_INSERT_AFTER () inserts the new element .I elm @@ -150,17 +150,17 @@ after the element .SS Traversal .BR SLIST_FIRST () returns the first element in the list, or NULL if the list is empty. -.PP +.P .BR SLIST_NEXT () returns the next element in the list. -.PP +.P .BR SLIST_FOREACH () traverses the list referenced by .I head in the forward direction, assigning each element in turn to .IR var . -.\" .PP +.\" .P .\" .BR SLIST_FOREACH_FROM () .\" behaves identically to .\" .BR SLIST_FOREACH () @@ -185,7 +185,7 @@ assigning each element in turn to .\" .I var .\" as well as free it from within the loop safely without interfering with the .\" traversal. -.\" .PP +.\" .P .\" .BR SLIST_FOREACH_FROM_SAFE () .\" behaves identically to .\" .BR SLIST_FOREACH_SAFE () @@ -202,7 +202,7 @@ assigning each element in turn to removes the element .I elm from the list. -.PP +.P .BR SLIST_REMOVE_HEAD () removes the element .I elm @@ -211,7 +211,7 @@ For optimum efficiency, elements being removed from the head of the list should explicitly use this macro instead of the generic .BR SLIST_REMOVE (). -.\" .PP +.\" .P .\" .BR SLIST_REMOVE_AFTER () .\" removes the element after .\" .I elm @@ -229,14 +229,14 @@ should explicitly use this macro instead of the generic .BR SLIST_EMPTY () returns nonzero if the list is empty, and zero if the list contains at least one entry. -.PP +.P .BR SLIST_FIRST (), and .BR SLIST_NEXT () return a pointer to the first or next .I TYPE structure, respectively. -.PP +.P .BR SLIST_HEAD_INITIALIZER () returns an initializer that can be assigned to the list .IR head . diff --git a/man3/sockatmark.3 b/man3/sockatmark.3 index ca03910..7d07791 100644 --- a/man3/sockatmark.3 +++ b/man3/sockatmark.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sockatmark 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sockatmark 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sockatmark \- determine whether socket is at out-of-band mark .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sockatmark(int " sockfd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sockatmark (): .nf _POSIX_C_SOURCE >= 200112L @@ -67,7 +67,6 @@ T{ .BR sockatmark () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -80,14 +79,14 @@ returns 1, then the out-of-band data can be read using the .B MSG_OOB flag of .BR recv (2). -.PP +.P Out-of-band data is supported only on some stream socket protocols. -.PP +.P .BR sockatmark () can safely be called from a handler for the .B SIGURG signal. -.PP +.P .BR sockatmark () is implemented using the .B SIOCATMARK @@ -102,7 +101,7 @@ The following code can be used after receipt of a .B SIGURG signal to read (and discard) all data up to the mark, and then read the byte of data at the mark: -.PP +.P .EX char buf[BUF_LEN]; char oobdata; diff --git a/man3/sqrt.3 b/man3/sqrt.3 index fac38c0..6c6e469 100644 --- a/man3/sqrt.3 +++ b/man3/sqrt.3 @@ -12,7 +12,7 @@ .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) -.TH sqrt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sqrt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sqrt, sqrtf, sqrtl \- square root function .SH LIBRARY @@ -21,17 +21,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double sqrt(double " x ); .BI "float sqrtf(float " x ); .BI "long double sqrtl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sqrtf (), .BR sqrtl (): .nf @@ -45,19 +45,19 @@ These functions return the nonnegative square root of .SH RETURN VALUE On success, these functions return the square root of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is less than \-0, @@ -68,7 +68,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP less than \-0 @@ -94,12 +94,11 @@ T{ .BR sqrtl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/sscanf.3 b/man3/sscanf.3 index 223f4f5..7e0198c 100644 --- a/man3/sscanf.3 +++ b/man3/sscanf.3 @@ -22,7 +22,7 @@ .\" Add ERRORS section. .\" Document the 'a' and 'm' modifiers for dynamic string allocation. .\" -.TH sscanf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sscanf 3 2023-12-09 "Linux man-pages 6.7" .SH NAME sscanf, vsscanf \- input string format conversion .SH LIBRARY @@ -31,21 +31,21 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sscanf(const char *restrict " str , .BI " const char *restrict " format ", ...);" -.PP +.P .B #include -.PP +.P .BI "int vsscanf(const char *restrict " str , .BI " const char *restrict " format ", va_list " ap ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vsscanf (): .nf _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L @@ -53,7 +53,7 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION The .BR sscanf () -family of functions scans input according to +family of functions scans formatted input according to .I format as described below. This format may contain @@ -67,7 +67,7 @@ Each .I pointer argument must be of a type that is appropriate for the value returned by the corresponding conversion specification. -.PP +.P If the number of conversion specifications in .I format exceeds the number of @@ -78,17 +78,17 @@ If the number of arguments exceeds the number of conversion specifications, then the excess .I pointer arguments are evaluated, but are otherwise ignored. -.PP +.P .BR sscanf () These functions read their input from the string pointed to by .IR str . -.PP +.P The .BR vsscanf () function is analogous to .BR vsprintf (3). -.PP +.P The .I format string consists of a sequence of @@ -102,7 +102,7 @@ A "failure" can be either of the following: meaning that input characters were unavailable, or .IR "matching failure" , meaning that the input was inappropriate (see below). -.PP +.P A directive is one of the following: .TP \[bu] @@ -125,7 +125,7 @@ argument. If the next item of input does not match the conversion specification, the conversion fails\[em]this is a .IR "matching failure" . -.PP +.P Each .I conversion specification in @@ -205,7 +205,7 @@ rather than a pointer to an A .I "conversion specifier" that specifies the type of input conversion to be performed. -.PP +.P The conversion specifications in .I format are of two forms, either beginning with \[aq]%\[aq] or beginning with @@ -344,7 +344,7 @@ As for but the next pointer is a pointer to a .IR size_t . This modifier was introduced in C99. -.PP +.P The following .I "conversion specifiers" are available: @@ -359,7 +359,6 @@ No conversion is done (but initial white space characters are discarded), and assignment does not occur. .TP .B d -.IR Deprecated . Matches an optionally signed decimal integer; the next pointer must be a pointer to .IR int . @@ -374,7 +373,6 @@ the next pointer must be a pointer to .\" is silently ignored, causing old programs to fail mysteriously.) .TP .B i -.IR Deprecated . Matches an optionally signed integer; the next pointer must be a pointer to .IR int . The integer is read in base 16 if it begins with @@ -387,18 +385,15 @@ and in base 10 otherwise. Only characters that correspond to the base are used. .TP .B o -.IR Deprecated . Matches an unsigned octal integer; the next pointer must be a pointer to .IR "unsigned int" . .TP .B u -.IR Deprecated . Matches an unsigned decimal integer; the next pointer must be a pointer to .IR "unsigned int" . .TP .B x -.IR Deprecated . Matches an unsigned hexadecimal integer (that may optionally begin with a prefix of .I 0x @@ -409,33 +404,27 @@ be a pointer to .IR "unsigned int" . .TP .B X -.IR Deprecated . Equivalent to .BR x . .TP .B f -.IR Deprecated . Matches an optionally signed floating-point number; the next pointer must be a pointer to .IR float . .TP .B e -.IR Deprecated . Equivalent to .BR f . .TP .B g -.IR Deprecated . Equivalent to .BR f . .TP .B E -.IR Deprecated . Equivalent to .BR f . .TP .B a -.IR Deprecated . (C99) Equivalent to .BR f . .TP @@ -522,7 +511,7 @@ On success, these functions return the number of input items successfully matched and assigned; this can be fewer than provided for, or even zero, in the event of an early matching failure. -.PP +.P The value .B EOF is returned if the end of input is reached before either the first @@ -554,12 +543,11 @@ T{ .BR vsscanf () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001. -.PP +.P The .B q specifier is the 4.4BSD notation for @@ -569,7 +557,7 @@ while or the usage of .B L in integer conversions is the GNU notation. -.PP +.P The Linux version of these functions is based on the .I GNU .I libio @@ -592,14 +580,14 @@ Thus, one could write the following to have allocate a buffer for a string, with a pointer to that buffer being returned in .IR *buf : -.PP +.P .in +4n .EX char *buf; sscanf(str, "%as", &buf); .EE .in -.PP +.P The use of the letter .B a for this purpose was problematic, since @@ -610,7 +598,7 @@ is also specified by the ISO C standard as a synonym for POSIX.1-2008 instead specifies the .B m modifier for assignment allocation (as documented in DESCRIPTION, above). -.PP +.P Note that the .B a modifier is not available if the program is compiled with @@ -622,13 +610,13 @@ or is also specified), in which case the .B a is interpreted as a specifier for floating-point numbers (see above). -.PP +.P Support for the .B m modifier was added to glibc 2.7, and new programs should use that modifier instead of .BR a . -.PP +.P As well as being standardized by POSIX, the .B m modifier has the following further advantages over @@ -662,8 +650,8 @@ Instead, programs should use functions such as .BR strtol (3) to parse numeric input. -This manual page deprecates use of the numeric conversion specifiers -until they are fixed by ISO C. +Alternatively, +mitigate it by specifying a maximum field width. .SS Nonstandard modifiers These functions are fully C99 conformant, but provide the additional modifiers @@ -677,7 +665,7 @@ and modifiers. The latter may be considered to be a bug, as it changes the behavior of modifiers defined in C99. -.PP +.P Some combinations of the type modifiers and conversion specifiers defined by C99 do not make sense (e.g., @@ -693,7 +681,7 @@ in combination with \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP conversions or .BR ll . -.PP +.P The usage of .B q is not the same as on 4.4BSD, @@ -709,7 +697,7 @@ or The caller must .BR free (3) the returned string, as in the following example: -.PP +.P .in +4n .EX char *p; @@ -727,7 +715,7 @@ if (n == 1) { } .EE .in -.PP +.P As shown in the above example, it is necessary to call .BR free (3) only if the diff --git a/man3/stailq.3 b/man3/stailq.3 index 2fca240..367b2bf 100644 --- a/man3/stailq.3 +++ b/man3/stailq.3 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH STAILQ 3 2023-05-03 "Linux man-pages 6.05.01" +.TH STAILQ 3 2023-10-31 "Linux man-pages 6.7" .SH NAME .\"SIMPLEQ_CONCAT, SIMPLEQ_EMPTY, @@ -54,43 +54,43 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B STAILQ_ENTRY(TYPE); -.PP +.P .B STAILQ_HEAD(HEADNAME, TYPE); .BI "STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD " head ); .BI "void STAILQ_INIT(STAILQ_HEAD *" head ); -.PP +.P .BI "int STAILQ_EMPTY(STAILQ_HEAD *" head ); -.PP +.P .BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head , .BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); .BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head , .BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); .BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm , .BI " struct TYPE *" elm ", STAILQ_ENTRY " NAME ); -.PP +.P .BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head ); .\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm , .\" .BI " STAILQ_ENTRY " NAME ); .BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME ); -.PP +.P .BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ); .\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head , .\" .BI " STAILQ_ENTRY " NAME ); -.\" .PP +.\" .P .\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head , .\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ); .\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head , .\" .BI " STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ); -.PP +.P .BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", struct TYPE *" elm ", TYPE," .BI " STAILQ_ENTRY " NAME ); .BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head , .BI " STAILQ_ENTRY " NAME ); .\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm , .\" .BI " STAILQ_ENTRY " NAME ); -.PP +.P .BI "void STAILQ_CONCAT(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ); .\" .BI "void STAILQ_SWAP(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 , .\" .BI " STAILQ_ENTRY " NAME ); @@ -99,7 +99,7 @@ Standard C library Identical macros prefixed with SIMPLEQ instead of STAILQ exist; see NOTES. .SH DESCRIPTION These macros define and operate on singly linked tail queues. -.PP +.P In the macro definitions, .I TYPE is the name of a user-defined structure, @@ -126,43 +126,43 @@ at the head of the tail queue, or at the end of the tail queue. A .I STAILQ_HEAD structure is declared as follows: -.PP +.P .in +4 .EX STAILQ_HEAD(HEADNAME, TYPE) head; .EE .in -.PP +.P where .I struct HEADNAME is the structure to be defined, and .I struct TYPE is the type of the elements to be linked into the tail queue. A pointer to the head of the tail queue can later be declared as: -.PP +.P .in +4 .EX struct HEADNAME *headp; .EE .in -.PP +.P (The names .I head and .I headp are user selectable.) -.PP +.P .BR STAILQ_ENTRY () declares a structure that connects the elements in the tail queue. -.PP +.P .BR STAILQ_HEAD_INITIALIZER () evaluates to an initializer for the tail queue .IR head . -.PP +.P .BR STAILQ_INIT () initializes the tail queue referenced by .IR head . -.PP +.P .BR STAILQ_EMPTY () evaluates to true if there are no items on the tail queue. .SS Insertion @@ -170,12 +170,12 @@ evaluates to true if there are no items on the tail queue. inserts the new element .I elm at the head of the tail queue. -.PP +.P .BR STAILQ_INSERT_TAIL () inserts the new element .I elm at the end of the tail queue. -.PP +.P .BR STAILQ_INSERT_AFTER () inserts the new element .I elm @@ -184,21 +184,21 @@ after the element .SS Traversal .BR STAILQ_FIRST () returns the first item on the tail queue or NULL if the tail queue is empty. -.\" .PP +.\" .P .\" .BR STAILQ_LAST () .\" returns the last item on the tail queue. .\" If the tail queue is empty the return value is NULL . -.PP +.P .BR STAILQ_NEXT () returns the next item on the tail queue, or NULL this item is the last. -.PP +.P .BR STAILQ_FOREACH () traverses the tail queue referenced by .I head in the forward direction, assigning each element in turn to .IR var . -.\" .PP +.\" .P .\" .BR STAILQ_FOREACH_FROM () .\" behaves identically to .\" .BR STAILQ_FOREACH () @@ -210,7 +210,7 @@ assigning each element in turn to .\" .I var .\" instead of the first element in the STAILQ referenced by .\" .IR head . -.\" .PP +.\" .P .\" .BR STAILQ_FOREACH_SAFE () .\" traverses the tail queue referenced by .\" .I head @@ -223,7 +223,7 @@ assigning each element in turn to .\" .I var .\" as well as free it from within the loop safely without interfering with the .\" traversal. -.\" .PP +.\" .P .\" .BR STAILQ_FOREACH_FROM_SAFE () .\" behaves identically to .\" .BR STAILQ_FOREACH_SAFE () @@ -240,7 +240,7 @@ assigning each element in turn to removes the element .I elm from the tail queue. -.PP +.P .BR STAILQ_REMOVE_HEAD () removes the element at the head of the tail queue. For optimum efficiency, @@ -248,7 +248,7 @@ elements being removed from the head of the tail queue should use this macro explicitly rather than the generic .BR STAILQ_REMOVE () macro. -.\" .PP +.\" .P .\" .BR STAILQ_REMOVE_AFTER () .\" removes the element after .\" .I elm @@ -263,7 +263,7 @@ concatenates the tail queue headed by onto the end of the one headed by .I head1 removing all entries from the former. -.\" .PP +.\" .P .\" .BR STAILQ_SWAP () .\" swaps the contents of .\" .I head1 @@ -273,14 +273,14 @@ removing all entries from the former. .BR STAILQ_EMPTY () returns nonzero if the queue is empty, and zero if the queue contains at least one entry. -.PP +.P .BR STAILQ_FIRST (), and .BR STAILQ_NEXT () return a pointer to the first or next .I TYPE structure, respectively. -.PP +.P .BR STAILQ_HEAD_INITIALIZER () returns an initializer that can be assigned to the queue .IR head . diff --git a/man3/static_assert.3 b/man3/static_assert.3 index 86c6673..a81306d 100644 --- a/man3/static_assert.3 +++ b/man3/static_assert.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH static_assert 3 2023-05-03 "Linux man-pages 6.05.01" +.TH static_assert 3 2023-10-31 "Linux man-pages 6.7" .SH NAME static_assert, _Static_assert \- fail compilation if assertion is false .SH LIBRARY @@ -11,9 +11,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void static_assert(scalar " constant-expression ", const char *" msg ); -.PP +.P /* Since C23: */ .BI "void static_assert(scalar " constant-expression ); .fi @@ -23,14 +23,14 @@ This macro is similar to but it works at compile time, generating a compilation error (with an optional message) when the input is false (i.e., compares equal to zero). -.PP +.P If the input is nonzero, no code is emitted. -.PP +.P .I msg must be a string literal. Since C23, this argument is optional. -.PP +.P There's a keyword, .BR \%_Static_assert (), that behaves identically, @@ -57,7 +57,7 @@ a macro can be written in terms of .BR \%static_assert (). The following program uses the macro to get the size of an array safely. -.PP +.P .in +4n .\" SRC BEGIN (must_be.c) .EX diff --git a/man3/statvfs.3 b/man3/statvfs.3 index 9b1978b..7d5d962 100644 --- a/man3/statvfs.3 +++ b/man3/statvfs.3 @@ -8,7 +8,7 @@ .\" .\" Modified 2004-06-23 by Michael Kerrisk .\" -.TH statvfs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH statvfs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME statvfs, fstatvfs \- get filesystem statistics .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int statvfs(const char *restrict " path \ ", struct statvfs *restrict " buf ); .BI "int fstatvfs(int " fd ", struct statvfs *" buf ); @@ -32,7 +32,7 @@ is the pathname of any file within the mounted filesystem. is a pointer to a .I statvfs structure defined approximately as follows: -.PP +.P .in +4n .EX struct statvfs { @@ -52,7 +52,7 @@ struct statvfs { }; .EE .in -.PP +.P Here the types .I fsblkcnt_t and @@ -61,7 +61,7 @@ are defined in .IR . Both used to be .IR "unsigned long" . -.PP +.P The field .I f_flag is a bit mask indicating various options that were employed @@ -104,10 +104,10 @@ Writes are synched to the filesystem immediately (see the description of .B O_SYNC in .BR open (2)). -.PP +.P It is unspecified whether all members of the returned struct have meaningful values on all filesystems. -.PP +.P .BR fstatvfs () returns the same information about an open file referenced by descriptor .IR fd . @@ -188,7 +188,6 @@ T{ .BR fstatvfs () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Only the .B ST_NOSUID @@ -205,9 +204,9 @@ The Linux kernel has system calls and .BR fstatfs (2) to support this library call. -.PP +.P The glibc implementations of -.PP +.P .in +4n .EX pathconf(path, _PC_REC_XFER_ALIGN); @@ -215,7 +214,7 @@ pathconf(path, _PC_ALLOC_SIZE_MIN); pathconf(path, _PC_REC_MIN_XFER_SIZE); .EE .in -.PP +.P respectively use the .IR f_frsize , .IR f_frsize , @@ -225,7 +224,7 @@ fields returned by a call to .BR statvfs () with the argument .IR path . -.PP +.P Under Linux, .I f_favail is always the same as @@ -237,7 +236,7 @@ since no filesystems with an inode root reservation exist. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Before glibc 2.13, .\" glibc commit 3cdaa6adb113a088fdfb87aa6d7747557eccc58d .BR statvfs () diff --git a/man3/stdarg.3 b/man3/stdarg.3 index f3762f7..ce04704 100644 --- a/man3/stdarg.3 +++ b/man3/stdarg.3 @@ -13,7 +13,7 @@ .\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu .\" Additions, 2001-10-14, aeb .\" -.TH stdarg 3 2023-07-20 "Linux man-pages 6.05.01" +.TH stdarg 3 2023-10-31 "Linux man-pages 6.7" .SH NAME stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void va_start(va_list " ap ", " last ); .IB type " va_arg(va_list " ap ", " type ); .BI "void va_end(va_list " ap ); @@ -37,7 +37,7 @@ declares a type .I va_list and defines three macros for stepping through a list of arguments whose number and types are not known to the called function. -.PP +.P The called function must declare an object of type .I va_list which is used by the macros @@ -55,12 +55,12 @@ for subsequent use by and .BR va_end (), and must be called first. -.PP +.P The argument .I last is the name of the last argument before the variable argument list, that is, the last argument of which the calling function knows the type. -.PP +.P Because the address of this argument may be used in the .BR va_start () macro, it should not be declared as a register variable, @@ -87,7 +87,7 @@ The argument is a type name specified so that the type of a pointer to an object that has the specified type can be obtained simply by adding a * to .IR type . -.PP +.P The first use of the .BR va_arg () macro after that of the @@ -95,12 +95,12 @@ macro after that of the macro returns the argument after .IR last . Successive invocations return the values of the remaining arguments. -.PP +.P If there is no next argument, or if .I type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), random errors will occur. -.PP +.P If .I ap is passed to a function that uses @@ -144,30 +144,30 @@ argument, followed by the same number of .BR va_arg () invocations that was used to reach the current state of .IR src . -.PP +.P .\" Proposal from clive@demon.net, 1997-02-28 An obvious implementation would have a .I va_list be a pointer to the stack frame of the variadic function. In such a setup (by far the most common) there seems nothing against an assignment -.PP +.P .in +4n .EX va_list aq = ap; .EE .in -.PP +.P Unfortunately, there are also systems that make it an array of pointers (of length 1), and there one needs -.PP +.P .in +4n .EX va_list aq; *aq = *ap; .EE .in -.PP +.P Finally, on systems where arguments are passed in registers, it may be necessary for .BR va_start () @@ -181,7 +181,7 @@ can free the allocated memory again. To accommodate this situation, C99 adds a macro .BR va_copy (), so that the above assignment can be replaced by -.PP +.P .in +4n .EX va_list aq; @@ -190,7 +190,7 @@ va_copy(aq, ap); va_end(aq); .EE .in -.PP +.P Each invocation of .BR va_copy () must be matched by a corresponding invocation of @@ -222,7 +222,6 @@ T{ .BR va_arg () T} Thread safety MT-Safe race:ap .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -257,7 +256,7 @@ The function .I foo takes a string of format characters and prints out the argument associated with each format character based on the type. -.PP +.P .EX #include #include diff --git a/man3/stdin.3 b/man3/stdin.3 index afe1fa5..42ed937 100644 --- a/man3/stdin.3 +++ b/man3/stdin.3 @@ -10,7 +10,7 @@ .\" 2005-06-16 mtk, mentioned freopen() .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH stdin 3 2023-03-30 "Linux man-pages 6.05.01" +.TH stdin 3 2023-10-31 "Linux man-pages 6.7" .SH NAME stdin, stdout, stderr \- standard I/O streams .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "extern FILE *" stdin ; .BI "extern FILE *" stdout ; .BI "extern FILE *" stderr ; @@ -35,7 +35,7 @@ but might instead refer to files or other devices, depending on what the parent process chose to set up. (See also the "Redirection" section of .BR sh (1).) -.PP +.P The input stream is referred to as "standard input"; the output stream is referred to as "standard output"; and the error stream is referred to as "standard error". @@ -45,7 +45,7 @@ used to refer to these files, namely .IR stdout , and .IR stderr . -.PP +.P Each of these symbols is a .BR stdio (3) macro of type pointer to @@ -54,7 +54,7 @@ and can be used with functions like .BR fprintf (3) or .BR fread (3). -.PP +.P Since .IR FILE s are a buffering wrapper around UNIX file descriptors, the @@ -63,7 +63,7 @@ interface, that is, the functions like .BR read (2) and .BR lseek (2). -.PP +.P On program startup, the integer file descriptors associated with the streams .IR stdin , @@ -82,7 +82,7 @@ are defined with these values in .BR freopen (3) to one of these streams can change the file descriptor number associated with the stream.) -.PP +.P Note that mixing use of .IR FILE s and raw file descriptors can produce @@ -95,7 +95,7 @@ This means for example, that after an .BR exec (3), the child inherits all open file descriptors, but all old streams have become inaccessible. -.PP +.P Since the symbols .IR stdin , .IR stdout , @@ -115,7 +115,7 @@ The standard streams are closed by a call to and by normal program termination. .SH STANDARDS C11, POSIX.1-2008. -.PP +.P The standards also stipulate that these three streams shall be open at program startup. .SH HISTORY diff --git a/man3/stdio.3 b/man3/stdio.3 index 3a5a447..73dfca2 100644 --- a/man3/stdio.3 +++ b/man3/stdio.3 @@ -9,7 +9,7 @@ .\" Converted for Linux, Mon Nov 29 16:07:22 1993, faith@cs.unc.edu .\" Modified, 2001-12-26, aeb .\" -.TH stdio 3 2023-07-30 "Linux man-pages 6.05.01" +.TH stdio 3 2023-12-29 "Linux man-pages 6.7" .SH NAME stdio \- standard input/output library functions .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "FILE *" stdin ; .BI "FILE *" stdout ; .BI "FILE *" stderr ; @@ -30,7 +30,7 @@ Input and output is mapped into logical data streams and the physical I/O characteristics are concealed. The functions and macros are listed below; more information is available from the individual man pages. -.PP +.P A stream is associated with an external file (which may be a physical device) by .I opening @@ -53,7 +53,7 @@ function; all output takes place as if all characters were written by successive calls to the .BR fputc (3) function. -.PP +.P A file is disassociated from a stream by .I closing the file. @@ -63,7 +63,7 @@ the file. The value of a pointer to a .I FILE object is indeterminate after a file is closed (garbage). -.PP +.P A file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it can be repositioned at the start). @@ -76,7 +76,7 @@ Other methods of program termination, such as .BR abort (3) do not bother about closing files properly. -.PP +.P At program startup, three text streams are predefined and need not be opened explicitly: .I standard input @@ -93,7 +93,7 @@ and When opened, the standard error stream is not fully buffered; the standard input and output streams are fully buffered if and only if the streams do not refer to an interactive device. -.PP +.P Output streams that refer to terminal devices are always line buffered by default; pending output to such streams is written automatically whenever an input stream that refers to a terminal device is read. @@ -103,7 +103,7 @@ output terminal, it is necessary to .BR fflush (3) the standard output before going off and computing so that the output will appear. -.PP +.P The .I stdio library is a part of the library @@ -115,7 +115,7 @@ SYNOPSIS sections of the following manual pages indicate which include files are to be used, what the compiler declaration for the function looks like and which external variables are of interest. -.PP +.P The following are defined as macros; these names may not be reused without first removing their current definitions with .BR #undef : @@ -192,9 +192,15 @@ T} \fBfileno\fP(3) T{ return the integer descriptor of the argument stream T} +\fBfmemopen\fP(3) T{ +open memory as stream +T} \fBfopen\fP(3) T{ stream open functions T} +\fBfopencookie\fP(3) T{ +open a custom stream +T} \fBfprintf\fP(3) T{ formatted output conversion T} @@ -243,6 +249,12 @@ T} \fBmktemp\fP(3) T{ make temporary filename (unique) T} +\fBopen_memstream\fP(3) T{ +open a dynamic memory buffer stream +T} +\fBopen_wmemstream\fP(3) T{ +open a dynamic memory buffer stream +T} \fBperror\fP(3) T{ system error messages T} diff --git a/man3/stdio_ext.3 b/man3/stdio_ext.3 index c154620..a98ffc5 100644 --- a/man3/stdio_ext.3 +++ b/man3/stdio_ext.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH stdio_ext 3 2023-07-20 "Linux man-pages 6.05.01" +.TH stdio_ext 3 2023-10-31 "Linux man-pages 6.7" .SH NAME __fbufsize, __flbf, __fpending, __fpurge, __freadable, __freading, __fsetlocking, __fwritable, __fwriting, _flushlbf \- @@ -15,7 +15,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "size_t __fbufsize(FILE *" stream ); .BI "size_t __fpending(FILE *" stream ); .BI "int __flbf(FILE *" stream ); @@ -32,46 +32,46 @@ Solaris introduced routines to allow portable access to the internals of the .I FILE structure, and glibc also implemented these. -.PP +.P The .BR __fbufsize () function returns the size of the buffer currently used by the given stream. -.PP +.P The .BR __fpending () function returns the number of bytes in the output buffer. For wide-oriented streams the unit is wide characters. This function is undefined on buffers in reading mode, or opened read-only. -.PP +.P The .BR __flbf () function returns a nonzero value if the stream is line-buffered, and zero otherwise. -.PP +.P The .BR __freadable () function returns a nonzero value if the stream allows reading, and zero otherwise. -.PP +.P The .BR __fwritable () function returns a nonzero value if the stream allows writing, and zero otherwise. -.PP +.P The .BR __freading () function returns a nonzero value if the stream is read-only, or if the last operation on the stream was a read operation, and zero otherwise. -.PP +.P The .BR __fwriting () function returns a nonzero value if the stream is write-only (or append-only), or if the last operation on the stream was a write operation, and zero otherwise. -.PP +.P The .BR __fsetlocking () function can be used to select the desired type of locking on the stream. @@ -95,13 +95,13 @@ will not do locking until the state is reset to .B FSETLOCKING_QUERY Don't change the type of locking. (Only return it.) -.PP +.P The .BR _flushlbf () function flushes all line-buffered streams. (Presumably so that output to a terminal is forced out, say before reading keyboard input.) -.PP +.P The .BR __fpurge () function discards the contents of the stream's buffer. @@ -132,7 +132,6 @@ T{ .BR _flushlbf () T} Thread safety MT-Safe .TE -.sp 1 .SH SEE ALSO .BR flockfile (3), .BR fpurge (3) diff --git a/man3/stpecpy.3 b/man3/stpecpy.3 deleted file mode 100644 index beb8507..0000000 --- a/man3/stpecpy.3 +++ /dev/null @@ -1 +0,0 @@ -.so man7/string_copying.7 diff --git a/man3/stpecpyx.3 b/man3/stpecpyx.3 deleted file mode 100644 index beb8507..0000000 --- a/man3/stpecpyx.3 +++ /dev/null @@ -1 +0,0 @@ -.so man7/string_copying.7 diff --git a/man3/stpncpy.3 b/man3/stpncpy.3 index 617eb9b..c4b5db4 100644 --- a/man3/stpncpy.3 +++ b/man3/stpncpy.3 @@ -3,32 +3,32 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH stpncpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH stpncpy 3 2024-02-12 "Linux man-pages 6.7" .SH NAME stpncpy, strncpy -\- zero a fixed-width buffer and -copy a string into a character sequence with truncation -and zero the rest of it +\- +fill a fixed-size buffer with non-null bytes from a string, +padding with null bytes as needed .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf .B #include -.PP -.BI "char *strncpy(char " dst "[restrict ." sz "], \ +.P +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.BI "char *stpncpy(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); +.BI " size_t " dsize ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR stpncpy (): .nf Since glibc 2.10: @@ -37,32 +37,36 @@ Feature Test Macro Requirements for glibc (see _GNU_SOURCE .fi .SH DESCRIPTION -These functions copy the string pointed to by +These functions copy non-null bytes from the string pointed to by .I src -into a null-padded character sequence at the fixed-width buffer pointed to by +into the array pointed to by .IR dst . +If the source has too few non-null bytes to fill the destination, +the functions pad the destination with trailing null bytes. If the destination buffer, limited by its size, isn't large enough to hold the copy, the resulting character sequence is truncated. For the difference between the two functions, see RETURN VALUE. -.PP +.P An implementation of these functions might be: -.PP +.P .in +4n .EX char * -strncpy(char *restrict dst, const char *restrict src, size_t sz) +strncpy(char *restrict dst, const char *restrict src, size_t dsize) { - stpncpy(dst, src, sz); + stpncpy(dst, src, dsize); return dst; } \& char * -stpncpy(char *restrict dst, const char *restrict src, size_t sz) +stpncpy(char *restrict dst, const char *restrict src, size_t dsize) { - bzero(dst, sz); - return mempcpy(dst, src, strnlen(src, sz)); + size_t dlen; +\& + dlen = strnlen(src, dsize); + return memset(mempcpy(dst, src, dlen), 0, dsize \- dlen); } .EE .in @@ -90,7 +94,6 @@ T{ .BR strncpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR strncpy () @@ -98,7 +101,7 @@ C11, POSIX.1-2008. .TP .BR stpncpy () POSIX.1-2008. -.SH STANDARDS +.SH HISTORY .TP .BR strncpy () C89, POSIX.1-2001, SVr4, 4.3BSD. @@ -111,13 +114,23 @@ The name of these functions is confusing. These functions produce a null-padded character sequence, not a string (see .BR string_copying (7)). -.PP +For example: +.P +.in +4n +.EX +strncpy(buf, "1", 5); // { \[aq]1\[aq], 0, 0, 0, 0 } +strncpy(buf, "1234", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], 0 } +strncpy(buf, "12345", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +strncpy(buf, "123456", 5); // { \[aq]1\[aq], \[aq]2\[aq], \[aq]3\[aq], \[aq]4\[aq], \[aq]5\[aq] } +.EE +.in +.P It's impossible to distinguish truncation by the result of the call, from a character sequence that just fits the destination buffer; truncation should be detected by comparing the length of the input string with the size of the destination buffer. -.PP +.P If you're going to use this function in chained calls, it would be useful to develop a similar function that accepts a pointer to the end (one after the last element) of the destination buffer @@ -139,20 +152,22 @@ main(void) size_t len; \& if (sizeof(buf2) < strlen("Hello world!")) - warnx("strncpy: truncating character sequence"); + errx("strncpy: truncating character sequence"); strncpy(buf2, "Hello world!", sizeof(buf2)); len = strnlen(buf2, sizeof(buf2)); \& printf("[len = %zu]: ", len); - printf("%.*s\en", (int) len, buf2); // "Hello world!" + fwrite(buf2, 1, len, stdout); + putchar(\[aq]\en\[aq]); \& if (sizeof(buf1) < strlen("Hello world!")) - warnx("stpncpy: truncating character sequence"); + errx("stpncpy: truncating character sequence"); p = stpncpy(buf1, "Hello world!", sizeof(buf1)); len = p \- buf1; \& printf("[len = %zu]: ", len); - printf("%.*s\en", (int) len, buf1); // "Hello world!" + fwrite(buf1, 1, len, stdout); + putchar(\[aq]\en\[aq]); \& exit(EXIT_SUCCESS); } diff --git a/man3/strcasecmp.3 b/man3/strcasecmp.3 index f19a5da..3154740 100644 --- a/man3/strcasecmp.3 +++ b/man3/strcasecmp.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:12:45 1993 by Rik Faith (faith@cs.unc.edu) -.TH strcasecmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strcasecmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strcasecmp, strncasecmp \- compare two strings ignoring case .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int strcasecmp(const char *" s1 ", const char *" s2 ); .BI "int strncasecmp(const char " s1 [. n "], const char " s2 [. n "], \ size_t " n ); @@ -36,7 +36,7 @@ less than, equal to, or greater than zero if is found, respectively, to be less than, to match, or be greater than .IR s2 . -.PP +.P The .BR strncasecmp () function is similar, except that it compares @@ -73,12 +73,11 @@ T{ .BR strncasecmp () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY 4.4BSD, POSIX.1-2001. -.PP +.P The .BR strcasecmp () and @@ -92,9 +91,9 @@ header file also declares these functions, if the (or, in glibc 2.19 and earlier, .BR _BSD_SOURCE ) feature test macro is defined. -.PP +.P The POSIX.1-2008 standard says of these functions: -.PP +.P .RS When the .B LC_CTYPE diff --git a/man3/strchr.3 b/man3/strchr.3 index 91bd8aa..bff3bd4 100644 --- a/man3/strchr.3 +++ b/man3/strchr.3 @@ -11,7 +11,7 @@ .\" 2006-05-19, Justin Pryzby .\" Document strchrnul(3). .\" -.TH strchr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strchr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strchr, strrchr, strchrnul \- locate character in string .SH LIBRARY @@ -20,13 +20,13 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strchr(const char *" s ", int " c ); .BI "char *strrchr(const char *" s ", int " c ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "char *strchrnul(const char *" s ", int " c ); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ of the character .I c in the string .IR s . -.PP +.P The .BR strrchr () function returns a pointer to the last occurrence @@ -45,7 +45,7 @@ of the character .I c in the string .IR s . -.PP +.P The .BR strchrnul () function is like @@ -58,7 +58,7 @@ then it returns a pointer to the null byte at the end of .IR s , rather than NULL. -.PP +.P Here "character" means "byte"; these functions do not work with wide or multibyte characters. .SH RETURN VALUE @@ -73,7 +73,7 @@ so that if .I c is specified as \[aq]\e0\[aq], these functions return a pointer to the terminator. -.PP +.P The .BR strchrnul () function returns a pointer to the matched character, @@ -98,7 +98,6 @@ T{ .BR strchrnul () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR strchr () diff --git a/man3/strcmp.3 b/man3/strcmp.3 index 57b378e..78fdf68 100644 --- a/man3/strcmp.3 +++ b/man3/strcmp.3 @@ -11,7 +11,7 @@ .\" Modified Sat Jul 24 18:08:52 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 2001-08-31, aeb .\" -.TH strcmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strcmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strcmp, strncmp \- compare two strings .SH LIBRARY @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int strcmp(const char *" s1 ", const char *" s2 ); .BI "int strncmp(const char " s1 [. n "], const char " s2 [. n "], size_t " n ); .fi @@ -34,7 +34,7 @@ and The locale is not taken into account (for a locale-aware comparison, see .BR strcoll (3)). The comparison is done using unsigned characters. -.PP +.P .BR strcmp () returns an integer indicating the result of the comparison, as follows: .IP \[bu] 3 @@ -53,7 +53,7 @@ a positive value if .I s1 is greater than .IR s2 . -.PP +.P The .BR strncmp () function is similar, except it compares @@ -91,18 +91,17 @@ T{ .BR strncmp () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS POSIX.1 specifies only that: .RS -.PP +.P The sign of a nonzero return value shall be determined by the sign of the difference between the values of the first pair of bytes (both interpreted as type .IR "unsigned char" ) that differ in the strings being compared. .RE -.PP +.P In glibc, as in most other implementations, the return value is the arithmetic result of subtracting the last compared byte in @@ -122,7 +121,7 @@ The program below can be used to demonstrate the operation of (when given three arguments). First, some examples using .BR strcmp (): -.PP +.P .in +4n .EX $ \fB./string_comp ABC ABC\fP @@ -137,16 +136,16 @@ $ .\fB/string_comp $\[aq]\e201\[aq] A\fP # 0201 \- 0101 = 0100 (or 64 decimal) is greater than (64) .EE .in -.PP +.P The last example uses .BR bash (1)-specific syntax to produce a string containing an 8-bit ASCII code; the result demonstrates that the string comparison uses unsigned characters. -.PP +.P And then some examples using .BR strncmp (): -.PP +.P .in +4n .EX $ \fB./string_comp ABC AB 3\fP diff --git a/man3/strcoll.3 b/man3/strcoll.3 index e8146b7..71918ea 100644 --- a/man3/strcoll.3 +++ b/man3/strcoll.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sun Jul 25 10:40:44 1993 by Rik Faith (faith@cs.unc.edu) -.TH strcoll 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strcoll 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strcoll \- compare two strings using the current locale .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int strcoll(const char *" s1 ", const char *" s2 ); .fi .SH DESCRIPTION @@ -64,7 +64,6 @@ T{ .BR strcoll () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/strcpy.3 b/man3/strcpy.3 index 63ed127..fd0c335 100644 --- a/man3/strcpy.3 +++ b/man3/strcpy.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH strcpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strcpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME stpcpy, strcpy, strcat \- copy or catenate a string .SH LIBRARY @@ -12,17 +12,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); .BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); .BI "char *strcat(char *restrict " dst ", const char *restrict " src ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR stpcpy (): .nf Since glibc 2.10: @@ -54,9 +54,9 @@ after the string pointed to by The programmer is responsible for allocating a destination buffer large enough, that is, .IR "strlen(dst) + strlen(src) + 1" . -.PP +.P An implementation of these functions might be: -.PP +.P .in +4n .EX char * @@ -112,7 +112,6 @@ T{ .BR strcat () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR stpcpy () @@ -137,19 +136,19 @@ The strings and .I dst may not overlap. -.PP +.P If the destination buffer is not large enough, the behavior is undefined. See .B _FORTIFY_SOURCE in .BR feature_test_macros (7). -.PP +.P .BR strcat () can be very inefficient. Read about .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ -Shlemiel the painter +Shlemiel the painter .UE . .SH EXAMPLES .\" SRC BEGIN (strcpy.c) diff --git a/man3/strdup.3 b/man3/strdup.3 index e787219..75b678e 100644 --- a/man3/strdup.3 +++ b/man3/strdup.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sun Jul 25 10:41:34 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Wed Oct 17 01:12:26 2001 by John Levon -.TH strdup 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strdup 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strdup, strndup, strdupa, strndupa \- duplicate a string .SH LIBRARY @@ -18,19 +18,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strdup(const char *" s ); -.PP +.P .BI "char *strndup(const char " s [. n "], size_t " n ); .BI "char *strdupa(const char *" s ); .BI "char *strndupa(const char " s [. n "], size_t " n ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strdup (): .nf _XOPEN_SOURCE >= 500 @@ -38,7 +38,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE .fi -.PP +.P .BR strndup (): .nf Since glibc 2.10: @@ -46,7 +46,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.10: _GNU_SOURCE .fi -.PP +.P .BR strdupa (), .BR strndupa (): .nf @@ -63,7 +63,7 @@ obtained with .BR malloc (3), and can be freed with .BR free (3). -.PP +.P The .BR strndup () function is similar, but copies at most @@ -76,7 +76,7 @@ is longer than only .I n bytes are copied, and a terminating null byte (\[aq]\e0\[aq]) is added. -.PP +.P .BR strdupa () and .BR strndupa () @@ -112,7 +112,6 @@ T{ .BR strndupa () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR strdup () diff --git a/man3/strerror.3 b/man3/strerror.3 index 5ed507e..89f4e9b 100644 --- a/man3/strerror.3 +++ b/man3/strerror.3 @@ -17,7 +17,7 @@ .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description .\" Addition of extra material on portability and standards. .\" -.TH strerror 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strerror 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- return string describing error number @@ -27,31 +27,31 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strerror(int " errnum ); .BI "const char *strerrorname_np(int " errnum ); .BI "const char *strerrordesc_np(int " errnum ); -.PP +.P .BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); /* XSI-compliant */ -.PP +.P .BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); /* GNU-specific */ -.PP +.P .BI "char *strerror_l(int " errnum ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strerrorname_np (), .BR strerrordesc_np (): .nf _GNU_SOURCE .fi -.PP +.P .BR strerror_r (): .nf The XSI-compliant version is provided if: @@ -72,15 +72,16 @@ part of the current locale to select the appropriate language. is .BR EINVAL , the returned description will be "Invalid argument".) -This string must not be modified by the application, but may be -modified by a subsequent call to +This string must not be modified by the application, +and the returned pointer will be invalidated on a subsequent call to .BR strerror () or -.BR strerror_l (). +.BR strerror_l (), +or if the thread that obtained the string exits. No other library function, including .BR perror (3), will modify this string. -.PP +.P Like .BR strerror (), the @@ -90,7 +91,7 @@ code passed in the argument .IR errnum , with the difference that the returned string is not translated according to the current locale. -.PP +.P The .BR strerrorname_np () function returns a pointer to a string containing the name of the error @@ -99,14 +100,18 @@ code passed in the argument For example, given .B EPERM as an argument, this function returns a pointer to the string "EPERM". +Given +.B 0 +as an argument, +this function returns a pointer to the string "0". .\" .SS strerror_r() -The .BR strerror_r () -function is similar to +is like .BR strerror (), -but is -thread safe. +but might use the supplied buffer +.I buf +instead of allocating one internally. This function is available in two versions: an XSI-compliant version specified in POSIX.1-2001 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), @@ -121,7 +126,7 @@ is defined by default with the value 200112L, so that the XSI-compliant version of .BR strerror_r () is provided by default. -.PP +.P The XSI-compliant .BR strerror_r () is preferred for portable applications. @@ -129,7 +134,7 @@ It returns the error string in the user-supplied buffer .I buf of length .IR buflen . -.PP +.P The GNU-specific .BR strerror_r () returns a pointer to a string containing the error message. @@ -174,7 +179,7 @@ and the GNU-specific functions return the appropriate error description string, or an "Unknown error nnn" message if the error number is unknown. -.PP +.P On success, .BR strerrorname_np () and @@ -183,7 +188,7 @@ return the appropriate error description string. If .I errnum is an invalid error number, these functions return NULL. -.PP +.P The XSI-compliant .BR strerror_r () function returns 0 on success. @@ -192,7 +197,7 @@ a (positive) error number is returned (since glibc 2.13), or \-1 is returned and .I errno is set to indicate the error (before glibc 2.13). -.PP +.P POSIX.1-2001 and POSIX.1-2008 require that a successful call to .BR strerror () or @@ -231,7 +236,7 @@ T{ T} Thread safety T{ .na .nh -MT-Unsafe race:strerror +MT-Safe T} T{ .na @@ -246,7 +251,10 @@ T{ .BR strerror_l () T} Thread safety MT-Safe .TE -.sp 1 +.P +Before glibc 2.32, +.BR strerror () +is not MT-Safe. .SH STANDARDS .TP .BR strerror () @@ -265,7 +273,7 @@ POSIX.1-2008. .TQ .BR strerrordesc_np () GNU. -.PP +.P POSIX.1-2001 permits .BR strerror () to set @@ -302,13 +310,6 @@ POSIX.1-2008. .BR strerrordesc_np () glibc 2.32. .SH NOTES -The GNU C Library uses a buffer of 1024 characters for -.BR strerror (). -This buffer size therefore should be sufficient to avoid an -.B ERANGE -error when calling -.BR strerror_r (). -.PP .BR strerrorname_np () and .BR strerrordesc_np () @@ -319,4 +320,5 @@ are thread-safe and async-signal-safe. .BR error (3), .BR perror (3), .BR strsignal (3), -.BR locale (7) +.BR locale (7), +.BR signal-safety (7) diff --git a/man3/strfmon.3 b/man3/strfmon.3 index a8e34f5..687da22 100644 --- a/man3/strfmon.3 +++ b/man3/strfmon.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH strfmon 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strfmon 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strfmon, strfmon_l \- convert monetary value to a string .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t strfmon(char " s "[restrict ." max "], size_t " max , .BI " const char *restrict " format ", ...);" .BI "ssize_t strfmon_l(char " s "[restrict ." max "], size_t " max ", \ @@ -31,7 +31,7 @@ result in the character array .I s of size .IR max . -.PP +.P The .BR strfmon_l () function performs the same task, @@ -47,7 +47,7 @@ is the special locale object (see .BR duplocale (3)) or is not a valid locale object handle. -.PP +.P Ordinary characters in .I format are copied to @@ -83,20 +83,20 @@ Omit the currency symbol. .B \- Left justify all fields. The default is right justification. -.PP +.P Next, there may be a field width: a decimal digit string specifying a minimum field width in bytes. The default is 0. A result smaller than this width is padded with spaces (on the left, unless the left-justify flag was given). -.PP +.P Next, there may be a left precision of the form "#" followed by a decimal digit string. If the number of digits left of the radix character is smaller than this, the representation is padded on the left with the numeric fill character. Grouping characters are not counted in this field width. -.PP +.P Next, there may be a right precision of the form "." followed by a decimal digit string. The amount being formatted is rounded to @@ -111,7 +111,7 @@ If the right precision is 0, no radix character is printed. .BR LC_MONETARY , and may differ from that specified by .BR LC_NUMERIC .) -.PP +.P Finally, the conversion specification must be ended with a conversion character. The three conversion characters are @@ -161,29 +161,28 @@ T{ .BR strfmon_l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. .SH EXAMPLES The call -.PP +.P .in +4n .EX strfmon(buf, sizeof(buf), "[%\[ha]=*#6n] [%=*#6i]", 1234.567, 1234.567); .EE .in -.PP +.P outputs -.PP +.P .in +4n .EX [€ **1234,57] [EUR **1 234,57] .EE .in -.PP +.P in the .I nl_NL locale. @@ -194,7 +193,7 @@ The and .I en_GB locales yield -.PP +.P .in +4n .EX [ **1234,57 €] [ **1.234,57 EUR] diff --git a/man3/strfromd.3 b/man3/strfromd.3 index 6bcc113..9243191 100644 --- a/man3/strfromd.3 +++ b/man3/strfromd.3 @@ -10,7 +10,7 @@ .\" ISO/IEC TS 18661-1 technical specification. .\" snprintf and other man.3 pages. .\" -.TH strfromd 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strfromd 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strfromd, strfromf, strfroml \- convert a floating-point value into a string @@ -20,7 +20,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int strfromd(char " str "[restrict ." n "], size_t " n , .BI " const char *restrict " format ", double " fp ");" .BI "int strfromf(char " str "[restrict ." n "], size_t " n , @@ -28,12 +28,12 @@ Standard C library .BI "int strfroml(char " str "[restrict ." n "], size_t " n , .BI " const char *restrict " format ", long double " fp ");" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strfromd (), .BR strfromf (), .BR strfroml (): @@ -52,26 +52,26 @@ At most .I n characters are stored into .IR str . -.PP +.P The terminating null byte ('\e0') is written if and only if .I n is sufficiently large, otherwise the written string is truncated at .I n characters. -.PP +.P The .BR strfromd (), .BR strfromf (), and .BR strfroml () functions are equivalent to -.PP +.P .in +4n .EX snprintf(str, n, format, fp); .EE .in -.PP +.P except for the .I format string. @@ -93,7 +93,7 @@ Finally, the format string should have one of the conversion specifiers .BR g , or .BR G . -.PP +.P The conversion specifier is applied based on the floating-point type indicated by the function suffix. Therefore, unlike @@ -102,10 +102,10 @@ the format string does not have a length modifier character. See .BR snprintf (3) for a detailed description of these conversion specifiers. -.PP +.P The implementation conforms to the C99 standard on conversion of NaN and infinity values: -.PP +.P .RS If .I fp @@ -124,12 +124,12 @@ If .BR E , .BR G ) is the conversion specifier, the conversion is to "NAN" or "\-NAN". -.PP +.P Likewise if .I fp is infinity, it is converted to [\-]inf or [\-]INF. .RE -.PP +.P A malformed .I format string results in undefined behavior. @@ -154,7 +154,7 @@ For an explanation of the terms used in this section, see and the .B POSIX Safety Concepts section in GNU C Library manual. -.PP +.P .TS allbox; lbx lb lb @@ -170,7 +170,7 @@ T} Thread safety MT-Safe locale \^ Async-signal safety AS-Unsafe heap \^ Async-cancel safety AC-Unsafe mem .TE -.sp 1 +.P Note: these attributes are preliminary. .SH STANDARDS ISO/IEC TS 18661-1. @@ -189,7 +189,7 @@ category of the current locale. .SH EXAMPLES To convert the value 12.1 as a float type to a string using decimal notation, resulting in "12.100000": -.PP +.P .in +4n .EX #define __STDC_WANT_IEC_60559_BFP_EXT__ @@ -199,10 +199,10 @@ char s[ssize]; strfromf(s, ssize, "%f", 12.1); .EE .in -.PP +.P To convert the value 12.3456 as a float type to a string using decimal notation with two digits of precision, resulting in "12.35": -.PP +.P .in +4n .EX #define __STDC_WANT_IEC_60559_BFP_EXT__ @@ -212,10 +212,10 @@ char s[ssize]; strfromf(s, ssize, "%.2f", 12.3456); .EE .in -.PP +.P To convert the value 12.345e19 as a double type to a string using scientific notation with zero digits of precision, resulting in "1E+20": -.PP +.P .in +4n .EX #define __STDC_WANT_IEC_60559_BFP_EXT__ diff --git a/man3/strfry.3 b/man3/strfry.3 index 74a342b..9871249 100644 --- a/man3/strfry.3 +++ b/man3/strfry.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sun Jul 25 10:39:43 1993 by Rik Faith (faith@cs.unc.edu) -.TH strfry 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strfry 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strfry \- randomize a string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "char *strfry(char *" string ); .fi .SH DESCRIPTION @@ -48,7 +48,6 @@ T{ .BR strfry () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS GNU. .SH SEE ALSO diff --git a/man3/strftime.3 b/man3/strftime.3 index 412ba06..191c0f4 100644 --- a/man3/strftime.3 +++ b/man3/strftime.3 @@ -15,7 +15,7 @@ .\" 2005-11-22 mtk, added glibc Notes covering optional 'flag' and .\" 'width' components of conversion specifications. .\" -.TH strftime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strftime 3 2024-01-28 "Linux man-pages 6.7" .SH NAME strftime \- format date and time .SH LIBRARY @@ -24,11 +24,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t strftime(char " s "[restrict ." max "], size_t " max , .BI " const char *restrict " format , .BI " const struct tm *restrict " tm ); -.PP +.P .BI "size_t strftime_l(char " s "[restrict ." max "], size_t " max , .BI " const char *restrict " format , .BI " const struct tm *restrict " tm , @@ -54,7 +54,7 @@ See also .BR ctime (3). .\" FIXME . POSIX says: Local timezone information is used as though .\" strftime() called tzset(). But this doesn't appear to be the case -.PP +.P The format specification is a null-terminated string and may contain special character sequences called .IR "conversion specifications", @@ -63,7 +63,7 @@ some other character known as a .IR "conversion specifier character". All other character sequences are .IR "ordinary character sequences". -.PP +.P The characters of ordinary character sequences (including the null byte) are copied verbatim from .I format @@ -168,10 +168,10 @@ Modifier: use alternative ("era-based") format, see below. (SU) .B %F Equivalent to .B %Y\-%m\-%d -(the ISO\ 8601 date format). (C99) +(the ISO\~8601 date format). (C99) .TP .B %G -The ISO\ 8601 week-based year (see NOTES) with century as a decimal number. +The ISO\~8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see .BR %V ). This has the same format and value as @@ -330,7 +330,7 @@ and .IR tm_wday .) .TP .B %V -The ISO\ 8601 week number (see NOTES) of the current year as a decimal number, +The ISO\~8601 week number (see NOTES) of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also @@ -431,7 +431,7 @@ format. (TZ) .TP .B %% A literal \[aq]%\[aq] character. -.PP +.P Some conversion specifications can be modified by preceding the conversion specifier character by the .B E @@ -477,7 +477,7 @@ as an argument to a One example of such alternative forms is the Japanese era calendar scheme in the .B ja_JP glibc locale. -.PP +.P .BR strftime_l () is equivalent to .BR strftime (), @@ -508,7 +508,7 @@ returns 0, and the contents of the array are undefined. .\" would return .\" .I max .\" if the array was too small.) -.PP +.P Note that the return value 0 does not necessarily indicate an error. For example, in many locales .B %p @@ -537,7 +537,6 @@ T{ .BR strftime_l () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS .TP .BR strftime () @@ -555,7 +554,7 @@ SVr4, C89. .TP .BR strftime_l () POSIX.1-2008. -.PP +.P There are strict inclusions between the set of conversions given in ANSI C (unmarked), those given in the Single UNIX Specification (marked SU), those given in Olson's timezone package (marked TZ), @@ -571,7 +570,7 @@ as well. The .B %F conversion is in C99 and POSIX.1-2001. -.PP +.P In SUSv2, the .B %S specifier allowed a range of 00 to 61, @@ -579,13 +578,13 @@ to allow for the theoretical possibility of a minute that included a double leap second (there never has been such a minute). .SH NOTES -.SS ISO 8601 week dates +.SS ISO\~8601 week dates .BR %G , .BR %g , and .B %V yield values calculated from the week-based year defined by the -ISO\ 8601 standard. +ISO\~8601 standard. In this system, weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week. Week 1 is the first week where four or more days fall within the @@ -594,16 +593,16 @@ the first week of the year that contains a Thursday; or, the week that has 4 January in it). When three or fewer days of the first calendar week of the new year fall within that year, -then the ISO 8601 week-based system counts those days as part of week 52 +then the ISO\~8601 week-based system counts those days as part of week 52 or 53 of the preceding year. For example, 1 January 2010 is a Friday, meaning that just three days of that calendar week fall in 2010. -Thus, the ISO\ 8601 week-based system considers these days to be part of +Thus, the ISO\~8601 week-based system considers these days to be part of week 53 .RB ( %V ) of the year 2009 .RB ( %G ); -week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010. +week 01 of ISO\~8601 year 2010 starts on Monday, 4 January 2010. Similarly, the first two days of January 2011 are considered to be part of week 52 of the year 2010. .SS glibc notes @@ -622,7 +621,7 @@ may be specified. or .B O modifiers, if present.) -.PP +.P The following flag characters are permitted: .TP .B _ @@ -645,7 +644,7 @@ Swap the case of the result string. (This flag works only with certain conversion specifier characters, and of these, it is only really useful with .BR %Z .) -.PP +.P An optional decimal width specifier may follow the (possibly absent) flag. If the natural size of the field is smaller than this width, then the result string is padded (on the left) to the specified width. @@ -667,7 +666,7 @@ specify any .I errno settings for .BR strftime (). -.PP +.P Some buggy versions of .BR gcc (1) complain about the use of @@ -682,7 +681,7 @@ to circumvent this problem. A relatively clean one is to add an intermediate function -.PP +.P .in +4n .EX size_t @@ -693,7 +692,7 @@ my_strftime(char *s, size_t max, const char *fmt, } .EE .in -.PP +.P Nowadays, .BR gcc (1) provides the @@ -703,16 +702,16 @@ so that the above workaround is no longer required. .SH EXAMPLES .B RFC\~2822-compliant date format (with an English locale for %a and %b) -.PP +.P .in +4n .EX "%a,\ %d\ %b\ %Y\ %T\ %z" .EE .in -.PP +.P .B RFC\~822-compliant date format (with an English locale for %a and %b) -.PP +.P .in +4n .EX "%a,\ %d\ %b\ %y\ %T\ %z" @@ -721,11 +720,11 @@ so that the above workaround is no longer required. .SS Example program The program below can be used to experiment with .BR strftime (). -.PP +.P Some examples of the result string produced by the glibc implementation of .BR strftime () are as follows: -.PP +.P .in +4n .EX .RB "$" " ./a.out \[aq]%m\[aq]" diff --git a/man3/string.3 b/man3/string.3 index dc1c415..e7fb777 100644 --- a/man3/string.3 +++ b/man3/string.3 @@ -7,7 +7,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sun Jul 25 10:54:31 1993, Rik Faith (faith@cs.unc.edu) -.TH string 3 2023-01-22 "Linux man-pages 6.05.01" +.TH string 3 2023-11-14 "Linux man-pages 6.7" .SH NAME stpcpy, strcasecmp, strcat, strchr, strcmp, strcoll, strcpy, strcspn, strdup, strfry, strlen, strncat, strncmp, strncpy, strncasecmp, strpbrk, @@ -179,21 +179,14 @@ to the current locale and copies the first .I n bytes to .IR dest . -.SS Obsolete functions .TP .nf .BI "char *strncpy(char " dest "[restrict ." n "], \ const char " src "[restrict ." n ], .BI " size_t " n ); .fi -Copy at most -.I n -bytes from string -.I src -to -.IR dest , -returning a pointer to the start of -.IR dest . +Fill a fixed-size buffer with leading non-null bytes from a source array, +padding with null bytes as needed. .SH DESCRIPTION The string functions perform operations on null-terminated strings. diff --git a/man3/strlen.3 b/man3/strlen.3 index c5820ba..9b0ec8e 100644 --- a/man3/strlen.3 +++ b/man3/strlen.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu) -.TH strlen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strlen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strlen \- calculate the length of a string .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t strlen(const char *" s ); .fi .SH DESCRIPTION @@ -45,7 +45,6 @@ T{ .BR strlen () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/strncat.3 b/man3/strncat.3 index f53c930..74848c9 100644 --- a/man3/strncat.3 +++ b/man3/strncat.3 @@ -3,43 +3,45 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH strncat 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strncat 3 2023-12-05 "Linux man-pages 6.7" .SH NAME -strncat \- concatenate a null-padded character sequence into a string +strncat +\- +append non-null bytes from a source array to a string, +and null-terminate the result .SH LIBRARY Standard C library .RI ( libc ", " \-lc ) .SH SYNOPSIS .nf .B #include -.PP -.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ], -.BI " size_t " sz ); +.P +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); .fi .SH DESCRIPTION -This function catenates the input character sequence -contained in a null-padded fixed-width buffer, -into a string at the buffer pointed to by +This function appends at most +.I ssize +non-null bytes from the array pointed to by +.IR src , +followed by a null character, +to the end of the string pointed to by .IR dst . -The programmer is responsible for allocating a destination buffer large enough, -that is, -.IR "strlen(dst) + strnlen(src, sz) + 1" . -.PP +.I dst +must point to a string contained in a buffer that is large enough, +that is, the buffer size must be at least +.IR "strlen(dst) + strnlen(src, ssize) + 1" . +.P An implementation of this function might be: -.PP +.P .in +4n .EX char * -strncat(char *restrict dst, const char *restrict src, size_t sz) +strncat(char *restrict dst, const char *restrict src, size_t ssize) { - int len; - char *p; -\& - len = strnlen(src, sz); - p = dst + strlen(dst); - p = mempcpy(p, src, len); - *p = \[aq]\e0\[aq]; + #define strnul(s) (s + strlen(s)) \& + stpcpy(mempcpy(strnul(dst), src, strnlen(src, ssize)), ""); return dst; } .EE @@ -62,17 +64,17 @@ T{ .BR strncat () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY POSIX.1-2001, C89, SVr4, 4.3BSD. .SH CAVEATS -The name of this function is confusing. -This function has no relation to +The name of this function is confusing; +it has no relation to .BR strncpy (3). -.PP -If the destination buffer is not large enough, +.P +If the destination buffer does not already contain a string, +or is not large enough, the behavior is undefined. See .B _FORTIFY_SOURCE @@ -82,7 +84,7 @@ in This function can be very inefficient. Read about .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ -Shlemiel the painter +Shlemiel the painter .UE . .SH EXAMPLES .\" SRC BEGIN (strncat.c) @@ -97,9 +99,9 @@ Shlemiel the painter int main(void) { - size_t maxsize; + size_t n; \& - // Null-padded fixed-width character sequences + // Null-padded fixed-size character sequences char pre[4] = "pre."; char new_post[50] = ".foo.bar"; \& @@ -108,9 +110,8 @@ main(void) char src[] = "some_long_body.post"; char *dest; \& - maxsize = nitems(pre) + strlen(src) \- strlen(post) + - nitems(new_post) + 1; - dest = malloc(sizeof(*dest) * maxsize); + n = nitems(pre) + strlen(src) \- strlen(post) + nitems(new_post) + 1; + dest = malloc(sizeof(*dest) * n); if (dest == NULL) err(EXIT_FAILURE, "malloc()"); \& @@ -128,4 +129,4 @@ main(void) .in .SH SEE ALSO .BR string (3), -.BR string_copying (3) +.BR string_copying (7) diff --git a/man3/strnlen.3 b/man3/strnlen.3 index eeaf3c6..78e5c51 100644 --- a/man3/strnlen.3 +++ b/man3/strnlen.3 @@ -6,7 +6,7 @@ .\" References consulted: .\" GNU glibc-2 source code and manual .\" -.TH strnlen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strnlen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strnlen \- determine the length of a fixed-size string .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t strnlen(const char " s [. maxlen "], size_t " maxlen ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strnlen (): .nf Since glibc 2.10: @@ -75,7 +75,6 @@ T{ .BR strnlen () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/strpbrk.3 b/man3/strpbrk.3 index abdf5af..c8d71a8 100644 --- a/man3/strpbrk.3 +++ b/man3/strpbrk.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu) -.TH strpbrk 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strpbrk 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strpbrk \- search a string for any of a set of bytes .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strpbrk(const char *" s ", const char *" accept ); .fi .SH DESCRIPTION @@ -51,7 +51,6 @@ T{ .BR strpbrk () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/strptime.3 b/man3/strptime.3 index 6dd0590..9ccccfd 100644 --- a/man3/strptime.3 +++ b/man3/strptime.3 @@ -9,7 +9,7 @@ .\" Modified, aeb, 2001-08-31 .\" Modified, wharms 2001-11-12, remark on white space and example .\" -.TH strptime 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strptime 3 2024-01-28 "Linux man-pages 6.7" .SH NAME strptime \- convert a string representation of time to a time tm structure .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .nf .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "char *strptime(const char *restrict " s ", const char *restrict " format , .BI " struct tm *restrict " tm ); .fi @@ -36,12 +36,12 @@ structure pointed to by .IR tm , using the format specified by .IR format . -.PP +.P The broken-down time structure .I tm is described in .BR tm (3type). -.PP +.P The .I format argument @@ -59,7 +59,7 @@ except for whitespace, which matches zero or more whitespace characters in the input string. There should be white\%space or other alphanumeric characters between any two field descriptors. -.PP +.P The .BR strptime () function processes the input string from left @@ -68,7 +68,7 @@ Each of the three possible input elements (whitespace, literal, or format) are handled one after the other. If the input cannot be matched to the format string, the function stops. The remainder of the format and input strings are not processed. -.PP +.P The supported input field descriptors are listed below. In case a text string (such as the name of a day of the week or a month name) is to be matched, the comparison is case insensitive. @@ -104,7 +104,7 @@ Equivalent to to non-Americans, especially since .B %d/%m/%y is widely used in Europe. -The ISO 8601 standard format is +The ISO\~8601 standard format is .BR %Y\-%m\-%d .) .TP .B %H @@ -180,13 +180,13 @@ range 00\[en]68 refer to years in the twenty-first century (2000\[en]2068). .TP .B %Y The year, including century (for example, 1991). -.PP +.P Some field descriptors can be modified by the E or O modifier characters to indicate that an alternative format or specification should be used. If the alternative format or specification does not exist in the current locale, the unmodified field descriptor is used. -.PP +.P The E modifier specifies that the input string may contain alternative locale-dependent versions of the date and time representation: .TP @@ -209,7 +209,7 @@ The offset from .TP .B %EY The full alternative year representation. -.PP +.P The O modifier specifies that the numerical input may be in an alternative locale-dependent format: .TP @@ -275,7 +275,6 @@ T{ .BR strptime () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -295,7 +294,7 @@ explicitly specified, except that it recomputes the and .I tm_yday field if any of the year, month, or day elements changed. -.\" .PP +.\" .P .\" This function is available since libc 4.6.8. .\" Linux libc4 and libc5 includes define the prototype unconditionally; .\" glibc2 includes provide a prototype only when @@ -303,12 +302,12 @@ field if any of the year, month, or day elements changed. .\" or .\" .B _GNU_SOURCE .\" are defined. -.\" .PP +.\" .P .\" Before libc 5.4.13 whitespace .\" (and the \[aq]n\[aq] and \[aq]t\[aq] specifications) was not handled, .\" no \[aq]E\[aq] and \[aq]O\[aq] locale modifier characters were accepted, .\" and the \[aq]C\[aq] specification was a synonym for the \[aq]c\[aq] specification. -.PP +.P The \[aq]y\[aq] (year in century) specification is taken to specify a year .\" in the 20th century by libc4 and libc5. .\" It is taken to be a year @@ -330,7 +329,7 @@ This leads to .B %F Equivalent to .BR %Y\-%m\-%d , -the ISO 8601 date format. +the ISO\~8601 date format. .TP .B %g The year corresponding to the ISO week number, but without the century @@ -344,18 +343,18 @@ The year corresponding to the ISO week number. The day of the week as a decimal number (1\[en]7, where Monday = 1). .TP .B %V -The ISO 8601:1988 week number as a decimal number (1\[en]53). +The ISO\~8601:1988 week number as a decimal number (1\[en]53). If the week (starting on Monday) containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1. .TP .B %z -An RFC-822/ISO 8601 standard timezone specification. +An RFC-822/ISO\~8601 standard timezone specification. .TP .B %Z The timezone name. -.PP +.P Similarly, because of GNU extensions to .BR strftime (3), .B %k @@ -375,7 +374,7 @@ Finally .B %s The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). Leap seconds are not counted unless leap second support is available. -.PP +.P The glibc implementation does not require whitespace between two field descriptors. .SH EXAMPLES @@ -383,7 +382,7 @@ The following example demonstrates the use of .BR strptime () and .BR strftime (3). -.PP +.P .\" SRC BEGIN (strptime.c) .EX #define _XOPEN_SOURCE diff --git a/man3/strsep.3 b/man3/strsep.3 index bf86fcf..aac29b9 100644 --- a/man3/strsep.3 +++ b/man3/strsep.3 @@ -11,7 +11,7 @@ .\" Modified Mon Jan 20 12:04:18 1997 by Andries Brouwer (aeb@cwi.nl) .\" Modified Tue Jan 23 20:23:07 2001 by Andries Brouwer (aeb@cwi.nl) .\" -.TH strsep 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strsep 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strsep \- extract token from string .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strsep(char **restrict " stringp ", const char *restrict " delim ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strsep (): .nf Since glibc 2.19: @@ -79,12 +79,11 @@ T{ .BR strsep () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY 4.4BSD. -.PP +.P The .BR strsep () function was introduced as a replacement for @@ -106,7 +105,7 @@ The identity of the delimiting character is lost. The program below is a port of the one found in .BR strtok (3), which, however, doesn't discard multiple delimiters or empty tokens: -.PP +.P .in +4n .EX .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" diff --git a/man3/strsignal.3 b/man3/strsignal.3 index 3aaacec..0d359d6 100644 --- a/man3/strsignal.3 +++ b/man3/strsignal.3 @@ -9,7 +9,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 17:59:03 1993 by Rik Faith (faith@cs.unc.edu) -.TH strsignal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strsignal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strsignal, sigabbrev_np, sigdescr_np, sys_siglist \- return string describing signal @@ -19,25 +19,25 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strsignal(int " sig ); .BI "const char *sigdescr_np(int " sig ); .BI "const char *sigabbrev_np(int " sig ); -.PP +.P .BI "[[deprecated]] extern const char *const " sys_siglist []; .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigabbrev_np (), .BR sigdescr_np (): .nf _GNU_SOURCE .fi -.PP +.P .BR strsignal (): .nf From glibc 2.10 to glibc 2.31: @@ -45,7 +45,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.10: _GNU_SOURCE .fi -.PP +.P .IR sys_siglist : .nf Since glibc 2.19: @@ -66,7 +66,7 @@ The string returned by is localized according to the .B LC_MESSAGES category in the current locale. -.PP +.P The .BR sigdescr_np () function returns a string describing the signal @@ -75,7 +75,7 @@ number passed in the argument Unlike .BR strsignal () this string is not influenced by the current locale. -.PP +.P The .BR sigabbrev_np () function returns the abbreviated name of the signal, @@ -83,7 +83,7 @@ function returns the abbreviated name of the signal, For example, given the value .BR SIGINT , it returns the string "INT". -.PP +.P The (deprecated) array .I sys_siglist holds the signal description strings @@ -100,7 +100,7 @@ function returns the appropriate description string, or an unknown signal message if the signal number is invalid. On some systems (but not on Linux), NULL may instead be returned for an invalid signal number. -.PP +.P The .BR sigdescr_np () and @@ -133,7 +133,6 @@ T{ .BR sigabbrev_np () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR strsignal () diff --git a/man3/strspn.3 b/man3/strspn.3 index 53e546d..b1398cf 100644 --- a/man3/strspn.3 +++ b/man3/strspn.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu) -.TH strspn 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strspn 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strspn, strcspn \- get length of a prefix substring .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t strspn(const char *" s ", const char *" accept ); .BI "size_t strcspn(const char *" s ", const char *" reject ); .fi @@ -29,7 +29,7 @@ segment of .I s which consists entirely of bytes in .IR accept . -.PP +.P The .BR strcspn () function calculates the length of the initial @@ -46,7 +46,7 @@ the initial segment of which consist only of bytes from .IR accept . -.PP +.P The .BR strcspn () function returns the number of bytes in @@ -69,7 +69,6 @@ T{ .BR strcspn () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/strstr.3 b/man3/strstr.3 index d07c0f4..ef455cf 100644 --- a/man3/strstr.3 +++ b/man3/strstr.3 @@ -11,7 +11,7 @@ .\" Added history, aeb, 980113. .\" 2005-05-05 mtk: added strcasestr() .\" -.TH strstr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strstr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strstr, strcasestr \- locate a substring .SH LIBRARY @@ -20,12 +20,12 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strstr(const char *" haystack ", const char *" needle ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "char *strcasestr(const char *" haystack ", const char *" needle ); .fi .SH DESCRIPTION @@ -36,7 +36,7 @@ function finds the first occurrence of the substring in the string .IR haystack . The terminating null bytes (\[aq]\e0\[aq]) are not compared. -.PP +.P The .BR strcasestr () function is like @@ -45,7 +45,7 @@ but ignores the case of both arguments. .SH RETURN VALUE These functions return a pointer to the beginning of the located substring, or NULL if the substring is not found. -.PP +.P If .I needle is the empty string, @@ -71,7 +71,6 @@ T{ .BR strcasestr () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS .TP .BR strstr () diff --git a/man3/strtod.3 b/man3/strtod.3 index 23e7578..5c650b1 100644 --- a/man3/strtod.3 +++ b/man3/strtod.3 @@ -15,7 +15,7 @@ .\" (michael@cantor.informatik.rwth-aachen.de) .\" Added strof, strtold, aeb, 2001-06-07 .\" -.TH strtod 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strtod 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strtod, strtof, strtold \- convert ASCII string to floating-point number .SH LIBRARY @@ -24,18 +24,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double strtod(const char *restrict " nptr ", char **restrict " endptr ); .BI "float strtof(const char *restrict " nptr ", char **restrict " endptr ); .BI "long double strtold(const char *restrict " nptr \ ", char **restrict " endptr ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strtof (), .BR strtold (): .nf @@ -55,14 +55,14 @@ to and .I long double representation, respectively. -.PP +.P The expected form of the (initial portion of the) string is optional leading white space as recognized by .BR isspace (3), an optional plus (\[aq]+\[aq]) or minus sign (\[aq]\-\[aq]) and then either (i) a decimal number, or (ii) a hexadecimal number, or (iii) an infinity, or (iv) a NAN (not-a-number). -.PP +.P A .I "decimal number" consists of a nonempty sequence of decimal digits @@ -71,7 +71,7 @@ usually \[aq].\[aq]), optionally followed by a decimal exponent. A decimal exponent consists of an \[aq]E\[aq] or \[aq]e\[aq], followed by an optional plus or minus sign, followed by a nonempty sequence of decimal digits, and indicates multiplication by a power of 10. -.PP +.P A .I "hexadecimal number" consists of a "0x" or "0X" followed by a nonempty sequence of @@ -82,11 +82,11 @@ consists of a \[aq]P\[aq] or \[aq]p\[aq], followed by an optional plus or minus sign, followed by a nonempty sequence of decimal digits, and indicates multiplication by a power of 2. At least one of radix character and binary exponent must be present. -.PP +.P An .I infinity is either "INF" or "INFINITY", disregarding case. -.PP +.P A .I NAN is "NAN" (disregarding case) optionally followed by a string, @@ -97,21 +97,21 @@ specifies in an implementation-dependent way the type of NAN (see NOTES). .SH RETURN VALUE These functions return the converted value, if any. -.PP +.P If .I endptr is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by .IR endptr . -.PP +.P If no conversion is performed, zero is returned and (unless .I endptr is null) the value of .I nptr is stored in the location referenced by .IR endptr . -.PP +.P If the correct value would cause overflow, plus or minus .BR HUGE_VAL , .BR HUGE_VALF , @@ -122,7 +122,7 @@ and .B ERANGE is stored in .IR errno . -.PP +.P If the correct value would cause underflow, a value with magnitude no larger than .BR DBL_MIN , @@ -153,7 +153,6 @@ T{ .BR strtold () T} Thread safety MT-Safe locale .TE -.sp 1 .SH VERSIONS In the glibc implementation, the .I n-char-sequence diff --git a/man3/strtoimax.3 b/man3/strtoimax.3 index 88ce973..1e73661 100644 --- a/man3/strtoimax.3 +++ b/man3/strtoimax.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH strtoimax 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strtoimax 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strtoimax, strtoumax \- convert string to integer .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "intmax_t strtoimax(const char *restrict " nptr ", char **restrict " endptr , .BI " int " base ); .BI "uintmax_t strtoumax(const char *restrict " nptr ", char **restrict " endptr , @@ -56,7 +56,6 @@ T{ .BR strtoumax () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/strtok.3 b/man3/strtok.3 index 6f01530..8454776 100644 --- a/man3/strtok.3 +++ b/man3/strtok.3 @@ -10,7 +10,7 @@ .\" 2005-11-17, mtk: Substantial parts rewritten .\" 2013-05-19, mtk: added much further detail on the operation of strtok() .\" -.TH strtok 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strtok 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strtok, strtok_r \- extract tokens from strings .SH LIBRARY @@ -19,17 +19,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *strtok(char *restrict " str ", const char *restrict " delim ); .BI "char *strtok_r(char *restrict " str ", const char *restrict " delim , .BI " char **restrict " saveptr ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strtok_r (): .nf _POSIX_C_SOURCE @@ -47,7 +47,7 @@ specified in In each subsequent call that should parse the same string, .I str must be NULL. -.PP +.P The .I delim argument specifies a set of bytes that @@ -56,7 +56,7 @@ The caller may specify different strings in .I delim in successive calls that parse the same string. -.PP +.P Each call to .BR strtok () returns a pointer to a @@ -65,7 +65,7 @@ This string does not include the delimiting byte. If no more tokens are found, .BR strtok () returns NULL. -.PP +.P A sequence of calls to .BR strtok () that operate on the same string maintains a pointer @@ -85,7 +85,7 @@ returns NULL. will thus cause .BR strtok () to return NULL on the first call.) -.PP +.P The end of each token is found by scanning forward until either the next delimiter byte is found or until the terminating null byte (\[aq]\e0\[aq]) is encountered. @@ -98,7 +98,7 @@ when searching for the next token. In this case, .BR strtok () returns a pointer to the start of the found token. -.PP +.P From the above description, it follows that a sequence of two or more contiguous delimiter bytes in the parsed string is considered to be a single delimiter, and that @@ -112,7 +112,7 @@ successive calls to that specify the delimiter string "\fI;,\fP" would return the strings "\fIaaa\fP" and "\fIbbb\fP", and then a null pointer. -.PP +.P The .BR strtok_r () function is a reentrant version of @@ -125,7 +125,7 @@ variable that is used internally by .BR strtok_r () in order to maintain context between successive calls that parse the same string. -.PP +.P On the first call to .BR strtok_r (), .I str @@ -138,7 +138,7 @@ should be NULL, and .I saveptr (and the buffer that it points to) should be unchanged since the previous call. -.PP +.P Different strings may be parsed concurrently using sequences of calls to .BR strtok_r () that specify different @@ -170,7 +170,6 @@ T{ .BR strtok_r () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS On some implementations, .\" Tru64, according to its manual page @@ -218,9 +217,9 @@ The second argument specifies the delimiter byte(s) to be used to separate that string into "major" tokens. The third argument specifies the delimiter byte(s) to be used to separate the "major" tokens into subtokens. -.PP +.P An example of the output produced by this program is the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out \[aq]a/bbb///cc;xxx:yyy:\[aq] \[aq]:;\[aq] \[aq]/\[aq]" @@ -273,7 +272,7 @@ main(int argc, char *argv[]) } .EE .\" SRC END -.PP +.P Another example program using .BR strtok () can be found in diff --git a/man3/strtol.3 b/man3/strtol.3 index fe5555a..b6609b2 100644 --- a/man3/strtol.3 +++ b/man3/strtol.3 @@ -10,7 +10,7 @@ .\" 386BSD man pages .\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) .\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 -.TH strtol 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strtol 3 2023-12-19 "Linux man-pages 6.7" .SH NAME strtol, strtoll, strtoq \- convert a string to a long integer .SH LIBRARY @@ -19,18 +19,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long strtol(const char *restrict " nptr , .BI " char **restrict " endptr ", int " base ); .BI "long long strtoll(const char *restrict " nptr , .BI " char **restrict " endptr ", int " base ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strtoll (): .nf _ISOC99_SOURCE @@ -45,7 +45,7 @@ in to a long integer value according to the given .IR base , which must be between 2 and 36 inclusive, or be the special value 0. -.PP +.P The string may begin with an arbitrary amount of white space (as determined by .BR isspace (3)) @@ -58,7 +58,7 @@ zero .I base is taken as 10 (decimal) unless the next character is \[aq]0\[aq], in which case it is taken as 8 (octal). -.PP +.P The remainder of the string is converted to a .I long value @@ -67,10 +67,13 @@ valid digit in the given base. (In bases above 10, the letter \[aq]A\[aq] in either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so forth, with \[aq]Z\[aq] representing 35.) -.PP +.P If .I endptr is not NULL, +and the +.I base +is supported, .BR strtol () stores the address of the first invalid character in @@ -88,7 +91,7 @@ In particular, if is not \[aq]\e0\[aq] but .I **endptr is \[aq]\e0\[aq] on return, the entire string is valid. -.PP +.P The .BR strtoll () function works just like the @@ -124,6 +127,9 @@ instead of and .BR LONG_MAX ). .SH ERRORS +This function does not modify +.I errno +on success. .TP .B EINVAL (not in C99) @@ -133,7 +139,7 @@ contains an unsupported value. .TP .B ERANGE The resulting value was out of range. -.PP +.P The implementation may also set .I errno to @@ -156,7 +162,6 @@ T{ .BR strtoq () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -182,28 +187,43 @@ on both success and failure, the calling program should set .I errno to 0 before the call, and then determine if an error occurred by checking whether -.I errno -has a nonzero value after the call. -.PP +.I errno == ERANGE +after the call. +.P According to POSIX.1, in locales other than "C" and "POSIX", these functions may accept other, implementation-defined numeric strings. -.PP +.P BSD also has -.PP +.P .in +4n .EX .BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); .EE .in -.PP +.P with completely analogous definition. Depending on the wordsize of the current architecture, this may be equivalent to .BR strtoll () or to .BR strtol (). +.SH CAVEATS +If the +.I base +needs to be tested, +it should be tested in a call where the string is known to succeed. +Otherwise, it's impossible to portably differentiate the errors. +.P +.in +4n +.EX +errno = 0; +strtol("0", NULL, base); +if (errno == EINVAL) + goto unsupported_base; +.EE +.in .SH EXAMPLES The program shown below demonstrates the use of .BR strtol (). @@ -218,7 +238,7 @@ a function that performs no error checking and has a simpler interface than .BR strtol ().) Some examples of the results produced by this program are the following: -.PP +.P .in +4n .EX .RB "$" " ./a.out 123" @@ -241,7 +261,6 @@ strtol: Numerical result out of range .\" SRC BEGIN (strtol.c) .EX #include -#include #include #include \& @@ -259,13 +278,20 @@ main(int argc, char *argv[]) \& str = argv[1]; base = (argc > 2) ? atoi(argv[2]) : 0; +\& + errno = 0; /* To distinguish success/failure after call */ + strtol("0", NULL, base); + if (errno == EINVAL) { + perror("strtol"); + exit(EXIT_FAILURE); + } \& errno = 0; /* To distinguish success/failure after call */ val = strtol(str, &endptr, base); \& /* Check for various possible errors. */ \& - if (errno != 0) { + if (errno == ERANGE) { perror("strtol"); exit(EXIT_FAILURE); } diff --git a/man3/strtoul.3 b/man3/strtoul.3 index a9a8d60..99b5a47 100644 --- a/man3/strtoul.3 +++ b/man3/strtoul.3 @@ -11,7 +11,7 @@ .\" Fixed typo, aeb, 950823 .\" 2002-02-22, joey, mihtjel: Added strtoull() .\" -.TH strtoul 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strtoul 3 2023-12-19 "Linux man-pages 6.7" .SH NAME strtoul, strtoull, strtouq \- convert a string to an unsigned long integer .SH LIBRARY @@ -20,18 +20,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "unsigned long strtoul(const char *restrict " nptr , .BI " char **restrict " endptr ", int " base ); .BI "unsigned long long strtoull(const char *restrict " nptr , .BI " char **restrict " endptr ", int " base ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strtoull (): .nf _ISOC99_SOURCE @@ -50,7 +50,7 @@ given .IR base , which must be between 2 and 36 inclusive, or be the special value 0. -.PP +.P The string may begin with an arbitrary amount of white space (as determined by .BR isspace (3)) @@ -64,7 +64,7 @@ zero .I base is taken as 10 (decimal) unless the next character is \[aq]0\[aq], in which case it is taken as 8 (octal). -.PP +.P The remainder of the string is converted to an .I "unsigned long" value in the obvious manner, @@ -73,10 +73,13 @@ valid digit in the given base. (In bases above 10, the letter \[aq]A\[aq] in either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so forth, with \[aq]Z\[aq] representing 35.) -.PP +.P If .I endptr is not NULL, +and the +.I base +is supported, .BR strtoul () stores the address of the first invalid character in @@ -94,7 +97,7 @@ In particular, if is not \[aq]\e0\[aq] but .I **endptr is \[aq]\e0\[aq] on return, the entire string is valid. -.PP +.P The .BR strtoull () function works just like the @@ -124,6 +127,9 @@ Precisely the same holds for instead of .BR ULONG_MAX ). .SH ERRORS +This function does not modify +.I errno +on success. .TP .B EINVAL (not in C99) @@ -133,7 +139,7 @@ contains an unsupported value. .TP .B ERANGE The resulting value was out of range. -.PP +.P The implementation may also set .I errno to @@ -156,7 +162,6 @@ T{ .BR strtouq () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -180,26 +185,26 @@ to 0 before the call, and then determine if an error occurred by checking whether .I errno has a nonzero value after the call. -.PP +.P In locales other than the "C" locale, other strings may be accepted. (For example, the thousands separator of the current locale may be supported.) -.PP +.P BSD also has -.PP +.P .in +4n .EX .BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base ); .EE .in -.PP +.P with completely analogous definition. Depending on the wordsize of the current architecture, this may be equivalent to .BR strtoull () or to .BR strtoul (). -.PP +.P Negative values are considered valid input and are silently converted to the equivalent .I "unsigned long" diff --git a/man3/strverscmp.3 b/man3/strverscmp.3 index e33a569..ad3ebeb 100644 --- a/man3/strverscmp.3 +++ b/man3/strverscmp.3 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH strverscmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strverscmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strverscmp \- compare two version strings .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int strverscmp(const char *" s1 ", const char *" s2 ); .fi .SH DESCRIPTION @@ -33,7 +33,7 @@ which is implemented using .BR versionsort (3), which again uses .BR strverscmp (). -.PP +.P Thus, the task of .BR strverscmp () is to compare two strings and find the "right" order, while @@ -44,7 +44,7 @@ the locale category .BR LC_COLLATE , so is meant mostly for situations where the strings are expected to be in ASCII. -.PP +.P What this function does is the following. If both strings are equal, return 0. Otherwise, find the position @@ -85,7 +85,6 @@ T{ .BR strverscmp () T} Thread safety MT-Safe .TE -.sp 1 .\" FIXME: The marking is different from that in the glibc manual, .\" which has: .\" @@ -105,7 +104,7 @@ It uses .BR strverscmp () to compare the two strings given as its command-line arguments. An example of its use is the following: -.PP +.P .in +4n .EX $ \fB./a.out jan1 jan10\fP diff --git a/man3/strxfrm.3 b/man3/strxfrm.3 index 03ff0a8..a646af0 100644 --- a/man3/strxfrm.3 +++ b/man3/strxfrm.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sun Jul 25 10:41:28 1993 by Rik Faith (faith@cs.unc.edu) -.TH strxfrm 3 2023-07-20 "Linux man-pages 6.05.01" +.TH strxfrm 3 2023-10-31 "Linux man-pages 6.7" .SH NAME strxfrm \- string transformation .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t strxfrm(char " dest "[restrict ." n "], \ const char " src "[restrict ." n ], .BI " size_t " n ); @@ -73,7 +73,6 @@ T{ .BR strxfrm () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/swab.3 b/man3/swab.3 index 046c0f8..73c840f 100644 --- a/man3/swab.3 +++ b/man3/swab.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sat Jul 24 17:52:15 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 2001-12-15, aeb -.TH swab 3 2023-07-20 "Linux man-pages 6.05.01" +.TH swab 3 2023-10-31 "Linux man-pages 6.7" .SH NAME swab \- swap adjacent bytes .SH LIBRARY @@ -19,7 +19,7 @@ Standard C library .nf .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void swab(const void " from "[restrict ." n "], void " to "[restrict ." n ], .BI " ssize_t " n ); .fi @@ -37,7 +37,7 @@ exchanging adjacent even and odd bytes. This function is used to exchange data between machines that have different low/high byte ordering. -.PP +.P This function does nothing when .I n is negative. @@ -68,7 +68,6 @@ T{ .BR swab () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/sysconf.3 b/man3/sysconf.3 index a4d14d3..29ce6bd 100644 --- a/man3/sysconf.3 +++ b/man3/sysconf.3 @@ -5,7 +5,7 @@ .\" .\" Modified Sat Jul 24 17:51:42 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Tue Aug 17 11:42:20 1999 by Ariel Scolnicov (ariels@compugen.co.il) -.TH sysconf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sysconf 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sysconf \- get configuration information at run time .SH LIBRARY @@ -14,20 +14,20 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long sysconf(int " "name" ); .fi .SH DESCRIPTION POSIX allows an application to test at compile or run time whether certain options are supported, or what the value is of certain configurable constants or limits. -.PP +.P At compile time this is done by including .I and/or .I and testing the value of certain macros. -.PP +.P At run time, one can ask for numerical values using the present function .BR sysconf (). One can ask for numerical values that may depend @@ -37,12 +37,12 @@ and .BR pathconf (3). One can ask for string values using .BR confstr (3). -.PP +.P The values obtained from these functions are system configuration constants. They do not change during the lifetime of a process. .\" except that sysconf(_SC_OPEN_MAX) may change answer after a call .\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit -.PP +.P For options, typically, there is a constant .B _POSIX_FOO that may be defined in @@ -65,7 +65,7 @@ argument will be .BR _SC_FOO . For a list of options, see .BR posixoptions (7). -.PP +.P For variables or limits, typically, there is a constant .BR _FOO , maybe defined in @@ -90,7 +90,7 @@ We give the name of the variable, the name of the .BR sysconf () argument used to inquire about its value, and a short description. -.PP +.P First, the POSIX.1 compatible values. .\" [for the moment: only the things that are unconditionally present] .\" .TP @@ -285,7 +285,7 @@ is supported. .BR POSIX2_SW_DEV " - " _SC_2_SW_DEV indicates whether the POSIX.2 software development utilities option is supported. -.PP +.P These values also exist, but may not be standard. .TP .BR "" " - " _SC_PHYS_PAGES @@ -366,7 +366,6 @@ T{ .BR sysconf () T} Thread safety MT-Safe env .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -377,7 +376,7 @@ It is difficult to use because it is not specified how much of the argument space for .BR exec (3) is consumed by the user's environment variables. -.PP +.P Some returned values may be huge; they are not suitable for allocating memory. .SH SEE ALSO diff --git a/man3/syslog.3 b/man3/syslog.3 index e8c9dc4..7b3c663 100644 --- a/man3/syslog.3 +++ b/man3/syslog.3 @@ -15,7 +15,7 @@ .\" Modified 13 Dec 2001, Martin Schulze .\" Modified 3 Jan 2002, Michael Kerrisk .\" -.TH syslog 3 2023-07-20 "Linux man-pages 6.05.01" +.TH syslog 3 2023-10-31 "Linux man-pages 6.7" .SH NAME closelog, openlog, syslog, vsyslog \- send messages to the system logger .SH LIBRARY @@ -24,19 +24,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void openlog(const char *" ident ", int " option ", int " facility ); .BI "void syslog(int " priority ", const char *" format ", ...);" .B "void closelog(void);" -.PP +.P .BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR vsyslog (): .nf Since glibc 2.19: @@ -48,7 +48,7 @@ Feature Test Macro Requirements for glibc (see .SS openlog() .BR openlog () opens a connection to the system logger for a program. -.PP +.P The string pointed to by .I ident is prepended to every message, and is typically set to the program name. @@ -58,7 +58,7 @@ is NULL, the program name is used. (POSIX.1-2008 does not specify the behavior when .I ident is NULL.) -.PP +.P The .I option argument specifies flags which control the operation of @@ -75,7 +75,7 @@ The values that may be specified for and .I facility are described below. -.PP +.P The use of .BR openlog () is optional; it will automatically be called by @@ -88,7 +88,7 @@ will default to NULL. .BR syslog () generates a log message, which will be distributed by .BR syslogd (8). -.PP +.P The .I priority argument is formed by ORing together a @@ -107,7 +107,7 @@ is used, or, if there was no preceding call, a default of .B LOG_USER is employed. -.PP +.P The remaining arguments are a .IR format , as in @@ -120,7 +120,7 @@ will be replaced by the error message string .IR strerror ( errno ). The format string need not include a terminating newline character. -.PP +.P The function .BR vsyslog () performs the same task as @@ -254,7 +254,7 @@ informational message .TP .B LOG_DEBUG debug-level message -.PP +.P The function .BR setlogmask (3) can be used to restrict logging to specified levels only. @@ -279,7 +279,6 @@ T{ .BR vsyslog () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS .TP .BR syslog () @@ -310,7 +309,7 @@ None. .\" .I .\" mechanism, which is not compatible with .\" .IR . -.PP +.P POSIX.1-2001 specifies only the .B LOG_USER and @@ -324,7 +323,7 @@ and the other .I facility values appear on most UNIX systems. -.PP +.P The .B LOG_PERROR value for @@ -343,10 +342,10 @@ is changed, may start prepending the changed string, and if the string it points to ceases to exist, the results are undefined. Most portable is to use a string constant. -.PP +.P Never pass a string with user-supplied data as a format, use the following instead: -.PP +.P .in +4n .EX syslog(priority, "%s", string); diff --git a/man3/system.3 b/man3/system.3 index 8615623..08ffb07 100644 --- a/man3/system.3 +++ b/man3/system.3 @@ -9,7 +9,7 @@ .\" Modified 14 May 2001, 23 Sep 2001 by aeb .\" 2004-12-20, mtk .\" -.TH system 3 2023-07-20 "Linux man-pages 6.05.01" +.TH system 3 2023-10-31 "Linux man-pages 6.7" .SH NAME system \- execute a shell command .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int system(const char *" "command" ); .fi .SH DESCRIPTION @@ -31,16 +31,16 @@ to create a child process that executed the shell command specified in using .BR execl (3) as follows: -.PP +.P .in +4n .EX execl("/bin/sh", "sh", "\-c", command, (char *) NULL); .EE .in -.PP +.P .BR system () returns after the command has been completed. -.PP +.P During execution of the command, .B SIGCHLD will be blocked, and @@ -52,7 +52,7 @@ will be ignored, in the process that calls (These signals will be handled according to their defaults inside the child process that executes .IR command .) -.PP +.P If .I command is NULL, then @@ -85,7 +85,7 @@ used to execute .IR command . (The termination status of a shell is the termination status of the last command it executes.) -.PP +.P In the last two cases, the return value is a "wait status" that can be examined using the macros described in @@ -94,7 +94,7 @@ the macros described in .BR WIFEXITED (), .BR WEXITSTATUS (), and so on). -.PP +.P .BR system () does not affect the wait status of any other children. .SH ERRORS @@ -115,7 +115,6 @@ T{ .BR system () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -137,7 +136,7 @@ The main cost of is inefficiency: additional system calls are required to create the process that runs the shell and to execute the shell. -.PP +.P If the .B _XOPEN_SOURCE feature test macro is defined @@ -149,7 +148,7 @@ then the macros described in .RB ( WEXITSTATUS (), etc.) are made available when including .IR . -.PP +.P As mentioned, .BR system () ignores @@ -160,7 +159,7 @@ This may make programs that call it from a loop uninterruptible, unless they take care themselves to check the exit status of the child. For example: -.PP +.P .in +4n .EX while (something) { @@ -172,13 +171,13 @@ while (something) { } .EE .in -.PP +.P According to POSIX.1, it is unspecified whether handlers registered using .BR pthread_atfork (3) are called during the execution of .BR system (). In the glibc implementation, such handlers are not called. -.PP +.P Before glibc 2.1.3, the check for the availability of .I /bin/sh was not actually performed if @@ -192,7 +191,7 @@ a shell, that shell may not be available or executable if the calling program has previously called .BR chroot (2) (which is not specified by POSIX.1-2001). -.PP +.P It is possible for the shell command to terminate with a status of 127, which yields a .BR system () @@ -219,7 +218,7 @@ or (which also use the .B PATH environment variable to search for an executable). -.PP +.P .BR system () will not, in fact, work properly from programs with set-user-ID or set-group-ID privileges on systems on which @@ -229,7 +228,7 @@ is bash version 2: as a security measure, bash 2 drops privileges on startup. .BR dash (1), which does not do this when invoked as .BR sh .) -.PP +.P Any user input that is employed as part of .I command should be @@ -253,7 +252,7 @@ option to .BR sh (1).) To work around this problem, prepend the command with a space as in the following call: -.PP +.P .in +4n .EX system(" \-unfortunate\-command\-name"); diff --git a/man3/sysv_signal.3 b/man3/sysv_signal.3 index 84d77fe..0c0c161 100644 --- a/man3/sysv_signal.3 +++ b/man3/sysv_signal.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sysv_signal 3 2023-07-20 "Linux man-pages 6.05.01" +.TH sysv_signal 3 2023-10-31 "Linux man-pages 6.7" .SH NAME sysv_signal \- signal handling with System V semantics .SH LIBRARY @@ -13,9 +13,9 @@ Standard C library .nf .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .B typedef void (*sighandler_t)(int); -.PP +.P .BI "sighandler_t sysv_signal(int " signum ", sighandler_t " handler ); .fi .SH DESCRIPTION @@ -23,7 +23,7 @@ The .BR sysv_signal () function takes the same arguments, and performs the same task, as .BR signal (2). -.PP +.P However .BR sysv_signal () provides the System V unreliable signal semantics, that is: @@ -56,14 +56,13 @@ T{ .BR sysv_signal () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS Use of .BR sysv_signal () should be avoided; use .BR sigaction (2) instead. -.PP +.P On older Linux systems, .BR sysv_signal () and @@ -74,7 +73,7 @@ But on newer systems, provides reliable signal semantics; see .BR signal (2) for details. -.PP +.P The use of .I sighandler_t is a GNU extension; diff --git a/man3/tailq.3 b/man3/tailq.3 index 15f9203..5e24501 100644 --- a/man3/tailq.3 +++ b/man3/tailq.3 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH TAILQ 3 2023-05-03 "Linux man-pages 6.05.01" +.TH TAILQ 3 2023-10-31 "Linux man-pages 6.7" .SH NAME TAILQ_CONCAT, TAILQ_EMPTY, @@ -38,15 +38,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B TAILQ_ENTRY(TYPE); -.PP +.P .B TAILQ_HEAD(HEADNAME, TYPE); .BI "TAILQ_HEAD TAILQ_HEAD_INITIALIZER(TAILQ_HEAD " head ); .BI "void TAILQ_INIT(TAILQ_HEAD *" head ); -.PP +.P .BI "int TAILQ_EMPTY(TAILQ_HEAD *" head ); -.PP +.P .BI "void TAILQ_INSERT_HEAD(TAILQ_HEAD *" head , .BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); .BI "void TAILQ_INSERT_TAIL(TAILQ_HEAD *" head , @@ -55,12 +55,12 @@ Standard C library .BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); .BI "void TAILQ_INSERT_AFTER(TAILQ_HEAD *" head ", struct TYPE *" listelm , .BI " struct TYPE *" elm ", TAILQ_ENTRY " NAME ); -.PP +.P .BI "struct TYPE *TAILQ_FIRST(TAILQ_HEAD *" head ); .BI "struct TYPE *TAILQ_LAST(TAILQ_HEAD *" head ", HEADNAME);" .BI "struct TYPE *TAILQ_PREV(struct TYPE *" elm ", HEADNAME, TAILQ_ENTRY " NAME ); .BI "struct TYPE *TAILQ_NEXT(struct TYPE *" elm ", TAILQ_ENTRY " NAME ); -.PP +.P .BI "TAILQ_FOREACH(struct TYPE *" var ", TAILQ_HEAD *" head , .BI " TAILQ_ENTRY " NAME ); .\" .BI "TAILQ_FOREACH_FROM(struct TYPE *" var ", TAILQ_HEAD *" head , @@ -69,7 +69,7 @@ Standard C library .BI " TAILQ_ENTRY " NAME ); .\" .BI "TAILQ_FOREACH_REVERSE_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME," .\" .BI " TAILQ_ENTRY " NAME ); -.\" .PP +.\" .P .\" .BI "TAILQ_FOREACH_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , .\" .BI " TAILQ_ENTRY " NAME , .\" .BI " struct TYPE *" temp_var ); @@ -82,10 +82,10 @@ Standard C library .\" .BI "TAILQ_FOREACH_REVERSE_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head , .\" .BI " HEADNAME, TAILQ_ENTRY " NAME , .\" .BI " struct TYPE *" temp_var ); -.PP +.P .BI "void TAILQ_REMOVE(TAILQ_HEAD *" head ", struct TYPE *" elm , .BI " TAILQ_ENTRY " NAME ); -.PP +.P .BI "void TAILQ_CONCAT(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 , .BI " TAILQ_ENTRY " NAME ); .\" .BI "void TAILQ_SWAP(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ", TYPE," @@ -93,7 +93,7 @@ Standard C library .fi .SH DESCRIPTION These macros define and operate on doubly linked tail queues. -.PP +.P In the macro definitions, .I TYPE is the name of a user defined structure, @@ -123,42 +123,42 @@ or at the end of the queue. A .I TAILQ_HEAD structure is declared as follows: -.PP +.P .in +4 .EX TAILQ_HEAD(HEADNAME, TYPE) head; .EE .in -.PP +.P where .I struct HEADNAME is the structure to be defined, and .I struct TYPE is the type of the elements to be linked into the queue. A pointer to the head of the queue can later be declared as: -.PP +.P .in +4 .EX struct HEADNAME *headp; .EE .in -.PP +.P (The names .I head and .I headp are user selectable.) -.PP +.P .BR TAILQ_ENTRY () declares a structure that connects the elements in the queue. -.PP +.P .BR TAILQ_HEAD_INITIALIZER () evaluates to an initializer for the queue .IR head . -.PP +.P .BR TAILQ_INIT () initializes the queue referenced by -.PP +.P .BR TAILQ_EMPTY () evaluates to true if there are no items on the queue. .IR head . @@ -167,18 +167,18 @@ evaluates to true if there are no items on the queue. inserts the new element .I elm at the head of the queue. -.PP +.P .BR TAILQ_INSERT_TAIL () inserts the new element .I elm at the end of the queue. -.PP +.P .BR TAILQ_INSERT_BEFORE () inserts the new element .I elm before the element .IR listelm . -.PP +.P .BR TAILQ_INSERT_AFTER () inserts the new element .I elm @@ -187,17 +187,17 @@ after the element .SS Traversal .BR TAILQ_FIRST () returns the first item on the queue, or NULL if the queue is empty. -.PP +.P .BR TAILQ_LAST () returns the last item on the queue. If the queue is empty the return value is NULL. -.PP +.P .BR TAILQ_PREV () returns the previous item on the queue, or NULL if this item is the first. -.PP +.P .BR TAILQ_NEXT () returns the next item on the queue, or NULL if this item is the last. -.PP +.P .BR TAILQ_FOREACH () traverses the queue referenced by .I head @@ -207,7 +207,7 @@ assigning each element in turn to .I var is set to NULL if the loop completes normally, or if there were no elements. -.\" .PP +.\" .P .\" .BR TAILQ_FOREACH_FROM () .\" behaves identically to .\" .BR TAILQ_FOREACH () @@ -219,14 +219,14 @@ or if there were no elements. .\" .I var .\" instead of the first element in the TAILQ referenced by .\" .IR head . -.PP +.P .BR TAILQ_FOREACH_REVERSE () traverses the queue referenced by .I head in the reverse direction, assigning each element in turn to .IR var . -.\" .PP +.\" .P .\" .BR TAILQ_FOREACH_REVERSE_FROM () .\" behaves identically to .\" .BR TAILQ_FOREACH_REVERSE () @@ -238,7 +238,7 @@ assigning each element in turn to .\" .I var .\" instead of the last element in the TAILQ referenced by .\" .IR head . -.\" .PP +.\" .P .\" .BR TAILQ_FOREACH_SAFE () .\" and .\" .BR TAILQ_FOREACH_REVERSE_SAFE () @@ -255,7 +255,7 @@ assigning each element in turn to .\" .I var .\" as well as free it from within the loop safely without interfering with the .\" traversal. -.\" .PP +.\" .P .\" .BR TAILQ_FOREACH_FROM_SAFE () .\" behaves identically to .\" .BR TAILQ_FOREACH_SAFE () @@ -267,7 +267,7 @@ assigning each element in turn to .\" .I var .\" instead of the first element in the TAILQ referenced by .\" .IR head . -.\" .PP +.\" .P .\" .BR TAILQ_FOREACH_REVERSE_FROM_SAFE () .\" behaves identically to .\" .BR TAILQ_FOREACH_REVERSE_SAFE () @@ -290,7 +290,7 @@ from the queue. .\" .I head1 .\" and .\" .IR head2 . -.\" .PP +.\" .P .BR TAILQ_CONCAT () concatenates the queue headed by .I head2 @@ -301,7 +301,7 @@ removing all entries from the former. .BR TAILQ_EMPTY () returns nonzero if the queue is empty, and zero if the queue contains at least one entry. -.PP +.P .BR TAILQ_FIRST (), .BR TAILQ_LAST (), .BR TAILQ_PREV (), @@ -310,7 +310,7 @@ and return a pointer to the first, last, previous, or next .I TYPE structure, respectively. -.PP +.P .BR TAILQ_HEAD_INITIALIZER () returns an initializer that can be assigned to the queue .IR head . diff --git a/man3/tan.3 b/man3/tan.3 index b0b185e..169a6ef 100644 --- a/man3/tan.3 +++ b/man3/tan.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH tan 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tan 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tan, tanf, tanl \- tangent function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double tan(double " x ); .BI "float tanf(float " x ); .BI "long double tanl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR tanf (), .BR tanl (): .nf @@ -50,17 +50,17 @@ given in radians. .SH RETURN VALUE On success, these functions return the tangent of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity or negative infinity, a domain error occurs, and a NaN is returned. -.PP +.P If the correct result would overflow, a range error occurs, and the functions return @@ -83,7 +83,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is an infinity @@ -120,12 +120,11 @@ T{ .BR tanl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/tanh.3 b/man3/tanh.3 index dc4d8fc..09d3e03 100644 --- a/man3/tanh.3 +++ b/man3/tanh.3 @@ -13,7 +13,7 @@ .\" Modified 2002-07-27 by Walter Harms .\" (walter.harms@informatik.uni-oldenburg.de) .\" -.TH tanh 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tanh 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tanh, tanhf, tanhl \- hyperbolic tangent function .SH LIBRARY @@ -22,17 +22,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double tanh(double " x ); .BI "float tanhf(float " x ); .BI "long double tanhl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR tanhf (), .BR tanhl (): .nf @@ -45,22 +45,22 @@ These functions return the hyperbolic tangent of .IR x , which is defined mathematically as: -.PP +.P .nf tanh(x) = sinh(x) / cosh(x) .fi .SH RETURN VALUE On success, these functions return the hyperbolic tangent of .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is +0 (\-0), +0 (\-0) is returned. -.PP +.P If .I x is positive infinity (negative infinity), @@ -87,12 +87,11 @@ T{ .BR tanhl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The variant returning .I double also conforms to diff --git a/man3/tcgetpgrp.3 b/man3/tcgetpgrp.3 index 494ed43..d80baed 100644 --- a/man3/tcgetpgrp.3 +++ b/man3/tcgetpgrp.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tcgetpgrp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tcgetpgrp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tcgetpgrp, tcsetpgrp \- get and set terminal foreground process group .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "pid_t tcgetpgrp(int " fd ); .BI "int tcsetpgrp(int " fd ", pid_t " pgrp ); .fi @@ -24,7 +24,7 @@ terminal associated to .IR fd , which must be the controlling terminal of the calling process. .\" The process itself may be a background process. -.PP +.P The function .BR tcsetpgrp () makes the process group with process group ID @@ -37,7 +37,7 @@ Moreover, .I pgrp must be a (nonempty) process group belonging to the same session as the calling process. -.PP +.P If .BR tcsetpgrp () is called by a member of a background process group in its session, @@ -61,7 +61,7 @@ does not refer to the controlling terminal of the calling process, \-1 is returned, and .I errno is set to indicate the error. -.PP +.P When successful, .BR tcsetpgrp () returns 0. @@ -106,7 +106,6 @@ T{ .BR tcsetpgrp () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS These functions are implemented via the .B TIOCGPGRP @@ -117,7 +116,7 @@ ioctls. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P The ioctls appeared in 4.2BSD. The functions are POSIX inventions. .SH SEE ALSO diff --git a/man3/tcgetsid.3 b/man3/tcgetsid.3 index 4fb349c..f727dfd 100644 --- a/man3/tcgetsid.3 +++ b/man3/tcgetsid.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tcgetsid 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tcgetsid 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tcgetsid \- get session ID .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .BR "#define _XOPEN_SOURCE 500" " /* See feature_test_macros(7) */" .B "#include " -.PP +.P .BI "pid_t tcgetsid(int " fd ); .fi .SH DESCRIPTION @@ -58,13 +58,12 @@ T{ .BR tcgetsid () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY glibc 2.1. POSIX.1-2001. -.PP +.P This function is implemented via the .B TIOCGSID .BR ioctl (2), diff --git a/man3/telldir.3 b/man3/telldir.3 index 6bbd158..dbc5d9c 100644 --- a/man3/telldir.3 +++ b/man3/telldir.3 @@ -8,7 +8,7 @@ .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) .\" 386BSD man pages .\" Modified Sat Jul 24 17:48:42 1993 by Rik Faith (faith@cs.unc.edu) -.TH telldir 3 2023-07-20 "Linux man-pages 6.05.01" +.TH telldir 3 2023-10-31 "Linux man-pages 6.7" .SH NAME telldir \- return current location in directory stream .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "long telldir(DIR *" dirp ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR telldir (): .nf _XOPEN_SOURCE @@ -63,12 +63,11 @@ T{ .BR telldir () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001, 4.3BSD. -.PP +.P Up to glibc 2.1.1, the return type of .BR telldir () was @@ -76,7 +75,7 @@ was POSIX.1-2001 specifies .IR long , and this is the type used since glibc 2.1.2. -.PP +.P In early filesystems, the value returned by .BR telldir () was a simple file offset within a directory. diff --git a/man3/tempnam.3 b/man3/tempnam.3 index fd68643..e1b7380 100644 --- a/man3/tempnam.3 +++ b/man3/tempnam.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tempnam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tempnam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tempnam \- create a name for a temporary file .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *tempnam(const char *" dir ", const char *" pfx ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR tempnam (): .nf Since glibc 2.19: @@ -35,7 +35,7 @@ Use or .BR tmpfile (3) instead. -.PP +.P The .BR tempnam () function returns a pointer to a string that is a valid filename, @@ -49,7 +49,7 @@ in case is a non-NULL string of at most five bytes. The directory prefix part of the pathname generated is required to be "appropriate" (often that at least implies writable). -.PP +.P Attempts to find an appropriate directory go through the following steps: .TP 3 @@ -73,7 +73,7 @@ is used when appropriate. .TP d) Finally an implementation-defined directory may be used. -.PP +.P The string returned by .BR tempnam () is allocated using @@ -105,7 +105,6 @@ T{ .BR tempnam () T} Thread safety MT-Safe env .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY @@ -130,7 +129,7 @@ Or better yet, use .BR mkstemp (3) or .BR tmpfile (3). -.PP +.P SUSv2 does not mention the use of .BR TMPDIR ; glibc will use it only @@ -138,12 +137,12 @@ when the program is not set-user-ID. On SVr4, the directory used under \fBd)\fP is .I /tmp (and this is what glibc does). -.PP +.P Because it dynamically allocates memory used to return the pathname, .BR tempnam () is reentrant, and thus thread safe, unlike .BR tmpnam (3). -.PP +.P The .BR tempnam () function generates a different string each time it is called, @@ -156,11 +155,11 @@ If it is called more than .B TMP_MAX times, the behavior is implementation defined. -.PP +.P .BR tempnam () uses at most the first five bytes from .IR pfx . -.PP +.P The glibc implementation of .BR tempnam () fails with the error diff --git a/man3/termios.3 b/man3/termios.3 index 9e015d1..28a5411 100644 --- a/man3/termios.3 +++ b/man3/termios.3 @@ -19,7 +19,7 @@ .\" Enhanced the discussion of "raw" mode for cfmakeraw(). .\" Document CMSPAR. .\" -.TH termios 3 2023-07-30 "Linux man-pages 6.05.01" +.TH termios 3 2023-10-31 "Linux man-pages 6.7" .SH NAME termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- @@ -31,31 +31,31 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int tcgetattr(int " fd ", struct termios *" termios_p ); .BI "int tcsetattr(int " fd ", int " optional_actions , .BI " const struct termios *" termios_p ); -.PP +.P .BI "int tcsendbreak(int " fd ", int " duration ); .BI "int tcdrain(int " fd ); .BI "int tcflush(int " fd ", int " queue_selector ); .BI "int tcflow(int " fd ", int " action ); -.PP +.P .BI "void cfmakeraw(struct termios *" termios_p ); -.PP +.P .BI "speed_t cfgetispeed(const struct termios *" termios_p ); .BI "speed_t cfgetospeed(const struct termios *" termios_p ); -.PP +.P .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR cfsetspeed (), .BR cfmakeraw (): .nf @@ -71,7 +71,7 @@ provided to control asynchronous communications ports. Many of the functions described here have a \fItermios_p\fP argument that is a pointer to a \fItermios\fP structure. This structure contains at least the following members: -.PP +.P .in +4n .EX tcflag_t c_iflag; /* input modes */ @@ -81,19 +81,19 @@ tcflag_t c_lflag; /* local modes */ cc_t c_cc[NCCS]; /* special characters */ .EE .in -.PP +.P The values that may be assigned to these fields are described below. In the case of the first four bit-mask fields, the definitions of some of the associated flags that may be set are exposed only if a specific feature test macro (see .BR feature_test_macros (7)) is defined, as noted in brackets ("[]"). -.PP +.P In the descriptions below, "not in POSIX" means that the value is not specified in POSIX.1-2001, and "XSI" means that the value is specified in POSIX.1-2001 as part of the XSI extension. -.PP +.P \fIc_iflag\fP flag constants: .TP .B IGNBRK @@ -168,7 +168,7 @@ Linux does not implement this bit, and acts as if it is always set. .BR IUTF8 " (since Linux 2.6.4)" (not in POSIX) Input is UTF8; this allows character-erase to be correctly performed in cooked mode. -.PP +.P .I c_oflag flag constants: .TP @@ -259,7 +259,7 @@ or .B _SVID_SOURCE or .BR _XOPEN_SOURCE ] -.PP +.P \fIc_cflag\fP flag constants: .TP .B CBAUD @@ -361,7 +361,7 @@ or .B _BSD_SOURCE or .BR _SVID_SOURCE ] -.PP +.P \fIc_lflag\fP flag constants: .TP .B ISIG @@ -472,7 +472,7 @@ Enable implementation-defined input processing. This flag, as well as \fBICANON\fP must be enabled for the special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, and for the \fBIUCLC\fP flag to be effective. -.PP +.P The \fIc_cc\fP array defines the terminal special characters. The symbolic indices (initial values) and meaning are: .TP @@ -634,13 +634,13 @@ Recognized when and .B IEXTEN are set, and then not passed as input. -.PP +.P An individual terminal special character can be disabled by setting the value of the corresponding .I c_cc element to .BR _POSIX_VDISABLE . -.PP +.P The above symbolic subscript values are all different, except that .BR VTIME , .B VMIN @@ -664,7 +664,7 @@ stores them in the \fItermios\fP structure referenced by This function may be invoked from a background process; however, the terminal attributes may be subsequently changed by a foreground process. -.PP +.P .BR tcsetattr () sets the parameters associated with the terminal (unless support is required from the underlying hardware that is not available) from the @@ -700,7 +700,7 @@ unset). By default, .B ICANON is set. -.PP +.P In canonical mode: .IP \[bu] 3 Input is made available line by line. @@ -734,7 +734,7 @@ processing) continues, but any input data after 4095 characters up to (but not including) any terminating newline is discarded. This ensures that the terminal can always receive more input until at least one line can be read. -.PP +.P In noncanonical mode input is available immediately (without the user having to type a line-delimiter character), no input processing is performed, @@ -806,7 +806,7 @@ becomes available, at least one byte will be read. If data is already available at the time of the call to .BR read (2), the call behaves as though the data was received immediately after the call. -.PP +.P POSIX .\" POSIX.1-2008 XBD 11.1.7 does not specify whether the setting of the @@ -833,7 +833,7 @@ input is available character by character, echoing is disabled, and all special processing of terminal input and output characters is disabled. The terminal attributes are set as follows: -.PP +.P .in +4n .EX termios_p\->c_iflag &= \[ti](IGNBRK | BRKINT | PARMRK | ISTRIP @@ -854,16 +854,16 @@ If \fIduration\fP is zero, it transmits zero-valued bits for at least 0.25 seconds, and not more than 0.5 seconds. If \fIduration\fP is not zero, it sends zero-valued bits for some implementation-defined length of time. -.PP +.P If the terminal is not using asynchronous serial data transmission, .BR tcsendbreak () returns without taking any action. -.PP +.P .BR tcdrain () waits until all output written to the object referred to by .I fd has been transmitted. -.PP +.P .BR tcflush () discards data written to the object referred to by .I fd @@ -880,7 +880,7 @@ flushes data written but not transmitted. .B TCIOFLUSH flushes both data received but not read, and data written but not transmitted. -.PP +.P .BR tcflow () suspends transmission or reception of data on the object referred to by .IR fd , @@ -900,7 +900,7 @@ transmitting data to the system. .B TCION transmits a START character, which starts the terminal device transmitting data to the system. -.PP +.P The default on open of a terminal file is that neither its input nor its output is suspended. .SS Line speed @@ -910,19 +910,19 @@ The new values do not take effect until .BR tcsetattr () is successfully called. -.PP +.P Setting the speed to \fBB0\fP instructs the modem to "hang up". The actual bit rate corresponding to \fBB38400\fP may be altered with .BR setserial (8). -.PP +.P The input and output baud rates are stored in the \fItermios\fP structure. -.PP +.P .BR cfgetospeed () returns the output baud rate stored in the \fItermios\fP structure pointed to by .IR termios_p . -.PP +.P .BR cfsetospeed () sets the output baud rate stored in the \fItermios\fP structure pointed to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: @@ -982,7 +982,7 @@ to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: .TQ .B B2000000 .RE -.PP +.P These constants are additionally supported on the SPARC architecture: .RS .TP @@ -994,7 +994,7 @@ These constants are additionally supported on the SPARC architecture: .TQ .B B614400 .RE -.PP +.P These constants are additionally supported on non-SPARC architectures: .RS .TP @@ -1006,12 +1006,12 @@ These constants are additionally supported on non-SPARC architectures: .TQ .B B4000000 .RE -.PP +.P Due to differences between architectures, portable applications should check if a particular .BI B nnn constant is defined prior to using it. -.PP +.P The zero baud rate, .BR B0 , is used to terminate the connection. @@ -1025,19 +1025,19 @@ for the speeds beyond those defined in POSIX.1 (57600 and above). Thus, .BR B57600 " & " CBAUDEX is nonzero. -.PP +.P Setting the baud rate to a value other than those defined by .BI B nnn constants is possible via the .B TCSETS2 ioctl; see .BR ioctl_tty (2). -.PP +.P .BR cfgetispeed () returns the input baud rate stored in the .I termios structure. -.PP +.P .BR cfsetispeed () sets the input baud rate stored in the .I termios @@ -1053,7 +1053,7 @@ If the input baud rate is set to the literal constant .BR B0 ), the input baud rate will be equal to the output baud rate. -.PP +.P .BR cfsetspeed () is a 4.4BSD extension. It takes the same arguments as @@ -1064,10 +1064,10 @@ and sets both input and output speed. returns the input baud rate stored in the \fItermios\fP structure. -.PP +.P .BR cfgetospeed () returns the output baud rate stored in the \fItermios\fP structure. -.PP +.P All other functions return: .TP .B 0 @@ -1077,7 +1077,7 @@ on success. on failure and set .I errno to indicate the error. -.PP +.P Note that .BR tcsetattr () returns success if \fIany\fP of the requested changes could be @@ -1111,7 +1111,6 @@ T{ .BR cfsetspeed () T} Thread safety MT-Safe .TE -.sp 1 .\" FIXME: The markings are different from that in the glibc manual. .\" markings in glibc manual are more detailed: .\" @@ -1186,7 +1185,7 @@ one finds the two constants .B EXTB ("External A" and "External B"). Many systems extend the list with much higher baud rates. -.PP +.P The effect of a nonzero \fIduration\fP with .BR tcsendbreak () varies. diff --git a/man3/tgamma.3 b/man3/tgamma.3 index d2c5969..e62069c 100644 --- a/man3/tgamma.3 +++ b/man3/tgamma.3 @@ -9,7 +9,7 @@ .\" Modified 2004-11-15, fixed error noted by Fabian Kreutz .\" .\" -.TH tgamma 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tgamma 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tgamma, tgammaf, tgammal \- true gamma function .SH LIBRARY @@ -18,17 +18,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double tgamma(double " x ); .BI "float tgammaf(float " x ); .BI "long double tgammal(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR tgamma (), .BR tgammaf (), .BR tgammal (): @@ -38,53 +38,53 @@ Feature Test Macro Requirements for glibc (see .SH DESCRIPTION These functions calculate the Gamma function of .IR x . -.PP +.P The Gamma function is defined by -.PP +.P .RS Gamma(x) = integral from 0 to infinity of t\[ha](x\-1) e\[ha]\-t dt .RE -.PP +.P It is defined for every real number except for nonpositive integers. For nonnegative integral .I m one has -.PP +.P .RS Gamma(m+1) = m! .RE -.PP +.P and, more generally, for all .IR x : -.PP +.P .RS Gamma(x+1) = x * Gamma(x) .RE -.PP +.P Furthermore, the following is valid for all values of .I x outside the poles: -.PP +.P .RS Gamma(x) * Gamma(1 \- x) = PI / sin(PI * x) .RE .SH RETURN VALUE On success, these functions return Gamma(x). -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is positive infinity, positive infinity is returned. -.PP +.P If .I x is a negative integer, or is negative infinity, a domain error occurs, and a NaN is returned. -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -93,11 +93,11 @@ and the functions return or .BR HUGE_VALL , respectively, with the correct mathematical sign. -.PP +.P If the result underflows, a range error occurs, and the functions return 0, with the correct mathematical sign. -.PP +.P If .I x is \-0 or +0, @@ -113,7 +113,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is a negative integer, or negative infinity @@ -139,7 +139,7 @@ is set to An overflow floating-point exception .RB ( FE_OVERFLOW ) is raised. -.PP +.P glibc also gives the following error which is not specified in C99 or POSIX.1-2001. .TP @@ -172,7 +172,6 @@ T{ .BR tgammal () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -194,7 +193,7 @@ to when .I x is negative infinity. -.PP +.P Before glibc 2.19, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6810 the glibc implementation of these functions did not set @@ -202,7 +201,7 @@ the glibc implementation of these functions did not set to .B ERANGE on an underflow range error. -.PP +.P .\" In glibc versions 2.3.3 and earlier, an argument of +0 or \-0 incorrectly produced a domain error diff --git a/man3/timegm.3 b/man3/timegm.3 index 659fc8a..ab21d77 100644 --- a/man3/timegm.3 +++ b/man3/timegm.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH timegm 3 2023-07-20 "Linux man-pages 6.05.01" +.TH timegm 3 2023-10-31 "Linux man-pages 6.7" .SH NAME timegm, timelocal \- inverses of gmtime and localtime .SH LIBRARY @@ -12,16 +12,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] time_t timelocal(struct tm *" tm ); .BI "time_t timegm(struct tm *" tm ); -.PP +.P .fi .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR timelocal (), .BR timegm (): .nf @@ -75,12 +75,11 @@ T{ .BR timegm () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS BSD. .SH HISTORY GNU, BSD. -.PP +.P The .BR timelocal () function is equivalent to the POSIX standard function diff --git a/man3/timeradd.3 b/man3/timeradd.3 index d64f5b4..aba49a3 100644 --- a/man3/timeradd.3 +++ b/man3/timeradd.3 @@ -4,7 +4,7 @@ .\" .\" 2007-07-31, mtk, Created .\" -.TH timeradd 3 2023-03-30 "Linux man-pages 6.05.01" +.TH timeradd 3 2023-10-31 "Linux man-pages 6.7" .SH NAME timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations .SH LIBRARY @@ -13,23 +13,23 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void timeradd(struct timeval *" a ", struct timeval *" b , .BI " struct timeval *" res ); .BI "void timersub(struct timeval *" a ", struct timeval *" b , .BI " struct timeval *" res ); -.PP +.P .BI "void timerclear(struct timeval *" tvp ); .BI "int timerisset(struct timeval *" tvp ); -.PP +.P .BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .nf Since glibc 2.19: @@ -43,7 +43,7 @@ The macros are provided to operate on structures, defined in .I as: -.PP +.P .in +4n .EX struct timeval { @@ -52,7 +52,7 @@ struct timeval { }; .EE .in -.PP +.P .BR timeradd () adds the time values in .I a @@ -65,7 +65,7 @@ pointed to by The result is normalized such that .I res\->tv_usec has a value in the range 0 to 999,999. -.PP +.P .BR timersub () subtracts the time value in .I b @@ -78,21 +78,21 @@ pointed to by The result is normalized such that .I res\->tv_usec has a value in the range 0 to 999,999. -.PP +.P .BR timerclear () zeros out the .I timeval structure pointed to by .IR tvp , so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P .BR timerisset () returns true (nonzero) if either field of the .I timeval structure pointed to by .I tvp contains a nonzero value. -.PP +.P .BR timercmp () compares the timer values in .I a @@ -119,7 +119,7 @@ and .I == do not work; portable applications can instead use -.PP +.P .in +4n .EX !timercmp(..., <) diff --git a/man3/tmpfile.3 b/man3/tmpfile.3 index 41999f5..d45202b 100644 --- a/man3/tmpfile.3 +++ b/man3/tmpfile.3 @@ -9,7 +9,7 @@ .\" 386BSD man pages .\" Modified Sat Jul 24 17:46:57 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 2001-11-17, aeb -.TH tmpfile 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tmpfile 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tmpfile \- create a temporary file .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B FILE *tmpfile(void); .fi .SH DESCRIPTION @@ -74,7 +74,6 @@ T{ .BR tmpfile () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The standard does not specify the directory that .BR tmpfile () diff --git a/man3/tmpnam.3 b/man3/tmpnam.3 index 5798faa..157c9a7 100644 --- a/man3/tmpnam.3 +++ b/man3/tmpnam.3 @@ -5,7 +5,7 @@ .\" .\" 2003-11-15, aeb, added tmpnam_r .\" -.TH tmpnam 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tmpnam 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tmpnam, tmpnam_r \- create a name for a temporary file .SH LIBRARY @@ -14,16 +14,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] char *tmpnam(char *" s ); .BI "[[deprecated]] char *tmpnam_r(char *" s ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR tmpnam_r () .nf Since glibc 2.19: @@ -38,7 +38,7 @@ avoid using these functions; use or .BR tmpfile (3) instead. -.PP +.P The .BR tmpnam () function returns a pointer to a string that is a valid filename, @@ -60,7 +60,7 @@ pointed to by and the value .I s is returned in case of success. -.PP +.P The created pathname has a directory prefix .IR P_tmpdir . (Both @@ -72,7 +72,7 @@ are defined in just like the .B TMP_MAX mentioned below.) -.PP +.P The .BR tmpnam_r () function performs the same task as @@ -104,7 +104,6 @@ T{ .BR tmpnam_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR tmpnam () @@ -131,7 +130,7 @@ If it is called more than .B TMP_MAX times, the behavior is implementation defined. -.PP +.P Although these functions generate names that are difficult to guess, it is nevertheless possible that between the time that the pathname is returned and the time that the program opens it, @@ -147,7 +146,7 @@ Or better yet, use .BR mkstemp (3) or .BR tmpfile (3). -.PP +.P Portable applications that use threads cannot call .BR tmpnam () with a NULL argument if either diff --git a/man3/toascii.3 b/man3/toascii.3 index 4e64cb0..20b91cd 100644 --- a/man3/toascii.3 +++ b/man3/toascii.3 @@ -5,7 +5,7 @@ .\" .\" Added BUGS section, aeb, 950919 .\" -.TH toascii 3 2023-07-20 "Linux man-pages 6.05.01" +.TH toascii 3 2023-10-31 "Linux man-pages 6.7" .SH NAME toascii \- convert character to ASCII .SH LIBRARY @@ -14,15 +14,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] int toascii(int " c ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR toascii (): .nf _XOPEN_SOURCE @@ -53,7 +53,6 @@ T{ .BR toascii () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/toupper.3 b/man3/toupper.3 index 0eaa693..84500c2 100644 --- a/man3/toupper.3 +++ b/man3/toupper.3 @@ -6,7 +6,7 @@ .\" .\" Modified Sat Jul 24 17:45:39 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified 2000-02-13 by Nicolás Lichtmaier -.TH toupper 3 2023-07-20 "Linux man-pages 6.05.01" +.TH toupper 3 2024-02-25 "Linux man-pages 6.7" .SH NAME toupper, tolower, toupper_l, tolower_l \- convert uppercase or lowercase .SH LIBRARY @@ -15,19 +15,19 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int toupper(int " "c" ); .BI "int tolower(int " "c" ); -.PP +.P .BI "int toupper_l(int " c ", locale_t " locale ); .BI "int tolower_l(int " c ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR toupper_l (), .BR tolower_l (): .nf @@ -38,7 +38,7 @@ Feature Test Macro Requirements for glibc (see .fi .SH DESCRIPTION These functions convert lowercase letters to uppercase, and vice versa. -.PP +.P If .I c is a lowercase letter, @@ -52,7 +52,7 @@ The function performs the same task, but uses the locale referred to by the locale handle .IR locale . -.PP +.P If .I c is an uppercase letter, @@ -66,7 +66,7 @@ The function performs the same task, but uses the locale referred to by the locale handle .IR locale . -.PP +.P If .I c is neither an @@ -75,7 +75,7 @@ value nor .BR EOF , the behavior of these functions is undefined. -.PP +.P The behavior of .BR toupper_l () and @@ -108,7 +108,6 @@ T{ .BR tolower_l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR toupper () @@ -145,7 +144,7 @@ is of type it must be cast to .IR "unsigned char" , as in the following example: -.PP +.P .in +4n .EX char c; @@ -153,7 +152,7 @@ char c; res = toupper((unsigned char) c); .EE .in -.PP +.P This is necessary because .I char may be the equivalent @@ -163,13 +162,13 @@ converting to .IR int , yielding a value that is outside the range of .IR "unsigned char" . -.PP +.P The details of what constitutes an uppercase or lowercase letter depend on the locale. For example, the default -.B """C""" +.B \[dq]C\[dq] locale does not know about umlauts, so no conversion is done for them. -.PP +.P In some non-English locales, there are lowercase letters with no corresponding uppercase equivalent; .\" FIXME One day the statement about "sharp s" needs to be reworked, diff --git a/man3/towctrans.3 b/man3/towctrans.3 index bf507fa..7e30c87 100644 --- a/man3/towctrans.3 +++ b/man3/towctrans.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH towctrans 3 2023-07-20 "Linux man-pages 6.05.01" +.TH towctrans 3 2023-10-31 "Linux man-pages 6.7" .SH NAME towctrans \- wide-character transliteration .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wint_t towctrans(wint_t " wc ", wctrans_t " desc ); .fi .SH DESCRIPTION @@ -35,7 +35,7 @@ is .BR WEOF , .B WEOF is returned. -.PP +.P .I desc must be a transliteration descriptor returned by the @@ -65,7 +65,6 @@ T{ .BR towctrans () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/towlower.3 b/man3/towlower.3 index 9748303..3a5f203 100644 --- a/man3/towlower.3 +++ b/man3/towlower.3 @@ -10,7 +10,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH towlower 3 2023-07-20 "Linux man-pages 6.05.01" +.TH towlower 3 2023-10-31 "Linux man-pages 6.7" .SH NAME towlower, towlower_l \- convert a wide character to lowercase .SH LIBRARY @@ -19,16 +19,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wint_t towlower(wint_t " wc ); .BI "wint_t towlower_l(wint_t " wc ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR towlower_l (): .nf Since glibc 2.10: @@ -51,7 +51,7 @@ it returns the lowercase equivalent of In all other cases, .I wc is returned unchanged. -.PP +.P The .BR towlower_l () function performs the same task, @@ -67,7 +67,7 @@ is the special locale object (see .BR duplocale (3)) or is not a valid locale object handle. -.PP +.P The argument .I wc must be representable as a @@ -101,7 +101,6 @@ T{ .BR towlower_l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR towlower () @@ -122,7 +121,7 @@ POSIX.1-2008. The behavior of these functions depends on the .B LC_CTYPE category of the locale. -.PP +.P These functions are not very appropriate for dealing with Unicode characters, because Unicode knows about three cases: upper, lower, and title case. .SH SEE ALSO diff --git a/man3/towupper.3 b/man3/towupper.3 index 0a9c1dd..fe3d609 100644 --- a/man3/towupper.3 +++ b/man3/towupper.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH towupper 3 2023-07-20 "Linux man-pages 6.05.01" +.TH towupper 3 2023-10-31 "Linux man-pages 6.7" .SH NAME towupper, towupper_l \- convert a wide character to uppercase .SH LIBRARY @@ -18,16 +18,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wint_t towupper(wint_t " wc ); .BI "wint_t towupper_l(wint_t " wc ", locale_t " locale ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR towupper_l (): .nf Since glibc 2.10: @@ -50,7 +50,7 @@ it returns the uppercase equivalent of In all other cases, .I wc is returned unchanged. -.PP +.P The .BR towupper_l () function performs the same task, @@ -66,7 +66,7 @@ is the special locale object (see .BR duplocale (3)) or is not a valid locale object handle. -.PP +.P The argument .I wc must be representable as a @@ -100,7 +100,6 @@ T{ .BR towupper_l () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR towupper () @@ -121,7 +120,7 @@ glibc 2.3. The behavior of these functions depends on the .B LC_CTYPE category of the locale. -.PP +.P These functions are not very appropriate for dealing with Unicode characters, because Unicode knows about three cases: upper, lower, and title case. .SH SEE ALSO diff --git a/man3/trunc.3 b/man3/trunc.3 index 4670f03..1c90c81 100644 --- a/man3/trunc.3 +++ b/man3/trunc.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH trunc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH trunc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME trunc, truncf, truncl \- round to integer, toward zero .SH LIBRARY @@ -12,17 +12,17 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double trunc(double " x ); .BI "float truncf(float " x ); .BI "long double truncl(long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR trunc (), .BR truncf (), .BR truncl (): @@ -36,7 +36,7 @@ to the nearest integer value that is not larger in magnitude than .IR x . .SH RETURN VALUE These functions return the rounded integer value, in floating format. -.PP +.P If .I x is integral, infinite, or NaN, @@ -60,7 +60,6 @@ T{ .BR truncl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/tsearch.3 b/man3/tsearch.3 index ff20302..1343cbe 100644 --- a/man3/tsearch.3 +++ b/man3/tsearch.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tsearch 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tsearch 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tsearch, tfind, tdelete, twalk, twalk_r, tdestroy \- manage a binary search tree .SH LIBRARY @@ -12,9 +12,9 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B typedef enum { preorder, postorder, endorder, leaf } VISIT; -.PP +.P .BI "void *tsearch(const void *" key ", void **" rootp , .BI " int (*" compar ")(const void *, const void *));" .BI "void *tfind(const void *" key ", void *const *" rootp , @@ -24,10 +24,10 @@ Standard C library .BI "void twalk(const void *" root , .BI " void (*" action ")(const void *" nodep ", VISIT " which , .BI " int " depth )); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "void twalk_r(const void *" root , .BI " void (*" action ")(const void *" nodep ", VISIT " which , .BI " void *" closure ), @@ -52,7 +52,7 @@ pointers to two items. It should return an integer which is negative, zero, or positive, depending on whether the first item is less than, equal to, or greater than the second. -.PP +.P .BR tsearch () searches the tree for an item. .I key @@ -74,7 +74,7 @@ If the item is not found, then .BR tsearch () adds it, and returns a pointer to the corresponding tree node. -.PP +.P .BR tfind () is like .BR tsearch (), @@ -82,12 +82,12 @@ except that if the item is not found, then .BR tfind () returns NULL. -.PP +.P .BR tdelete () deletes an item from the tree. Its arguments are the same as for .BR tsearch (). -.PP +.P .BR twalk () performs depth-first, left-to-right traversal of a binary tree. @@ -122,7 +122,7 @@ if this is the single visit to a leaf node. .IR .) The third argument is the depth of the node; the root node has depth zero. -.PP +.P (More commonly, .BR preorder , .BR postorder , @@ -138,7 +138,7 @@ and after visiting the children. Thus, the choice of name .B post\%order is rather confusing.) -.PP +.P .BR twalk_r () is similar to .BR twalk (), @@ -151,7 +151,7 @@ unchanged. This pointer can be used to pass information to and from the callback function in a thread-safe fashion, without resorting to global variables. -.PP +.P .BR tdestroy () removes the whole tree pointed to by .IR root , @@ -176,14 +176,14 @@ returns a pointer to the node, or NULL if no match is found. If there are multiple items that match the key, the item whose node is returned is unspecified. -.PP +.P .BR tdelete () returns a pointer to the parent of the node deleted, or NULL if the item was not found. If the deleted node was the root node, .BR tdelete () returns a dangling pointer that must not be accessed. -.PP +.P .BR tsearch (), .BR tfind (), and @@ -223,7 +223,6 @@ T{ .BR tdestroy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR tsearch () @@ -256,12 +255,12 @@ glibc 2.30. .BR twalk () takes a pointer to the root, while the other functions take a pointer to a variable which points to the root. -.PP +.P .BR tdelete () frees the memory required for the node in the tree. The user is responsible for freeing the memory for the corresponding data. -.PP +.P The example program depends on the fact that .BR twalk () makes no @@ -273,7 +272,7 @@ implementation, but is not in the System V documentation. The following program inserts twelve random numbers into a binary tree, where duplicate numbers are collapsed, then prints the numbers in order. -.PP +.P .\" SRC BEGIN (tsearch.c) .EX #define _GNU_SOURCE /* Expose declaration of tdestroy() */ diff --git a/man3/ttyname.3 b/man3/ttyname.3 index cfdbb22..ca12a14 100644 --- a/man3/ttyname.3 +++ b/man3/ttyname.3 @@ -6,7 +6,7 @@ .\" Modified 2001-12-13, Martin Schulze .\" Added ttyname_r, aeb, 2002-07-20 .\" -.TH ttyname 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ttyname 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ttyname, ttyname_r \- return name of a terminal .SH LIBRARY @@ -15,7 +15,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "char *ttyname(int " fd ); .BI "int ttyname_r(int " fd ", char " buf [. buflen "], size_t " buflen ); .fi @@ -81,7 +81,6 @@ T{ .BR ttyname_r () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/ttyslot.3 b/man3/ttyslot.3 index d50af49..f4eaa7f 100644 --- a/man3/ttyslot.3 +++ b/man3/ttyslot.3 @@ -6,7 +6,7 @@ .\" This replaces an earlier man page written by Walter Harms .\" . .\" -.TH ttyslot 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ttyslot 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ttyslot \- find the slot of the current user's terminal in some file .SH LIBRARY @@ -15,15 +15,15 @@ Standard C library .SH SYNOPSIS .nf .BR "#include " " /* See NOTES */" -.PP +.P .B "int ttyslot(void);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ttyslot (): .nf Since glibc 2.24: @@ -37,7 +37,7 @@ Feature Test Macro Requirements for glibc (see The legacy function .BR ttyslot () returns the index of the current user's entry in some file. -.PP +.P Now "What file?" you ask. Well, let's first look at some history. .SS Ancient history @@ -57,7 +57,7 @@ indicating the sequence of line speeds to try (\[aq]\-\[aq] was: start trying Thus a typical line was "18\-". A hang on some line was solved by changing the \[aq]1\[aq] to a \[aq]0\[aq], signaling init, changing back again, and signaling init again. -.PP +.P In UNIX\ V7 the format was changed: here the second character was the argument to .BR getty (8) @@ -65,7 +65,7 @@ indicating the sequence of line speeds to try (\[aq]0\[aq] was: cycle through 300-1200-150-110 baud; \[aq]4\[aq] was for the on-line console DECwriter) while the rest of the line contained the name of the tty. Thus a typical line was "14console". -.PP +.P Later systems have more elaborate syntax. System V-like systems have .I /etc/inittab @@ -119,7 +119,6 @@ T{ .BR ttyslot () T} Thread safety MT-Unsafe .TE -.sp 1 .SH VERSIONS The utmp file is found in various places on various systems, such as .IR /etc/utmp , @@ -130,7 +129,7 @@ None. .SH HISTORY SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001. SUSv2 requires \-1 on error. -.PP +.P The glibc2 implementation of this function reads the file .BR _PATH_TTYS , defined in @@ -139,7 +138,7 @@ as "/etc/ttys". It returns 0 on error. Since Linux systems do not usually have "/etc/ttys", it will always return 0. -.PP +.P On BSD-like systems and Linux, the declaration of .BR ttyslot () is provided by @@ -150,7 +149,7 @@ Since glibc 2.24, .I also provides the declaration with the following feature test macro definitions: -.PP +.P .in +4n .EX (_XOPEN_SOURCE >= 500 || @@ -158,7 +157,7 @@ feature test macro definitions: && ! (_POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600) .EE .in -.PP +.P Minix also has .IR fttyslot ( fd ). .\" .SH HISTORY diff --git a/man3/tzset.3 b/man3/tzset.3 index 4027bb3..3c97684 100644 --- a/man3/tzset.3 +++ b/man3/tzset.3 @@ -11,7 +11,7 @@ .\" Modified 2001-11-13, aeb .\" Modified 2004-12-01 mtk and Martin Schulze .\" -.TH tzset 3 2023-07-20 "Linux man-pages 6.05.01" +.TH tzset 3 2023-10-31 "Linux man-pages 6.7" .SH NAME tzset, tzname, timezone, daylight \- initialize time conversion information .SH LIBRARY @@ -20,29 +20,29 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B void tzset(void); -.PP +.P .BI "extern char *" tzname [2]; .BI "extern long " timezone ; .BI "extern int " daylight ; .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR tzset (): .nf _POSIX_C_SOURCE .fi -.PP +.P .IR tzname : .nf _POSIX_C_SOURCE .fi -.PP +.P .IR timezone , .IR daylight : .nf @@ -62,7 +62,7 @@ In a System-V-like environment, it will also set the variables \fItimezone\fP (seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not have any daylight saving time rules, or to nonzero if there is a time, past, present, or future when daylight saving time applies). -.PP +.P If the .B TZ variable does not appear in the environment, the system timezone is used. @@ -72,25 +72,25 @@ format to .IR /etc/localtime . A timezone database of these files may be located in the system timezone directory (see the \fBFILES\fP section below). -.PP +.P If the .B TZ variable does appear in the environment, but its value is empty, or its value cannot be interpreted using any of the formats specified below, then Coordinated Universal Time (UTC) is used. -.PP +.P The value of .B TZ can be one of two formats. The first format is a string of characters that directly represent the timezone to be used: -.PP +.P .in +4n .EX .IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]] .EE .in -.PP +.P There are no spaces in the specification. The \fIstd\fP string specifies an abbreviation for the timezone and must be three or more alphabetic characters. @@ -104,18 +104,18 @@ The \fIoffset\fP is positive if the local timezone is west of the Prime Meridian and negative if it is east. The hour must be between 0 and 24, and the minutes and seconds 00 and 59: -.PP +.P .in +4n .EX .RI [ + | \- ] hh [ :mm [ :ss ]] .EE .in -.PP +.P The \fIdst\fP string and \fIoffset\fP specify the name and offset for the corresponding daylight saving timezone. If the offset is omitted, it defaults to one hour ahead of standard time. -.PP +.P The \fIstart\fP field specifies when daylight saving time goes into effect and the \fIend\fP field specifies when the change is made back to standard time. @@ -138,32 +138,32 @@ Week 1 is the first week in which day \fId\fP occurs and week 5 is the last week in which day \fId\fP occurs. Day 0 is a Sunday. -.PP +.P The \fItime\fP fields specify when, in the local time currently in effect, the change to the other time occurs. If omitted, the default is 02:00:00. -.PP +.P Here is an example for New Zealand, where the standard time (NZST) is 12 hours ahead of UTC, and daylight saving time (NZDT), 13 hours ahead of UTC, runs from the first Sunday in October to the third Sunday in March, and the changeovers happen at the default time of 02:00:00: -.PP +.P .in +4n .EX TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0" .EE .in -.PP +.P The second format specifies that the timezone information should be read from a file: -.PP +.P .in +4n .EX :[filespec] .EE .in -.PP +.P If the file specification \fIfilespec\fP is omitted, or its value cannot be interpreted, then Coordinated Universal Time (UTC) is used. If \fIfilespec\fP is given, it specifies another @@ -173,9 +173,9 @@ If \fIfilespec\fP does not begin with a \[aq]/\[aq], the file specification is relative to the system timezone directory. If the colon is omitted each of the above \fBTZ\fP formats will be tried. -.PP +.P Here's an example, once more for New Zealand: -.PP +.P .in +4n .EX TZ=":Pacific/Auckland" @@ -206,7 +206,7 @@ It is in the format. By default, the zoneinfo Makefile hard links it to the .IR America/New_York " tzfile." -.PP +.P Above are the current standard file locations, but they are configurable when glibc is compiled. .SH ATTRIBUTES @@ -223,12 +223,11 @@ T{ .BR tzset () T} Thread safety MT-Safe env locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4, 4.3BSD. -.PP +.P 4.3BSD had a function .BI "char *timezone(" zone ", " dst ) that returned the diff --git a/man3/ualarm.3 b/man3/ualarm.3 index 55ca2d7..0d4275c 100644 --- a/man3/ualarm.3 +++ b/man3/ualarm.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ualarm 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ualarm 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ualarm \- schedule signal after given number of microseconds .SH LIBRARY @@ -12,15 +12,15 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "useconds_t ualarm(useconds_t " usecs ", useconds_t " interval ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR ualarm (): .nf Since glibc 2.12: @@ -42,11 +42,11 @@ microseconds. The delay may be lengthened slightly by any system activity or by the time spent processing the call or by the granularity of system timers. -.PP +.P Unless caught or ignored, the .B SIGALRM signal will terminate the process. -.PP +.P If the .I interval argument is nonzero, further @@ -80,23 +80,22 @@ T{ .BR ualarm () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY 4.3BSD, POSIX.1-2001. POSIX.1-2001 marks it as obsolete. Removed in POSIX.1-2008. -.PP +.P 4.3BSD, SUSv2, and POSIX do not define any errors. -.PP +.P POSIX.1-2001 does not specify what happens if the .I usecs argument is 0. .\" This case is not documented in HP-US, Solar, FreeBSD, NetBSD, or OpenBSD! On Linux (and probably most other systems), the effect is to cancel any pending alarm. -.PP +.P The type .I useconds_t is an unsigned integer type capable of holding integers @@ -109,7 +108,7 @@ were instead typed as Programs will be more portable if they never mention .I useconds_t explicitly. -.PP +.P The interaction of this function with other timer functions such as .BR alarm (2), @@ -123,7 +122,7 @@ other timer functions such as .BR timer_settime (2), .BR usleep (3) is unspecified. -.PP +.P This function is obsolete. Use .BR setitimer (2) diff --git a/man3/ulimit.3 b/man3/ulimit.3 index 8cd8f6d..f003482 100644 --- a/man3/ulimit.3 +++ b/man3/ulimit.3 @@ -5,7 +5,7 @@ .\" .\" Moved to man3, aeb, 980612 .\" -.TH ulimit 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ulimit 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ulimit \- get and set user limits .SH LIBRARY @@ -14,7 +14,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "[[deprecated]] long ulimit(int " cmd ", long " newlimit ); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ For the shell command .BR ulimit , see .BR bash (1). -.PP +.P The .BR ulimit () call will get or set some limit for the calling process. @@ -75,7 +75,6 @@ T{ .BR ulimit () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/undocumented.3 b/man3/undocumented.3 index 8ee3484..b67b9f0 100644 --- a/man3/undocumented.3 +++ b/man3/undocumented.3 @@ -7,7 +7,7 @@ .\" 2004-10-31, aeb, changed maintainer address, updated list .\" 2015-04-20, william@tuffbizz.com, updated list .\" -.TH undocumented 3 2022-10-30 "Linux man-pages 6.05.01" +.TH undocumented 3 2022-10-30 "Linux man-pages 6.7" .SH NAME undocumented \- undocumented library functions .SH SYNOPSIS diff --git a/man3/ungetwc.3 b/man3/ungetwc.3 index 04d5563..2b16322 100644 --- a/man3/ungetwc.3 +++ b/man3/ungetwc.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH ungetwc 3 2023-07-20 "Linux man-pages 6.05.01" +.TH ungetwc 3 2023-10-31 "Linux man-pages 6.7" .SH NAME ungetwc \- push back a wide character onto a FILE stream .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wint_t ungetwc(wint_t " wc ", FILE *" stream ); .fi .SH DESCRIPTION @@ -30,7 +30,7 @@ function. It pushes back a wide character onto .I stream and returns it. -.PP +.P If .I wc is @@ -46,7 +46,7 @@ to .B EILSEQ and returns .BR WEOF . -.PP +.P If .I wc is a valid wide character, it is pushed back onto the stream @@ -55,12 +55,12 @@ The file-position indicator is decremented by one or more. The end-of-file indicator is cleared. The backing storage of the file is not affected. -.PP +.P Note: .I wc need not be the last wide-character read from the stream; it can be any other valid wide character. -.PP +.P If the implementation supports multiple push-back operations in a row, the pushed-back wide characters will be read in reverse order; however, only one level of push-back is guaranteed. @@ -87,7 +87,6 @@ T{ .BR ungetwc () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/unlocked_stdio.3 b/man3/unlocked_stdio.3 index a74e6b2..627bfbc 100644 --- a/man3/unlocked_stdio.3 +++ b/man3/unlocked_stdio.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH unlocked_stdio 3 2023-07-30 "Linux man-pages 6.05.01" +.TH unlocked_stdio 3 2023-10-31 "Linux man-pages 6.7" .SH NAME getc_unlocked, getchar_unlocked, putc_unlocked, putchar_unlocked \- nonlocking stdio functions @@ -13,53 +13,53 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int getc_unlocked(FILE *" stream ); .B "int getchar_unlocked(void);" .BI "int putc_unlocked(int " c ", FILE *" stream ); .BI "int putchar_unlocked(int " c ); -.PP +.P .BI "void clearerr_unlocked(FILE *" stream ); .BI "int feof_unlocked(FILE *" stream ); .BI "int ferror_unlocked(FILE *" stream ); .BI "int fileno_unlocked(FILE *" stream ); .BI "int fflush_unlocked(FILE *_Nullable " stream ); -.PP +.P .BI "int fgetc_unlocked(FILE *" stream ); .BI "int fputc_unlocked(int " c ", FILE *" stream ); -.PP +.P .BI "size_t fread_unlocked(void " ptr "[restrict ." size " * ." n ], .BI " size_t " size ", size_t " n , .BI " FILE *restrict " stream ); .BI "size_t fwrite_unlocked(const void " ptr "[restrict ." size " * ." n ], .BI " size_t " size ", size_t " n , .BI " FILE *restrict " stream ); -.PP +.P .BI "char *fgets_unlocked(char " s "[restrict ." n "], int " n \ ", FILE *restrict " stream ); .BI "int fputs_unlocked(const char *restrict " s ", FILE *restrict " stream ); -.PP +.P .B #include -.PP +.P .BI "wint_t getwc_unlocked(FILE *" stream ); .B "wint_t getwchar_unlocked(void);" .BI "wint_t fgetwc_unlocked(FILE *" stream ); -.PP +.P .BI "wint_t fputwc_unlocked(wchar_t " wc ", FILE *" stream ); .BI "wint_t putwc_unlocked(wchar_t " wc ", FILE *" stream ); .BI "wint_t putwchar_unlocked(wchar_t " wc ); -.PP +.P .BI "wchar_t *fgetws_unlocked(wchar_t " ws "[restrict ." n "], int " n , .BI " FILE *restrict " stream ); .BI "int fputws_unlocked(const wchar_t *restrict " ws , .BI " FILE *restrict " stream ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR \%getc_unlocked (), .BR \%getchar_unlocked (), .BR \%putc_unlocked (), @@ -69,7 +69,7 @@ Feature Test Macro Requirements for glibc (see || /* glibc <= 2.23: */ _POSIX_C_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P .BR \%clearerr_unlocked (), .BR \%feof_unlocked (), .BR \%ferror_unlocked (), @@ -83,7 +83,7 @@ Feature Test Macro Requirements for glibc (see /* glibc >= 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P .BR \%fgets_unlocked (), .BR \%fputs_unlocked (), .BR \%getwc_unlocked (), @@ -163,7 +163,6 @@ T{ .BR fileno_unlocked () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR getc_unlocked () diff --git a/man3/unlockpt.3 b/man3/unlockpt.3 index 1ed2ad9..8760870 100644 --- a/man3/unlockpt.3 +++ b/man3/unlockpt.3 @@ -3,7 +3,7 @@ .\" This page is in the public domain. - aeb .\" %%%LICENSE_END .\" -.TH unlockpt 3 2023-07-20 "Linux man-pages 6.05.01" +.TH unlockpt 3 2023-10-31 "Linux man-pages 6.7" .SH NAME unlockpt \- unlock a pseudoterminal master/slave pair .SH LIBRARY @@ -13,15 +13,15 @@ Standard C library .nf .B #define _XOPEN_SOURCE .B #include -.PP +.P .BI "int unlockpt(int " fd ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR unlockpt (): .nf Since glibc 2.24: @@ -36,7 +36,7 @@ The function unlocks the slave pseudoterminal device corresponding to the master pseudoterminal referred to by the file descriptor .IR fd . -.PP +.P .BR unlockpt () should be called before opening the slave side of a pseudoterminal. .SH RETURN VALUE @@ -71,7 +71,6 @@ T{ .BR unlockpt () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/updwtmp.3 b/man3/updwtmp.3 index 99113e8..6548393 100644 --- a/man3/updwtmp.3 +++ b/man3/updwtmp.3 @@ -8,7 +8,7 @@ .\" Added -lutil remark, 030718 .\" 2008-07-02, mtk, document updwtmpx() .\" -.TH updwtmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH updwtmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME updwtmp, logwtmp \- append an entry to the wtmp file .SH LIBRARY @@ -17,7 +17,7 @@ System utilities library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "void updwtmp(const char *" wtmp_file ", const struct utmp *" ut ); .BI "void logwtmp(const char *" line ", const char *" name \ ", const char *" host ); @@ -27,7 +27,7 @@ System utilities library appends the utmp structure .I ut to the wtmp file. -.PP +.P .BR logwtmp () constructs a utmp structure using .IR line ", " name ", " host , @@ -54,12 +54,11 @@ T{ .BR logwtmp () T} Thread safety MT-Unsafe sig:ALRM timer .TE -.sp 1 .SH VERSIONS For consistency with the other "utmpx" functions (see .BR getutxent (3)), glibc provides (since glibc 2.1): -.PP +.P .in +4n .EX .BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" @@ -67,7 +66,7 @@ glibc provides (since glibc 2.1): .BI "void updwtmpx (const char *" wtmpx_file ", const struct utmpx *" utx ); .EE .in -.PP +.P This function performs the same task as .BR updwtmp (), but differs in that it takes a diff --git a/man3/uselocale.3 b/man3/uselocale.3 index 19995c3..6e97649 100644 --- a/man3/uselocale.3 +++ b/man3/uselocale.3 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH uselocale 3 2023-03-30 "Linux man-pages 6.05.01" +.TH uselocale 3 2023-10-31 "Linux man-pages 6.7" .SH NAME uselocale \- set/get the locale for the calling thread .SH LIBRARY @@ -11,15 +11,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "locale_t uselocale(locale_t " newloc ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR uselocale (): .nf Since glibc 2.10: @@ -37,7 +37,7 @@ After a successful call to any calls by this thread to functions that depend on the locale will operate as though the locale has been set to .IR newloc . -.PP +.P The .I newloc argument can have one of the following values: diff --git a/man3/usleep.3 b/man3/usleep.3 index a05472d..cb3ee05 100644 --- a/man3/usleep.3 +++ b/man3/usleep.3 @@ -11,7 +11,7 @@ .\" Modified 2001-04-01 by aeb .\" Modified 2003-07-23 by aeb .\" -.TH usleep 3 2023-07-20 "Linux man-pages 6.05.01" +.TH usleep 3 2023-10-31 "Linux man-pages 6.7" .SH NAME usleep \- suspend execution for microsecond intervals .SH LIBRARY @@ -20,15 +20,15 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int usleep(useconds_t " usec ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR usleep (): .nf Since glibc 2.12: @@ -77,7 +77,6 @@ T{ .BR usleep () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS None. .SH HISTORY @@ -86,14 +85,14 @@ POSIX.1-2001 declares it obsolete, suggesting .BR nanosleep (2) instead. Removed in POSIX.1-2008. -.PP +.P On the original BSD implementation, and before glibc 2.2.2, the return type of this function is .IR void . The POSIX version returns .IR int , and this is also the prototype used since glibc 2.2.2. -.PP +.P Only the .B EINVAL error return is documented by SUSv2 and POSIX.1-2001. diff --git a/man3/ustpcpy.3 b/man3/ustpcpy.3 deleted file mode 100644 index beb8507..0000000 --- a/man3/ustpcpy.3 +++ /dev/null @@ -1 +0,0 @@ -.so man7/string_copying.7 diff --git a/man3/ustr2stp.3 b/man3/ustr2stp.3 deleted file mode 100644 index beb8507..0000000 --- a/man3/ustr2stp.3 +++ /dev/null @@ -1 +0,0 @@ -.so man7/string_copying.7 diff --git a/man3/wcpcpy.3 b/man3/wcpcpy.3 index dfdc079..ea83da8 100644 --- a/man3/wcpcpy.3 +++ b/man3/wcpcpy.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcpcpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcpcpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcpcpy \- copy a wide-character string, returning a pointer to its end .SH LIBRARY @@ -17,16 +17,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcpcpy(wchar_t *restrict " dest \ ", const wchar_t *restrict " src ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcpcpy (): .nf Since glibc 2.10: @@ -45,9 +45,9 @@ It copies the wide-character string pointed to by including the terminating null wide character (L\[aq]\e0\[aq]), to the array pointed to by .IR dest . -.PP +.P The strings may not overlap. -.PP +.P The programmer must ensure that there is room for at least .I wcslen(src)+1 @@ -72,7 +72,6 @@ T{ .BR wcpcpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH SEE ALSO diff --git a/man3/wcpncpy.3 b/man3/wcpncpy.3 index 40538d0..dcb3911 100644 --- a/man3/wcpncpy.3 +++ b/man3/wcpncpy.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcpncpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcpncpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcpncpy \- copy a fixed-size string of wide characters, returning a pointer to its end @@ -18,17 +18,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcpncpy(wchar_t " dest "[restrict ." n ], .BI " const wchar_t " src "[restrict ." n ], .BI " size_t " n ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcpncpy (): .nf Since glibc 2.10: @@ -73,9 +73,9 @@ the string pointed to by .I dest will not be L\[aq]\e0\[aq] terminated. -.PP +.P The strings may not overlap. -.PP +.P The programmer must ensure that there is room for at least .I n wide @@ -99,7 +99,6 @@ T{ .BR wcpncpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH SEE ALSO diff --git a/man3/wcrtomb.3 b/man3/wcrtomb.3 index 2732832..9957bd0 100644 --- a/man3/wcrtomb.3 +++ b/man3/wcrtomb.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcrtomb 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcrtomb 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcrtomb \- convert a wide character to a multibyte sequence .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcrtomb(char *restrict " s ", wchar_t " wc \ ", mbstate_t *restrict " ps ); .fi @@ -45,7 +45,7 @@ returns the length of said multibyte representation, that is, the number of bytes written at .IR s . -.PP +.P A different case is when .I s is not NULL, @@ -69,7 +69,7 @@ it into the initial state), and returns the length of the shift sequence plus one, that is, the number of bytes written at .IR s . -.PP +.P A third case is when .I s is NULL. @@ -77,17 +77,17 @@ In this case, .I wc is ignored, and the function effectively returns -.PP +.P .in +4n .EX wcrtomb(buf, L\[aq]\e0\[aq], ps) .EE .in -.PP +.P where .I buf is an internal anonymous buffer. -.PP +.P In all of the above cases, if .I ps is NULL, a static anonymous @@ -124,7 +124,6 @@ T{ .BR wcrtomb () T} Thread safety MT-Unsafe race:wcrtomb/!ps .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -136,7 +135,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P Passing NULL as .I ps is not multithread safe. diff --git a/man3/wcscasecmp.3 b/man3/wcscasecmp.3 index 252228c..121fa45 100644 --- a/man3/wcscasecmp.3 +++ b/man3/wcscasecmp.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcscasecmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcscasecmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcscasecmp \- compare two wide-character strings, ignoring case .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wcscasecmp(const wchar_t *" s1 ", const wchar_t *" s2 ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcscasecmp (): .nf Since glibc 2.10: @@ -83,7 +83,6 @@ T{ .BR wcscasecmp () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/wcscat.3 b/man3/wcscat.3 index 6f3e539..36c8fc9 100644 --- a/man3/wcscat.3 +++ b/man3/wcscat.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcscat 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcscat 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcscat \- concatenate two wide-character strings .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcscat(wchar_t *restrict " dest \ ", const wchar_t *restrict " src ); .fi @@ -34,9 +34,9 @@ It copies the wide-character string pointed to by including the terminating null wide character (L\[aq]\e0\[aq]), to the end of the wide-character string pointed to by .IR dest . -.PP +.P The strings may not overlap. -.PP +.P The programmer must ensure that there is room for at least .IR wcslen(dest) + wcslen(src) +1 wide characters at @@ -59,7 +59,6 @@ T{ .BR wcscat () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcschr.3 b/man3/wcschr.3 index e4c1d76..e8f017e 100644 --- a/man3/wcschr.3 +++ b/man3/wcschr.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcschr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcschr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcschr \- search a wide character in a wide-character string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcschr(const wchar_t *" wcs ", wchar_t " wc ); .fi .SH DESCRIPTION @@ -57,7 +57,6 @@ T{ .BR wcschr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcscmp.3 b/man3/wcscmp.3 index 264bb09..04d1eb5 100644 --- a/man3/wcscmp.3 +++ b/man3/wcscmp.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcscmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcscmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcscmp \- compare two wide-character strings .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wcscmp(const wchar_t *" s1 ", const wchar_t *" s2 ); .fi .SH DESCRIPTION @@ -69,7 +69,6 @@ T{ .BR wcscmp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcscpy.3 b/man3/wcscpy.3 index 76882b5..cdb33a0 100644 --- a/man3/wcscpy.3 +++ b/man3/wcscpy.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcscpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcscpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcscpy \- copy a wide-character string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcscpy(wchar_t *restrict " dest \ ", const wchar_t *restrict " src ); .fi @@ -34,9 +34,9 @@ It copies the wide-character string pointed to by including the terminating null wide character (L\[aq]\e0\[aq]), to the array pointed to by .IR dest . -.PP +.P The strings may not overlap. -.PP +.P The programmer must ensure that there is room for at least .I wcslen(src)+1 @@ -60,7 +60,6 @@ T{ .BR wcscpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcscspn.3 b/man3/wcscspn.3 index 20fe000..d427a4c 100644 --- a/man3/wcscspn.3 +++ b/man3/wcscspn.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcscspn 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcscspn 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcscspn \- search a wide-character string for any of a set of wide characters .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcscspn(const wchar_t *" wcs ", const wchar_t *" reject ); .fi .SH DESCRIPTION @@ -71,7 +71,6 @@ T{ .BR wcscspn () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsdup.3 b/man3/wcsdup.3 index 8e7c71b..58dc92c 100644 --- a/man3/wcsdup.3 +++ b/man3/wcsdup.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcsdup 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsdup 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsdup \- duplicate a wide-character string .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcsdup(const wchar_t *" s ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcsdup (): .nf Since glibc 2.10: @@ -43,7 +43,7 @@ function. It allocates and returns a new wide-character string whose initial contents is a duplicate of the wide-character string pointed to by .IR s . -.PP +.P Memory for the new wide-character string is obtained with .BR malloc (3), @@ -74,7 +74,6 @@ T{ .BR wcsdup () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/wcslen.3 b/man3/wcslen.3 index e716484..223c274 100644 --- a/man3/wcslen.3 +++ b/man3/wcslen.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcslen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcslen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcslen \- determine the length of a wide-character string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcslen(const wchar_t *" s ); .fi .SH DESCRIPTION @@ -52,7 +52,6 @@ T{ .BR wcslen () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsncasecmp.3 b/man3/wcsncasecmp.3 index ad233b4..b4d0ea6 100644 --- a/man3/wcsncasecmp.3 +++ b/man3/wcsncasecmp.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcsncasecmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsncasecmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsncasecmp \- compare two fixed-size wide-character strings, ignoring case .SH LIBRARY @@ -17,16 +17,16 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wcsncasecmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], s\ ize_t " n ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcsncasecmp (): .nf Since glibc 2.10: @@ -89,7 +89,6 @@ T{ .BR wcsncasecmp () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsncat.3 b/man3/wcsncat.3 index 73ff7e8..131b8b6 100644 --- a/man3/wcsncat.3 +++ b/man3/wcsncat.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsncat 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsncat 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsncat \- concatenate two wide-character strings .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcsncat(wchar_t " dest "[restrict ." n ], .BI " const wchar_t " src "[restrict ." n ], .BI " size_t " n ); @@ -38,9 +38,9 @@ to the end of the wide-character string pointed to by .IR dest , and adds a terminating null wide character (L\[aq]\e0\[aq]). -.PP +.P The strings may not overlap. -.PP +.P The programmer must ensure that there is room for at least .IR wcslen(dest) + n +1 wide characters at @@ -63,7 +63,6 @@ T{ .BR wcsncat () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsncmp.3 b/man3/wcsncmp.3 index 8e53bf2..bbf490d 100644 --- a/man3/wcsncmp.3 +++ b/man3/wcsncmp.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsncmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsncmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsncmp \- compare two fixed-size wide-character strings .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wcsncmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \ size_t " n ); .fi @@ -84,7 +84,6 @@ T{ .BR wcsncmp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsncpy.3 b/man3/wcsncpy.3 index ee04677..82bdbef 100644 --- a/man3/wcsncpy.3 +++ b/man3/wcsncpy.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsncpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsncpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsncpy \- copy a fixed-size string of wide characters .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcsncpy(wchar_t " dest "[restrict ." n ], .BI " const wchar_t " src "[restrict ." n ], .BI " size_t " n ); @@ -55,9 +55,9 @@ to the string pointed to by .I dest will not be terminated by a null wide character. -.PP +.P The strings may not overlap. -.PP +.P The programmer must ensure that there is room for at least .I n wide @@ -81,7 +81,6 @@ T{ .BR wcsncpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsnlen.3 b/man3/wcsnlen.3 index 8e2426d..3f846e4 100644 --- a/man3/wcsnlen.3 +++ b/man3/wcsnlen.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcsnlen 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsnlen 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsnlen \- determine the length of a fixed-size wide-character string .SH LIBRARY @@ -17,15 +17,15 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcsnlen(const wchar_t " s [. maxlen "], size_t " maxlen ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcsnlen (): .nf Since glibc 2.10: @@ -82,7 +82,6 @@ T{ .BR wcsnlen () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsnrtombs.3 b/man3/wcsnrtombs.3 index 21ad0fa..787d56f 100644 --- a/man3/wcsnrtombs.3 +++ b/man3/wcsnrtombs.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcsnrtombs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsnrtombs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsnrtombs \- convert a wide-character string to a multibyte string .SH LIBRARY @@ -17,18 +17,18 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcsnrtombs(char " dest "[restrict ." len "], \ const wchar_t **restrict " src , .BI " size_t " nwc ", size_t " len ", \ mbstate_t *restrict " ps ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wcsnrtombs (): .nf Since glibc 2.10: @@ -47,7 +47,7 @@ starting at .IR *src , is limited to .IR nwc . -.PP +.P If .I dest is not NULL, @@ -115,7 +115,7 @@ of bytes written to .IR dest , excluding the terminating null byte (\[aq]\e0\[aq]), is returned. -.PP +.P If .I dest is NULL, @@ -124,7 +124,7 @@ is ignored, and the conversion proceeds as above, except that the converted bytes are not written out to memory, and that no destination length limit exists. -.PP +.P In both of the above cases, if .I ps @@ -132,7 +132,7 @@ is NULL, a static anonymous state known only to the .BR wcsnrtombs () function is used instead. -.PP +.P The programmer must ensure that there is room for at least .I len bytes @@ -170,7 +170,6 @@ T} Thread safety T{ MT-Unsafe race:wcsnrtombs/!ps T} .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH NOTES @@ -180,7 +179,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P Passing NULL as .I ps is not multithread safe. diff --git a/man3/wcspbrk.3 b/man3/wcspbrk.3 index 539d881..ec76fd6 100644 --- a/man3/wcspbrk.3 +++ b/man3/wcspbrk.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcspbrk 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcspbrk 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcspbrk \- search a wide-character string for any of a set of wide characters .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcspbrk(const wchar_t *" wcs ", const wchar_t *" accept ); .fi .SH DESCRIPTION @@ -59,7 +59,6 @@ T{ .BR wcspbrk () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsrchr.3 b/man3/wcsrchr.3 index beae570..59b2476 100644 --- a/man3/wcsrchr.3 +++ b/man3/wcsrchr.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsrchr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsrchr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsrchr \- search a wide character in a wide-character string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcsrchr(const wchar_t *" wcs ", wchar_t " wc ); .fi .SH DESCRIPTION @@ -57,7 +57,6 @@ T{ .BR wcsrchr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsrtombs.3 b/man3/wcsrtombs.3 index 99304e4..49a581f 100644 --- a/man3/wcsrtombs.3 +++ b/man3/wcsrtombs.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsrtombs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsrtombs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsrtombs \- convert a wide-character string to a multibyte string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcsrtombs(char " dest "[restrict ." len "], \ const wchar_t **restrict " src , .BI " size_t " len ", mbstate_t *restrict " ps ); @@ -86,7 +86,7 @@ of bytes written to .IR dest , excluding the terminating null byte (\[aq]\e0\[aq]), is returned. -.PP +.P If .I dest is NULL, @@ -95,7 +95,7 @@ is ignored, and the conversion proceeds as above, except that the converted bytes are not written out to memory, and that no length limit exists. -.PP +.P In both of the above cases, if .I ps @@ -103,7 +103,7 @@ is NULL, a static anonymous state known only to the .BR wcsrtombs () function is used instead. -.PP +.P The programmer must ensure that there is room for at least .I len bytes @@ -141,7 +141,6 @@ T} Thread safety T{ MT-Unsafe race:wcsrtombs/!ps T} .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -153,7 +152,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P Passing NULL as .I ps is not multithread safe. diff --git a/man3/wcsspn.3 b/man3/wcsspn.3 index aa9e265..b7b571a 100644 --- a/man3/wcsspn.3 +++ b/man3/wcsspn.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsspn 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsspn 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsspn \- get length of a prefix wide-character substring .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcsspn(const wchar_t *" wcs ", const wchar_t *" accept ); .fi .SH DESCRIPTION @@ -69,7 +69,6 @@ T{ .BR wcsspn () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcsstr.3 b/man3/wcsstr.3 index 75b3d3b..ae3746a 100644 --- a/man3/wcsstr.3 +++ b/man3/wcsstr.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcsstr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcsstr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcsstr \- locate a substring in a wide-character string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcsstr(const wchar_t *" haystack ", const wchar_t *" needle ); .fi .SH DESCRIPTION @@ -44,7 +44,7 @@ It returns NULL if does not occur as a substring in .IR haystack . -.PP +.P Note the special case: If .I needle @@ -66,7 +66,6 @@ T{ .BR wcsstr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcstoimax.3 b/man3/wcstoimax.3 index e3e5ed1..82dea8e 100644 --- a/man3/wcstoimax.3 +++ b/man3/wcstoimax.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH wcstoimax 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcstoimax 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcstoimax, wcstoumax \- convert wide-character string to integer .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "intmax_t wcstoimax(const wchar_t *restrict " nptr , .BI " wchar_t **restrict " endptr ", int " base ); .BI "uintmax_t wcstoumax(const wchar_t *restrict " nptr , @@ -44,7 +44,6 @@ T{ .BR wcstoumax () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcstok.3 b/man3/wcstok.3 index b63789c..26f18db 100644 --- a/man3/wcstok.3 +++ b/man3/wcstok.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcstok 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcstok 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcstok \- split wide-character string into tokens .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wcstok(wchar_t *restrict " wcs \ ", const wchar_t *restrict " delim , .BI " wchar_t **restrict " ptr ); @@ -36,7 +36,7 @@ to split a wide-character string into tokens, where a token is defined as a substring not containing any wide-characters from .IR delim . -.PP +.P The search starts at .IR wcs , if @@ -90,7 +90,6 @@ T{ .BR wcstok () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -102,7 +101,7 @@ wide-character string is destructively modified during the operation. .SH EXAMPLES The following code loops over the tokens contained in a wide-character string. -.PP +.P .EX wchar_t *wcs = ...; wchar_t *token; diff --git a/man3/wcstombs.3 b/man3/wcstombs.3 index a813615..85a6ae2 100644 --- a/man3/wcstombs.3 +++ b/man3/wcstombs.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wcstombs 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcstombs 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcstombs \- convert a wide-character string to a multibyte string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "size_t wcstombs(char " dest "[restrict ." n "], \ const wchar_t *restrict " src , .BI " size_t " n ); @@ -59,13 +59,13 @@ In this case, the conversion ends in the initial shift state. The number of bytes written to .IR dest , excluding the terminating null byte (\[aq]\e0\[aq]), is returned. -.PP +.P The programmer must ensure that there is room for at least .I n bytes at .IR dest . -.PP +.P If .I dest is NULL, @@ -73,7 +73,7 @@ is NULL, is ignored, and the conversion proceeds as above, except that the converted bytes are not written out to memory, and no length limit exists. -.PP +.P In order to avoid the case 2 above, the programmer should make sure .I n is greater than or equal to @@ -102,7 +102,6 @@ T{ .BR wcstombs () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS The function .BR wcsrtombs (3) diff --git a/man3/wcswidth.3 b/man3/wcswidth.3 index a85254a..2f5c148 100644 --- a/man3/wcswidth.3 +++ b/man3/wcswidth.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcswidth 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcswidth 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcswidth \- determine columns needed for a fixed-size wide-character string .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int wcswidth(const wchar_t *" s ", size_t " n ); .fi .SH DESCRIPTION @@ -57,7 +57,6 @@ T{ .BR wcswidth () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY diff --git a/man3/wctob.3 b/man3/wctob.3 index c8a669d..ff38a40 100644 --- a/man3/wctob.3 +++ b/man3/wctob.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wctob 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wctob 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wctob \- try to represent a wide character as a single byte .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wctob(wint_t " c ); .fi .SH DESCRIPTION @@ -32,7 +32,7 @@ starting in the initial state, consists of a single byte. If so, it is returned as an .IR "unsigned char" . -.PP +.P Never use this function. It cannot help you in writing internationalized programs. @@ -60,7 +60,6 @@ T{ .BR wctob () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -72,7 +71,7 @@ depends on the .B LC_CTYPE category of the current locale. -.PP +.P This function should never be used. Internationalized programs must never distinguish single-byte and multibyte characters. diff --git a/man3/wctomb.3 b/man3/wctomb.3 index 70ddb28..9606dc8 100644 --- a/man3/wctomb.3 +++ b/man3/wctomb.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wctomb 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wctomb 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wctomb \- convert a wide character to a multibyte sequence .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wctomb(char *" s ", wchar_t " wc ); .fi .SH DESCRIPTION @@ -41,13 +41,13 @@ and returns the length of said multibyte representation, that is, the number of bytes written at .IR s . -.PP +.P The programmer must ensure that there is room for at least .B MB_CUR_MAX bytes at .IR s . -.PP +.P If .I s is NULL, the @@ -73,7 +73,7 @@ If can not be represented as a multibyte sequence (according to the current locale), \-1 is returned. -.PP +.P If .I s is NULL, the @@ -94,7 +94,6 @@ T{ .BR wctomb () T} Thread safety MT-Unsafe race .TE -.sp 1 .SH VERSIONS The function .BR wcrtomb (3) diff --git a/man3/wctrans.3 b/man3/wctrans.3 index ae17629..f7832ee 100644 --- a/man3/wctrans.3 +++ b/man3/wctrans.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wctrans 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wctrans 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wctrans \- wide-character translation mapping .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wctrans_t wctrans(const char *" name ); .fi .SH DESCRIPTION @@ -37,7 +37,7 @@ values can be passed to the .BR towctrans (3) function to actually perform the wide-character mapping. -.PP +.P The .BR wctrans () function returns a mapping, given by its name. @@ -46,7 +46,7 @@ valid names depends on the .B LC_CTYPE category of the current locale, but the following names are valid in all locales. -.PP +.P .nf "tolower" \- realizes the \fBtolower\fP(3) mapping "toupper" \- realizes the \fBtoupper\fP(3) mapping @@ -73,7 +73,6 @@ T{ .BR wctrans () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wctype.3 b/man3/wctype.3 index 21de442..48257b7 100644 --- a/man3/wctype.3 +++ b/man3/wctype.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wctype 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wctype 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wctype \- wide-character classification .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wctype_t wctype(const char *" name ); .fi .SH DESCRIPTION @@ -38,7 +38,7 @@ can be passed to the function to actually test whether a given wide character has the property. -.PP +.P The .BR wctype () function returns a property, given by its name. @@ -47,7 +47,7 @@ valid names depends on the .B LC_CTYPE category of the current locale, but the following names are valid in all locales. -.PP +.P .nf "alnum" \- realizes the \fBisalnum\fP(3) classification function "alpha" \- realizes the \fBisalpha\fP(3) classification function @@ -85,7 +85,6 @@ T{ .BR wctype () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wcwidth.3 b/man3/wcwidth.3 index 127b3ed..6942179 100644 --- a/man3/wcwidth.3 +++ b/man3/wcwidth.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wcwidth 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wcwidth 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wcwidth \- determine columns needed for a wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .nf .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include -.PP +.P .BI "int wcwidth(wchar_t " c ); .fi .SH DESCRIPTION @@ -55,14 +55,13 @@ T{ .BR wcwidth () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Note that before glibc 2.2.5, glibc used the prototype -.PP +.P .nf .BI "int wcwidth(wint_t " c ); .fi diff --git a/man3/wmemchr.3 b/man3/wmemchr.3 index 15cc1cf..059e2c0 100644 --- a/man3/wmemchr.3 +++ b/man3/wmemchr.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wmemchr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wmemchr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wmemchr \- search a wide character in a wide-character array .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wmemchr(const wchar_t " s [. n "], wchar_t " c ", size_t " n ); .fi .SH DESCRIPTION @@ -61,7 +61,6 @@ T{ .BR wmemchr () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wmemcmp.3 b/man3/wmemcmp.3 index ebc9cef..c3d9ebd 100644 --- a/man3/wmemcmp.3 +++ b/man3/wmemcmp.3 @@ -8,7 +8,7 @@ .\" Dinkumware C library reference http://www.dinkumware.com/ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" -.TH wmemcmp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wmemcmp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wmemcmp \- compare two arrays of wide-characters .SH LIBRARY @@ -17,7 +17,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int wmemcmp(const wchar_t " s1 [. n "], const wchar_t " s2 [. n "], \ size_t " n ); .fi @@ -81,7 +81,6 @@ T{ .BR wmemcmp () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wmemcpy.3 b/man3/wmemcpy.3 index 155a3d5..781502e 100644 --- a/man3/wmemcpy.3 +++ b/man3/wmemcpy.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wmemcpy 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wmemcpy 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wmemcpy \- copy an array of wide-characters .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wmemcpy(wchar_t " dest "[restrict ." n ], .BI " const wchar_t " src "[restrict ." n ], .BI " size_t " n ); @@ -35,12 +35,12 @@ wide characters from the array starting at .I src to the array starting at .IR dest . -.PP +.P The arrays may not overlap; use .BR wmemmove (3) to copy between overlapping arrays. -.PP +.P The programmer must ensure that there is room for at least .I n wide @@ -64,7 +64,6 @@ T{ .BR wmemcpy () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wmemmove.3 b/man3/wmemmove.3 index ff518ad..2d01143 100644 --- a/man3/wmemmove.3 +++ b/man3/wmemmove.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wmemmove 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wmemmove 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wmemmove \- copy an array of wide-characters .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wmemmove(wchar_t " dest [. n "], const wchar_t " src [. n "], \ size_t " n ); .fi @@ -37,7 +37,7 @@ to the array starting at .IR dest . The arrays may overlap. -.PP +.P The programmer must ensure that there is room for at least .I n wide @@ -61,7 +61,6 @@ T{ .BR wmemmove () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wmemset.3 b/man3/wmemset.3 index 4ef4cf9..3331d42 100644 --- a/man3/wmemset.3 +++ b/man3/wmemset.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wmemset 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wmemset 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wmemset \- fill an array of wide-characters with a constant wide character .SH LIBRARY @@ -18,7 +18,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "wchar_t *wmemset(wchar_t " wcs [. n "], wchar_t " wc ", size_t " n ); .fi .SH DESCRIPTION @@ -53,7 +53,6 @@ T{ .BR wmemset () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY diff --git a/man3/wordexp.3 b/man3/wordexp.3 index 554c266..b078707 100644 --- a/man3/wordexp.3 +++ b/man3/wordexp.3 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH wordexp 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wordexp 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wordexp, wordfree \- perform word expansion like a posix-shell .SH LIBRARY @@ -12,17 +12,17 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "int wordexp(const char *restrict " s ", wordexp_t *restrict " p \ ", int " flags ); .BI "void wordfree(wordexp_t *" p ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR wordexp (), .BR wordfree (): .nf @@ -62,7 +62,7 @@ is sometimes (depending on see below) used to indicate the number of initial elements in the .I we_wordv array that should be filled with NULLs. -.PP +.P The function .BR wordfree () frees the allocated memory again. @@ -80,7 +80,7 @@ parameters. In particular, there must not be any unescaped newline or |, &, ;, <, >, (, ), {, } characters outside a command substitution or parameter substitution context. -.PP +.P If the argument .I s contains a word that starts with an unquoted comment character #, @@ -93,10 +93,10 @@ variable substitution (replacing $FOO by the value of the environment variable FOO), command substitution (replacing $(command) or \`command\` by the output of command), arithmetic expansion, field splitting, wildcard expansion, quote removal. -.PP +.P The result of expansion of special parameters ($@, $*, $#, $?, $\-, $$, $!, $0) is unspecified. -.PP +.P Field splitting is done using the environment variable $IFS. If it is not set, the field separators are space, tab, and newline. .SS The output array @@ -195,7 +195,7 @@ T{ .BR wordfree () T} Thread safety MT-Safe .TE -.sp 1 +.P In the above table, .I utent in @@ -218,7 +218,7 @@ glibc 2.1. .SH EXAMPLES The output of the following example program is approximately that of "ls [a-c]*.c". -.PP +.P .\" SRC BEGIN (wordexp.c) .EX #include diff --git a/man3/wprintf.3 b/man3/wprintf.3 index 95854a3..4140496 100644 --- a/man3/wprintf.3 +++ b/man3/wprintf.3 @@ -9,7 +9,7 @@ .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html .\" ISO/IEC 9899:1999 .\" -.TH wprintf 3 2023-07-20 "Linux man-pages 6.05.01" +.TH wprintf 3 2023-10-31 "Linux man-pages 6.7" .SH NAME wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted wide-character output conversion @@ -20,25 +20,25 @@ Standard C library .nf .B #include .B #include -.PP +.P .BI "int wprintf(const wchar_t *restrict " format ", ...);" .BI "int fwprintf(FILE *restrict " stream , .BI " const wchar_t *restrict " format ", ...);" .BI "int swprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen , .BI " const wchar_t *restrict " format ", ...);" -.PP +.P .BI "int vwprintf(const wchar_t *restrict " format ", va_list " args ); .BI "int vfwprintf(FILE *restrict " stream , .BI " const wchar_t *restrict " format ", va_list " args ); .BI "int vswprintf(wchar_t " wcs "[restrict ." maxlen "], size_t " maxlen , .BI " const wchar_t *restrict " format ", va_list " args ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P All functions shown above: .\" .BR wprintf (), .\" .BR fwprintf (), @@ -59,7 +59,7 @@ the wide-character equivalent of the family of functions. It performs formatted output of wide characters. -.PP +.P The .BR wprintf () and @@ -71,7 +71,7 @@ perform wide-character output to must not be byte oriented; see .BR fwide (3) for more information. -.PP +.P The .BR fwprintf () and @@ -83,7 +83,7 @@ perform wide-character output to must not be byte oriented; see .BR fwide (3) for more information. -.PP +.P The .BR swprintf () and @@ -97,7 +97,7 @@ room for at least wide characters at .IR wcs . -.PP +.P These functions are like the .BR printf (3), @@ -135,7 +135,7 @@ take a .I maxlen argument, but these functions do not return \-1 upon buffer overflow on Linux.) -.PP +.P The treatment of the conversion characters .B c and @@ -222,7 +222,6 @@ T{ .BR vswprintf () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -235,7 +234,7 @@ on the .B LC_CTYPE category of the current locale. -.PP +.P If the .I format string contains non-ASCII wide characters, the program diff --git a/man3/xcrypt.3 b/man3/xcrypt.3 index 1a60327..320523f 100644 --- a/man3/xcrypt.3 +++ b/man3/xcrypt.3 @@ -9,7 +9,7 @@ .\" 3. xencrypt() a hexstring .\" to bad to be true :( .\" -.TH XCRYPT 3 2023-07-20 "Linux man-pages 6.05.01" +.TH XCRYPT 3 2023-10-31 "Linux man-pages 6.7" .SH NAME xencrypt, xdecrypt, passwd2des \- RFS password encryption .SH LIBRARY @@ -18,9 +18,9 @@ Standard C library .SH SYNOPSIS .nf .B "#include " -.PP +.P .BI "void passwd2des(char " *passwd ", char *" key ");" -.PP +.P .BI "int xencrypt(char *" secret ", char *" passwd ");" .BI "int xdecrypt(char *" secret ", char *" passwd ");" .fi @@ -28,7 +28,7 @@ Standard C library .BR WARNING : Do not use these functions in new code. They do not achieve any type of acceptable cryptographic security guarantees. -.PP +.P The function .BR passwd2des () takes a character string @@ -44,7 +44,7 @@ Both other functions described here use this function to turn their argument .I passwd into a DES key. -.PP +.P The .BR xencrypt () function takes the ASCII character string @@ -61,7 +61,7 @@ and outputs the result again in as a hex string .\" (over the alphabet 0123456789abcdef) of the same length. -.PP +.P The .BR xdecrypt () function performs the converse operation. @@ -87,7 +87,6 @@ T{ .BR xdecrypt () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS These functions are available since glibc 2.1. .SH BUGS diff --git a/man3/xdr.3 b/man3/xdr.3 index a3f9a02..b067348 100644 --- a/man3/xdr.3 +++ b/man3/xdr.3 @@ -9,7 +9,7 @@ .\" .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax .\" -.TH xdr 3 2023-07-20 "Linux man-pages 6.05.01" +.TH xdr 3 2023-10-31 "Linux man-pages 6.7" .SH NAME xdr \- library routines for external data representation .SH LIBRARY @@ -20,24 +20,24 @@ These routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls are transmitted using these routines. -.PP +.P The prototypes below are declared in .I and make use of the following types: -.PP +.P .RS 4 .EX .BI "typedef int " bool_t ; -.PP +.P .BI "typedef bool_t (*" xdrproc_t ")(XDR *, void *,...);" .EE .RE -.PP +.P For the declaration of the .I XDR type, see .IR . -.PP +.P .nf .BI "bool_t xdr_array(XDR *" xdrs ", char **" arrp ", unsigned int *" sizep , .BI " unsigned int " maxsize ", unsigned int " elsize , @@ -63,7 +63,7 @@ is an XDR filter that translates between the array elements' C form, and their external representation. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_bool(XDR *" xdrs ", bool_t *" bp ); .fi @@ -74,7 +74,7 @@ and their external representations. When encoding data, this filter produces values of either one or zero. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_bytes(XDR *" xdrs ", char **" sp ", unsigned int *" sizep , .BI " unsigned int " maxsize ); @@ -91,7 +91,7 @@ string is located at address strings cannot be longer than .IR maxsize . This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_char(XDR *" xdrs ", char *" cp ); .fi @@ -106,7 +106,7 @@ consider .BR xdr_opaque (), or .BR xdr_string (). -.PP +.P .nf .BI "void xdr_destroy(XDR *" xdrs ); .fi @@ -120,7 +120,7 @@ Using after invoking .BR xdr_destroy () is undefined. -.PP +.P .nf .BI "bool_t xdr_double(XDR *" xdrs ", double *" dp ); .fi @@ -129,7 +129,7 @@ A filter primitive that translates between C .I double precision numbers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_enum(XDR *" xdrs ", enum_t *" ep ); .fi @@ -138,7 +138,7 @@ A filter primitive that translates between C .IR enum s (actually integers) and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_float(XDR *" xdrs ", float *" fp ); .fi @@ -147,7 +147,7 @@ A filter primitive that translates between C .IR float s and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "void xdr_free(xdrproc_t " proc ", char *" objp ); .fi @@ -160,7 +160,7 @@ Note: the pointer passed to this routine is freed, but what it points to .I is freed (recursively). -.PP +.P .nf .BI "unsigned int xdr_getpos(XDR *" xdrs ); .fi @@ -173,7 +173,7 @@ which indicates the position of the XDR byte stream. A desirable feature of XDR streams is that simple arithmetic works with this number, although the XDR stream instances need not guarantee this. -.PP +.P .nf .BI "long *xdr_inline(XDR *" xdrs ", int " len ); .fi @@ -193,7 +193,7 @@ may return NULL (0) if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. -.PP +.P .nf .BI "bool_t xdr_int(XDR *" xdrs ", int *" ip ); .fi @@ -201,7 +201,7 @@ it exists for the sake of efficiency. A filter primitive that translates between C integers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_long(XDR *" xdrs ", long *" lp ); .fi @@ -210,7 +210,7 @@ A filter primitive that translates between C .I long integers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "void xdrmem_create(XDR *" xdrs ", char *" addr ", unsigned int " size , .BI " enum xdr_op " op ); @@ -231,7 +231,7 @@ determines the direction of the XDR stream (either .BR XDR_DECODE , or .BR XDR_FREE ). -.PP +.P .nf .BI "bool_t xdr_opaque(XDR *" xdrs ", char *" cp ", unsigned int " cnt ); .fi @@ -244,7 +244,7 @@ is the address of the opaque object, and .I cnt is its size in bytes. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_pointer(XDR *" xdrs ", char **" objpp , .BI " unsigned int " objsize ", xdrproc_t " xdrobj ); @@ -260,7 +260,7 @@ Thus, can represent recursive data structures, such as binary trees or linked lists. -.PP +.P .nf .BI "void xdrrec_create(XDR *" xdrs ", unsigned int " sendsize , .BI " unsigned int " recvsize ", char *" handle , @@ -303,7 +303,7 @@ record boundary information. Also, XDR streams created with different .B xdr*_create APIs are not compatible for the same reason. -.PP +.P .nf .BI "bool_t xdrrec_endofrecord(XDR *" xdrs ", int " sendnow ); .fi @@ -315,7 +315,7 @@ and the output buffer is optionally written out if .I sendnow is nonzero. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdrrec_eof(XDR *" xdrs ); .fi @@ -325,7 +325,7 @@ This routine can be invoked only on streams created by After consuming the rest of the current record in the stream, this routine returns one if the stream has no more input, zero otherwise. -.PP +.P .nf .BI "bool_t xdrrec_skiprecord(XDR *" xdrs ); .fi @@ -336,7 +336,7 @@ streams created by It tells the XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_reference(XDR *" xdrs ", char **" pp ", unsigned int " size , .BI " xdrproc_t " proc ); @@ -361,7 +361,7 @@ Warning: this routine does not understand null pointers. Use .BR xdr_pointer () instead. -.PP +.P .nf .BI "xdr_setpos(XDR *" xdrs ", unsigned int " pos ); .fi @@ -379,7 +379,7 @@ and zero otherwise. Warning: it is difficult to reposition some types of XDR streams, so this routine may fail with one type of stream and succeed with another. -.PP +.P .nf .BI "bool_t xdr_short(XDR *" xdrs ", short *" sp ); .fi @@ -388,7 +388,7 @@ A filter primitive that translates between C .I short integers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "void xdrstdio_create(XDR *" xdrs ", FILE *" file ", enum xdr_op " op ); .fi @@ -413,7 +413,7 @@ on the .I file stream, but never .BR fclose (3). -.PP +.P .nf .BI "bool_t xdr_string(XDR *" xdrs ", char **" sp ", unsigned int " maxsize ); .fi @@ -426,7 +426,7 @@ Note: .I sp is the address of the string's pointer. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_u_char(XDR *" xdrs ", unsigned char *" ucp ); .fi @@ -435,7 +435,7 @@ A filter primitive that translates between .I unsigned C characters and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_u_int(XDR *" xdrs ", unsigned int *" up ); .fi @@ -444,7 +444,7 @@ A filter primitive that translates between C .I unsigned integers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_u_long(XDR *" xdrs ", unsigned long *" ulp ); .fi @@ -453,7 +453,7 @@ A filter primitive that translates between C .I "unsigned long" integers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_u_short(XDR *" xdrs ", unsigned short *" usp ); .fi @@ -462,7 +462,7 @@ A filter primitive that translates between C .I "unsigned short" integers and their external representations. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_union(XDR *" xdrs ", enum_t *" dscmp ", char *" unp , .BI " const struct xdr_discrim *" choices , @@ -501,7 +501,7 @@ array, then the .I defaultarm procedure is called (if it is not NULL). Returns one if it succeeds, zero otherwise. -.PP +.P .nf .BI "bool_t xdr_vector(XDR *" xdrs ", char *" arrp ", unsigned int " size , .BI " unsigned int " elsize ", xdrproc_t " elproc ); @@ -524,7 +524,7 @@ is an XDR filter that translates between the array elements' C form, and their external representation. This routine returns one if it succeeds, zero otherwise. -.PP +.P .nf .B bool_t xdr_void(void); .fi @@ -532,7 +532,7 @@ This routine returns one if it succeeds, zero otherwise. This routine always returns one. It may be passed to RPC routines that require a function argument, where nothing is to be done. -.PP +.P .nf .BI "bool_t xdr_wrapstring(XDR *" xdrs ", char **" sp ); .fi @@ -594,10 +594,9 @@ T{ .BR xdr_wrapstring () T} Thread safety MT-Safe .TE -.sp 1 .SH SEE ALSO .BR rpc (3) -.PP +.P The following manuals: .RS eXternal Data Representation Standard: Protocol Specification diff --git a/man3/y0.3 b/man3/y0.3 index 16c2032..e8cfc91 100644 --- a/man3/y0.3 +++ b/man3/y0.3 @@ -14,7 +14,7 @@ .\" Modified 2004-11-12 as per suggestion by Fabian Kreutz/AEB .\" 2008-07-24, mtk, created this page, based on material from j0.3. .\" -.TH y0 3 2023-07-20 "Linux man-pages 6.05.01" +.TH y0 3 2023-10-31 "Linux man-pages 6.7" .SH NAME y0, y0f, y0l, y1, y1f, y1l, yn, ynf, ynl \- Bessel functions of the second kind @@ -24,25 +24,25 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "double y0(double " x ); .BI "double y1(double " x ); .BI "double yn(int " n ", double " x ); -.PP +.P .BI "float y0f(float " x ); .BI "float y1f(float " x ); .BI "float ynf(int " n ", float " x ); -.PP +.P .BI "long double y0l(long double " x ); .BI "long double y1l(long double " x ); .BI "long double ynl(int " n ", long double " x ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR y0 (), .BR y1 (), .BR yn (): @@ -51,7 +51,7 @@ Feature Test Macro Requirements for glibc (see || /* Since glibc 2.19: */ _DEFAULT_SOURCE || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE .fi -.PP +.P .BR y0f (), .BR y0l (), .BR y1f (), @@ -79,11 +79,11 @@ returns the Bessel function of .I x of the second kind of order .IR n . -.PP +.P The value of .I x must be positive. -.PP +.P The .BR y0f (), .BR y1f (), @@ -104,11 +104,11 @@ values. On success, these functions return the appropriate Bessel value of the second kind for .IR x . -.PP +.P If .I x is a NaN, a NaN is returned. -.PP +.P If .I x is negative, @@ -120,7 +120,7 @@ or .RB \- HUGE_VALL , respectively. (POSIX.1-2001 also allows a NaN return for this case.) -.PP +.P If .I x is 0.0, @@ -131,11 +131,11 @@ and the functions return or .RB \- HUGE_VALL , respectively. -.PP +.P If the result underflows, a range error occurs, and the functions return 0.0 -.PP +.P If the result overflows, a range error occurs, and the functions return @@ -150,7 +150,7 @@ See .BR math_error (7) for information on how to determine whether an error has occurred when calling these functions. -.PP +.P The following errors can occur: .TP Domain error: \fIx\fP is negative @@ -224,7 +224,6 @@ T{ .BR ynl () T} Thread safety MT-Safe .TE -.sp 1 .SH STANDARDS .TP .BR y0 () @@ -260,13 +259,13 @@ instead of and no .B FE_DIVBYZERO exception was raised. -.PP +.P Before glibc 2.17, .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6808 did not set .I errno for "range error: result underflow". -.PP +.P In glibc 2.3.2 and earlier, .\" Actually, 2.3.2 is the earliest test result I have; so yet .\" to confirm if this error occurs only in glibc 2.3.2. diff --git a/man3/zustr2stp.3 b/man3/zustr2stp.3 deleted file mode 100644 index beb8507..0000000 --- a/man3/zustr2stp.3 +++ /dev/null @@ -1 +0,0 @@ -.so man7/string_copying.7 diff --git a/man3/zustr2ustp.3 b/man3/zustr2ustp.3 deleted file mode 100644 index beb8507..0000000 --- a/man3/zustr2ustp.3 +++ /dev/null @@ -1 +0,0 @@ -.so man7/string_copying.7 diff --git a/man3const/EOF.3const b/man3const/EOF.3const index ae64401..5b961a4 100644 --- a/man3const/EOF.3const +++ b/man3const/EOF.3const @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH EOF 3const 2023-02-05 "Linux man-pages 6.05.01" +.TH EOF 3const 2023-10-31 "Linux man-pages 6.7" .SH NAME EOF \- end of file or error indicator .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR "#define EOF " "/* ... */" .fi .SH DESCRIPTION @@ -20,7 +20,7 @@ Standard C library represents the end of an input file, or an error indication. It is a negative value, of type .IR int . -.PP +.P .B EOF is not a character (it can't be represented by diff --git a/man3const/EXIT_SUCCESS.3const b/man3const/EXIT_SUCCESS.3const index b9e4c9a..515305f 100644 --- a/man3const/EXIT_SUCCESS.3const +++ b/man3const/EXIT_SUCCESS.3const @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH EXIT_SUCCESS 3const 2023-05-03 "Linux man-pages 6.05.01" +.TH EXIT_SUCCESS 3const 2023-10-31 "Linux man-pages 6.7" .SH NAME EXIT_SUCCESS, EXIT_FAILURE \- termination status constants .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR "#define EXIT_SUCCESS " 0 .BR "#define EXIT_FAILURE " "/* nonzero */" .fi diff --git a/man3const/NULL.3const b/man3const/NULL.3const index e043c1e..c88bbe0 100644 --- a/man3const/NULL.3const +++ b/man3const/NULL.3const @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH NULL 3const 2023-02-05 "Linux man-pages 6.05.01" +.TH NULL 3const 2023-10-31 "Linux man-pages 6.7" .SH NAME NULL \- null pointer constant .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .B "#define NULL ((void *) 0)" .fi .SH DESCRIPTION @@ -36,12 +36,12 @@ and .SH CAVEATS It is undefined behavior to dereference a null pointer, and that usually causes a segmentation fault in practice. -.PP +.P It is also undefined behavior to perform pointer arithmetic on it. -.PP +.P .I NULL \- NULL is undefined behavior, according to ISO C, but is defined to be 0 in C++. -.PP +.P To avoid confusing human readers of the code, do not compare pointer variables to .BR 0 , @@ -50,7 +50,7 @@ and do not assign to them. Instead, always use .BR NULL . -.PP +.P .B NULL shouldn't be confused with .BR NUL , diff --git a/man3head/printf.h.3head b/man3head/printf.h.3head index 1c6ad32..8f1b9a0 100644 --- a/man3head/printf.h.3head +++ b/man3head/printf.h.3head @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH printf.h 3head 2022-09-18 "Linux man-pages 6.05.01" +.TH printf.h 3head 2024-03-14 "Linux man-pages 6.7" .SH NAME printf.h, \%register_printf_specifier, @@ -33,7 +33,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int register_printf_specifier(int " spec ", printf_function " func , .BI " printf_arginfo_size_function " arginfo ); .BI "int register_printf_modifier(const wchar_t *" str ); @@ -148,7 +148,7 @@ or a custom one, and optionally ORed with an appropriate length modifier .RB ( PA_FLAG_ *). .RS -.PP +.P The type is determined by using one of the following constants: .TP .B PA_INT @@ -188,7 +188,7 @@ For user-defined types, the size of the type (in bytes) should also be specified through this array. Otherwise, leave it unused. .RE -.PP +.P .I arginfo is called before .IR func , @@ -209,7 +209,7 @@ The callback of type .I printf_function should return the number of characters written, or \-1 on error. -.PP +.P The callback of type .I \%printf_arginfo_size_function should return the number of arguments to be parsed by this specifier. @@ -229,16 +229,16 @@ is an older function similar to .BR \%register_printf_specifier (), and is now deprecated. That function can't handle user-defined types. -.PP +.P .BR \%register_printf_specifier () -superseeds +supersedes .BR \%register_printf_function (3). .SH EXAMPLES The following example program registers the 'b' and 'B' specifiers to print integers in binary format, mirroring rules for other unsigned conversion specifiers like 'x' and 'u'. This can be used to print in binary prior to C23. -.PP +.P .\" SRC BEGIN (register_printf_specifier.c) .EX /* This code is in the public domain */ diff --git a/man3head/sysexits.h.3head b/man3head/sysexits.h.3head index a1b8d08..f373234 100644 --- a/man3head/sysexits.h.3head +++ b/man3head/sysexits.h.3head @@ -8,7 +8,7 @@ .\" .\" Rewritten for the Linux man-pages by Alejandro Colomar .\" -.TH sysexits.h 3head 2023-03-30 "Linux man-pages 6.05.01" +.TH sysexits.h 3head 2023-10-31 "Linux man-pages 6.7" .SH NAME sysexits.h \- exit codes for programs .SH LIBRARY @@ -23,11 +23,11 @@ lB2 lB2 l1 lX. #define EX_OK 0 /* T{ successful termination */ T} -.PP +.P #define EX__BASE 64 /* T{ base value for error messages */ T} -.PP +.P #define EX_USAGE 64 /* T{ command line usage error */ T} @@ -73,7 +73,7 @@ T} #define EX_CONFIG 78 /* T{ configuration error */ T} -.PP +.P .T& lB2 l2 l1 lX. #define EX__MAX ... /* T{ @@ -82,7 +82,7 @@ T} .TE .SH DESCRIPTION A few programs exit with the following error codes. -.PP +.P The successful exit is always indicated by a status of .BR 0 , or @@ -181,7 +181,7 @@ but rather for higher level permissions. .TP .B EX_CONFIG Something was found in an unconfigured or misconfigured state. -.PP +.P The numerical values corresponding to the symbolical ones are given in parenthesis for easy reference. .SH STANDARDS diff --git a/man3type/FILE.3type b/man3type/FILE.3type index 6edeeb4..3e8ea24 100644 --- a/man3type/FILE.3type +++ b/man3type/FILE.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH FILE 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH FILE 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME FILE \- input/output stream .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " FILE; .fi .SH DESCRIPTION diff --git a/man3type/aiocb.3type b/man3type/aiocb.3type index 45739e2..5daec06 100644 --- a/man3type/aiocb.3type +++ b/man3type/aiocb.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH aiocb 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH aiocb 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME aiocb \- asynchronous I/O control block .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct aiocb { .BR " int aio_fildes;" " /* File descriptor */" .BR " off_t aio_offset;" " /* File offset */" diff --git a/man3type/blkcnt_t.3type b/man3type/blkcnt_t.3type index 5cdacdc..d5b2e44 100644 --- a/man3type/blkcnt_t.3type +++ b/man3type/blkcnt_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH blkcnt_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH blkcnt_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME blkcnt_t \- file block counts .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " blkcnt_t; .fi .SH DESCRIPTION diff --git a/man3type/blksize_t.3type b/man3type/blksize_t.3type index 5406a88..00f341c 100644 --- a/man3type/blksize_t.3type +++ b/man3type/blksize_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH blksize_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH blksize_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME blksize_t \- file block sizes .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " blksize_t; .fi .SH DESCRIPTION diff --git a/man3type/cc_t.3type b/man3type/cc_t.3type index 33d5829..c7b4021 100644 --- a/man3type/cc_t.3type +++ b/man3type/cc_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH cc_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH cc_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME cc_t, speed_t, tcflag_t \- terminal special characters, baud rates, modes .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " cc_t; .BR typedef " /* ... */ " speed_t; .BR typedef " /* ... */ " tcflag_t; @@ -25,7 +25,7 @@ is used for terminal special characters, for baud rates, and .I tcflag_t for modes. -.PP +.P All are unsigned integer types. .SH STANDARDS POSIX.1-2008. diff --git a/man3type/clock_t.3type b/man3type/clock_t.3type index e1346e3..aa061b0 100644 --- a/man3type/clock_t.3type +++ b/man3type/clock_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH clock_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH clock_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME clock_t \- system time .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " clock_t; .fi .SH DESCRIPTION @@ -31,7 +31,7 @@ C89, POSIX.1-2001. The following headers also provide this type: .I and -.IR . +.IR . .SH SEE ALSO .BR times (2), .BR clock (3) diff --git a/man3type/clockid_t.3type b/man3type/clockid_t.3type index bc9a3b8..a28c065 100644 --- a/man3type/clockid_t.3type +++ b/man3type/clockid_t.3type @@ -1,4 +1,4 @@ -.TH clockid_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH clockid_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME clockid_t \- clock ID for the clock and timer functions .SH LIBRARY @@ -7,7 +7,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " clockid_t; .fi .SH DESCRIPTION diff --git a/man3type/dev_t.3type b/man3type/dev_t.3type index e4c4ae9..d30803b 100644 --- a/man3type/dev_t.3type +++ b/man3type/dev_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH dev_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH dev_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME dev_t \- device ID .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " dev_t; .fi .SH DESCRIPTION diff --git a/man3type/div_t.3type b/man3type/div_t.3type index f0bce13..977d5af 100644 --- a/man3type/div_t.3type +++ b/man3type/div_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH div_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH div_t 3type 2024-01-16 "Linux man-pages 6.7" .SH NAME div_t, ldiv_t, lldiv_t, imaxdiv_t \- quotient and remainder of an integer division @@ -14,24 +14,24 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B typedef struct { .BR " int quot;" " /* Quotient */" .BR " int rem;" " /* Remainder */" .B } div_t; -.PP +.P .B typedef struct { .BR " long quot;" " /* Quotient */" .BR " long rem;" " /* Remainder */" .B } ldiv_t; -.PP +.P .B typedef struct { .BR " long long quot;" " /* Quotient */" .BR " long long rem;" " /* Remainder */" .B } lldiv_t; -.PP +.P .B #include -.PP +.P .B typedef struct { .BR " intmax_t quot;" " /* Quotient */" .BR " intmax_t rem;" " /* Remainder */" @@ -40,9 +40,10 @@ Standard C library .SH DESCRIPTION .RI [[ l ] l ] div_t is the type of the value returned by the -.RB [[ l ] l ] div (3) +.RB [[ l ] l ]\c +.BR div (3) function. -.PP +.P .I imaxdiv_t is the type of the value returned by the .BR imaxdiv (3) diff --git a/man3type/double_t.3type b/man3type/double_t.3type index ca200af..06c7699 100644 --- a/man3type/double_t.3type +++ b/man3type/double_t.3type @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH double_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH double_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME float_t, double_t \- most efficient floating types .SH LIBRARY @@ -14,7 +14,7 @@ Math library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " float_t; .BR typedef " /* ... */ " double_t; .fi @@ -28,7 +28,7 @@ Their type depends on the value of the macro .B FLT_EVAL_METHOD (defined in .IR ): -.PP +.P .TS lB rI rI. FLT_EVAL_METHOD float_t double_t @@ -39,7 +39,7 @@ _ 1 double double 2 long double long double .TE -.PP +.P For other values of .BR FLT_EVAL_METHOD , the types of diff --git a/man3type/epoll_event.3type b/man3type/epoll_event.3type index 0a9fa74..1ba679d 100644 --- a/man3type/epoll_event.3type +++ b/man3type/epoll_event.3type @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH epoll_event 3type 2023-07-08 "Linux man-pages 6.05.01" +.TH epoll_event 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll_event, epoll_data, epoll_data_t \- epoll event @@ -13,19 +13,19 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct epoll_event { .BR " uint32_t events;" " /* Epoll events */" .BR " epoll_data_t data;" " /* User data variable */" .B }; -.PP +.P .B union epoll_data { .B " void *ptr;" .B " int fd;" .B " uint32_t u32;" .B " uint64_t u64;" .B }; -.PP +.P .B "typedef union epoll_data epoll_data_t;" .EE .SH DESCRIPTION @@ -37,7 +37,7 @@ return when the corresponding file descriptor becomes ready. .SS C library/kernel differences The Linux kernel headers also provide this type, with a slightly different definition: -.PP +.P .in +4n .EX #include diff --git a/man3type/fenv_t.3type b/man3type/fenv_t.3type index 95e036e..bc430b0 100644 --- a/man3type/fenv_t.3type +++ b/man3type/fenv_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH fenv_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH fenv_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME fenv_t, fexcept_t \- floating-point environment .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " fenv_t; .BR typedef " /* ... */ " fexcept_t; .fi @@ -21,10 +21,10 @@ Standard C library .I fenv_t represents the entire floating-point environment, including control modes and status flags. -.PP +.P .I fexcept_t represents the floating-point status flags collectively. -.PP +.P For further details see .BR fenv (3). .SH STANDARDS diff --git a/man3type/id_t.3type b/man3type/id_t.3type index 9b30e47..23c130c 100644 --- a/man3type/id_t.3type +++ b/man3type/id_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH id_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH id_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME pid_t, uid_t, gid_t, id_t \- process/user/group identifier .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " pid_t; .BR typedef " /* ... */ " uid_t; .BR typedef " /* ... */ " gid_t; @@ -23,15 +23,15 @@ Standard C library .I pid_t is a type used for storing process IDs, process group IDs, and session IDs. It is a signed integer type. -.PP +.P .I uid_t is a type used to hold user IDs. It is an integer type. -.PP +.P .I gid_t is a type used to hold group IDs. It is an integer type. -.PP +.P .I id_t is a type used to hold a general identifier. It is an integer type that can be used to contain a @@ -59,7 +59,7 @@ The following headers also provide .IR , and .IR . -.PP +.P The following headers also provide .IR uid_t : .IR , @@ -69,7 +69,7 @@ The following headers also provide .IR , and .IR . -.PP +.P The following headers also provide .IR gid_t : .IR , @@ -80,7 +80,7 @@ The following headers also provide .IR , and .IR . -.PP +.P The following header also provides .IR id_t : .IR . diff --git a/man3type/intN_t.3type b/man3type/intN_t.3type index 56cd445..dc42042 100644 --- a/man3type/intN_t.3type +++ b/man3type/intN_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH intN_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH intN_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME intN_t, int8_t, int16_t, int32_t, int64_t, uintN_t, uint8_t, uint16_t, uint32_t, uint64_t @@ -15,47 +15,47 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " int8_t; .BR typedef " /* ... */ " int16_t; .BR typedef " /* ... */ " int32_t; .BR typedef " /* ... */ " int64_t; -.PP +.P .BR typedef " /* ... */ " uint8_t; .BR typedef " /* ... */ " uint16_t; .BR typedef " /* ... */ " uint32_t; .BR typedef " /* ... */ " uint64_t; -.PP +.P .B "#define INT8_WIDTH 8" .B "#define INT16_WIDTH 16" .B "#define INT32_WIDTH 32" .B "#define INT64_WIDTH 64" -.PP +.P .B "#define UINT8_WIDTH 8" .B "#define UINT16_WIDTH 16" .B "#define UINT32_WIDTH 32" .B "#define UINT64_WIDTH 64" -.PP +.P .BR "#define INT8_MAX " "/* 2**(INT8_WIDTH - 1) - 1 */" .BR "#define INT16_MAX " "/* 2**(INT16_WIDTH - 1) - 1 */" .BR "#define INT32_MAX " "/* 2**(INT32_WIDTH - 1) - 1 */" .BR "#define INT64_MAX " "/* 2**(INT64_WIDTH - 1) - 1 */" -.PP +.P .BR "#define INT8_MIN " "/* - 2**(INT8_WIDTH - 1) */" .BR "#define INT16_MIN " "/* - 2**(INT16_WIDTH - 1) */" .BR "#define INT32_MIN " "/* - 2**(INT32_WIDTH - 1) */" .BR "#define INT64_MIN " "/* - 2**(INT64_WIDTH - 1) */" -.PP +.P .BR "#define UINT8_MAX " "/* 2**INT8_WIDTH - 1 */" .BR "#define UINT16_MAX " "/* 2**INT16_WIDTH - 1 */" .BR "#define UINT32_MAX " "/* 2**INT32_WIDTH - 1 */" .BR "#define UINT64_MAX " "/* 2**INT64_WIDTH - 1 */" -.PP +.P .BI "#define INT8_C(" c ") " c " ## " "\fR/* ... */\fP" .BI "#define INT16_C(" c ") " c " ## " "\fR/* ... */\fP" .BI "#define INT32_C(" c ") " c " ## " "\fR/* ... */\fP" .BI "#define INT64_C(" c ") " c " ## " "\fR/* ... */\fP" -.PP +.P .BI "#define UINT8_C(" c ") " c " ## " "\fR/* ... */\fP" .BI "#define UINT16_C(" c ") " c " ## " "\fR/* ... */\fP" .BI "#define UINT32_C(" c ") " c " ## " "\fR/* ... */\fP" @@ -74,7 +74,7 @@ They are be capable of storing values in the range substituting .I N by the appropriate number. -.PP +.P .IR uint N _t are unsigned integer types @@ -86,7 +86,7 @@ They are capable of storing values in the range substituting .I N by the appropriate number. -.PP +.P According to POSIX, .RI [ u ] int8_t , .RI [ u ] int16_t , @@ -96,25 +96,25 @@ are required; .RI [ u ] int64_t are only required in implementations that provide integer types with width 64; and all other types of this form are optional. -.PP +.P The macros .RB [ U ] INT \fIN\fP _WIDTH expand to the width in bits of these types .RI ( N ). -.PP +.P The macros .RB [ U ] INT \fIN\fP _MAX expand to the maximum value that these types can hold. -.PP +.P The macros .BI INT N _MIN expand to the minimum value that these types can hold. -.PP +.P The macros .RB [ U ] INT \fIN\fP _C () expand their argument to an integer constant of type .RI [ u ] int N _t . -.PP +.P The length modifiers for the .RI [ u ] int N _t types for the @@ -159,7 +159,7 @@ values. C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.PP +.P The .RB [ U ] INT \fIN\fP _WIDTH macros were added in C23. diff --git a/man3type/intmax_t.3type b/man3type/intmax_t.3type index 9048e63..846c5cc 100644 --- a/man3type/intmax_t.3type +++ b/man3type/intmax_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH intmax_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH intmax_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME intmax_t, uintmax_t \- greatest-width basic integer types .SH LIBRARY @@ -13,17 +13,17 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " intmax_t; .BR typedef " /* ... */ " uintmax_t; -.PP +.P .BR "#define INTMAX_WIDTH " "/* ... */" .B "#define UINTMAX_WIDTH INTMAX_WIDTH" -.PP +.P .BR "#define INTMAX_MAX " "/* 2**(INTMAX_WIDTH - 1) - 1 */" .BR "#define INTMAX_MIN " "/* - 2**(INTMAX_WIDTH - 1) */" .BR "#define UINTMAX_MAX " "/* 2**UINTMAX_WIDTH - 1 */" -.PP +.P .BI "#define INTMAX_C(" c ) " c " ## " \fR/* ... */\fP" .BI "#define UINTMAX_C(" c ) " c " ## " \fR/* ... */\fP" .fi @@ -35,7 +35,7 @@ supported by the implementation. It is capable of storing values in the range .RB [ INTMAX_MIN , .BR INTMAX_MAX ]. -.PP +.P .I uintmax_t is an unsigned integer type capable of representing any value of any basic unsigned integer type @@ -43,26 +43,26 @@ supported by the implementation. It is capable of storing values in the range .RB [ 0 , .BR UINTMAX_MAX ]. -.PP +.P The macros .RB [ U ] INTMAX_WIDTH expand to the width in bits of these types. -.PP +.P The macros .RB [ U ] INTMAX_MAX expand to the maximum value that these types can hold. -.PP +.P The macro .B INTMAX_MIN expands to the minimum value that .I intmax_t can hold. -.PP +.P The macros .RB [ U ] INTMAX_C () expand their argument to an integer constant of type .RI [ u ] intmax_t . -.PP +.P The length modifier for .RI [ u ] intmax_t for the diff --git a/man3type/intptr_t.3type b/man3type/intptr_t.3type index 1bec12f..4ee3291 100644 --- a/man3type/intptr_t.3type +++ b/man3type/intptr_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH intptr_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH intptr_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME intptr_t, uintptr_t \- integer types wide enough to hold pointers .SH LIBRARY @@ -13,13 +13,13 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " intptr_t; .BR typedef " /* ... */ " uintptr_t; -.PP +.P .BR "#define INTPTR_WIDTH" " /* ... */" .B #define UINTPTR_WIDTH INTPTR_WIDTH -.PP +.P .BR "#define INTPTR_MAX" " /* 2**(INTPTR_WIDTH \- 1) \- 1 */" .BR "#define INTPTR_MIN" " /* \- 2**(INTPTR_WIDTH \- 1) */" .BR "#define UINTPTR_MAX" " /* 2**UINTPTR_WIDTH \- 1 */" @@ -33,7 +33,7 @@ value can be converted to this type and then converted back. It is capable of storing values in the range .RB [ INTPTR_MIN , .BR INTPTR_MAX ]. -.PP +.P .I uintptr_t is an unsigned integer type such that any valid @@ -42,21 +42,21 @@ value can be converted to this type and then converted back. It is capable of storing values in the range .RB [ 0 , .BR INTPTR_MAX ]. -.PP +.P The macros .RB [ U ] INTPTR_WIDTH expand to the width in bits of these types. -.PP +.P The macros .RB [ U ] INTPTR_MAX expand to the maximum value that these types can hold. -.PP +.P The macro .B INTPTR_MIN expands to the minimum value that .I intptr_t can hold. -.PP +.P The length modifiers for the .RI [ u ] intptr_t types diff --git a/man3type/iovec.3type b/man3type/iovec.3type index c2786f5..4d5c9ec 100644 --- a/man3type/iovec.3type +++ b/man3type/iovec.3type @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH iovec 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH iovec 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME iovec \- Vector I/O data structure .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct iovec { .BR " void *iov_base;" " /* Starting address */" .BR " size_t iov_len;" " /* Size of the memory pointed to by "\c diff --git a/man3type/itimerspec.3type b/man3type/itimerspec.3type index 7def422..1650e0a 100644 --- a/man3type/itimerspec.3type +++ b/man3type/itimerspec.3type @@ -3,16 +3,16 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH itimerspec 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH itimerspec 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME -timespec \- interval for a timer with nanosecond precision +itimerspec \- interval for a timer with nanosecond precision .SH LIBRARY Standard C library .RI ( libc ) .SH SYNOPSIS .EX .B #include -.PP +.P .B struct itimerspec { .BR " struct timespec it_interval;" " /* Interval for periodic timer */" .BR " struct timespec it_value;" " /* Initial expiration */" @@ -23,10 +23,9 @@ Describes the initial expiration of a timer, and its interval, in seconds and nanoseconds. .SH STANDARDS -Linux. -.SH NOTES -The following header also provides this type: -.IR . +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. .SH SEE ALSO .BR timerfd_create (2), .BR timer_settime (2), diff --git a/man3type/lconv.3type b/man3type/lconv.3type index f36522c..5fe2e74 100644 --- a/man3type/lconv.3type +++ b/man3type/lconv.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH lconv 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH lconv 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME lconv \- numeric formatting information .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .BR "struct lconv {" " /* Values in the \[dq]C\[dq] locale: */" .BR " char *decimal_point;" " /* \[dq].\[dq] */" .BR " char *thousands_sep;" " /* \[dq]\[dq] */" diff --git a/man3type/mode_t.3type b/man3type/mode_t.3type index 7d56100..36f4bb8 100644 --- a/man3type/mode_t.3type +++ b/man3type/mode_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH mode_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH mode_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME mode_t \- file attributes .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " mode_t; .fi .SH DESCRIPTION diff --git a/man3type/off_t.3type b/man3type/off_t.3type index b544f66..95193d2 100644 --- a/man3type/off_t.3type +++ b/man3type/off_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH off_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH off_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME off_t, off64_t, loff_t \- file sizes .SH LIBRARY @@ -13,28 +13,28 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " off_t; -.PP +.P .B #define _LARGEFILE64_SOURCE .B #include -.PP +.P .BR typedef " /* ... */ " off64_t; -.PP +.P .B #define _GNU_SOURCE .B #include -.PP +.P .BR typedef " /* ... */ " loff_t; .fi .SH DESCRIPTION .I off_t is used for describing file sizes. It is a signed integer type. -.PP +.P .I off64_t is a 64-bit version of the type, used in glibc. -.PP +.P .I loff_t is a 64-bit version of the type, introduced by the Linux kernel. @@ -52,7 +52,7 @@ Linux. .TP .I off_t POSIX.1-2001. -.PP +.P .I and .I @@ -65,7 +65,7 @@ the width of .I off_t can be controlled with the feature test macro .BR _FILE_OFFSET_BITS . -.PP +.P The following headers also provide .IR off_t : .IR , diff --git a/man3type/ptrdiff_t.3type b/man3type/ptrdiff_t.3type index bb6b404..7e1ce76 100644 --- a/man3type/ptrdiff_t.3type +++ b/man3type/ptrdiff_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ptrdiff_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH ptrdiff_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME ptrdiff_t \- count of elements or array index .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " ptrdiff_t; .fi .SH DESCRIPTION @@ -21,9 +21,9 @@ Used for a count of elements, or an array index. It is the result of subtracting two pointers. It is a signed integer type capable of storing values in the range -.RB [ PTRDIFF_MAX , +.RB [ PTRDIFF_MIN , .BR PTRDIFF_MAX ]. -.PP +.P The length modifier for .I ptrdiff_t for the diff --git a/man3type/sigevent.3type b/man3type/sigevent.3type index db50c0f..4f1cb71 100644 --- a/man3type/sigevent.3type +++ b/man3type/sigevent.3type @@ -1 +1,142 @@ -.so man7/system_data_types.7 +.\" Copyright (c) 2006, 2010, 2020, Michael Kerrisk +.\" Copyright (C) 2009 Petr Baudis +.\" Copyright (c) 2020-2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigevent 3type 2023-10-31 "Linux man-pages 6.7" +.SH NAME +sigevent, sigval \- structure for notification from asynchronous routines +.SH SYNOPSIS +.EX +.B #include +.P +.B struct sigevent { +.BR " int sigev_notify;" " /* Notification type */" +.BR " int sigev_signo;" " /* Signal number */" +.BR " union sigval sigev_value;" " /* Data passed with notification */" +\& +.B " void (*sigev_notify_function)(union sigval);" +.BR " " " /* Notification function" +.BR " " " (SIGEV_THREAD) */" +.B " pthread_attr_t *sigev_notify_attributes;" +.BR " " " /* Notification attributes */" +\& +.BR " " "/* Linux only: */" +.B " pid_t sigev_notify_thread_id;" +.BR " " " /* ID of thread to signal" +.BR " " " (SIGEV_THREAD_ID) */" +.B }; +.P +.BR "union sigval {" " /* Data passed with notification */" +.BR " int sival_int;" " /* Integer value */" +.BR " void *sival_ptr;" " /* Pointer value */" +.B }; +.EE +.SH DESCRIPTION +.SS sigevent +The +.I sigevent +structure is used by various APIs +to describe the way a process is to be notified about an event +(e.g., completion of an asynchronous request, expiration of a timer, +or the arrival of a message). +.P +The definition shown in the SYNOPSIS is approximate: +some of the fields in the +.I sigevent +structure may be defined as part of a union. +Programs should employ only those fields relevant +to the value specified in +.IR sigev_notify . +.P +The +.I sigev_notify +field specifies how notification is to be performed. +This field can have one of the following values: +.TP +.B SIGEV_NONE +A "null" notification: don't do anything when the event occurs. +.TP +.B SIGEV_SIGNAL +Notify the process by sending the signal specified in +.IR sigev_signo . +.IP +If the signal is caught with a signal handler that was registered using the +.BR sigaction (2) +.B SA_SIGINFO +flag, then the following fields are set in the +.I siginfo_t +structure that is passed as the second argument of the handler: +.RS +.TP 10 +.I si_code +This field is set to a value that depends on the API +delivering the notification. +.TP +.I si_signo +This field is set to the signal number (i.e., the same value as in +.IR sigev_signo ). +.TP +.I si_value +This field is set to the value specified in +.IR sigev_value . +.RE +.IP +Depending on the API, other fields may also be set in the +.I siginfo_t +structure. +.IP +The same information is also available if the signal is accepted using +.BR sigwaitinfo (2). +.TP +.B SIGEV_THREAD +Notify the process by invoking +.I sigev_notify_function +"as if" it were the start function of a new thread. +(Among the implementation possibilities here are that +each timer notification could result in the creation of a new thread, +or that a single thread is created to receive all notifications.) +The function is invoked with +.I sigev_value +as its sole argument. +If +.I sigev_notify_attributes +is not NULL, it should point to a +.I pthread_attr_t +structure that defines attributes for the new thread (see +.BR pthread_attr_init (3)). +.TP +.BR SIGEV_THREAD_ID " (Linux-specific)" +.\" | SIGEV_SIGNAL vs not? +Currently used only by POSIX timers; see +.BR timer_create (2). +.SS sigval +Data passed with a signal. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +.I +and +.I +define +.I sigevent +since POSIX.1-2008. +.SH NOTES +The following headers also provide +.IR sigevent : +.IR , +.IR , +and +.IR . +.SH SEE ALSO +.BR timer_create (2), +.BR getaddrinfo_a (3), +.BR lio_listio (3), +.BR mq_notify (3), +.BR pthread_sigqueue (3), +.BR sigqueue (3), +.BR aiocb (3type), +.BR siginfo_t (3type) diff --git a/man3type/sigval.3type b/man3type/sigval.3type index db50c0f..b43f1bb 100644 --- a/man3type/sigval.3type +++ b/man3type/sigval.3type @@ -1 +1 @@ -.so man7/system_data_types.7 +.so man3type/sigevent.3type diff --git a/man3type/size_t.3type b/man3type/size_t.3type index 9df433a..c9ac9c2 100644 --- a/man3type/size_t.3type +++ b/man3type/size_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH size_t 3type 2023-03-31 "Linux man-pages 6.05.01" +.TH size_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME size_t, ssize_t \- count of bytes .SH LIBRARY @@ -13,11 +13,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " size_t; -.PP +.P .B #include -.PP +.P .BR typedef " /* ... */ " ssize_t; .fi .SH DESCRIPTION @@ -99,7 +99,7 @@ C89, POSIX.1-2001. .TP .I ssize_t POSIX.1-2001. -.PP +.P .IR , .IR , .IR , @@ -112,7 +112,7 @@ and define .I size_t since POSIX.1-2008. -.PP +.P .IR , .IR , and diff --git a/man3type/sockaddr.3type b/man3type/sockaddr.3type index dacc9ad..2ca69c8 100644 --- a/man3type/sockaddr.3type +++ b/man3type/sockaddr.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH sockaddr 3type 2023-04-22 "Linux man-pages 6.05.01" +.TH sockaddr 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME sockaddr, sockaddr_storage, sockaddr_in, sockaddr_in6, sockaddr_un, socklen_t, in_addr, in6_addr, in_addr_t, in_port_t, @@ -15,30 +15,30 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct sockaddr { .BR " sa_family_t sa_family;" " /* Address family */" .BR " char sa_data[];" " /* Socket address */" .B }; -.PP +.P .B struct sockaddr_storage { .BR " sa_family_t ss_family;" " /* Address family */" .B }; -.PP +.P .BR typedef " /* ... */ " socklen_t; .BR typedef " /* ... */ " sa_family_t; -.PP +.P .EE .SS Internet domain sockets .EX .B #include -.PP +.P .B struct sockaddr_in { .BR " sa_family_t sin_family;" " /* " AF_INET " */" .BR " in_port_t sin_port;" " /* Port number */" .BR " struct in_addr sin_addr;" " /* IPv4 address */" .B }; -.PP +.P .B struct sockaddr_in6 { .BR " sa_family_t sin6_family;" " /* " AF_INET6 " */" .BR " in_port_t sin6_port;" " /* Port number */" @@ -46,22 +46,22 @@ Standard C library .BR " struct in6_addr sin6_addr;" " /* IPv6 address */" .BR " uint32_t sin6_scope_id;" " /* Set of interfaces for a scope */" .B }; -.PP +.P .B struct in_addr { .B " in_addr_t s_addr;" .B }; -.PP +.P .B struct in6_addr { .B " uint8_t s6_addr[16];" .B }; -.PP +.P .B typedef uint32_t in_addr_t; .B typedef uint16_t in_port_t; .EE .SS UNIX domain sockets .EX .B #include -.PP +.P .B struct sockaddr_un { .BR " sa_family_t sun_family;" " /* Address family */" .BR " char sun_path[];" " /* Socket pathname */" @@ -112,12 +112,12 @@ Describes a UNIX domain socket address. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P .I socklen_t was invented by POSIX. See also .BR accept (2). -.PP +.P These structures were invented before modern ISO C strict-aliasing rules. If aliasing rules are applied strictly, these structures would be extremely difficult to use @@ -129,7 +129,7 @@ can be safely used as they were designed. .I socklen_t is also defined in .IR . -.PP +.P .I sa_family_t is also defined in .I diff --git a/man3type/stat.3type b/man3type/stat.3type index 6630641..71b850e 100644 --- a/man3type/stat.3type +++ b/man3type/stat.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH stat 3type 2023-05-03 "Linux man-pages 6.05.01" +.TH stat 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME stat \- file status .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct stat { .BR " dev_t st_dev;" " /* ID of device containing file */" .BR " ino_t st_ino;" " /* Inode number */" @@ -39,12 +39,12 @@ Standard C library .B "#define st_ctime st_ctim.tv_sec" .B }; .EE -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .IR st_atim , .IR st_mtim , .IR st_ctim : @@ -56,7 +56,7 @@ Feature Test Macro Requirements for glibc (see .fi .SH DESCRIPTION Describes information about a file. -.PP +.P The fields are as follows: .TP .I st_dev @@ -113,14 +113,14 @@ This is the time of last modification of file data. .I st_ctime This is the file's last status change timestamp (time of last change to the inode). -.PP +.P For further information on the above fields, see .BR inode (7). .SH STANDARDS POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P Old kernels and old standards did not support nanosecond timestamp fields. Instead, there were three timestamp .RI fields\[em] st_atime , @@ -130,7 +130,7 @@ and as .I time_t that recorded timestamps with one-second precision. -.PP +.P Since Linux 2.5.48, the .I stat structure supports nanosecond resolution for the three file timestamp fields. diff --git a/man3type/time_t.3type b/man3type/time_t.3type index 2b087e5..d528ad3 100644 --- a/man3type/time_t.3type +++ b/man3type/time_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH time_t 3type 2023-03-31 "Linux man-pages 6.05.01" +.TH time_t 3type 2023-11-11 "Linux man-pages 6.7" .SH NAME time_t, suseconds_t, useconds_t \- integer time .SH LIBRARY @@ -13,11 +13,11 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " time_t; -.PP +.P .B #include -.PP +.P .BR typedef " /* ... */ " suseconds_t; .BR typedef " /* ... */ " useconds_t; .fi @@ -64,12 +64,12 @@ C89, POSIX.1-2001. .TQ .I useconds_t POSIX.1-2001. -.PP +.P .I defines .I time_t since POSIX.1-2008. -.PP +.P POSIX.1-2001 defined .I useconds_t in @@ -81,7 +81,9 @@ the width of .I time_t can be controlled with the feature test macro .BR _TIME_BITS . -.PP +See +.BR feature_test_macros (7). +.P The following headers also provide .IR time_t : .IR , @@ -94,7 +96,7 @@ The following headers also provide .IR , and .IR . -.PP +.P The following headers also provide .IR suseconds_t : .I diff --git a/man3type/timer_t.3type b/man3type/timer_t.3type index 8341ec1..a14dc1e 100644 --- a/man3type/timer_t.3type +++ b/man3type/timer_t.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH timer_t 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH timer_t 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME timer_t \- timer ID .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " timer_t; .fi .SH DESCRIPTION diff --git a/man3type/timespec.3type b/man3type/timespec.3type index 213c131..8e18d2e 100644 --- a/man3type/timespec.3type +++ b/man3type/timespec.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH timespec 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH timespec 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME timespec \- time in seconds and nanoseconds .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct timespec { .BR " time_t tv_sec;" " /* Seconds */" .RB " /* ... */" " tv_nsec;" \ @@ -22,7 +22,7 @@ Standard C library .EE .SH DESCRIPTION Describes times in seconds and nanoseconds. -.PP +.P .I tv_nsec is of an implementation-defined signed type capable of holding the specified range. diff --git a/man3type/timeval.3type b/man3type/timeval.3type index 97f450d..9724029 100644 --- a/man3type/timeval.3type +++ b/man3type/timeval.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH timeval 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH timeval 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME timeval \- time in seconds and microseconds .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct timeval { .BR " time_t tv_sec;" " /* Seconds */" .BR " suseconds_t tv_usec;" " /* Microseconds */" diff --git a/man3type/tm.3type b/man3type/tm.3type index 42cd1e3..721a5aa 100644 --- a/man3type/tm.3type +++ b/man3type/tm.3type @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH tm 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH tm 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME tm \- broken-down time .SH LIBRARY @@ -12,7 +12,7 @@ Standard C library .SH SYNOPSIS .EX .B #include -.PP +.P .B struct tm { .BR " int tm_sec;" " /* Seconds [" 0 ", " 60 "] */" .BR " int tm_min;" " /* Minutes [" 0 ", " 59 "] */" @@ -26,17 +26,17 @@ Standard C library .BR " int tm_yday;" \ " /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */" .BR " int tm_isdst;" " /* Daylight savings flag */" -.PP +.P .BR " long tm_gmtoff;" " /* Seconds East of UTC */" .BR " const char *tm_zone;" " /* Timezone abbreviation */" .B }; .EE -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .IR tm_gmtoff , .IR tm_zone : .nf @@ -48,19 +48,19 @@ Feature Test Macro Requirements for glibc (see .fi .SH DESCRIPTION Describes time, broken down into distinct components. -.PP +.P .I tm_isdst describes whether daylight saving time is in effect at the time described. The value is positive if daylight saving time is in effect, zero if it is not, and negative if the information is not available. -.PP +.P .I tm_gmtoff is the difference, in seconds, of the timezone represented by this broken-down time and UTC (this is the additive inverse of .BR timezone (3)). -.PP +.P .I tm_zone is the equivalent of .BR tzname (3) @@ -75,7 +75,7 @@ UTC doesn't permit double leap seconds, so it was limited to .B 60 in C99. -.PP +.P .BR timezone (3), as a variable, is an XSI extension: some systems provide the V7-compatible .\" FreeBSD @@ -84,7 +84,7 @@ function. The .I tm_gmtoff field provides an alternative (with the opposite sign) for those systems. -.PP +.P .I tm_zone points to static storage and may be overridden on subsequent calls to .BR localtime (3) @@ -93,7 +93,7 @@ and similar functions (however, this never happens under glibc). C11, POSIX.1-2008. .SH HISTORY C89, POSIX.1-2001. -.PP +.P .I tm_gmtoff and .I tm_zone diff --git a/man3type/va_list.3type b/man3type/va_list.3type index 3549829..d520594 100644 --- a/man3type/va_list.3type +++ b/man3type/va_list.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH va_list 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH va_list 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME va_list \- variable argument list .SH LIBRARY @@ -13,7 +13,7 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BR typedef " /* ... */ " va_list; .fi .SH DESCRIPTION diff --git a/man3type/void.3type b/man3type/void.3type index 45907e9..4174f5f 100644 --- a/man3type/void.3type +++ b/man3type/void.3type @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH void 3type 2023-03-30 "Linux man-pages 6.05.01" +.TH void 3type 2023-10-31 "Linux man-pages 6.7" .SH NAME void \- abstract type .SH SYNOPSIS @@ -20,7 +20,7 @@ including pointers to functions, may be converted to a pointer to .I void and back. -.PP +.P Conversions from and to any other pointer type are done implicitly, not requiring casts at all. Note that this feature prevents any kind of type checking: @@ -28,13 +28,13 @@ the programmer should be careful not to convert a .I void * value to a type incompatible to that of the underlying data, because that would result in undefined behavior. -.PP +.P This type is useful in function parameters and return value to allow passing values of any type. The function will typically use some mechanism to know the real type of the data being passed via a pointer to .IR void . -.PP +.P A value of this type can't be dereferenced, as it would give a value of type .IR void , diff --git a/man4/cciss.4 b/man4/cciss.4 index 9194c8a..6b6a6d1 100644 --- a/man4/cciss.4 +++ b/man4/cciss.4 @@ -6,7 +6,7 @@ .\" .\" shorthand for double quote that works everywhere. .ds q \N'34' -.TH cciss 4 2023-05-03 "Linux man-pages 6.05.01" +.TH cciss 4 2023-10-31 "Linux man-pages 6.7" .SH NAME cciss \- HP Smart Array block driver .SH SYNOPSIS @@ -20,7 +20,7 @@ This obsolete driver was removed in Linux 4.14, as it is superseded by the .BR hpsa (4) driver in newer kernels. -.PP +.P .B cciss is a block driver for older HP Smart Array RAID controllers. .SS Options @@ -32,7 +32,7 @@ driver from attempting to drive any controllers that the driver is capable of controlling, which is to say, the .B cciss driver is restricted by this option to the following controllers: -.PP +.P .nf Smart Array 5300 Smart Array 5i @@ -56,7 +56,7 @@ driver is restricted by this option to the following controllers: The .B cciss driver supports the following Smart Array boards: -.PP +.P .nf Smart Array 5300 Smart Array 5i @@ -95,7 +95,7 @@ run from the Smart Array's option ROM at boot time. .SH FILES .SS Device nodes The device naming scheme is as follows: -.PP +.P Major numbers: .IP .TS @@ -109,9 +109,9 @@ r r. 110 cciss6 111 cciss7 .TE -.PP +.P Minor numbers: -.PP +.P .EX b7 b6 b5 b4 b3 b2 b1 b0 |\-\-\-\-+\-\-\-\-| |\-\-\-\-+\-\-\-\-| @@ -120,7 +120,7 @@ Minor numbers: | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- Logical Volume number .EE -.PP +.P The device naming scheme is: .TS li l. @@ -140,7 +140,7 @@ The files contain information about the configuration of each controller. For example: -.PP +.P .in +4n .EX $ \fBcd /proc/driver/cciss\fP @@ -237,7 +237,7 @@ for more details.) You must enable "SCSI tape drive support for Smart Array 5xxx" and "SCSI support" in your kernel configuration to be able to use SCSI tape drives with your Smart Array 5xxx controller. -.PP +.P Additionally, note that the driver will not engage the SCSI core at init time. The driver must be directed to dynamically engage the SCSI core via the @@ -255,7 +255,7 @@ This is best done via an initialization script .IR /etc/init.d , but could vary depending on distribution). For example: -.PP +.P .in +4n .EX for x in /proc/driver/cciss/cciss[0\-9]* @@ -264,10 +264,10 @@ do done .EE .in -.PP +.P Once the SCSI core is engaged by the driver, it cannot be disengaged (except by unloading the driver, if it happens to be linked as a module.) -.PP +.P Note also that if no sequential access devices or medium changers are detected, the SCSI core will not be engaged by the action of the above script. @@ -283,7 +283,7 @@ filesystem. For example: .IP echo "rescan" > /proc/scsi/cciss0/1 -.PP +.P This causes the driver to: .RS .IP (1) 5 @@ -293,20 +293,20 @@ physical SCSI buses and/or fiber channel arbitrated loop, and make note of any new or removed sequential access devices or medium changers. .RE -.PP +.P The driver will output messages indicating which devices have been added or removed and the controller, bus, target, and lun used to address each device. The driver then notifies the SCSI midlayer of these changes. -.PP +.P Note that the naming convention of the .I /proc filesystem entries contains a number in addition to the driver name (e.g., "cciss0" instead of just "cciss", which you might expect). -.PP +.P Note: .I Only sequential access devices and medium changers are presented @@ -340,7 +340,7 @@ If that doesn't work, the device is reset. If that doesn't work, the SCSI bus is reset. .IP (4) If that doesn't work, the host bus adapter is reset. -.PP +.P The .B cciss driver is a block @@ -358,7 +358,7 @@ in aborting commands, and sometimes it appears they will not even obey a reset command, though in most circumstances they will. If the command cannot be aborted and the device cannot be reset, the device will be set offline. -.PP +.P In the event that the error-handling code is triggered and a tape drive is successfully reset or the tardy command is successfully aborted, the tape drive may still not allow I/O to continue until some command @@ -371,7 +371,7 @@ for example) before I/O can proceed again to a tape drive that was reset. .BR cciss_vol_status (8), .BR hpacucli (8), .BR hpacuxe (8) -.PP +.P .UR http://cciss.sf.net .UE , and diff --git a/man4/console_codes.4 b/man4/console_codes.4 index e2ac4e8..afc8c70 100644 --- a/man4/console_codes.4 +++ b/man4/console_codes.4 @@ -6,7 +6,7 @@ .\" This is combined from many sources. .\" For Linux, the definitive source is of course console.c. .\" About vt100-like escape sequences in general there are -.\" the ISO 6429 and ISO 2022 norms, the descriptions of +.\" the ISO/IEC 6429 and ISO/IEC 2022 norms, the descriptions of .\" an actual vt100, and the xterm docs (ctlseqs.ms). .\" Substantial portions of this text are derived from a write-up .\" by Eric S. Raymond . @@ -15,41 +15,42 @@ .\" .\" 2006-05-27, Several corrections - Thomas E. Dickey .\" -.TH console_codes 4 2023-02-05 "Linux man-pages 6.05.01" +.TH console_codes 4 2024-01-28 "Linux man-pages 6.7" .SH NAME console_codes \- Linux console escape and control sequences .SH DESCRIPTION -The Linux console implements a large subset of the VT102 and ECMA-48/ISO -6429/ANSI X3.64 terminal controls, plus certain private-mode sequences +The Linux console implements a large subset of +the VT102 and ECMA-48 / ISO/IEC\~6429 / ANSI X3.64 terminal controls, +plus certain private-mode sequences for changing the color palette, character-set mapping, and so on. In the tabular descriptions below, the second column gives ECMA-48 or DEC mnemonics (the latter if prefixed with DEC) for the given function. Sequences without a mnemonic are neither ECMA-48 nor VT102. -.PP +.P After all the normal output processing has been done, and a stream of characters arrives at the console driver for actual printing, the first thing that happens is a translation from the code used for processing to the code used for printing. -.PP +.P If the console is in UTF-8 mode, then the incoming bytes are first assembled into 16-bit Unicode codes. Otherwise, each byte is transformed according to the current mapping table (which translates it to a Unicode value). See the \fBCharacter Sets\fP section below for discussion. -.PP +.P In the normal case, the Unicode value is converted to a font index, and this is stored in video memory, so that the corresponding glyph (as found in video ROM) appears on the screen. Note that the use of Unicode (and the design of the PC hardware) allows us to use 512 different glyphs simultaneously. -.PP +.P If the current Unicode value is a control character, or we are currently processing an escape sequence, the value will treated specially. Instead of being turned into a font index and rendered as a glyph, it may trigger cursor movement or other control functions. See the \fBLinux Console Controls\fP section below for discussion. -.PP +.P It is generally not good practice to hard-wire terminal controls into programs. Linux supports a @@ -65,9 +66,9 @@ or This section describes all the control characters and escape sequences that invoke special functions (i.e., anything other than writing a glyph at the current cursor location) on the Linux console. -.PP +.P .B "Control characters" -.PP +.P A character is a control character if (before transformation according to the mapping table) it has one of the 14 codes 00 (NUL), 07 (BEL), 08 (BS), 09 (HT), 0a (LF), 0b (VT), @@ -78,7 +79,7 @@ and allow 07, 09, 0b, 18, 1a, 7f to be displayed as glyphs. On the other hand, in UTF-8 mode all codes 00\[en]1f are regarded as control characters, regardless of any "display control characters" mode. -.PP +.P If we have a control character, it is acted upon immediately and then discarded (even in the middle of an escape sequence) and the escape sequence continues with the next character. @@ -129,7 +130,7 @@ is ignored; .TP CSI (0x9B) is equivalent to ESC [. -.PP +.P .B "ESC- but not CSI-sequences" .ad l .TS @@ -152,7 +153,7 @@ ESC 8 DECRC T{ Restore state most recently saved by ESC 7. T} ESC % Start sequence selecting character set -ESC % @ \0\0\0Select default (ISO 646 / ISO 8859-1) +ESC % @ \0\0\0Select default (ISO/IEC\~646 / ISO/IEC\~8859-1) ESC % G \0\0\0Select UTF-8 ESC % 8 \0\0\0Select UTF-8 (obsolete) ESC # 8 DECALN T{ @@ -163,7 +164,7 @@ Start sequence defining G0 character set (followed by one of B, 0, U, K, as below) T} ESC ( B T{ -Select default (ISO 8859-1 mapping). +Select default (ISO/IEC\~8859-1 mapping). T} ESC ( 0 T{ Select VT100 graphics mapping. @@ -190,19 +191,19 @@ the red/green/blue values (0\[en]255). T} .TE .ad -.PP +.P .B "ECMA-48 CSI sequences" -.PP +.P CSI (or ESC [) is followed by a sequence of parameters, at most NPAR (16), that are decimal numbers separated by semicolons. An empty or absent parameter is taken to be 0. The sequence of parameters may be preceded by a single question mark. -.PP +.P However, after CSI [ (or ESC [ [) a single character is read and this entire sequence is ignored. (The idea is to ignore an echoed function key.) -.PP +.P The action of a CSI sequence is determined by its final character. .ad l .TS @@ -309,9 +310,9 @@ Move cursor to indicated column in current row. T} .TE .ad -.PP +.P .B ECMA-48 Select Graphic Rendition -.PP +.P The ECMA-48 SGR sequence ESC [ \fIparameters\fP m sets display attributes. Several attributes can be set in the same sequence, separated by @@ -397,7 +398,7 @@ set background, same as 40..47 (bright not supported) T} .TE .ad -.PP +.P Commands 38 and 48 require further arguments: .TS l lx. @@ -409,7 +410,7 @@ T} 24-bit color, r/g/b components are in the range 0..255 T} .TE -.PP +.P .B ECMA-48 Mode Switches .TP ESC [ 3 h @@ -421,7 +422,7 @@ DECIM (default off): Set insert mode. ESC [ 20 h LF/NL (default off): Automatically follow echo of LF, VT, or FF with CR. .\" -.PP +.P .B ECMA-48 Status Report Commands .\" .TP @@ -432,9 +433,9 @@ ESC [ 6 n Cursor position report (CPR): Answer is ESC [ \fIy\fP ; \fIx\fP R, where \fIx,y\fP is the cursor location. .\" -.PP +.P .B DEC Private Mode (DECSET/DECRST) sequences -.PP +.P .\" These are not described in ECMA-48. We list the Set Mode sequences; @@ -479,9 +480,9 @@ ESC [ ? 1000 h X11 Mouse Reporting (default off): Set reporting mode to 2 (or reset to 0)\[em]see below. .\" -.PP +.P .B Linux Console Private CSI Sequences -.PP +.P .\" The following sequences are neither ECMA-48 nor native VT102. They are native to the Linux console driver. @@ -532,13 +533,13 @@ The kernel knows about 4 translations of bytes into console-screen symbols. The four tables are: a) Latin1 \-> PC, b) VT100 graphics \-> PC, c) PC \-> PC, d) user-defined. -.PP +.P There are two character sets, called G0 and G1, and one of them is the current character set. (Initially G0.) Typing \fB\[ha]N\fP causes G1 to become current, \fB\[ha]O\fP causes G0 to become current. -.PP +.P These variables G0 and G1 point at a translation table, and can be changed by the user. Initially they point at tables a) and b), respectively. @@ -546,7 +547,7 @@ The sequences ESC ( B and ESC ( 0 and ESC ( U and ESC ( K cause G0 to point at translation table a), b), c), and d), respectively. The sequences ESC ) B and ESC ) 0 and ESC ) U and ESC ) K cause G1 to point at translation table a), b), c), and d), respectively. -.PP +.P The sequence ESC c causes a terminal reset, which is what you want if the screen is all garbled. The oft-advised "echo \[ha]V\[ha]O" will make only G0 current, @@ -556,7 +557,7 @@ In some distributions there is a program that just does "echo \[ha][c". If your terminfo entry for the console is correct (and has an entry rs1=\eEc), then "tput reset" will also work. -.PP +.P The user-defined mapping table can be set using .BR mapscrn (8). The result of the mapping is that if a symbol c is printed, the symbol @@ -576,13 +577,13 @@ These ioctls must be generated by a mouse-aware user-mode application such as the .BR gpm (8) daemon. -.PP +.P The mouse tracking escape sequences generated by \fBxterm\fP(1) encode numeric parameters in a single character as \fIvalue\fP+040. For example, \[aq]!\[aq] is 1. The screen coordinate system is 1-based. -.PP +.P The X10 compatibility mode sends an escape sequence on button press encoding the location and the mouse button pressed. It is enabled by sending ESC [ ? 9 h and disabled with ESC [ ? 9 l. @@ -592,7 +593,7 @@ Here \fIb\fP is button\-1, and \fIx\fP and \fIy\fP are the x and y coordinates of the mouse when the button was pressed. This is the same code the kernel also produces. -.PP +.P Normal tracking mode (not implemented in Linux 2.0.24) sends an escape sequence on both button press and release. Modifier information is also sent. @@ -614,9 +615,9 @@ Here we discuss differences between the Linux console and the two most important others, the DEC VT102 and .BR xterm (1). .\" -.PP +.P .B Control-character handling -.PP +.P The VT102 also recognized the following control characters: .TP NUL (0x00) @@ -631,17 +632,17 @@ resumed transmission; DC3 (0x13, \fB\[ha]S\fP, XOFF) caused VT100 to ignore (and stop transmitting) all codes except XOFF and XON. -.PP +.P VT100-like DC1/DC3 processing may be enabled by the terminal driver. -.PP +.P The .BR xterm (1) program (in VT100 mode) recognizes the control characters BEL, BS, HT, LF, VT, FF, CR, SO, SI, ESC. .\" -.PP +.P .B Escape sequences -.PP +.P VT100 console sequences not implemented on the Linux console: .TS l l l. @@ -660,7 +661,7 @@ ESC \e ST String terminator ESC * ... Designate G2 character set ESC + ... Designate G3 character set .TE -.PP +.P The program .BR xterm (1) (in VT100 mode) recognizes ESC c, ESC # 8, ESC >, ESC =, @@ -671,11 +672,11 @@ and ESC \[ha] ... ESC \e with the same meanings as indicated above. It accepts ESC (, ESC ), ESC *, ESC + followed by 0, A, B for the DEC special character and line drawing set, UK, and US-ASCII, respectively. -.PP +.P The user can configure \fBxterm\fP(1) to respond to VT220-specific control sequences, and it will identify itself as a VT52, VT100, and up depending on the way it is configured and initialized. -.PP +.P It accepts ESC ] (OSC) for the setting of certain resources. In addition to the ECMA-48 string terminator (ST), \fBxterm\fP(1) accepts a BEL to terminate an OSC string. @@ -694,7 +695,7 @@ Change log file to \fIname\fP (normally disabled by a compile-time option). T} ESC ] 5 0 ; \fIfn\fP ST Set font to \fIfn\fP. .TE -.PP +.P It recognizes the following with slightly modified meaning (saving more state, behaving closer to VT100/VT220): .TS @@ -702,7 +703,7 @@ l l l. ESC 7 DECSC Save cursor ESC 8 DECRC Restore cursor .TE -.PP +.P It also recognizes .TS l l lx. @@ -719,13 +720,13 @@ ESC | LS3R Invoke the G3 character set as GR. ESC } LS2R Invoke the G2 character set as GR. ESC \[ti] LS1R Invoke the G1 character set as GR. .TE -.PP +.P It also recognizes ESC % and provides a more complete UTF-8 implementation than Linux console. .\" -.PP +.P .B CSI Sequences -.PP +.P Old versions of \fBxterm\fP(1), for example, from X11R5, interpret the blink SGR as a bold SGR. Later versions which implemented ANSI colors, for example, @@ -739,7 +740,7 @@ All ECMA-48 CSI sequences recognized by Linux are also recognized by .IR xterm , however \fBxterm\fP(1) implements several ECMA-48 and DEC control sequences not recognized by Linux. -.PP +.P The \fBxterm\fP(1) program recognizes all of the DEC Private Mode sequences listed above, but none of the Linux private-mode sequences. @@ -753,21 +754,21 @@ and Thomas E.\& Dickey available with the X distribution. That document, though terse, is much longer than this manual page. For a chronological overview, -.PP +.P .RS .UR http://invisible\-island.net\:/xterm\:/xterm.log.html .UE .RE -.PP +.P details changes to xterm. -.PP +.P The \fIvttest\fP program -.PP +.P .RS .UR http://invisible\-island.net\:/vttest/ .UE .RE -.PP +.P demonstrates many of these control sequences. The \fBxterm\fP(1) source distribution also contains sample scripts which exercise other features. @@ -777,7 +778,7 @@ ESC %. .SH BUGS In Linux 2.0.23, CSI is broken, and NUL is not ignored inside escape sequences. -.PP +.P Some older kernel versions (after Linux 2.0) interpret 8-bit control sequences. These "C1 controls" use codes between 128 and 159 to replace @@ -786,7 +787,7 @@ There are fragments of that in modern kernels (either overlooked or broken by changes to support UTF-8), but the implementation is incomplete and should be regarded as unreliable. -.PP +.P Linux "private mode" sequences do not follow the rules in ECMA-48 for private mode control sequences. In particular, those ending with ] do not use a standard terminating @@ -801,7 +802,7 @@ will fix that). To accommodate applications which have been hardcoded to use Linux control sequences, set the \fBxterm\fP(1) resource \fBbrokenLinuxOSC\fP to true. -.PP +.P An older version of this document implied that Linux recognizes the ECMA-48 control sequence for invisible text. It is ignored. diff --git a/man4/cpuid.4 b/man4/cpuid.4 index 3f7d184..e58e29e 100644 --- a/man4/cpuid.4 +++ b/man4/cpuid.4 @@ -3,19 +3,19 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH cpuid 4 2022-10-30 "Linux man-pages 6.05.01" +.TH cpuid 4 2024-01-05 "Linux man-pages 6.7" .SH NAME cpuid \- x86 CPUID access device .SH DESCRIPTION CPUID provides an interface for querying information about the x86 CPU. -.PP +.P This device is accessed by .BR lseek (2) or .BR pread (2) to the appropriate CPUID level and reading in chunks of 16 bytes. A larger read size means multiple reads of consecutive levels. -.PP +.P The lower 32 bits of the file position is used as the incoming .IR %eax , and the upper 32 bits of the file position as the incoming @@ -24,7 +24,7 @@ the latter is intended for "counting" .I eax levels like .IR eax=4 . -.PP +.P This driver uses .IR /dev/cpu/CPUNUM/cpuid , where @@ -34,7 +34,7 @@ and on an SMP box will direct the access to CPU .I CPUNUM as listed in .IR /proc/cpuinfo . -.PP +.P This file is protected so that it can be read only by the user .IR root , or members of the group @@ -44,7 +44,7 @@ The CPUID instruction can be directly executed by a program using inline assembler. However this device allows convenient access to all CPUs without changing process affinity. -.PP +.P Most of the information in .I cpuid is reported by the kernel in cooked form either in @@ -53,29 +53,31 @@ or through subdirectories in .IR /sys/devices/system/cpu . Direct CPUID access through this device should only be used in exceptional cases. -.PP +.P The .I cpuid driver is not auto-loaded. On modular kernels you might need to use the following command to load it explicitly before use: -.PP +.P .in +4n .EX $ modprobe cpuid .EE .in -.PP +.P There is no support for CPUID functions that require additional input registers. -.PP -Very old x86 CPUs don't support CPUID. +.P +Early i486 CPUs do not support the CPUID instruction; +.\" arch/x86/kernel/cpuid.c cpuid_open() +opening this device for those CPUs fails with EIO. .SH SEE ALSO .BR cpuid (1) -.PP +.P Intel Corporation, Intel 64 and IA-32 Architectures Software Developer's Manual Volume 2A: Instruction Set Reference, A-M, 3-180 CPUID reference. -.PP +.P Intel Corporation, Intel Processor Identification and the CPUID Instruction, Application note 485. diff --git a/man4/dsp56k.4 b/man4/dsp56k.4 index a7b2682..36a856d 100644 --- a/man4/dsp56k.4 +++ b/man4/dsp56k.4 @@ -4,16 +4,16 @@ .\" .\" Modified, Thu Jan 27 19:16:19 CET 2000, lars@nocrew.org .\" -.TH dsp56k 4 2023-03-08 "Linux man-pages 6.05.01" +.TH dsp56k 4 2023-10-31 "Linux man-pages 6.7" .SH NAME dsp56k \- DSP56001 interface device .SH SYNOPSIS .nf .B #include -.PP +.P .BI "ssize_t read(int " fd ", void *" data ", size_t " length ); .BI "ssize_t write(int " fd ", void *" data ", size_t " length ); -.PP +.P .BI "int ioctl(int " fd ", DSP56K_UPLOAD, struct dsp56k_upload *" program ); .BI "int ioctl(int " fd ", DSP56K_SET_TX_WSIZE, int " wsize ); .BI "int ioctl(int " fd ", DSP56K_SET_RX_WSIZE, int " wsize ); @@ -31,7 +31,7 @@ processor found in Atari Falcon030-compatible computers. The \fIdsp56k\fP special file is used to control the DSP56001, and to send and receive data using the bidirectional handshaked host port. -.PP +.P To send a data stream to the signal processor, use .BR write (2) to the @@ -41,7 +41,7 @@ to receive processed data. The data can be sent or received in 8, 16, 24, or 32-bit quantities on the host side, but will always be seen as 24-bit quantities in the DSP56001. -.PP +.P The following .BR ioctl (2) calls are used to control the diff --git a/man4/fd.4 b/man4/fd.4 index da04acb..e1aaacb 100644 --- a/man4/fd.4 +++ b/man4/fd.4 @@ -6,7 +6,7 @@ .\" .\" Modified, Sun Feb 26 15:00:02 1995, faith@cs.unc.edu .\" -.TH fd 4 2022-12-15 "Linux man-pages 6.05.01" +.TH fd 4 2023-10-31 "Linux man-pages 6.7" .SH NAME fd \- floppy disk device .SH CONFIGURATION @@ -26,14 +26,14 @@ number on its controller and 128 if the drive is on the secondary controller. In the following device tables, \fIn\fP represents the drive number. -.PP +.P \fBWarning: if you use formats with more tracks than supported by your drive, you may cause it mechanical damage.\fP Trying once if more tracks than the usual 40/80 are supported should not damage it, but no warranty is given for that. If you are not sure, don't create device entries for those formats, so as to prevent their usage. -.PP +.P Drive-independent device files which automatically detect the media format and capacity: .TS @@ -44,7 +44,7 @@ Name Base _ \fBfd\fP\fIn\fP 0 .TE -.PP +.P 5.25 inch double-density device files: .TS lw(1i) l l l l c @@ -54,7 +54,7 @@ Name Capacity Cyl. Sect. Heads Base _ \fBfd\fP\fIn\fP\fBd360\fP 360 40 9 2 4 .TE -.PP +.P 5.25 inch high-density device files: .TS lw(1i) l l l l c @@ -73,7 +73,7 @@ _ \fBfd\fP\fIn\fP\fBh1494\fP 1494 83 18 2 72 \fBfd\fP\fIn\fP\fBh1600\fP 1600 80 20 2 92 .TE -.PP +.P 3.5 inch double-density device files: .TS lw(1i) l l l l c @@ -87,7 +87,7 @@ _ \fBfd\fP\fIn\fP\fBu1040\fP 1040 80 13 2 84 \fBfd\fP\fIn\fP\fBu1120\fP 1120 80 14 2 88 .TE -.PP +.P 3.5 inch high-density device files: .TS lw(1i) l l l l c @@ -108,7 +108,7 @@ _ \fBfd\fP\fIn\fP\fBu1840\fP 1840 80 23 2 116 \fBfd\fP\fIn\fP\fBu1920\fP 1920 80 24 2 100 .TE -.PP +.P 3.5 inch extra-density device files: .TS lw(1i) l l l l c @@ -198,7 +198,7 @@ resets the floppy controller under certain conditions. .TP .B FDRAWCMD sends a raw command to the floppy controller. -.PP +.P For more precise information, consult also the \fI\fP and \fI\fP include files, as well as the .BR floppycontrol (1) @@ -211,11 +211,11 @@ However, if a floppy is formatted with an inter-sector gap that is too small, performance may drop, to the point of needing a few seconds to access an entire track. To prevent this, use interleaved formats. -.PP +.P It is not possible to read floppies which are formatted using GCR (group code recording), which is used by Apple II and Macintosh computers (800k disks). -.PP +.P Reading floppies which are hard sectored (one hole per sector, with the index hole being a little skewed) is not supported. This used to be common with older 8-inch floppies. diff --git a/man4/full.4 b/man4/full.4 index 654b74b..9d5289b 100644 --- a/man4/full.4 +++ b/man4/full.4 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" correction, aeb, 970825 -.TH full 4 2022-10-30 "Linux man-pages 6.05.01" +.TH full 4 2023-10-31 "Linux man-pages 6.7" .SH NAME full \- always full device .SH CONFIGURATION @@ -11,7 +11,7 @@ If your system does not have .I /dev/full created already, it can be created with the following commands: -.PP +.P .in +4n .EX mknod \-m 666 /dev/full c 1 7 @@ -23,18 +23,18 @@ The file .I /dev/full has major device number 1 and minor device number 7. -.PP +.P Writes to the .I /dev/full device fail with an .B ENOSPC error. This can be used to test how a program handles disk-full errors. -.PP +.P Reads from the .I /dev/full device will return \e0 characters. -.PP +.P Seeks on .I /dev/full will always succeed. diff --git a/man4/fuse.4 b/man4/fuse.4 index a68a7ea..fbdd918 100644 --- a/man4/fuse.4 +++ b/man4/fuse.4 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH fuse 4 2023-05-03 "Linux man-pages 6.05.01" +.TH fuse 4 2023-10-31 "Linux man-pages 6.7" .SH NAME fuse \- Filesystem in Userspace (FUSE) device .SH SYNOPSIS @@ -21,7 +21,7 @@ Those implementing a FUSE filesystem may wish to make use of a user-space library such as .I libfuse that abstracts away the low-level interface. -.PP +.P At its core, FUSE is a simple client-server protocol, in which the Linux kernel is the client and the daemon is the server. After obtaining a file descriptor for this device, the daemon may @@ -38,7 +38,7 @@ through the first file descriptor (and vice versa). .SS The basic protocol Every message that is read by the daemon begins with a header described by the following structure: -.PP +.P .in +4n .EX struct fuse_in_header { @@ -55,19 +55,19 @@ struct fuse_in_header { }; .EE .in -.PP +.P The header is followed by a variable-length data portion (which may be empty) specific to the requested operation (the requested operation is indicated by .IR opcode ). -.PP +.P The daemon should then process the request and if applicable send a reply (almost all operations require a reply; if they do not, this is documented below), by performing a .BR write (2) to the file descriptor. All replies must start with the following header: -.PP +.P .in +4n .EX struct fuse_out_header { @@ -79,7 +79,7 @@ struct fuse_out_header { }; .EE .in -.PP +.P This header is also followed by (potentially empty) variable-sized data depending on the executed request. However, if the reply is an error reply (i.e., @@ -494,7 +494,7 @@ file descriptor that has not been mounted. Linux. .SH NOTES The following messages are not yet documented in this manual page: -.PP +.P .\" FIXME: Document the following. .in +4n .EX diff --git a/man4/hd.4 b/man4/hd.4 index 4f91c6b..995468f 100644 --- a/man4/hd.4 +++ b/man4/hd.4 @@ -7,7 +7,7 @@ .\" Modified Mon Oct 21 21:38:51 1996 by Eric S. Raymond .\" (and some more by aeb) .\" -.TH hd 4 2023-02-05 "Linux man-pages 6.05.01" +.TH hd 4 2023-10-31 "Linux man-pages 6.7" .SH NAME hd \- MFM/IDE hard disk devices .SH DESCRIPTION @@ -25,7 +25,7 @@ is .B hdc and the slave is .BR hdd . -.PP +.P General IDE block device names have the form .BI hd X\c , or @@ -49,15 +49,15 @@ Thus, the first logical partition will be \&. Both DOS-type partitioning and BSD-disklabel partitioning are supported. You can have at most 63 partitions on an IDE disk. -.PP +.P For example, .I /dev/hda refers to all of the first IDE drive in the system; and .I /dev/hdb3 refers to the third DOS "primary" partition on the second one. -.PP +.P They are typically created by: -.PP +.P .in +4n .EX mknod \-m 660 /dev/hda b 3 0 diff --git a/man4/hpsa.4 b/man4/hpsa.4 index 28ba8cf..2145bf1 100644 --- a/man4/hpsa.4 +++ b/man4/hpsa.4 @@ -5,7 +5,7 @@ .\" .\" shorthand for double quote that works everywhere. .ds q \N'34' -.TH hpsa 4 2022-10-30 "Linux man-pages 6.05.01" +.TH hpsa 4 2023-10-31 "Linux man-pages 6.7" .SH NAME hpsa \- HP Smart Array SCSI driver .SH SYNOPSIS @@ -38,7 +38,7 @@ should still be used for these. The .B hpsa driver supports the following Smart Array boards: -.PP +.P .nf Smart Array P700M Smart Array P212 @@ -50,10 +50,10 @@ driver supports the following Smart Array boards: Smart Array P711m StorageWorks P1210m .fi -.PP +.P .\" commit 135ae6edeb51979d0998daf1357f149a7d6ebb08 Since Linux 4.14, the following Smart Array boards are also supported: -.PP +.P .nf Smart Array 5300 Smart Array 5312 @@ -161,7 +161,7 @@ This attribute contains the 16 hex-digit (8 byte) LUN ID by which a logical drive or physical device can be addressed. .IR c : b : t : l are the controller, bus, target, and lun of the device. -.PP +.P For example: .IP .in +4n @@ -185,7 +185,11 @@ The data structures used by these ioctls are described in the Linux kernel source file .IR include/linux/cciss_ioctl.h . .TP -.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD +.B CCISS_DEREGDISK +.TQ +.B CCISS_REGNEWDISK +.TQ +.B CCISS_REGNEWD These three ioctls all do exactly the same thing, which is to cause the driver to rescan for new devices. This does exactly the same thing as writing to the @@ -204,7 +208,9 @@ Returns driver version in three bytes encoded as: .EE .in .TP -.BR CCISS_PASSTHRU ", " CCISS_BIG_PASSTHRU +.B CCISS_PASSTHRU +.TQ +.B CCISS_BIG_PASSTHRU Allows "BMIC" and "CISS" commands to be passed through to the Smart Array. These are used extensively by the HP Array Configuration Utility, SNMP storage agents, and so on. @@ -221,7 +227,7 @@ for some examples. .BR cciss_vol_status (8), .BR hpacucli (8), .BR hpacuxe (8) -.PP +.P .UR http://cciss.sf.net .UE , and diff --git a/man4/initrd.4 b/man4/initrd.4 index 28a16ea..1490f8e 100644 --- a/man4/initrd.4 +++ b/man4/initrd.4 @@ -12,7 +12,7 @@ .\" phone: (302)654-5478 .\" .\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ -.TH initrd 4 2023-02-05 "Linux man-pages 6.05.01" +.TH initrd 4 2023-10-31 "Linux man-pages 6.7" .SH NAME initrd \- boot loader initialized RAM disk .SH CONFIGURATION @@ -27,14 +27,14 @@ with mode 0400 (read access by root only). If the Linux system does not have .I /dev/initrd already created, it can be created with the following commands: -.PP +.P .in +4n .EX mknod \-m 400 /dev/initrd b 1 250 chown root:disk /dev/initrd .EE .in -.PP +.P Also, support for both "RAM disk" and "Initial RAM disk" (e.g., .B CONFIG_BLK_DEV_RAM=y @@ -57,7 +57,7 @@ by the boot loader before the kernel is started. The kernel then can use .IR /dev/initrd "'s" contents for a two-phase system boot-up. -.PP +.P In the first boot-up phase, the kernel starts up and mounts an initial root filesystem from the contents of .I /dev/initrd @@ -233,7 +233,7 @@ For more information on setting the root filesystem see also the and .B LOADLIN documentation. -.PP +.P It is also possible for the .I /linuxrc executable to change the normal root device. @@ -265,19 +265,19 @@ and then writing 0xff (e.g., the pseudo-NFS-device number) into file For example, the following shell command line would change the normal root device to .IR /dev/hdb1 : -.PP +.P .in +4n .EX echo 0x365 >/proc/sys/kernel/real\-root\-dev .EE .in -.PP +.P For an NFS example, the following shell command lines would change the normal root device to the NFS directory .I /var/nfsroot on a local networked NFS server with IP number 193.8.232.7 for a system with IP number 193.8.232.2 and named "idefix": -.PP +.P .in +4n .EX echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name @@ -286,7 +286,7 @@ echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e echo 255 >/proc/sys/kernel/real\-root\-dev .EE .in -.PP +.P .BR Note : The use of .I /proc/sys/kernel/real\-root\-dev @@ -310,7 +310,7 @@ for information on the modern method of changing the root filesystem. The main motivation for implementing .B initrd was to allow for modular kernel configuration at system installation. -.PP +.P A possible system installation scenario is as follows: .IP (1) 5 The loader program boots from floppy or other media with a minimal kernel @@ -364,13 +364,13 @@ to a file.) .IP (9) The system is now bootable and additional installation tasks can be performed. -.PP +.P The key role of .I /dev/initrd in the above is to reuse the configuration data during normal system operation without requiring initial kernel selection, a large generic kernel or, recompiling the kernel. -.PP +.P A second scenario is for installations where Linux runs on systems with different hardware configurations in a single administrative network. In such cases, it may be desirable to use only a small set of kernels @@ -383,14 +383,14 @@ Then, only the file or a file executed by .I /linuxrc would be different. -.PP +.P A third scenario is more convenient recovery disks. Because information like the location of the root filesystem partition is not needed at boot time, the system loaded from .I /dev/initrd can use a dialog and/or auto-detection followed by a possible sanity check. -.PP +.P Last but not least, Linux distributions on CD-ROM may use .B initrd for easy installation from the CD-ROM. @@ -469,7 +469,7 @@ The behavior may change in future versions of the Linux kernel. .BR ram (4), .BR freeramdisk (8), .BR rdev (8) -.PP +.P .I Documentation/admin\-guide/initrd.rst .\" commit 9d85025b0418163fae079c9ba8f8445212de8568 (or diff --git a/man4/intro.4 b/man4/intro.4 index a2fa45e..bcfcee4 100644 --- a/man4/intro.4 +++ b/man4/intro.4 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 16:57:14 1993 by Rik Faith (faith@cs.unc.edu) -.TH intro 4 2023-02-05 "Linux man-pages 6.05.01" +.TH intro 4 2023-02-05 "Linux man-pages 6.7" .SH NAME intro \- introduction to special files .SH DESCRIPTION diff --git a/man4/lirc.4 b/man4/lirc.4 index dcaae9b..227172f 100644 --- a/man4/lirc.4 +++ b/man4/lirc.4 @@ -2,7 +2,7 @@ .\" Copyright (c) 2018, Sean Young .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH lirc 4 2023-05-03 "Linux man-pages 6.05.01" +.TH lirc 4 2023-10-31 "Linux man-pages 6.7" .SH NAME lirc \- lirc devices .SH DESCRIPTION @@ -13,7 +13,7 @@ bidirectional interface to infra-red (IR) remotes. Most of these devices can receive, and some can send. When receiving or sending data, the driver works in two different modes depending on the underlying hardware. -.PP +.P Some hardware (typically TV-cards) decodes the IR signal internally and provides decoded button presses as scancode values. Drivers for this kind of hardware work in @@ -23,7 +23,7 @@ Such hardware usually does not support sending IR signals. Furthermore, such hardware can only decode a limited set of IR protocols, usually only the protocol of the specific remote which is bundled with, for example, a TV-card. -.PP +.P Other hardware provides a stream of pulse/space durations. Such drivers work in .B LIRC_MODE_MODE2 @@ -39,7 +39,7 @@ and attached to the device. Sometimes, this kind of hardware also supports sending IR data. -.PP +.P The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether receiving and sending is supported, and in which modes, amongst other features. @@ -119,7 +119,7 @@ device cannot transmit. \& int ioctl(int fd, int cmd, int *val); .fi -.PP +.P The following .BR ioctl (2) operations are provided by the @@ -132,7 +132,7 @@ hardware settings. .TP 4 .BR LIRC_GET_FEATURES " (\fIvoid\fP)" Returns a bit mask of combined features bits; see FEATURES. -.PP +.P If a device returns an error code for .BR LIRC_GET_FEATURES , it is safe to assume it is not a @@ -215,8 +215,9 @@ describes the pulse width as a percentage of the total cycle. Currently, no special meaning is defined for 0 or 100, but the values are reserved for future use. .TP -.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ -LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" +.BI LIRC_GET_MIN_TIMEOUT( void ) +.TQ +.BI LIRC_GET_MAX_TIMEOUT( void ) Some devices have internal timers that can be used to detect when there has been no IR activity for a long time. This can help @@ -417,6 +418,6 @@ Users of older kernels could use the file bundled in .\" .SH SEE ALSO \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2) -.PP +.P .UR https://www.kernel.org/\:doc/\:html/\:latest/\:userspace\-api/\:media/\:rc/\:lirc\-dev.html .UE diff --git a/man4/loop.4 b/man4/loop.4 index 71c2e4a..273456c 100644 --- a/man4/loop.4 +++ b/man4/loop.4 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH loop 4 2023-05-03 "Linux man-pages 6.05.01" +.TH loop 4 2023-10-31 "Linux man-pages 6.7" .SH NAME loop, loop-control \- loop devices .SH SYNOPSIS @@ -20,7 +20,7 @@ image stored in a file, so that it can be mounted with the .BR mount (8) command. You could do -.PP +.P .in +4n .EX $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP @@ -30,14 +30,14 @@ $ \fBsudo mkdir /myloopdev\fP $ \fBsudo mount /dev/loop4 /myloopdev\fP .EE .in -.PP +.P See .BR losetup (8) for another example. -.PP +.P A transfer function can be specified for each loop device for encryption and decryption purposes. -.PP +.P The following .BR ioctl (2) operations are provided by the loop block device: @@ -214,12 +214,14 @@ explicitly request read-only mode by setting in .IR loop_config.info.lo_flags . .RE -.PP +.P Since Linux 2.6, there are two new .BR ioctl (2) operations: .TP -.BR LOOP_SET_STATUS64 ", " LOOP_GET_STATUS64 +.B LOOP_SET_STATUS64 +.TQ +.B LOOP_GET_STATUS64 These are similar to .BR LOOP_SET_STATUS " and " LOOP_GET_STATUS described above but use the @@ -293,7 +295,7 @@ device to find a free loop device, opens the loop device, opens a file to be used as the underlying storage for the device, and then associates the loop device with the backing store. The following shell session demonstrates the use of the program: -.PP +.P .in +4n .EX $ \fBdd if=/dev/zero of=file.img bs=1MiB count=10\fP diff --git a/man4/lp.4 b/man4/lp.4 index 16288ec..aa4376b 100644 --- a/man4/lp.4 +++ b/man4/lp.4 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified, Sun Feb 26 15:02:58 1995, faith@cs.unc.edu -.TH lp 4 2023-02-05 "Linux man-pages 6.05.01" +.TH lp 4 2023-02-05 "Linux man-pages 6.7" .SH NAME lp \- line printer devices .SH SYNOPSIS diff --git a/man4/mem.4 b/man4/mem.4 index 4ccb827..cfaa99c 100644 --- a/man4/mem.4 +++ b/man4/mem.4 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 16:59:10 1993 by Rik Faith (faith@cs.unc.edu) -.TH mem 4 2022-10-30 "Linux man-pages 6.05.01" +.TH mem 4 2023-10-31 "Linux man-pages 6.7" .SH NAME mem, kmem, port \- system memory, kernel memory and system ports .SH DESCRIPTION @@ -12,31 +12,31 @@ mem, kmem, port \- system memory, kernel memory and system ports is a character device file that is an image of the main memory of the computer. It may be used, for example, to examine (and even patch) the system. -.PP +.P Byte addresses in .I /dev/mem are interpreted as physical memory addresses. References to nonexistent locations cause errors to be returned. -.PP +.P Examining and patching is likely to lead to unexpected results when read-only or write-only bits are present. -.PP +.P Since Linux 2.6.26, and depending on the architecture, the .B CONFIG_STRICT_DEVMEM kernel configuration option limits the areas which can be accessed through this file. For example: on x86, RAM access is not allowed but accessing memory-mapped PCI regions is. -.PP +.P It is typically created by: -.PP +.P .in +4n .EX mknod \-m 660 /dev/mem c 1 1 chown root:kmem /dev/mem .EE .in -.PP +.P The file .I /dev/kmem is the same as @@ -46,23 +46,23 @@ rather than physical memory is accessed. Since Linux 2.6.26, this file is available only if the .B CONFIG_DEVKMEM kernel configuration option is enabled. -.PP +.P It is typically created by: -.PP +.P .in +4n .EX mknod \-m 640 /dev/kmem c 1 2 chown root:kmem /dev/kmem .EE .in -.PP +.P .I /dev/port is similar to .IR /dev/mem , but the I/O ports are accessed. -.PP +.P It is typically created by: -.PP +.P .in +4n .EX mknod \-m 660 /dev/port c 1 4 diff --git a/man4/mouse.4 b/man4/mouse.4 index 69278a0..21ff1a2 100644 --- a/man4/mouse.4 +++ b/man4/mouse.4 @@ -3,7 +3,7 @@ .\" Updates Nov 1998, Andries Brouwer .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH mouse 4 2023-02-05 "Linux man-pages 6.05.01" +.TH mouse 4 2023-10-31 "Linux man-pages 6.7" .SH NAME mouse \- serial mouse interface .SH CONFIGURATION @@ -13,7 +13,7 @@ for a description. .SH DESCRIPTION .SS Introduction The pinout of the usual 9 pin plug as used for serial mice is: -.PP +.P .TS center; r c l. @@ -24,15 +24,15 @@ pin name used for 7 RTS +12 V, Imax = 10 mA 5 GND Ground .TE -.PP +.P This is the specification, in fact 9 V suffices with most mice. -.PP +.P The mouse driver can recognize a mouse by dropping RTS to low and raising it again. About 14 ms later the mouse will send 0x4D (\[aq]M\[aq]) on the data line. After a further 63 ms, a Microsoft-compatible 3-button mouse will send 0x33 (\[aq]3\[aq]). -.PP +.P The relative mouse movement is sent as .I dx (positive means right) @@ -44,7 +44,7 @@ To select speeds, cycle through the speeds 9600, 4800, 2400, and 1200 bit/s, each time writing the two characters from the table below and waiting 0.1 seconds. The following table shows available speeds and the strings that select them: -.PP +.P .TS center; l l. @@ -54,7 +54,7 @@ bit/s string 2400 *o 1200 *n .TE -.PP +.P The first byte of a data packet can be used for synchronization purposes. .SS Microsoft protocol The @@ -72,7 +72,7 @@ two's-complement, .RI ( rb ) are set when the left (right) button is pressed: -.PP +.P .TS center; r c c c c c c c. @@ -117,7 +117,7 @@ values. .IR rb ) are cleared when the left (middle, right) button is pressed: -.PP +.P .TS center; r c c c c c c c c. @@ -128,7 +128,7 @@ byte d7 d6 d5 d4 d3 d2 d1 d0 4 0 dxb6 dxb5 dxb4 dxb3 dxb2 dxb1 dxb0 5 0 dyb6 dyb5 dyb4 dyb3 dyb2 dyb1 dyb0 .TE -.PP +.P Bytes 4 and 5 describe the change that occurred since bytes 2 and 3 were transmitted. .SS Sun protocol @@ -153,7 +153,7 @@ sign bit indicating a negative value. .IR rb ) are set when the left (middle, right) button is pressed: -.PP +.P .TS center; r c c c c c c c c. diff --git a/man4/msr.4 b/man4/msr.4 index c499a6e..6a6438c 100644 --- a/man4/msr.4 +++ b/man4/msr.4 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH msr 4 2022-10-30 "Linux man-pages 6.05.01" +.TH msr 4 2023-10-31 "Linux man-pages 6.7" .SH NAME msr \- x86 CPU MSR access device .SH DESCRIPTION @@ -13,13 +13,13 @@ registers (MSRs) of an x86 CPU. .I CPUNUM is the number of the CPU to access as listed in .IR /proc/cpuinfo . -.PP +.P The register access is done by opening the file and seeking to the MSR number as offset in the file, and then reading or writing in chunks of 8 bytes. An I/O transfer of more than 8 bytes means multiple reads or writes of the same register. -.PP +.P This file is protected so that it can be read and written only by the user .IR root , or members of the group @@ -30,7 +30,7 @@ The driver is not auto-loaded. On modular kernels you might need to use the following command to load it explicitly before use: -.PP +.P .in +4n .EX $ modprobe msr diff --git a/man4/null.4 b/man4/null.4 index c1299fb..0d59e4f 100644 --- a/man4/null.4 +++ b/man4/null.4 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 17:00:12 1993 by Rik Faith (faith@cs.unc.edu) -.TH null 4 2023-02-05 "Linux man-pages 6.05.01" +.TH null 4 2023-10-31 "Linux man-pages 6.7" .SH NAME null, zero \- data sink .SH DESCRIPTION @@ -13,7 +13,7 @@ Data written to the and .I /dev/zero special files is discarded. -.PP +.P Reads from .I /dev/null always return end of file (i.e., @@ -21,9 +21,9 @@ always return end of file (i.e., returns 0), whereas reads from .I /dev/zero always return bytes containing zero (\[aq]\e0\[aq] characters). -.PP +.P These devices are typically created by: -.PP +.P .in +4n .EX mknod \-m 666 /dev/null c 1 3 @@ -38,7 +38,7 @@ chown root:root /dev/null /dev/zero .SH NOTES If these devices are not writable and readable for all users, many programs will act strangely. -.PP +.P Since Linux 2.6.31, .\" commit 2b83868723d090078ac0e2120e06a1cc94dbaef0 reads from diff --git a/man4/pts.4 b/man4/pts.4 index d330907..db778d3 100644 --- a/man4/pts.4 +++ b/man4/pts.4 @@ -5,7 +5,7 @@ .\" Redistribute and revise at will. .\" %%%LICENSE_END .\" -.TH pts 4 2022-10-30 "Linux man-pages 6.05.01" +.TH pts 4 2023-10-31 "Linux man-pages 6.7" .SH NAME ptmx, pts \- pseudoterminal master and slave .SH DESCRIPTION @@ -15,7 +15,7 @@ The file is a character file with major number 5 and minor number 2, usually with mode 0666 and ownership root:root. It is used to create a pseudoterminal master and slave pair. -.PP +.P When a process opens .IR /dev/ptmx , it gets a file @@ -29,19 +29,19 @@ is an independent pseudoterminal master with its own associated slave, whose path can be found by passing the file descriptor to .BR ptsname (3). -.PP +.P Before opening the pseudoterminal slave, you must pass the master's file descriptor to .BR grantpt (3) and .BR unlockpt (3). -.PP +.P Once both the pseudoterminal master and slave are open, the slave provides processes with an interface that is identical to that of a real terminal. -.PP +.P Data written to the slave is presented on the master file descriptor as input. Data written to the master is presented to the slave as input. -.PP +.P In practice, pseudoterminals are used for implementing terminal emulators such as .BR xterm (1), @@ -52,7 +52,7 @@ programs such as .BR sshd (8), in which data read from the pseudoterminal master is sent across the network to a client program that is connected to a terminal or terminal emulator. -.PP +.P Pseudoterminals can also be used to send input to programs that normally refuse to read input from pipes (such as .BR su (1), diff --git a/man4/ram.4 b/man4/ram.4 index 04ba495..6c4e037 100644 --- a/man4/ram.4 +++ b/man4/ram.4 @@ -4,16 +4,16 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 17:01:11 1993 by Rik Faith (faith@cs.unc.edu) -.TH ram 4 2022-10-30 "Linux man-pages 6.05.01" +.TH ram 4 2023-10-31 "Linux man-pages 6.7" .SH NAME ram \- ram disk device .SH DESCRIPTION The .I ram device is a block device to access the ram disk in raw mode. -.PP +.P It is typically created by: -.PP +.P .in +4n .EX mknod \-m 660 /dev/ram b 1 1 diff --git a/man4/random.4 b/man4/random.4 index 0f0eb21..7a1d15d 100644 --- a/man4/random.4 +++ b/man4/random.4 @@ -9,13 +9,13 @@ .\" 2008-06-20, George Spelvin , .\" Matt Mackall .\" -.TH random 4 2023-04-18 "Linux man-pages 6.05.01" +.TH random 4 2023-10-31 "Linux man-pages 6.7" .SH NAME random, urandom \- kernel random number source devices .SH SYNOPSIS .nf #include -.PP +.P .BI "int ioctl(" fd ", RND" request ", " param ");" .fi .SH DESCRIPTION @@ -28,27 +28,27 @@ has major device number 1 and minor device number 8. The file .I /dev/urandom has major device number 1 and minor device number 9. -.PP +.P The random number generator gathers environmental noise from device drivers and other sources into an entropy pool. The generator also keeps an estimate of the number of bits of noise in the entropy pool. From this entropy pool, random numbers are created. -.PP +.P Linux 3.17 and later provides the simpler and safer .BR getrandom (2) interface which requires no special files; see the .BR getrandom (2) manual page for details. -.PP +.P When read, the .I /dev/urandom device returns random bytes using a pseudorandom number generator seeded from the entropy pool. Reads from this device do not block (i.e., the CPU is not yielded), but can incur an appreciable delay when requesting large amounts of data. -.PP +.P When read during early boot time, .I /dev/urandom may return data prior to the entropy pool being initialized. @@ -57,7 +57,7 @@ may return data prior to the entropy pool being initialized. If this is of concern in your application, use .BR getrandom (2) or \fI/dev/random\fP instead. -.PP +.P The \fI/dev/random\fP device is a legacy interface which dates back to a time where the cryptographic primitives used in the implementation of \fI/dev/urandom\fP were not widely trusted. @@ -65,7 +65,7 @@ It will return random bytes only within the estimated number of bits of fresh noise in the entropy pool, blocking if necessary. \fI/dev/random\fP is suitable for applications that need high quality randomness, and can afford indeterminate delays. -.PP +.P When the entropy pool is empty, reads from \fI/dev/random\fP will block until additional environmental noise is gathered. Since Linux 5.6, the @@ -89,7 +89,7 @@ will return \-1 and .I errno will be set to .BR EAGAIN . -.PP +.P The .B O_NONBLOCK flag has no effect when opening @@ -104,7 +104,7 @@ Reads with a buffer over this limit may return less than the requested number of bytes or fail with the error .BR EINTR , if interrupted by a signal handler. -.PP +.P Since Linux 3.16, .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc a @@ -119,7 +119,7 @@ from will return at most 512 bytes .\" SEC_XFER_SIZE in drivers/char/random.c (340 bytes before Linux 2.6.12). -.PP +.P Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the entropy pool with the data written, but this will not result in a higher entropy count. @@ -137,7 +137,7 @@ these applications, .BR getrandom (2) must be used instead, because it will block until the entropy pool is initialized. -.PP +.P If a seed file is saved across reboots as recommended below, the output is cryptographically secure against attackers without local root access as @@ -156,7 +156,7 @@ entropy is not immediately available. If your system does not have \fI/dev/random\fP and \fI/dev/urandom\fP created already, they can be created with the following commands: -.PP +.P .in +4n .EX mknod \-m 666 /dev/random c 1 8 @@ -164,7 +164,7 @@ mknod \-m 666 /dev/urandom c 1 9 chown root:root /dev/random /dev/urandom .EE .in -.PP +.P When a Linux system starts up without much operator interaction, the entropy pool may be in a fairly predictable state. This reduces the actual amount of noise in the entropy pool @@ -173,7 +173,7 @@ In order to counteract this effect, it helps to carry entropy pool information across shut-downs and start-ups. To do this, add the lines to an appropriate script which is run during the Linux system start-up sequence: -.PP +.P .in +4n .EX echo "Initializing random number generator..." @@ -192,10 +192,10 @@ bytes=$(expr $bits / 8) dd if=/dev/urandom of=$random_seed count=1 bs=$bytes .EE .in -.PP +.P Also, add the following lines in an appropriate script which is run during the Linux system shutdown: -.PP +.P .in +4n .EX # Carry a random seed from shut\-down to start\-up @@ -210,7 +210,7 @@ bytes=$(expr $bits / 8) dd if=/dev/urandom of=$random_seed count=1 bs=$bytes .EE .in -.PP +.P In the above examples, we assume Linux 2.6.0 or later, where .I /proc/sys/kernel/random/poolsize returns the size of the entropy pool in bits (see below). @@ -321,7 +321,9 @@ is the buffer of size .I buf_size which gets added to the entropy pool. .TP -.BR RNDZAPENTCNT ", " RNDCLEARPOOL +.B RNDZAPENTCNT +.TQ +.B RNDCLEARPOOL Zero the entropy count of all pools and add some system data (such as wall clock) to the pools. .SH FILES @@ -343,5 +345,5 @@ may return data prior to the entropy pool being initialized. .BR mknod (1), .BR getrandom (2), .BR random (7) -.PP +.P RFC\ 1750, "Randomness Recommendations for Security" diff --git a/man4/rtc.4 b/man4/rtc.4 index aae4fc2..5a04a7b 100644 --- a/man4/rtc.4 +++ b/man4/rtc.4 @@ -8,30 +8,30 @@ .\" 2006-02-08 Various additions by mtk .\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell .\" -.TH rtc 4 2023-02-05 "Linux man-pages 6.05.01" +.TH rtc 4 2023-10-31 "Linux man-pages 6.7" .SH NAME rtc \- real-time clock .SH SYNOPSIS .nf #include -.PP +.P .BI "int ioctl(" fd ", RTC_" request ", " param ");" .fi .SH DESCRIPTION This is the interface to drivers for real-time clocks (RTCs). -.PP +.P Most computers have one or more hardware clocks which record the current "wall clock" time. These are called "Real Time Clocks" (RTCs). One of these usually has battery backup power so that it tracks the time even while the computer is turned off. RTCs often provide alarms and other interrupts. -.PP +.P All i386 PCs, and ACPI-based systems, have an RTC that is compatible with the Motorola MC146818 chip on the original PC/AT. Today such an RTC is usually integrated into the mainboard's chipset (south bridge), and uses a replaceable coin-sized backup battery. -.PP +.P Non-PC systems, such as embedded systems built around system-on-chip processors, use other implementations. They usually won't offer the same functionality as the RTC from a PC/AT. @@ -47,7 +47,7 @@ defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). (One common implementation counts timer interrupts, once per "jiffy", at a frequency of 100, 250, or 1000 Hz.) That is, it is supposed to report wall clock time, which RTCs also do. -.PP +.P A key difference between an RTC and the system clock is that RTCs run even when the system is in a low power state (including "off"), and the system clock can't. @@ -63,7 +63,7 @@ RTCs can be read and written with or directly with the .BR ioctl (2) requests listed below. -.PP +.P Besides tracking the date and time, many RTCs can also generate interrupts .IP \[bu] 3 @@ -73,7 +73,7 @@ at periodic intervals with a frequency that can be set to any power-of-2 multiple in the range 2 Hz to 8192 Hz; .IP \[bu] on reaching a previously specified alarm time. -.PP +.P Each of those interrupt sources can be enabled or disabled separately. On many systems, the alarm interrupt can be configured as a system wakeup event, which can resume the system from a low power state such as @@ -82,7 +82,7 @@ Hibernation (called S4 in ACPI systems), or even "off" (called S5 in ACPI systems). On some systems, the battery backed RTC can't issue interrupts, but another one can. -.PP +.P The .I /dev/rtc (or @@ -145,7 +145,9 @@ RTC's time the process must be privileged (i.e., have the .B CAP_SYS_TIME capability). .TP -.BR RTC_ALM_READ ", " RTC_ALM_SET +.B RTC_ALM_READ +.TQ +.B RTC_ALM_SET Read and set the alarm time, for RTCs that support alarms. The alarm interrupt must be separately enabled or disabled using the .BR RTC_AIE_ON ", " RTC_AIE_OFF @@ -162,7 +164,9 @@ and .I tm_hour fields of this structure are used. .TP -.BR RTC_IRQP_READ ", " RTC_IRQP_SET +.B RTC_IRQP_READ +.TQ +.B RTC_IRQP_SET Read and set the frequency for periodic interrupts, for RTCs that support periodic interrupts. The periodic interrupt must be separately enabled or disabled using the @@ -184,20 +188,26 @@ capability) can set frequencies above the value specified in .IR /proc/sys/dev/rtc/max\-user\-freq . (This file contains the value 64 by default.) .TP -.BR RTC_AIE_ON ", " RTC_AIE_OFF +.B RTC_AIE_ON +.TQ +.B RTC_AIE_OFF Enable or disable the alarm interrupt, for RTCs that support alarms. The third .BR ioctl (2) argument is ignored. .TP -.BR RTC_UIE_ON ", " RTC_UIE_OFF +.B RTC_UIE_ON +.TQ +.B RTC_UIE_OFF Enable or disable the interrupt on every clock update, for RTCs that support this once-per-second interrupt. The third .BR ioctl (2) argument is ignored. .TP -.BR RTC_PIE_ON ", " RTC_PIE_OFF +.B RTC_PIE_ON +.TQ +.B RTC_PIE_OFF Enable or disable the periodic interrupt, for RTCs that support these periodic interrupts. The third @@ -209,7 +219,9 @@ capability) can enable the periodic interrupt if the frequency is currently set above the value specified in .IR /proc/sys/dev/rtc/max\-user\-freq . .TP -.BR RTC_EPOCH_READ ", " RTC_EPOCH_SET +.B RTC_EPOCH_READ +.TQ +.B RTC_EPOCH_SET Many RTCs encode the year in an 8-bit register which is either interpreted as an 8-bit binary number or as a BCD number. In both cases, @@ -232,10 +244,12 @@ To set the RTC's Epoch the process must be privileged (i.e., have the .B CAP_SYS_TIME capability). .TP -.BR RTC_WKALM_RD ", " RTC_WKALM_SET +.B RTC_WKALM_RD +.TQ +.B RTC_WKALM_SET Some RTCs support a more powerful alarm interface, using these ioctls to read or write the RTC's alarm time (respectively) with this structure: -.PP +.P .RS .in +4n .EX @@ -278,7 +292,13 @@ A pointer to this structure should be passed as the third argument. .SH FILES .TP -.IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc." +.I /dev/rtc +.TQ +.I /dev/rtc0 +.TQ +.I /dev/rtc1 +.TQ +\&.\|.\|. RTC special character device files. .TP .I /proc/driver/rtc @@ -290,21 +310,21 @@ reference using it will update a designated RTC periodically every 11 minutes. To do so, the kernel has to briefly turn off periodic interrupts; this might affect programs using that RTC. -.PP +.P An RTC's Epoch has nothing to do with the POSIX Epoch which is used only for the system clock. -.PP +.P If the year according to the RTC's Epoch and the year register is less than 1970 it is assumed to be 100 years later, that is, between 2000 and 2069. -.PP +.P Some RTCs support "wildcard" values in alarm fields, to support scenarios like periodic alarms at fifteen minutes after every hour, or on the first day of each month. Such usage is nonportable; portable user-space code expects only a single alarm interrupt, and will either disable or reinitialize the alarm after receiving it. -.PP +.P Some RTCs support periodic interrupts with periods that are multiples of a second rather than fractions of a second; multiple alarms; @@ -322,6 +342,6 @@ capabilities that are not currently exposed by this API. .BR gmtime (3), .BR time (7), .BR hwclock (8) -.PP +.P .I Documentation/rtc.txt in the Linux kernel source tree diff --git a/man4/sd.4 b/man4/sd.4 index b465124..a2bf814 100644 --- a/man4/sd.4 +++ b/man4/sd.4 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sd 4 2023-02-05 "Linux man-pages 6.05.01" +.TH sd 4 2023-10-31 "Linux man-pages 6.7" .SH NAME sd \- driver for SCSI disk drives .SH SYNOPSIS @@ -22,7 +22,7 @@ is a number denoting the partition on that physical drive. Often, the partition number, .IR p , will be left off when the device corresponds to the whole drive. -.PP +.P SCSI disks have a major device number of 8, and a minor device number of the form (16 * .IR drive_number ") + " partition_number , @@ -37,7 +37,7 @@ partition 0 is the whole drive partitions 1\[en]4 are the DOS "primary" partitions .IP \[bu] partitions 5\[en]8 are the DOS "extended" (or "logical") partitions -.PP +.P For example, .I /dev/sda will have major 8, minor 0, and will refer to all of the first SCSI drive @@ -45,7 +45,7 @@ in the system; and .I /dev/sdb3 will have major 8, minor 19, and will refer to the third DOS "primary" partition on the second SCSI drive in the system. -.PP +.P At this time, only block devices are provided. Raw devices have not yet been implemented. .SH DESCRIPTION @@ -55,7 +55,7 @@ are provided: .TP .B HDIO_GETGEO Returns the BIOS disk parameters in the following structure: -.PP +.P .in +4n .EX struct hd_geometry { diff --git a/man4/sk98lin.4 b/man4/sk98lin.4 index a8cbbbc..808a769 100644 --- a/man4/sk98lin.4 +++ b/man4/sk98lin.4 @@ -6,7 +6,7 @@ .\" .\" This manpage can be viewed using `groff -Tascii -man sk98lin.4 | less` .\" -.TH sk98lin 4 2023-07-28 "Linux man-pages 6.05.01" +.TH sk98lin 4 2023-10-31 "Linux man-pages 6.7" .SH NAME sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21 .SH SYNOPSIS @@ -46,27 +46,27 @@ sk98lin \- Marvell/SysKonnect Gigabit Ethernet driver v6.21 .hy 0 .BR Note : This obsolete driver was removed in Linux 2.6.26. -.PP +.P .B sk98lin is the Gigabit Ethernet driver for Marvell and SysKonnect network adapter cards. It supports SysKonnect SK-98xx/SK-95xx compliant Gigabit Ethernet Adapter and any Yukon compliant chipset. -.PP +.P When loading the driver using insmod, parameters for the network adapter cards might be stated as a sequence of comma separated commands. If for instance two network adapters are installed and AutoNegotiation on Port A of the first adapter should be ON, but on the Port A of the second adapter switched OFF, one must enter: -.PP +.P .in +4n .EX insmod sk98lin.o AutoNeg_A=On,Off .EE .in -.PP +.P After .B sk98lin is bound to one or more adapter cards and the @@ -81,7 +81,7 @@ where .I x is the number of the interface that has been assigned to a dedicated port by the system. -.PP +.P If loading is finished, any desired IP address can be assigned to the respective .I eth[x] @@ -91,7 +91,7 @@ command. This causes the adapter to connect to the Ethernet and to display a status message on the console saying "ethx: network connection up using port y" followed by the configured or detected connection parameters. -.PP +.P The .B sk98lin also supports large frames (also called jumbo frames). @@ -107,22 +107,22 @@ command with the mtu parameter. If for instance eth0 needs an IP address and a large frame MTU size, the following two commands might be used: -.PP +.P .in +4n .EX ifconfig eth0 10.1.1.1 ifconfig eth0 mtu 9000 .EE .in -.PP +.P Those two commands might even be combined into one: -.PP +.P .in +4n .EX ifconfig eth0 10.1.1.1 mtu 9000 .EE .in -.PP +.P Note that large frames can be used only if permitted by your network infrastructure. This means, that any switch being used in your Ethernet must @@ -135,23 +135,23 @@ In addition to the switches inside the network, all network adapters that are to be used must also be enabled regarding jumbo frames. If an adapter is not set to receive large frames, it will simply drop them. -.PP +.P Switching back to the standard Ethernet frame size can be done by using the .BR ifconfig (8) command again: -.PP +.P .in +4n .EX ifconfig eth0 mtu 1500 .EE .in -.PP +.P The Marvell/SysKonnect Gigabit Ethernet driver for Linux is able to support VLAN and Link Aggregation according to IEEE standards 802.1, 802.1q, and 802.3ad. Those features are available only after installation of open source modules which can be found on the Internet: -.PP +.P .IR VLAN : .UR http://www.candelatech.com\:/\[ti]greear\:/vlan.html .UE @@ -160,7 +160,7 @@ which can be found on the Internet: .IR Aggregation : .UR http://www.st.rim.or.jp\:/\[ti]yumo .UE -.PP +.P Note that Marvell/SysKonnect does not offer any support for these open source modules and does not take the responsibility for any kind of failures or problems arising when using these modules. diff --git a/man4/smartpqi.4 b/man4/smartpqi.4 index ce1f5b7..5e9f25c 100644 --- a/man4/smartpqi.4 +++ b/man4/smartpqi.4 @@ -1,13 +1,13 @@ '\" t -.\" Copyright (C) 2019, Microchip Technology Inc. and its subsidiaries +.\" Copyright (C) 2019-2023, Microchip Technology Inc. and its subsidiaries .\" Copyright (C) 2016-2018, Microsemi Corporation .\" Copyright (C) 2016, PMC-Sierra, Inc. -.\" Written by Kevin Barnett +.\" Written by Kevin Barnett .\" .\" SPDX-License-Identifier: GPL-2.0-only -.TH smartpqi 4 2022-12-15 "Linux man-pages 6.05.01" +.TH smartpqi 4 2023-10-31 "Linux man-pages 6.7" .SH NAME -smartpqi \- Microsemi Smart Family SCSI driver +smartpqi \- Microchip Smart Storage SCSI driver .SH SYNOPSIS .SY "modprobe smartpqi" .RB [ disable_device_id_wildcards= { 0 | 1 }] @@ -16,10 +16,12 @@ smartpqi \- Microsemi Smart Family SCSI driver .RB [ lockup_action= { none | reboot | panic }] .RB [ expose_ld_first= { 0 | 1 }] .RB [ hide_vsep= { 0 | 1 }] +.RB [ disable_managed_interrupts= { 0 | 1 }] +.RB [ ctrl_ready_timeout= { 0 |[ 30 , 1800 ]}] .YS .SH DESCRIPTION .B smartpqi -is a SCSI driver for Microsemi Smart Family controllers. +is a SCSI driver for Microchip Smart Storage controllers. .SS Supported \f[BI]ioctl\fP\/() operations For compatibility with applications written for the .BR cciss (4) @@ -36,7 +38,11 @@ The data structures used by these operations are described in the Linux kernel source file .IR include/linux/cciss_ioctl.h . .TP -.BR CCISS_DEREGDISK ", " CCISS_REGNEWDISK ", " CCISS_REGNEWD +.B CCISS_DEREGDISK +.TQ +.B CCISS_REGNEWDISK +.TQ +.B CCISS_REGNEWD These operations all do exactly the same thing, which is to cause the driver to re-scan for new devices. @@ -66,17 +72,17 @@ Allows BMIC and CISS commands to be passed through to the controller. .TP .BR disable_device_id_wildcards= { 0 | 1 } Disables support for device ID wildcards. -The default value is 0. +The default value is 0 (wildcards are enabled). .TP .BR disable_heartbeat= { 0 | 1 } Disables support for the controller's heartbeat check. This parameter is used for debugging purposes. -The default value is 0, leaving the controller's heartbeat check active. +The default value is 0 (the controller's heartbeat check is enabled). .TP .BR disable_ctrl_shutdown= { 0 | 1 } Disables support for shutting down the controller in the event of a controller lockup. -The default value is 0. +The default value is 0 (controller will be shut down). .TP .BR lockup_action= { none | reboot | panic } Specifies the action the driver takes when a controller @@ -94,17 +100,29 @@ parameter action .TE .TP .BR expose_ld_first= { 0 | 1 } -This option enables support for exposing logical devices to -the operating system before physical devices. -The default value is 0. +This option exposes logical devices to the OS before physical devices. +The default value is 0 (physical devices exposed first). .TP .BR hide_vsep= { 0 | 1 } -This option enables disabling exposure of the virtual SEP to the host. -This is usually associated with direct attached drives. -The default value is 0. +This option disables exposure of the virtual SEP to the OS. +The default value is 0 (virtual SEP is exposed). +.TP +.BR disable_managed_interrupts= { 0 | 1 } +Disables driver utilization of Linux kernel managed interrupts for controllers. +The managed interrupts feature automatically distributes interrupts +to all available CPUs and assigns SMP affinity. +The default value is 0 (managed interrupts enabled). +.TP +.BR ctrl_ready_timeout= { 0 |[ 30 , 1800 ]} +This option specifies the timeout in seconds for the driver to wait +for the controller to be ready. +The valid range is 0 or +.RB [ 30 ", " 1800 ]. +The default value is 0, +which causes the driver to use a timeout of 180 seconds. .SH FILES .SS Device nodes -Logical drives are accessed via the SCSI disk driver +Disk drives are accessed via the SCSI disk driver .RI ( sd ), tape drives via the SCSI tape driver .RI ( st ), @@ -124,30 +142,12 @@ The host attribute is a write-only attribute. Writing to this attribute will cause the driver to scan for new, changed, or removed devices (e.g., hot-plugged tape drives, or newly -configured or deleted logical drives) and notify the SCSI mid-layer of +configured or deleted logical volumes) and notify the SCSI mid-layer of any changes detected. Usually this action is triggered automatically by configuration changes, so the user should not normally have to write to this file. Doing so may be useful when hot-plugging devices such as tape drives or -entire storage boxes containing pre-configured logical drives. -.TP -.IR /sys/class/scsi_host/host * /version -The host -.I version -attribute is a read-only attribute. -This attribute contains the driver version and the controller firmware -version. -.IP -For example: -.IP -.in +4n -.EX -$ \c -.B cat /sys/class/scsi_host/host1/version -driver: 1.1.2\-126 -firmware: 1.29\-112 -.EE -.in +entire storage boxes containing pre-configured logical volumes. .TP .IR /sys/class/scsi_host/host * /lockup_action The host @@ -162,7 +162,7 @@ for an explanation of the .I lockup_action values. .TP -.I /sys/class/scsi_host/host*/driver_version +.IR /sys/class/scsi_host/host * /driver_version The .I driver_version attribute is read-only. @@ -178,7 +178,7 @@ $ \c .EE .in .TP -.I /sys/class/scsi_host/host*/firmware_version +.IR /sys/class/scsi_host/host * /firmware_version The .I firmware_version attribute is read-only. @@ -194,7 +194,7 @@ $ \c .EE .in .TP -.I /sys/class/scsi_host/host*/model +.IR /sys/class/scsi_host/host * /model The .I model attribute is read-only. @@ -210,7 +210,7 @@ $ \c .EE .in .TP -.I /sys/class/scsi_host/host*/serial_number +.IR /sys/class/scsi_host/host * /serial_number The .I serial_number attribute is read-only. @@ -226,7 +226,7 @@ $ \c .EE .in .TP -.I /sys/class/scsi_host/host*/vendor +.IR /sys/class/scsi_host/host * /vendor The .I vendor attribute is read-only. @@ -241,6 +241,69 @@ $ \c Adaptec .EE .in +.TP +.IR /sys/class/scsi_host/host * /enable_stream_detection +The +.I enable_stream_detection +attribute is read-write. +This attribute enables/disables stream detection in the driver. +Enabling stream detection can improve sequential write performance +for ioaccel-enabled volumes. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +The default value is 1 (stream detection enabled). +.IP +Enable example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_host/host1/enable_stream_detection +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /enable_r5_writes +The +.I enable_r5_writes +attribute is read-write. +This attribute enables/disables RAID 5 write operations +for ioaccel-enabled volumes. +Enabling can improve sequential write performance. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +The default value is 1 (RAID 5 writes enabled). +.IP +Enable example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_host/host1/enable_r5_writes +.EE +.in +.TP +.IR /sys/class/scsi_host/host * /enable_r6_writes +The +.I enable_r6_writes +attribute is read-write. +This attribute enables/disables RAID 6 write operations +for ioaccel-enabled volumes. +Enabling can improve sequential write performance. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +The default value is 1 (RAID 6 writes enabled). +.IP +Enable example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_host/host1/enable_r6_writes +.EE +.in .SS SmartPQI-specific disk attribute files in \f[BI]/sys\fP In the file specifications below, .I c @@ -256,7 +319,7 @@ is the logical unit number (LUN). The .I raid_level attribute is read-only. -This attribute contains the RAID level of each logical drive. +This attribute contains the RAID level of the logical volume. .IP For example: .IP @@ -268,11 +331,11 @@ RAID 0 .EE .in .TP -.IR /sys/class/scsi_disk/c : b : t : l/device/sas_address +.IR /sys/class/scsi_disk/ c : b : t : l /device/sas_address The .I sas_address attribute is read-only. -This attribute contains the unique identifier of the disk. +This attribute contains the SAS address of the device. .IP For example: .IP @@ -284,7 +347,7 @@ $ \c .EE .in .TP -.IR /sys/class/scsi_disk/c : b : t : l/device/ssd_smart_path_enabled +.IR /sys/class/scsi_disk/ c : b : t : l /device/ssd_smart_path_enabled The .I ssd_smart_path_enabled attribute is read-only. @@ -305,22 +368,129 @@ $ \c 0 .EE .in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/lunid +The +.I lunid +attribute is read-only. +This attribute contains the SCSI LUN ID for the device. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/lunid +0x0300004000000000 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/unique_id +The +.I unique_id +attribute is read-only. +This attribute contains a 16-byte ID +that uniquely identifies the device within the controller. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/unique_id +600508B1001C6D4723A8E98D704FDB94 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/path_info +The +.I path_info +attribute is read-only. +This attribute contains the +.IR c : b : t : l +of the device +along with the device type +and whether the device is Active or Inactive. +If the device is an HBA device, +.I path_info +will also display the PORT, BOX, and BAY the device is plugged into. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/path_info +[13:1:0:3] Direct-Access Active +\& +$ \c +.B cat /sys/class/scsi_disk/12:0:9:0/device/path_info +[12:0:9:0] Direct-Access PORT: C1 BOX: 1 BAY: 14 Inactive +[12:0:9:0] Direct-Access PORT: C0 BOX: 1 BAY: 14 Active +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/raid_bypass_cnt +The +.I raid_bypass_cnt +attribute is read-only. +This attribute contains the number of I/O requests +that have gone through the ioaccel path +for ioaccel-enabled volumes. +See the +.B ssd_smart_path_enabled +disk attribute section for details on ioaccel-enabled volumes. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B cat /sys/class/scsi_disk/13:1:0:3/device/raid_bypass_cnt +0x300 +.EE +.in +.TP +.IR /sys/class/scsi_disk/ c : b : t : l /device/sas_ncq_prio_enable +The +.I sas_ncq_prio_enable +attribute is read/write. +This attribute enables SATA NCQ priority support. +This attribute works only when device has NCQ support +and controller firmware can handle IO with NCQ priority attribute. +.IP +For example: +.IP +.in +4n +.EX +$ \c +.B echo 1 > /sys/class/scsi_disk/13:1:0:3/device/sas_ncq_prio_enable +.EE +.in .SH VERSIONS The .B smartpqi driver was added in Linux 4.9. .SH NOTES .SS Configuration -To configure a Microsemi Smart Family controller, +To configure a Microchip Smart Storage controller, refer to the User Guide for the controller, which can be found by searching for the specific controller at -.UR https://storage.microsemi.com/ +.UR https://www.microchip.com/design-centers/storage .UE . +.SH HISTORY +.I /sys/class/scsi_host/host*/version +was replaced by two sysfs entries: +.IP +.I /sys/class/scsi_host/host*/driver_version +.IP +.I /sys/class/scsi_host/host*/firmware_version .SH SEE ALSO .BR cciss (4), .BR hpsa (4), .BR sd (4), -.BR st (4) -.PP +.BR st (4), +.BR sg (4) +.P .I Documentation/ABI/testing/sysfs\-bus\-pci\-devices\-cciss in the Linux kernel source tree. diff --git a/man4/st.4 b/man4/st.4 index 254aec0..7366a22 100644 --- a/man4/st.4 +++ b/man4/st.4 @@ -2,13 +2,13 @@ .\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi) .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH st 4 2023-02-05 "Linux man-pages 6.05.01" +.TH st 4 2023-10-31 "Linux man-pages 6.7" .SH NAME st \- SCSI tape device .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);" .BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd ); .BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status ); @@ -23,7 +23,7 @@ Currently, the driver takes control of all detected devices of type The .B st driver uses major device number 9. -.PP +.P Each device uses eight minor device numbers. The lowermost five bits in the minor numbers are assigned sequentially in the order of @@ -43,7 +43,7 @@ Devices opened using the \[lq]no-rewind\[rq] device number will not. for instance, mt does not lead to the desired result: the tape is rewound after the mt command and the next command starts from the beginning of the tape). -.PP +.P Within each group, four minor numbers are available to define devices with different characteristics (block size, compression, density, etc.) @@ -57,9 +57,9 @@ drive. The default allocation allows control of 32 tape drives. For instance, it is possible to control up to 64 tape drives with two minor numbers for different options.) -.PP +.P Devices are typically created by: -.PP +.P .in +4n .EX mknod \-m 666 /dev/st0 c 9 0 @@ -72,9 +72,9 @@ mknod \-m 666 /dev/nst0m c 9 192 mknod \-m 666 /dev/nst0a c 9 224 .EE .in -.PP +.P There is no corresponding block device. -.PP +.P The driver uses an internal buffer that has to be large enough to hold at least one tape block. Before Linux 2.1.121, the buffer is @@ -89,7 +89,7 @@ By default, the maximum number of parts is 16. This means that the maximum block size is very large (2\ MB if allocation of 16 blocks of 128\ kB succeeds). -.PP +.P The driver's internal buffer size is determined by a compile-time constant which can be overridden with a kernel startup option. In addition to this, the driver tries to allocate a larger temporary @@ -98,7 +98,7 @@ However, run-time allocation of large contiguous blocks of memory may fail and it is advisable not to rely too much on dynamic buffer allocation before Linux 2.1.121 (this applies also to demand-loading the driver with kerneld or kmod). -.PP +.P The driver does not specifically support any tape drive brand or model. After system start-up the tape device options are defined by @@ -111,7 +111,7 @@ be changed with explicit calls and remain in effect when the device is closed and reopened. Setting the options affects both the auto-rewind and the nonrewind device. -.PP +.P Different options can be specified for the different devices within the subgroup of four. The options take effect when the device is @@ -120,7 +120,7 @@ For example, the system administrator can define one device that writes in fixed-block mode with a certain block size, and one which writes in variable-block mode (if the drive supports both modes). -.PP +.P The driver supports .B tape partitions if they are supported by the drive. @@ -143,12 +143,12 @@ compile-time constant (originally four). The driver contains an .BR ioctl (2) that can format a tape with either one or two partitions. -.PP +.P Device .I /dev/tape is usually created as a hard or soft link to the default tape device on the system. -.PP +.P Starting from Linux 2.6.2, the driver exports in the sysfs directory .I /sys/class/scsi_tape the attached devices and some parameters assigned to the devices. @@ -165,7 +165,7 @@ Note that the blocks on the tape don't contain any information about the writing mode: when reading, the only important thing is to use commands that accept the block sizes on the tape. -.PP +.P In variable-block mode the read byte count does not have to match the tape block size exactly. If the byte count is larger than the @@ -173,7 +173,7 @@ next block on tape, the driver returns the data and the function returns the actual block size. If the block size is larger than the byte count, an error is returned. -.PP +.P In fixed-block mode the read byte counts can be arbitrary if buffering is enabled, or a multiple of the tape block size if buffering is disabled. @@ -182,7 +182,7 @@ arbitrary byte count if buffering is enabled. In all other cases (before Linux 2.1.121 with buffering disabled or newer kernel) the write byte count must be a multiple of the tape block size. -.PP +.P In Linux 2.6, the driver tries to use direct transfers between the user buffer and the device. If this is not possible, the driver's internal buffer @@ -191,10 +191,10 @@ The reasons for not using direct transfers include improper alignment of the user buffer (default is 512 bytes but this can be changed by the HBA driver), one or more pages of the user buffer not reachable by the SCSI adapter, and so on. -.PP +.P A filemark is automatically written to tape if the last tape operation before close was a write. -.PP +.P When a filemark is encountered while reading, the following happens. If there are data remaining in the buffer when the filemark @@ -224,7 +224,7 @@ Not all drives support all operations. The driver returns an .B EIO error if the drive rejects an operation. -.PP +.P .in +4n .EX /* Structure for MTIOCTOP \- mag tape op command: */ @@ -234,7 +234,7 @@ struct mtop { }; .EE .in -.PP +.P Magnetic tape operations for normal tape use: .TP .B MTBSF @@ -395,7 +395,7 @@ filemarks. Write .I mt_count setmarks. -.PP +.P Magnetic tape operations for setting of device options (by the superuser): .TP .B MTSETDRVBUFFER @@ -609,9 +609,9 @@ In BSD semantics the tape position is not changed. .BR MT_NO_WAIT " (Default: false)" Enables immediate mode (i.e., don't wait for the command to finish) for some commands (e.g., rewind). -.PP +.P An example: -.PP +.P .in +4n .EX struct mtop mt_cmd; @@ -621,14 +621,14 @@ mt_cmd.mt_count = MT_ST_BOOLEANS | ioctl(fd, MTIOCTOP, mt_cmd); .EE .in -.PP +.P The default block size for a device can be set with .B MT_ST_DEF_BLKSIZE and the default density code can be set with .BR MT_ST_DEFDENSITY . The values for the parameters are or'ed with the operation code. -.PP +.P With Linux 2.1.x and later, the timeout values can be set with the subcommand .B MT_ST_SET_TIMEOUT @@ -645,7 +645,7 @@ These commands can be used to set more practical values for a specific drive. The timeouts set for one device apply for all devices linked to the same drive. -.PP +.P Starting from Linux 2.4.19 and Linux 2.5.43, the driver supports a status bit which indicates whether the drive requests cleaning. The method used by the @@ -670,7 +670,7 @@ the masked sense data byte. .SS MTIOCGET \[em] get status This request takes an argument of type .IR "(struct mtget\ *)" . -.PP +.P .in +4n .EX /* structure for MTIOCGET \- mag tape get status command */ @@ -812,7 +812,7 @@ This drive must be a SCSI-2 drive that supports the command (device-specific address) or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive Viper, Wangtek, ... ). -.PP +.P .in +4n .EX /* structure for MTIOCPOS \- mag tape get position command */ @@ -940,7 +940,7 @@ telling it to use larger blocks). If this is not possible, direct transfers can be disabled. .SH SEE ALSO .BR mt (1) -.PP +.P The file .I drivers/scsi/README.st or diff --git a/man4/tty.4 b/man4/tty.4 index 1493e87..72bfcdf 100644 --- a/man4/tty.4 +++ b/man4/tty.4 @@ -6,7 +6,7 @@ .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu) .\" Modified 2003-04-07 by Michael Kerrisk .\" -.TH tty 4 2022-10-30 "Linux man-pages 6.05.01" +.TH tty 4 2023-10-31 "Linux man-pages 6.7" .SH NAME tty \- controlling terminal .SH DESCRIPTION @@ -15,7 +15,7 @@ The file is a character file with major number 5 and minor number 0, usually with mode 0666 and ownership root:tty. It is a synonym for the controlling terminal of a process, if any. -.PP +.P In addition to the .BR ioctl (2) requests supported by the device that @@ -27,7 +27,7 @@ request is supported. .SS TIOCNOTTY Detach the calling process from its controlling terminal. -.PP +.P If the process is the session leader, then .B SIGHUP @@ -35,7 +35,7 @@ and .B SIGCONT signals are sent to the foreground process group and all processes in the current session lose their controlling tty. -.PP +.P This .BR ioctl (2) call works only on file descriptors connected diff --git a/man4/ttyS.4 b/man4/ttyS.4 index eadd6bd..66fb119 100644 --- a/man4/ttyS.4 +++ b/man4/ttyS.4 @@ -4,15 +4,15 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 17:03:24 1993 by Rik Faith (faith@cs.unc.edu) -.TH ttyS 4 2022-10-30 "Linux man-pages 6.05.01" +.TH ttyS 4 2023-10-31 "Linux man-pages 6.7" .SH NAME ttyS \- serial terminal lines .SH DESCRIPTION .B ttyS[0\-3] are character devices for the serial terminal lines. -.PP +.P They are typically created by: -.PP +.P .in +4n .EX mknod \-m 660 /dev/ttyS0 c 4 64 # base address 0x3f8 diff --git a/man4/vcs.4 b/man4/vcs.4 index 3aa3523..bf5dba2 100644 --- a/man4/vcs.4 +++ b/man4/vcs.4 @@ -7,7 +7,7 @@ .\" 2007-12-17, Samuel Thibault : .\" document the VT_GETHIFONTMASK ioctl .\" " -.TH vcs 4 2023-05-03 "Linux man-pages 6.05.01" +.TH vcs 4 2023-10-31 "Linux man-pages 6.7" .SH NAME vcs, vcsa \- virtual console memory .SH DESCRIPTION @@ -16,7 +16,7 @@ is a character device with major number 7 and minor number 0, usually with mode 0644 and ownership root:tty. It refers to the memory of the currently displayed virtual console terminal. -.PP +.P .I /dev/vcs[1\-63] are character devices for virtual console terminals, they have major number 7 and minor number 1 to 63, usually @@ -36,7 +36,7 @@ dimensions and cursor position: = .I y = 0 at the top left corner of the screen.) -.PP +.P When a 512-character font is loaded, the 9th bit position can be fetched by applying the .BR ioctl (2) @@ -50,16 +50,16 @@ the value is returned in the pointed to by the third .BR ioctl (2) argument. -.PP +.P These devices replace the screendump .BR ioctl (2) operations of .BR ioctl_console (2), so the system administrator can control access using filesystem permissions. -.PP +.P The devices for the first eight virtual consoles may be created by: -.PP +.P .in +4n .EX for x in 0 1 2 3 4 5 6 7 8; do @@ -69,7 +69,7 @@ done chown root:tty /dev/vcs* .EE .in -.PP +.P No .BR ioctl (2) requests are supported. @@ -83,39 +83,39 @@ requests are supported. Introduced with Linux 1.1.92. .SH EXAMPLES You may do a screendump on vt3 by switching to vt1 and typing -.PP +.P .in +4n .EX cat /dev/vcs3 >foo .EE .in -.PP +.P Note that the output does not contain newline characters, so some processing may be required, like in -.PP +.P .in +4n .EX fold \-w 81 /dev/vcs3 | lpr .EE .in -.PP +.P or (horrors) -.PP +.P .in +4n .EX setterm \-dump 3 \-file /proc/self/fd/1 .EE .in -.PP +.P The .I /dev/vcsa0 device is used for Braille support. -.PP +.P This program displays the character and screen attributes under the cursor of the second virtual console, then changes the background color there: -.PP +.P .EX #include #include diff --git a/man4/veth.4 b/man4/veth.4 index cbb2456..d6c9a19 100644 --- a/man4/veth.4 +++ b/man4/veth.4 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" -.TH veth 4 2023-02-05 "Linux man-pages 6.05.01" +.TH veth 4 2023-10-31 "Linux man-pages 6.7" .SH NAME veth \- Virtual Ethernet Device .SH DESCRIPTION @@ -15,27 +15,27 @@ devices are virtual Ethernet devices. They can act as tunnels between network namespaces to create a bridge to a physical network device in another namespace, but can also be used as standalone network devices. -.PP +.P .B veth devices are always created in interconnected pairs. A pair can be created using the command: -.PP +.P .in +4n .EX # ip link add type veth peer name .EE .in -.PP +.P In the above, .I p1-name and .I p2-name are the names assigned to the two connected end points. -.PP +.P Packets transmitted on one device in the pair are immediately received on the other device. When either device is down, the link state of the pair is down. -.PP +.P .B veth device pairs are useful for combining the network facilities of the kernel together in interesting ways. @@ -46,28 +46,28 @@ thus allowing communication between network namespaces. To do this, one can provide the .B netns parameter when creating the interfaces: -.PP +.P .in +4n .EX # ip link add netns type veth peer netns .EE .in -.PP +.P or, for an existing .B veth pair, move one side to the other namespace: -.PP +.P .in +4n .EX # ip link set netns .EE .in -.PP +.P .BR ethtool (8) can be used to find the peer of a .B veth network interface, using commands something like: -.PP +.P .in +4n .EX # \fBip link add ve_A type veth peer name ve_B\fP # Create veth pair diff --git a/man4/wavelan.4 b/man4/wavelan.4 index 8ab01df..3e2f3b4 100644 --- a/man4/wavelan.4 +++ b/man4/wavelan.4 @@ -8,7 +8,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH wavelan 4 2023-02-05 "Linux man-pages 6.05.01" +.TH wavelan 4 2023-10-31 "Linux man-pages 6.7" .SH NAME wavelan \- AT&T GIS WaveLAN ISA device driver .SH SYNOPSIS @@ -18,7 +18,7 @@ wavelan \- AT&T GIS WaveLAN ISA device driver .SH DESCRIPTION .I This driver is obsolete: it was removed in Linux 2.6.35. -.PP +.P .B wavelan is the low-level device driver for the NCR / AT&T / Lucent .B WaveLAN ISA @@ -120,7 +120,7 @@ This driver fails to detect some Wavelan cards. If this happens for you, you must look in the source code on how to add your card to the detection routine. -.PP +.P Some of the mentioned features are optional. You may enable or disable them by changing flags in the driver header and recompile. diff --git a/man5/acct.5 b/man5/acct.5 index e1d88d4..a140bc4 100644 --- a/man5/acct.5 +++ b/man5/acct.5 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH acct 5 2023-05-03 "Linux man-pages 6.05.01" +.TH acct 5 2023-10-31 "Linux man-pages 6.7" .SH NAME acct \- process accounting file .SH SYNOPSIS @@ -15,18 +15,18 @@ If the kernel is built with the process accounting option enabled then calling .BR acct (2) starts process accounting, for example: -.PP +.P .in +4n acct("/var/log/pacct"); .in -.PP +.P When process accounting is enabled, the kernel writes a record to the accounting file as each process on the system terminates. This record contains information about the terminated process, and is defined in .I as follows: -.PP +.P .in +4n .EX #define ACCT_COMM 16 @@ -65,7 +65,7 @@ enum { /* Bits that may be set in ac_flag field */ }; .EE .in -.PP +.P The .I comp_t data type is a floating-point value consisting of a 3-bit, base-8 exponent, @@ -73,11 +73,11 @@ and a 13-bit mantissa. A value, .IR c , of this type can be converted to a (long) integer as follows: -.PP +.P .nf v = (c & 0x1fff) << (((c >> 13) & 0x7) * 3); .fi -.PP +.P The .IR ac_utime , .IR ac_stime , @@ -101,7 +101,7 @@ and fields is widened from 16 to 32 bits (in line with the increased size of UID and GIDs in Linux 2.4 and later). The records are defined as follows: -.PP +.P .in +4n .EX struct acct_v3 { @@ -135,19 +135,19 @@ and the details vary somewhat between systems. None. .SH HISTORY glibc 2.6. -.PP +.P Process accounting originated on BSD. .SH NOTES Records in the accounting file are ordered by termination time of the process. -.PP +.P Up to and including Linux 2.6.9, a separate accounting record is written for each thread created using the NPTL threading library; since Linux 2.6.10, a single accounting record is written for the entire process on termination of the last thread in the process. -.PP +.P The .I /proc/sys/kernel/acct file, described in diff --git a/man5/charmap.5 b/man5/charmap.5 index 280ba4e..7dda95c 100644 --- a/man5/charmap.5 +++ b/man5/charmap.5 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH charmap 5 2022-10-30 "Linux man-pages 6.05.01" +.TH charmap 5 2023-10-31 "Linux man-pages 6.7" .SH NAME charmap \- character set description file .SH DESCRIPTION @@ -38,11 +38,11 @@ This value must be less than or equal than .RI < mb_cur_max >. If not specified, it defaults to .RI < mb_cur_max >. -.PP +.P The character set definition section starts with the keyword .I CHARMAP in the first column. -.PP +.P The following lines may have one of the two following forms to define the character set: .TP @@ -55,23 +55,23 @@ being optional. This form defines a character range and its byte sequence, .I comment being optional. -.PP +.P The character set definition section ends with the string .IR "END CHARMAP" . -.PP +.P The character set definition section may optionally be followed by a section to define widths of characters. -.PP +.P The .I WIDTH_DEFAULT keyword can be used to define the default width for all characters not explicitly listed. The default character width is 1. -.PP +.P The width section for individual characters starts with the keyword .I WIDTH in the first column. -.PP +.P The following lines may have one of the two following forms to define the widths of the characters: .TP @@ -80,7 +80,7 @@ This form defines the width of exactly one character. .TP .RI < character >...< character >\ width This form defines the width for all the characters in the range. -.PP +.P The width definition section ends with the string .IR "END WIDTH" . .SH FILES @@ -93,7 +93,7 @@ POSIX.2. The Euro sign is defined as follows in the .I UTF\-8 charmap: -.PP +.P .nf /xe2/x82/xac EURO SIGN .fi diff --git a/man5/core.5 b/man5/core.5 index c19846e..ea250e2 100644 --- a/man5/core.5 +++ b/man5/core.5 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH core 5 2023-05-03 "Linux man-pages 6.05.01" +.TH core 5 2023-10-31 "Linux man-pages 6.7" .SH NAME core \- core dump file .SH DESCRIPTION @@ -16,14 +16,14 @@ This image can be used in a debugger (e.g., to inspect the state of the program at the time that it terminated. A list of the signals which cause a process to dump core can be found in .BR signal (7). -.PP +.P A process can set its soft .B RLIMIT_CORE resource limit to place an upper limit on the size of the core dump file that will be produced if it receives a "core dump" signal; see .BR getrlimit (2) for details. -.PP +.P There are various circumstances in which a core dump file is not produced: .IP \[bu] 3 @@ -115,13 +115,13 @@ option. The kernel was configured without the .B CONFIG_COREDUMP option. -.PP +.P In addition, a core dump may exclude part of the address space of the process if the .BR madvise (2) .B MADV_DONTDUMP flag was employed. -.PP +.P On systems that employ .BR systemd (1) as the @@ -139,7 +139,7 @@ file (since Linux 2.6 and 2.4.21) can be set to define a template that is used to name core dump files. The template can contain % specifiers which are substituted by the following values when a core file is created: -.PP +.P .RS 4 .PD 0 .TP 4 @@ -211,7 +211,7 @@ Epoch, 1970-01-01 00:00:00 +0000 (UTC). Numeric real UID of dumped process. .PD .RE -.PP +.P A single % at the end of the template is dropped from the core filename, as is the combination of a % followed by any character other than those listed above. @@ -230,7 +230,7 @@ and .I /proc/sys/kernel/core_uses_pid (see below) is nonzero, then .PID will be appended to the core filename. -.PP +.P Paths are interpreted according to the settings that are active for the crashing process. That means the crashing process's mount namespace (see @@ -239,7 +239,7 @@ its current working directory (found via .BR getcwd (2)), and its root directory (see .BR chroot (2)). -.PP +.P Since Linux 2.4, Linux has also provided a more primitive method of controlling the name of the core dump file. @@ -250,7 +250,7 @@ file contains the value 0, then a core dump file is simply named If this file contains a nonzero value, then the core dump file includes the process ID in a name of the form .IR core.PID . -.PP +.P Since Linux 3.6, .\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 if @@ -264,7 +264,7 @@ file. If the first character of this file is a pipe symbol (\fB|\fP), then the remainder of the line is interpreted as the command-line for a user-space program (or script) that is to be executed. -.PP +.P Since Linux 5.3.0, .\" commit 315c69261dd3fa12dbc830d4fa00d1fad98d3b03 the pipe template is split on spaces into an argument list @@ -283,7 +283,7 @@ Executable names with multiple spaces in them are not correctly represented in earlier kernels, meaning that the core dump handler needs to use mechanisms to find the executable name. -.PP +.P Instead of being written to a file, the core dump is given as standard input to the program. Note the following points: @@ -354,7 +354,7 @@ files prematurely. This in turn creates the possibility that a misbehaving collecting program can block the reaping of a crashed process by simply never exiting. -.PP +.P Since Linux 2.6.32, .\" commit a293980c2e261bd5b0d2a77340dd04f684caff58 the @@ -364,7 +364,7 @@ The value in this file defines how many concurrent crashing processes may be piped to user-space programs in parallel. If this value is exceeded, then those crashing processes above this value are noted in the kernel log and their core dumps are skipped. -.PP +.P A value of 0 in this file is special. It indicates that unlimited processes may be captured in parallel, but that no waiting will take place (i.e., the collecting @@ -378,13 +378,13 @@ Since Linux 2.6.23, the Linux-specific file can be used to control which memory segments are written to the core dump file in the event that a core dump is performed for the process with the corresponding process ID. -.PP +.P The value in the file is a bit mask of memory mapping types (see .BR mmap (2)). If a bit is set in the mask, then memory mappings of the corresponding type are dumped; otherwise they are not dumped. The bits in this file have the following meanings: -.PP +.P .PD 0 .RS 4 .TP @@ -420,24 +420,24 @@ bit 8 (since Linux 4.4) Dump shared DAX pages. .RE .PD -.PP +.P By default, the following bits are set: 0, 1, 4 (if the .B CONFIG_CORE_DUMP_DEFAULT_ELF_HEADERS kernel configuration option is enabled), and 5. This default can be modified at boot time using the .I coredump_filter boot option. -.PP +.P The value of this file is displayed in hexadecimal. (The default value is thus displayed as 33.) -.PP +.P Memory-mapped I/O pages such as frame buffer are never dumped, and virtual DSO .RB ( vdso (7)) pages are always dumped, regardless of the .I coredump_filter value. -.PP +.P A child process created via .BR fork (2) inherits its parent's @@ -447,18 +447,18 @@ the .I coredump_filter value is preserved across an .BR execve (2). -.PP +.P It can be useful to set .I coredump_filter in the parent shell before running a program, for example: -.PP +.P .in +4n .EX .RB "$" " echo 0x7 > /proc/self/coredump_filter" .RB "$" " ./some_program" .EE .in -.PP +.P This file is provided only if the kernel was built with the .B CONFIG_ELF_CORE configuration option. @@ -477,14 +477,14 @@ feature that allows piping core dumps to a program. One can verify this by checking whether core dumps are being piped to the .BR systemd\-coredump (8) program: -.PP +.P .in +4n .EX $ \fBcat /proc/sys/kernel/core_pattern\fP |/usr/lib/systemd/systemd\-coredump %P %u %g %s %t %c %e .EE .in -.PP +.P In this case, core dumps will be placed in the location configured for .BR systemd\-coredump (8), typically as @@ -495,7 +495,7 @@ One can list the core dumps that have been recorded by .BR systemd\-coredump (8) using .BR coredumpctl (1): -.PP +.P .EX $ \fBcoredumpctl list | tail \-5\fP Wed 2017\-10\-11 22:25:30 CEST 2748 1000 1000 3 present /usr/bin/sleep @@ -504,7 +504,7 @@ Thu 2017\-10\-12 06:30:50 CEST 2767 1000 1000 3 present /usr/bin/sleep Thu 2017\-10\-12 06:37:40 CEST 2918 1000 1000 3 present /usr/bin/cat Thu 2017\-10\-12 08:13:07 CEST 2955 1000 1000 3 present /usr/bin/cat .EE -.PP +.P The information shown for each core dump includes the date and time of the dump, the PID, UID, and GID of the dumping process, the signal number that caused the core dump, @@ -517,24 +517,24 @@ location into a specified file. For example, to extract the core dump for PID 2955 shown above to a file named .I core in the current directory, one could use: -.PP +.P .in +4n .EX $ \fBcoredumpctl dump 2955 \-o core\fP .EE .in -.PP +.P For more extensive details, see the .BR coredumpctl (1) manual page. -.PP +.P To (persistently) disable the .BR systemd (1) mechanism that archives core dumps, restoring to something more like traditional Linux behavior, one can set an override for the .BR systemd (1) mechanism, using something like: -.PP +.P .in +4n .EX # \fBecho "kernel.core_pattern=core.%p" > \e\fP @@ -542,13 +542,13 @@ mechanism, using something like: # \fB/lib/systemd/systemd\-sysctl\fP .EE .in -.PP +.P It is also possible to temporarily (i.e., until the next reboot) change the .I core_pattern setting using a command such as the following (which causes the names of core dump files to include the executable name as well as the number of the signal which triggered the core dump): -.PP +.P .in +4n .EX # \fBsysctl \-w kernel.core_pattern="%e\-%s.core"\fP @@ -560,7 +560,7 @@ The .BR gdb (1) .I gcore command can be used to obtain a core dump of a running process. -.PP +.P In Linux versions up to and including 2.6.27, .\" Changed with commit 6409324b385f3f63a03645b4422e3be67348d922 if a multithreaded process (or, more precisely, a process that @@ -593,7 +593,7 @@ file. The following shell session demonstrates the use of this program (compiled to create an executable named .IR core_pattern_pipe_test ): -.PP +.P .in +4n .EX .RB "$" " cc \-o core_pattern_pipe_test core_pattern_pipe_test.c" diff --git a/man5/dir_colors.5 b/man5/dir_colors.5 index ccee252..7c49f31 100644 --- a/man5/dir_colors.5 +++ b/man5/dir_colors.5 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH dir_colors 5 2023-07-15 "Linux man-pages 6.05.01" +.TH dir_colors 5 2024-01-28 "Linux man-pages 6.7" .SH NAME dir_colors \- configuration file for dircolors(1) .SH DESCRIPTION @@ -13,11 +13,11 @@ uses the environment variable .B LS_COLORS to determine the colors in which the filenames are to be displayed. This environment variable is usually set by a command like -.PP +.P .RS eval \`dircolors some_path/dir_colors\` .RE -.PP +.P found in a system default shell initialization file, like .I /etc/profile or @@ -29,13 +29,13 @@ Usually, the file used here is and can be overridden by a .I .dir_colors file in one's home directory. -.PP +.P This configuration file consists of several statements, one per line. Anything right of a hash mark (#) is treated as a comment, if the hash mark is at the beginning of a line or is preceded by at least one whitespace. Blank lines are ignored. -.PP +.P The .I global section of the file consists of any statement before the first @@ -53,7 +53,7 @@ statements which specify the terminal types (as given by the environment variable) the following declarations apply to. It is always possible to override a global declaration by a subsequent terminal-specific one. -.PP +.P The following statements are recognized; case is insignificant: .TP .B TERM \fIterminal-type\fR @@ -75,7 +75,7 @@ The default is \fIno\fR. .B EIGHTBIT yes|no (Slackware only; ignored by GNU .BR dircolors (1).) -Specifies that eight-bit ISO 8859 characters should be enabled by +Specifies that eight-bit ISO/IEC\~8859 characters should be enabled by default. For compatibility reasons, this can also be specified as 1 for \fIyes\fR or 0 for \fIno\fR. @@ -191,7 +191,7 @@ Synonym: .B LEFTCODE \fIcolor-sequence\fR Specifies the .I "left code" -for non-ISO\ 6429 terminals (see below). +for non-ISO/IEC\~6429 terminals (see below). .IP Synonym: .BR LEFT . @@ -199,7 +199,7 @@ Synonym: .B RIGHTCODE \fIcolor-sequence\fR Specifies the .I "right code" -for non-ISO\ 6429 terminals (see below). +for non-ISO/IEC\~6429 terminals (see below). .IP Synonym: .BR RIGHT . @@ -207,7 +207,7 @@ Synonym: .B ENDCODE \fIcolor-sequence\fR Specifies the .I "end code" -for non-ISO\ 6429 terminals (see below). +for non-ISO/IEC\~6429 terminals (see below). .IP Synonym: .BR END . @@ -227,16 +227,16 @@ for .B emacs backup files. This form should be considered obsolete. -.SS ISO 6429 (ANSI) color sequences -Most color-capable ASCII terminals today use ISO 6429 (ANSI) color sequences, +.SS ISO/IEC\~6429 (ANSI) color sequences +Most color-capable ASCII terminals today use ISO/IEC\~6429 (ANSI) color sequences, and many common terminals without color capability, including .B xterm -and the widely used and cloned DEC VT100, will recognize ISO 6429 color +and the widely used and cloned DEC VT100, will recognize ISO/IEC\~6429 color codes and harmlessly eliminate them from the output or emulate them. .B ls -uses ISO 6429 codes by default, assuming colorization is enabled. -.PP -ISO 6429 color sequences are composed of sequences of numbers +uses ISO/IEC\~6429 codes by default, assuming colorization is enabled. +.P +ISO/IEC\~6429 color sequences are composed of sequences of numbers separated by semicolons. The most common codes are: .RS @@ -264,9 +264,9 @@ l l. 47 for white (or gray) background .TE .RE -.PP +.P Not all commands will work on all systems or display devices. -.PP +.P .B ls uses the following defaults: .TS @@ -283,7 +283,7 @@ BLK 44;37 Block device CHR 44;37 Character device EXEC 35 Executable file .TE -.PP +.P A few terminal programs do not recognize the default properly. If all text gets colorized after you do a directory @@ -303,7 +303,7 @@ To do so, you will have to use the and .B ENDCODE definitions. -.PP +.P When writing out a filename, .B ls generates the following output sequence: @@ -326,7 +326,7 @@ escape codes away from the user). If they are not appropriate for your terminal, you can eliminate them by specifying the respective keyword on a line by itself. -.PP +.P .B NOTE: If the .B ENDCODE @@ -366,7 +366,7 @@ lb l. \e# Hash mark (#) .TE .RE -.PP +.P Note that escapes are necessary to enter a space, backslash, caret, or any control character anywhere in the string, as well as a hash mark as the first character. @@ -377,7 +377,7 @@ System-wide configuration file. .TP .I \[ti]/.dir_colors Per-user configuration file. -.PP +.P This page describes the .B dir_colors file format as used in the fileutils-4.1 package; @@ -387,7 +387,7 @@ The default .B LEFTCODE and .B RIGHTCODE -definitions, which are used by ISO 6429 terminals are: +definitions, which are used by ISO/IEC\~6429 terminals are: .RS .TS lb l. @@ -395,7 +395,7 @@ LEFTCODE \ee[ RIGHTCODE m .TE .RE -.PP +.P The default .B ENDCODE is undefined. diff --git a/man5/elf.5 b/man5/elf.5 index 6fa4ddf..84c7f27 100644 --- a/man5/elf.5 +++ b/man5/elf.5 @@ -32,7 +32,7 @@ .\" 2007-10-11, Mike Frysinger , various fixes .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH ELF 5 2023-05-03 "Linux man-pages 6.05.01" +.TH ELF 5 2024-02-25 "Linux man-pages 6.7" .SH NAME elf \- format of Executable and Linking Format (ELF) files .SH SYNOPSIS @@ -47,7 +47,7 @@ defines the format of ELF executable binary files. Amongst these files are normal executable files, relocatable object files, core files, and shared objects. -.PP +.P An executable file using the ELF file format consists of an ELF header, followed by a program header table or a section header table, or both. The ELF header is always at offset zero of the file. @@ -56,7 +56,7 @@ table and the section header table's offset in the file are defined in the ELF header. The two tables describe the rest of the particularities of the file. -.PP +.P .\" Applications which wish to process ELF binary files for their native .\" architecture only should include .\" .I @@ -68,7 +68,7 @@ the file. .\" ELF_xxx". .\" Applications written this way can be compiled on any architecture, .\" regardless of whether the host is 32-bit or 64-bit. -.\" .PP +.\" .P .\" Should an application need to process ELF files of an unknown .\" architecture, then the application needs to explicitly use either .\" "Elf32_xxx" @@ -79,7 +79,7 @@ the file. .\" "ELF32_xxx" .\" or .\" "ELF64_xxx". -.\" .PP +.\" .P This header file describes the above mentioned headers as C structures and also includes structures for dynamic sections, relocation sections and symbol tables. @@ -96,7 +96,7 @@ stands for .I uint32_t or .IR uint64_t ): -.PP +.P .in +4n .EX ElfN_Addr Unsigned program address, uintN_t @@ -112,7 +112,7 @@ ElfN_Xword uint64_t .\" Elf32_Size Unsigned object size .EE .in -.PP +.P (Note: the *BSD terminology is a bit different. There, .I Elf64_Half @@ -125,7 +125,7 @@ is used for .IR uint16_t . In order to avoid confusion these types are replaced by explicit ones in the below.) -.PP +.P All data structures that the file format defines follow the "natural" size and alignment guidelines for the relevant class. @@ -138,7 +138,7 @@ The ELF header is described by the type .I Elf32_Ehdr or .IR Elf64_Ehdr : -.PP +.P .in +4n .EX #define EI_NIDENT 16 @@ -161,7 +161,7 @@ typedef struct { } ElfN_Ehdr; .EE .in -.PP +.P The fields have the following meanings: .\" .\" @@ -632,7 +632,7 @@ The ELF program header is described by the type or .I Elf64_Phdr depending on the architecture: -.PP +.P .in +4n .EX typedef struct { @@ -647,7 +647,7 @@ typedef struct { } Elf32_Phdr; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -662,7 +662,7 @@ typedef struct { } Elf64_Phdr; .EE .in -.PP +.P The main difference between the 32-bit and the 64-bit program header lies in the location of the .I p_flags @@ -727,7 +727,9 @@ occur only if the program header table is part of the memory image of the program. If it is present, it must precede any loadable segment entry. .TP -.BR PT_LOPROC ", " PT_HIPROC +.B PT_LOPROC +.TQ +.B PT_HIPROC Values in the inclusive range .RB [ PT_LOPROC , .BR PT_HIPROC ] @@ -783,7 +785,7 @@ A readable segment. A text segment commonly has the flags .B PF_X and -.B PF_R . +.BR PF_R . A data segment commonly has .B PF_W and @@ -824,7 +826,7 @@ header table. holds the number of entries the section header table contains. .I e_shentsize holds the size in bytes of each entry. -.PP +.P A section header table index is a subscript into this array. Some section header table indices are reserved: @@ -848,7 +850,9 @@ or otherwise meaningless section reference. .B SHN_LORESERVE This value specifies the lower bound of the range of reserved indices. .TP -.BR SHN_LOPROC ", " SHN_HIPROC +.B SHN_LOPROC +.TQ +.B SHN_HIPROC Values greater in the inclusive range .RB [ SHN_LOPROC , .BR SHN_HIPROC ] @@ -875,9 +879,9 @@ and inclusive. The section header table does not contain entries for the reserved indices. -.PP +.P The section header has the following structure: -.PP +.P .in +4n .EX typedef struct { @@ -894,7 +898,7 @@ typedef struct { } Elf32_Shdr; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -911,7 +915,7 @@ typedef struct { } Elf64_Shdr; .EE .in -.PP +.P No real differences exist between the 32-bit and 64-bit section headers. .TP .I sh_name @@ -1002,7 +1006,9 @@ object file can also contain a .B SHT_SYMTAB section. .TP -.BR SHT_LOPROC ", " SHT_HIPROC +.B SHT_LOPROC +.TQ +.B SHT_HIPROC Values in the inclusive range .RB [ SHT_LOPROC , .BR SHT_HIPROC ] @@ -1106,7 +1112,7 @@ Some sections hold a table of fixed-sized entries, such as a symbol table. For such a section, this member gives the size in bytes for each entry. This member contains zero if the section does not hold a table of fixed-size entries. -.PP +.P Various sections hold program and control information: .TP .I .bss @@ -1438,12 +1444,12 @@ The first byte, which is index zero, is defined to hold a null byte (\[aq]\e0\[aq]). Similarly, a string table's last byte is defined to hold a null byte, ensuring null termination for all strings. -.PP +.P An object file's symbol table holds information needed to locate and relocate a program's symbolic definitions and references. A symbol table index is a subscript into this array. -.PP +.P .in +4n .EX typedef struct { @@ -1456,7 +1462,7 @@ typedef struct { } Elf32_Sym; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -1469,7 +1475,7 @@ typedef struct { } Elf64_Sym; .EE .in -.PP +.P The 32-bit and 64-bit versions have the same members, just in a different order. .TP @@ -1520,7 +1526,9 @@ and it precedes the other .B STB_LOCAL symbols of the file, if it is present. .TP -.BR STT_LOPROC ", " STT_HIPROC +.B STT_LOPROC +.TQ +.B STT_HIPROC Values in the inclusive range .RB [ STT_LOPROC , .BR STT_HIPROC ] @@ -1542,7 +1550,9 @@ reference to the same symbol. Weak symbols resemble global symbols, but their definitions have lower precedence. .TP -.BR STB_LOPROC ", " STB_HIPROC +.B STB_LOPROC +.TQ +.B STB_HIPROC Values in the inclusive range .RB [ STB_LOPROC , .BR STB_HIPROC ] @@ -1552,18 +1562,23 @@ are reserved for processor-specific semantics. There are macros for packing and unpacking the binding and type fields: .RS .TP -.BR ELF32_ST_BIND( \fIinfo\fP ) ", " ELF64_ST_BIND( \fIinfo\fP ) +.BI ELF32_ST_BIND( info ) +.TQ +.BI ELF64_ST_BIND( info ) Extract a binding from an .I st_info value. .TP -.BR ELF32_ST_TYPE( \fIinfo ) ", " ELF64_ST_TYPE( \fIinfo\fP ) +.BI ELF32_ST_TYPE( info ) +.TQ +.BI ELF64_ST_TYPE( info ) Extract a type from an .I st_info value. .TP -.BR ELF32_ST_INFO( \fIbind\fP ", " \fItype\fP ) ", " \ -ELF64_ST_INFO( \fIbind\fP ", " \fItype\fP ) +.BI ELF32_ST_INFO( bind ", " type ) +.TQ +.BI ELF64_ST_INFO( bind ", " type ) Convert a binding and a type into an .I st_info value. @@ -1592,9 +1607,9 @@ references in the local module always resolve to the local symbol Symbol is available to other modules, but references in the local module always resolve to the local symbol. .PD -.PP +.P There are macros for extracting the visibility type: -.PP +.P .BR ELF32_ST_VISIBILITY (other) or .BR ELF64_ST_VISIBILITY (other) @@ -1615,9 +1630,9 @@ describes how to modify their section contents, thus allowing executable and shared object files to hold the right information for a process's program image. Relocation entries are these data. -.PP +.P Relocation structures that do not need an addend: -.PP +.P .in +4n .EX typedef struct { @@ -1626,7 +1641,7 @@ typedef struct { } Elf32_Rel; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -1635,9 +1650,9 @@ typedef struct { } Elf64_Rel; .EE .in -.PP +.P Relocation structures that need an addend: -.PP +.P .in +4n .EX typedef struct { @@ -1647,7 +1662,7 @@ typedef struct { } Elf32_Rela; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -1695,7 +1710,7 @@ The member controls the interpretation of .IR d_un . -.PP +.P .in +4n .EX typedef struct { @@ -1708,7 +1723,7 @@ typedef struct { extern Elf32_Dyn _DYNAMIC[]; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -1806,7 +1821,9 @@ transferring control to the executable .B DT_RUNPATH String table offset to library search path .TP -.BR DT_LOPROC ", " DT_HIPROC +.B DT_LOPROC +.TQ +.B DT_HIPROC Values in the inclusive range .RB [ DT_LOPROC , .BR DT_HIPROC ] @@ -1855,7 +1872,7 @@ but many projects define their own set of extensions. For example, the GNU tool chain uses ELF notes to pass information from the linker to the C library. -.PP +.P Note sections contain a series of notes (see the .I struct definitions below). @@ -1863,10 +1880,10 @@ Each note is followed by the name field (whose length is defined in \fIn_namesz\fR) and then by the descriptor field (whose length is defined in \fIn_descsz\fR) and whose starting address has a 4 byte alignment. Neither field is defined in the note struct due to their arbitrary lengths. -.PP +.P An example for parsing out two consecutive notes should clarify their layout in memory: -.PP +.P .in +4n .EX void *memory, *name, *desc; @@ -1890,7 +1907,7 @@ next_note = memory + sizeof(*note) + ALIGN_UP(note\->n_descsz, 4); .EE .in -.PP +.P Keep in mind that the interpretation of .I n_type depends on the namespace defined by the @@ -1902,7 +1919,7 @@ field is not set (e.g., is 0), then there are two sets of notes: one for core files and one for all other ELF types. If the namespace is unknown, then tools will usually fallback to these sets of notes as well. -.PP +.P .in +4n .EX typedef struct { @@ -1912,7 +1929,7 @@ typedef struct { } Elf32_Nhdr; .EE .in -.PP +.P .in +4n .EX typedef struct { @@ -2143,7 +2160,7 @@ Architecture information. ELF first appeared in System V. The ELF format is an adopted standard. -.PP +.P The extensions for .IR e_phnum , .IR e_shnum , @@ -2178,19 +2195,19 @@ look under SEE ALSO. .BR dl_iterate_phdr (3), .BR core (5), .BR ld.so (8) -.PP +.P Hewlett-Packard, .IR "Elf-64 Object File Format" . -.PP +.P Santa Cruz Operation, .IR "System V Application Binary Interface" . -.PP +.P UNIX System Laboratories, "Object Files", .IR "Executable and Linking Format (ELF)" . -.PP +.P Sun Microsystems, .IR "Linker and Libraries Guide" . -.PP +.P AMD64 ABI Draft, .IR "System V Application Binary Interface AMD64 Architecture Processor Supplement" . diff --git a/man5/erofs.5 b/man5/erofs.5 index 97edfdc..f0756c7 100644 --- a/man5/erofs.5 +++ b/man5/erofs.5 @@ -2,14 +2,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH erofs 5 2023-04-29 "Linux man-pages 6.05.01" +.TH erofs 5 2023-10-31 "Linux man-pages 6.7" .SH NAME erofs \- the Enhanced Read-Only File System .SH DESCRIPTION .B erofs is a create-once read-only filesystem, with support for compression and a multi-device backing store. -.PP +.P There are two inode formats: .IP \[bu] 3 32-byte compact with 16-bit UID/GID, @@ -92,6 +92,6 @@ of some of the parameters above. .BR mkfs.erofs (1), .BR fsck.erofs (1), .BR dump.erofs (1) -.PP +.P .I Documentation/filesystems/erofs.txt in the Linux source. diff --git a/man5/filesystems.5 b/man5/filesystems.5 index cc76699..14b4906 100644 --- a/man5/filesystems.5 +++ b/man5/filesystems.5 @@ -4,7 +4,7 @@ .\" .\" 2007-12-14 mtk Added Reiserfs, XFS, JFS. .\" -.TH filesystems 5 2023-04-10 "Linux man-pages 6.05.01" +.TH filesystems 5 2024-01-28 "Linux man-pages 6.7" .nh .SH NAME filesystems \- Linux filesystem types: ext, ext2, ext3, ext4, hpfs, iso9660, @@ -31,17 +31,17 @@ that enables enumeration of the currently available filesystem types regardless of .I /proc availability and/or sanity. -.PP +.P If you need a currently unsupported filesystem, insert the corresponding kernel module or recompile the kernel. -.PP +.P In order to use a filesystem, you have to .I mount it; see .BR mount (2) and .BR mount (8). -.PP +.P The following list provides a short description of the available or historically available filesystems in the Linux kernel. @@ -99,11 +99,11 @@ This filesystem is read-only under Linux due to the lack of available documentation. .TP .B iso9660 -is a CD-ROM filesystem type conforming to the ISO 9660 standard. +is a CD-ROM filesystem type conforming to the ISO/IEC\~9660 standard. .RS .TP .B "High Sierra" -Linux supports High Sierra, the precursor to the ISO 9660 standard for +Linux supports High Sierra, the precursor to the ISO/IEC\~9660 standard for CD-ROM filesystems. It is automatically recognized within the .B iso9660 diff --git a/man5/ftpusers.5 b/man5/ftpusers.5 index 9af5c52..21b2706 100644 --- a/man5/ftpusers.5 +++ b/man5/ftpusers.5 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ftpusers 5 2022-10-30 "Linux man-pages 6.05.01" +.TH ftpusers 5 2023-10-31 "Linux man-pages 6.7" .SH NAME ftpusers \- list of users that may not log in via the FTP daemon .SH DESCRIPTION @@ -13,14 +13,14 @@ File Transfer Protocol (FTP) server daemon. This file is used not merely for system administration purposes but also for improving security within a TCP/IP networked environment. -.PP +.P The .B ftpusers file will typically contain a list of the users that either have no business using ftp or have too many privileges to be allowed to log in through the FTP server daemon. Such users usually include root, daemon, bin, uucp, and news. -.PP +.P If your FTP server daemon doesn't use .BR ftpusers , then it is suggested that you read its documentation to find out how to diff --git a/man5/gai.conf.5 b/man5/gai.conf.5 index bba4480..0b2c2e3 100644 --- a/man5/gai.conf.5 +++ b/man5/gai.conf.5 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH gai.conf 5 2023-02-05 "Linux man-pages 6.05.01" +.TH gai.conf 5 2023-10-31 "Linux man-pages 6.7" .SH NAME gai.conf \- getaddrinfo(3) configuration file .SH DESCRIPTION @@ -20,11 +20,11 @@ to dynamically change the sorting. For the glibc implementation, this can be achieved with the .I /etc/gai.conf file. -.PP +.P Each line in the configuration file consists of a keyword and its parameters. White spaces in any place are ignored. Lines starting with \[aq]#\[aq] are comments and are ignored. -.PP +.P The keywords currently recognized are: .TP \fBlabel\fR \fInetmask\fR \fIprecedence\fR @@ -66,7 +66,7 @@ file is supported since glibc 2.5. .SH EXAMPLES The default table according to RFC\ 3484 would be specified with the following configuration file: -.PP +.P .in +4n .EX label ::1/128 0 diff --git a/man5/group.5 b/man5/group.5 index d39f843..233f307 100644 --- a/man5/group.5 +++ b/man5/group.5 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 17:06:03 1993 by Rik Faith (faith@cs.unc.edu) -.TH group 5 2022-10-30 "Linux man-pages 6.05.01" +.TH group 5 2023-10-31 "Linux man-pages 6.7" .SH NAME group \- user group file .SH DESCRIPTION @@ -12,13 +12,13 @@ The .I /etc/group file is a text file that defines the groups on the system. There is one entry per line, with the following format: -.PP +.P .in +4n .EX group_name:password:GID:user_list .EE .in -.PP +.P The fields are as follows: .TP .I group_name diff --git a/man5/host.conf.5 b/man5/host.conf.5 index 8f64551..73f2969 100644 --- a/man5/host.conf.5 +++ b/man5/host.conf.5 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" 2003-08-23 Martin Schulze Updated according to glibc 2.3.2 -.TH host.conf 5 2023-03-08 "Linux man-pages 6.05.01" +.TH host.conf 5 2023-10-31 "Linux man-pages 6.7" .SH NAME host.conf \- resolver configuration file .SH DESCRIPTION @@ -121,7 +121,7 @@ Line comments can appear anywhere and not only at the beginning of a line. The .BR nsswitch.conf (5) file is the modern way of controlling the order of host lookups. -.PP +.P In glibc 2.4 and earlier, the following keyword is recognized: .TP .I order @@ -134,7 +134,7 @@ Valid methods are Overrides the .I order command. -.PP +.P .\" commit 7d68cdaa4f748e87ee921f587ee2d483db624b3d Since glibc 2.0.7, and up through glibc 2.24, the following keywords and environment variable diff --git a/man5/hosts.5 b/man5/hosts.5 index 7e17814..b01c346 100644 --- a/man5/hosts.5 +++ b/man5/hosts.5 @@ -5,7 +5,7 @@ .\" Minor polishing, aeb .\" Modified, 2002-06-16, Mike Coleman .\" -.TH hosts 5 2023-05-03 "Linux man-pages 6.05.01" +.TH hosts 5 2023-10-31 "Linux man-pages 6.7" .SH NAME hosts \- static table lookup for hostnames .SH SYNOPSIS @@ -21,10 +21,10 @@ with hostnames, one line per IP address. For each host a single line should be present with the following information: .RS -.PP +.P IP_address canonical_hostname [aliases...] .RE -.PP +.P The IP address can conform to either IPv4 or IPv6. Fields of the entry are separated by any number of blanks and/or tab characters. @@ -39,7 +39,7 @@ shorter hostnames, or generic hostnames (for example, .IR localhost ). If required, a host may have two separate entries in this file; one for each version of the Internet Protocol (IPv4 and IPv6). -.PP +.P The Berkeley Internet Name Domain (BIND) Server implements the Internet name server for UNIX systems. It augments or replaces the @@ -47,7 +47,7 @@ It augments or replaces the file or hostname lookup, and frees a host from relying on .I /etc/hosts being up to date and complete. -.PP +.P In modern systems, even though the host table has been superseded by DNS, it is still widely used for: .TP @@ -77,7 +77,7 @@ except in cases where the file is cached by applications. .SS Historical notes RFC\ 952 gave the original format for the host table, though it has since changed. -.PP +.P Before the advent of DNS, the host table was the only way of resolving hostnames on the fledgling Internet. Indeed, this file could be @@ -115,7 +115,7 @@ ff02::2 ip6\-allrouters .BR resolver (5), .BR hostname (7), .BR named (8) -.PP +.P Internet RFC\ 952 .\" .SH AUTHOR .\" This manual page was written by Manoj Srivastava , diff --git a/man5/hosts.equiv.5 b/man5/hosts.equiv.5 index a9521da..b8ff0f6 100644 --- a/man5/hosts.equiv.5 +++ b/man5/hosts.equiv.5 @@ -1,7 +1,7 @@ .\" Copyright (c) 1995 Peter Tobias .\" .\" SPDX-License-Identifier: GPL-1.0-or-later -.TH hosts.equiv 5 2023-02-05 "Linux man-pages 6.05.01" +.TH hosts.equiv 5 2023-10-31 "Linux man-pages 6.7" .SH NAME hosts.equiv \- list of hosts and users that are granted "trusted" .B r @@ -17,11 +17,11 @@ or .BR rcp ) without supplying a password. -.PP +.P The file uses the following format: .TP \fI+|[\-]hostname|+@netgroup|\-@netgroup\fP \fI[+|[\-]username|+@netgroup|\-@netgroup]\fP -.PP +.P The .I hostname is the name of a host which is logically equivalent @@ -39,7 +39,7 @@ Users from that host must always supply additional credentials, including possibly a password. For security reasons you should always use the FQDN of the hostname and not the short hostname. -.PP +.P The .I username entry grants a specific user access to all user @@ -57,9 +57,9 @@ with a minus (\-) sign. This says that the user is not trusted no matter what other entries for that host exist. -.PP +.P Netgroups can be specified by preceding the netgroup by an @ sign. -.PP +.P Be extremely careful when using the plus (+) sign. A simple typographical error could result in a standalone plus sign. @@ -72,7 +72,7 @@ Some systems will honor the contents of this file only when it has owner root and no write permission for anybody else. Some exceptionally paranoid systems even require that there be no other hard links to the file. -.PP +.P Modern systems use the Pluggable Authentication Modules library (PAM). With PAM a standalone plus sign is considered a wildcard character which means "any host" only when the word @@ -86,124 +86,124 @@ Below are some example or .I \[ti]/.rhosts files. -.PP +.P Allow any user to log in from any host: -.PP +.P .in +4n .EX + .EE .in -.PP +.P Allow any user from .I host with a matching local account to log in: -.PP +.P .in +4n .EX host .EE .in -.PP +.P Note: the use of .I +host is never a valid syntax, including attempting to specify that any user from the host is allowed. -.PP +.P Allow any user from .I host to log in: -.PP +.P .in +4n .EX host + .EE .in -.PP +.P Note: this is distinct from the previous example since it does not require a matching local account. -.PP +.P Allow .I user from .I host to log in as any non-root user: -.PP +.P .in +4n .EX host user .EE .in -.PP +.P Allow all users with matching local accounts from .I host to log in except for .IR baduser : -.PP +.P .in +4n .EX host \-baduser host .EE .in -.PP +.P Deny all users from .IR host : -.PP +.P .in +4n .EX \-host .EE .in -.PP +.P Note: the use of .I "\-host\ \-user" is never a valid syntax, including attempting to specify that a particular user from the host is not trusted. -.PP +.P Allow all users with matching local accounts on all hosts in a .IR netgroup : -.PP +.P .in +4n .EX +@netgroup .EE .in -.PP +.P Disallow all users on all hosts in a .IR netgroup : -.PP +.P .in +4n .EX \-@netgroup .EE .in -.PP +.P Allow all users in a .I netgroup to log in from .I host as any non-root user: -.PP +.P .in +4n .EX host +@netgroup .EE .in -.PP +.P Allow all users with matching local accounts on all hosts in a .I netgroup except .IR baduser : -.PP +.P .in +4n .EX +@netgroup \-baduser +@netgroup .EE .in -.PP +.P Note: the deny statements must always precede the allow statements because the file is processed sequentially until the first matching rule is found. .SH SEE ALSO diff --git a/man5/intro.5 b/man5/intro.5 index d30e194..10e885b 100644 --- a/man5/intro.5 +++ b/man5/intro.5 @@ -5,13 +5,13 @@ .\" .\" Modified Sat Jul 24 17:06:52 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Jan 14 00:34:09 1996 by Andries Brouwer (aeb@cwi.nl) -.TH intro 5 2022-10-30 "Linux man-pages 6.05.01" +.TH intro 5 2023-10-31 "Linux man-pages 6.7" .SH NAME intro \- introduction to file formats and filesystems .SH DESCRIPTION Section 5 of the manual describes various file formats, as well as the corresponding C structures, if any. -.PP +.P In addition, this section contains a number of pages that document various filesystems. .SH NOTES diff --git a/man5/issue.5 b/man5/issue.5 index 98dfe68..c5e2501 100644 --- a/man5/issue.5 +++ b/man5/issue.5 @@ -5,7 +5,7 @@ .\" .\" Modified Sun Jul 25 11:06:22 1993 by Rik Faith .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond -.TH issue 5 2022-10-30 "Linux man-pages 6.05.01" +.TH issue 5 2022-10-30 "Linux man-pages 6.7" .SH NAME issue \- prelogin message and identification file .SH DESCRIPTION diff --git a/man5/locale.5 b/man5/locale.5 index 051e5ed..3dade71 100644 --- a/man5/locale.5 +++ b/man5/locale.5 @@ -7,7 +7,7 @@ .\" 2008-06-17 Petr Baudis .\" LC_TIME: Describe first_weekday and first_workday .\" -.TH locale 5 2023-02-05 "Linux man-pages 6.05.01" +.TH locale 5 2024-01-28 "Linux man-pages 6.7" .SH NAME locale \- describes a locale definition file .SH DESCRIPTION @@ -16,7 +16,7 @@ The definition file contains all the information that the .BR localedef (1) command needs to convert it into the binary locale database. -.PP +.P The definition files consist of sections which each describe a locale category in detail. See @@ -36,7 +36,7 @@ It defaults to the backslash (\e). is followed by a character that will be used as the comment-character for the rest of the file. It defaults to the number sign (#). -.PP +.P The locale definition has one part for each locale category. Each part can be copied from another existing locale or can be defined from scratch. @@ -52,7 +52,7 @@ and where a .I copy statement can be followed by locale-specific rules and selected overrides. -.PP +.P When defining a locale or a category from scratch, an existing system- provided locale definition file should be used as a reference to follow common glibc conventions. @@ -70,7 +70,7 @@ The following category sections are defined by POSIX: .B LC_NUMERIC .IP \[bu] .B LC_TIME -.PP +.P In addition, since glibc 2.2, the GNU C library supports the following nonstandard categories: .IP \[bu] 3 @@ -85,7 +85,7 @@ the GNU C library supports the following nonstandard categories: .B LC_PAPER .IP \[bu] .B LC_TELEPHONE -.PP +.P See .BR locale (7) for a more detailed description of each category. @@ -93,7 +93,7 @@ for a more detailed description of each category. The definition starts with the string .I LC_ADDRESS in the first column. -.PP +.P The following keywords are allowed: .TP .I postal_fmt @@ -159,7 +159,7 @@ State, province, or prefecture. .TP %c Country, as taken from data record. -.PP +.P Each field descriptor may have an \[aq]R\[aq] after the \[aq]%\[aq] to specify that the information is taken from a Romanized version string of the @@ -176,13 +176,13 @@ locale). followed by the abbreviation of the country (see CERT_MAILCODES). .TP .I country_ab2 -followed by the two-letter abbreviation of the country (ISO 3166). +followed by the two-letter abbreviation of the country (ISO\~3166). .TP .I country_ab3 -followed by the three-letter abbreviation of the country (ISO 3166). +followed by the three-letter abbreviation of the country (ISO\~3166). .TP .I country_num -followed by the numeric country code (ISO 3166). +followed by the numeric country code (ISO\~3166). .TP .I country_car followed by the international license plate country code. @@ -194,19 +194,19 @@ followed by the ISBN code (for books). followed by the language name in the language of the current document. .TP .I lang_ab -followed by the two-letter abbreviation of the language (ISO 639). +followed by the two-letter abbreviation of the language (ISO\~639). .TP .I lang_term -followed by the three-letter abbreviation of the language (ISO 639-2/T). +followed by the three-letter abbreviation of the language (ISO\~639-2/T). .TP .I lang_lib followed by the three-letter abbreviation of the language for library -use (ISO 639-2/B). +use (ISO\~639-2/B). Applications should in general prefer .I lang_term over .IR lang_lib . -.PP +.P The .B LC_ADDRESS definition ends with the string @@ -215,7 +215,7 @@ definition ends with the string The definition starts with the string .I LC_CTYPE in the first column. -.PP +.P The following keywords are allowed: .TP .I upper @@ -461,7 +461,7 @@ in the target character set. .TP .I translit_end marks the end of the transliteration rules. -.PP +.P The .B LC_CTYPE definition ends with the string @@ -469,11 +469,11 @@ definition ends with the string .SS LC_COLLATE Note that glibc does not support all POSIX-defined options, only the options described below are supported (as of glibc 2.23). -.PP +.P The definition starts with the string .I LC_COLLATE in the first column. -.PP +.P The following keywords are allowed: .TP .I coll_weight_max @@ -506,7 +506,7 @@ followed by a redefinition of a collation rule. .I reorder\-end marks the end of the redefinition of a collation rule. .TP -.I reorde\r-sections\-after +.I reorder\-sections\-after followed by a script name to reorder listed scripts after. .TP .I reorder\-sections\-end @@ -518,7 +518,7 @@ followed by a declaration of a script. .I symbol\-equivalence followed by a collating-symbol to be equivalent to another defined collating-symbol. -.PP +.P The collation rule definition starts with a line: .TP .I order_start @@ -530,7 +530,7 @@ or The order definition consists of lines that describe the collation order and is terminated with the keyword .IR order_end . -.PP +.P The .B LC_COLLATE definition ends with the string @@ -539,7 +539,7 @@ definition ends with the string The definition starts with the string .I LC_IDENTIFICATION in the first column. -.PP +.P The following keywords are allowed: .TP .I title @@ -595,7 +595,7 @@ followed by the revision number of this document. .TP .I date followed by the revision date of this document. -.PP +.P In addition, for each of the categories defined by the document, there should be a line starting with the keyword .IR category , @@ -608,7 +608,7 @@ a semicolon, and one of the .B LC_* identifiers. -.PP +.P The .B LC_IDENTIFICATION definition ends with the string @@ -617,7 +617,7 @@ definition ends with the string The definition starts with the string .I LC_MESSAGES in the first column. -.PP +.P The following keywords are allowed: .TP .I yesexpr @@ -633,7 +633,7 @@ followed by the output string corresponding to "yes". .TP .I nostr followed by the output string corresponding to "no". -.PP +.P The .B LC_MESSAGES definition ends with the string @@ -642,7 +642,7 @@ definition ends with the string The definition starts with the string .I LC_MEASUREMENT in the first column. -.PP +.P The following keywords are allowed: .TP .I measurement @@ -656,7 +656,7 @@ Metric. .B 2 US customary measurements. .RE -.PP +.P The .B LC_MEASUREMENT definition ends with the string @@ -665,14 +665,14 @@ definition ends with the string The definition starts with the string .I LC_MONETARY in the first column. -.PP +.P The following keywords are allowed: .TP .I int_curr_symbol followed by the international currency symbol. This must be a 4-character string containing the international currency symbol as -defined by the ISO 4217 standard (three characters) followed by a +defined by the ISO\~4217 standard (three characters) followed by a separator. .TP .I currency_symbol @@ -848,7 +848,7 @@ should be placed for a negative internationally formatted monetary quantity. The same values are recognized as for .IR p_sign_posn . -.PP +.P The .B LC_MONETARY definition ends with the string @@ -857,7 +857,7 @@ definition ends with the string The definition starts with the string .I LC_NAME in the first column. -.PP +.P Various keywords are allowed, but only .I name_fmt is mandatory. @@ -935,7 +935,7 @@ followed by the salutation for unmarried women. .TP .I name_ms followed by the salutation valid for all women. -.PP +.P The .B LC_NAME definition ends with the string @@ -944,7 +944,7 @@ definition ends with the string The definition starts with the string .I LC_NUMERIC in the first column. -.PP +.P The following keywords are allowed: .TP .I decimal_point @@ -967,7 +967,7 @@ left of the previous group. If the last integer is not \-1, then the size of the previous group (if any) is repeatedly used for the remainder of the digits. If the last integer is \-1, then no further grouping is performed. -.PP +.P The .B LC_NUMERIC definition ends with the string @@ -976,7 +976,7 @@ definition ends with the string The definition starts with the string .I LC_PAPER in the first column. -.PP +.P The following keywords are allowed: .TP .I height @@ -984,7 +984,7 @@ followed by the height, in millimeters, of the standard paper format. .TP .I width followed by the width, in millimeters, of the standard paper format. -.PP +.P The .B LC_PAPER definition ends with the string @@ -993,7 +993,7 @@ definition ends with the string The definition starts with the string .I LC_TELEPHONE in the first column. -.PP +.P The following keywords are allowed: .TP .I tel_int_fmt @@ -1036,7 +1036,7 @@ followed by the prefix used to call international phone numbers. .TP .I int_prefix followed by the prefix used from other countries to dial this country. -.PP +.P The .B LC_TELEPHONE definition ends with the string @@ -1045,7 +1045,7 @@ definition ends with the string The definition starts with the string .I LC_TIME in the first column. -.PP +.P The following keywords are allowed: .TP .I abday @@ -1105,9 +1105,9 @@ followed by semicolon-separated strings that define how years are counted and displayed for each era in the locale. Each string has the following format: .RS -.PP +.P .IR direction ":" offset ":" start_date ":" end_date ":" era_name ":" era_format -.PP +.P The fields are to be defined as follows: .TP 4 .I direction @@ -1237,7 +1237,7 @@ followed by the appropriate date representation for .BR date (1) (for syntax, see .BR strftime (3)). -.PP +.P The .B LC_TIME definition ends with the string diff --git a/man5/motd.5 b/man5/motd.5 index b506c95..26dc74e 100644 --- a/man5/motd.5 +++ b/man5/motd.5 @@ -5,7 +5,7 @@ .\" .\" Modified Sat Jul 24 17:08:16 1993 by Rik Faith .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond -.TH motd 5 2022-10-30 "Linux man-pages 6.05.01" +.TH motd 5 2023-10-31 "Linux man-pages 6.7" .SH NAME motd \- message of the day .SH DESCRIPTION @@ -14,7 +14,7 @@ The contents of are displayed by .BR login (1) after a successful login but just before it executes the login shell. -.PP +.P The abbreviation "motd" stands for "message of the day", and this file has been traditionally used for exactly that (it requires much less disk space than mail to all users). diff --git a/man5/networks.5 b/man5/networks.5 index cf660e3..168c2c5 100644 --- a/man5/networks.5 +++ b/man5/networks.5 @@ -4,7 +4,7 @@ .\" .\" 2008-09-04, mtk, taken from Debian downstream, with a few light edits .\" -.TH networks 5 2022-10-30 "Linux man-pages 6.05.01" +.TH networks 5 2024-02-25 "Linux man-pages 6.7" .SH NAME networks \- network name information .SH DESCRIPTION @@ -13,18 +13,18 @@ The file is a plain ASCII file that describes known DARPA networks and symbolic names for these networks. Each line represents a network and has the following structure: -.PP +.P .RS -.I name number aliases ... +.I name number aliases .\|.\|. .RE -.PP +.P where the fields are delimited by spaces or tabs. Empty lines are ignored. The hash character (\fB#\fP) indicates the start of a comment: this character, and the remaining characters up to the end of the current line, are ignored by library functions that process the file. -.PP +.P The field descriptions are: .TP .I name @@ -40,7 +40,7 @@ may be omitted. .TP .I aliases Optional aliases for the network. -.PP +.P This file is read by the .BR route (8) and diff --git a/man5/nologin.5 b/man5/nologin.5 index af006f5..b5242a4 100644 --- a/man5/nologin.5 +++ b/man5/nologin.5 @@ -5,7 +5,7 @@ .\" .\" Modified Sun Jul 25 11:06:34 1993 by Rik Faith (faith@cs.unc.edu) .\" Corrected Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) -.TH nologin 5 2022-10-30 "Linux man-pages 6.05.01" +.TH nologin 5 2022-10-30 "Linux man-pages 6.7" .SH NAME nologin \- prevent unprivileged users from logging into the system .SH DESCRIPTION diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5 index 041793e..c2a1d61 100644 --- a/man5/nscd.conf.5 +++ b/man5/nscd.conf.5 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH nscd.conf 5 2023-02-05 "Linux man-pages 6.05.01" +.TH nscd.conf 5 2023-10-31 "Linux man-pages 6.7" .SH NAME nscd.conf \- name service cache daemon configuration file .SH DESCRIPTION @@ -20,16 +20,16 @@ or TAB characters. A \[aq]#\[aq] (number sign) indicates the beginning of a comment; following characters, up to the end of the line, are not interpreted by nscd. -.PP +.P Valid services are \fIpasswd\fP, \fIgroup\fP, \fIhosts\fP, \fIservices\fP, or \fInetgroup\fP. -.PP +.P .B logfile .I debug-file-name .RS Specifies name of the file to which debug info should be written. .RE -.PP +.P .B debug\-level .I value .RS @@ -40,7 +40,7 @@ Sets the desired debug level. 3 (and above) shows all debug info. The default is 0. .RE -.PP +.P .B threads .I number .RS @@ -52,14 +52,14 @@ The number of threads may increase dynamically up to in response to demand from clients, but never decreases. .RE -.PP +.P .B max\-threads .I number .RS Specifies the maximum number of threads. The default is 32. .RE -.PP +.P .B server\-user .I user .RS @@ -67,13 +67,13 @@ If this option is set, nscd will run as this user and not as root. If a separate cache for every user is used (\-S parameter), this option is ignored. .RE -.PP +.P .B stat\-user .I user .RS Specifies the user who is allowed to request statistics. .RE -.PP +.P .B reload\-count unlimited | .I number @@ -93,14 +93,14 @@ The default limit is 5. A limit of 0 turns off the reloading feature. See NOTES below for further discussion of reloading. .RE -.PP +.P .B paranoia .I .RS Enabling paranoia mode causes nscd to restart itself periodically. The default is no. .RE -.PP +.P .B restart\-interval .I time .RS @@ -112,7 +112,7 @@ if periodic restart is enabled by enabling mode. The default is 3600. .RE -.PP +.P .B enable\-cache .I service .I @@ -122,7 +122,7 @@ Enables or disables the specified cache. The default is no. .RE -.PP +.P .B positive\-time\-to\-live .I service .I value @@ -138,7 +138,7 @@ Note that for some name services (including specifically DNS) the TTL returned from the name service is used and this attribute is ignored. .RE -.PP +.P .B negative\-time\-to\-live .I service .I value @@ -153,7 +153,7 @@ are several files owned by UIDs (user IDs) not in system databases (for example untarring the Linux kernel sources as root); should be kept small to reduce cache coherency problems. .RE -.PP +.P .B suggested\-size .I service .I value @@ -163,7 +163,7 @@ This is the internal hash table size, should remain a prime number for optimum efficiency. The default is 211. .RE -.PP +.P .B check\-files .I service .I @@ -181,7 +181,7 @@ and .IR /etc/netgroup . The default is yes. .RE -.PP +.P .B persistent .I service .I @@ -193,7 +193,7 @@ over server restarts; useful when mode is set. The default is no. .RE -.PP +.P .B shared .I service .I @@ -207,7 +207,7 @@ The default is no. Note that a cache miss will still result in asking the daemon over the socket. .RE -.PP +.P .B max\-db\-size .I service .I bytes @@ -216,7 +216,7 @@ The maximum allowable size, in bytes, of the database files for the .IR service . The default is 33554432. .RE -.PP +.P .B auto\-propagate .I service .I @@ -252,13 +252,13 @@ your distribution might differ. .BR nscd (8) has a feature called reloading, whose behavior can be surprising. -.PP +.P Reloading is enabled when the .B reload-count attribute has a non-zero value. The default value in the source code enables reloading, although your distribution may differ. -.PP +.P When reloading is enabled, positive cached entries (the results of successful queries) do not simply expire when their TTL is up. @@ -282,7 +282,7 @@ reset the reload counter on the entry. Purging the cache using .I nscd\~-i overrides the reload logic and removes the entry. -.PP +.P Reloading has the effect of extending cache entry TTLs without compromising on cache coherency, at the cost of additional load on the backing name service. @@ -297,7 +297,7 @@ the effective TTL is the value returned from the name service and the value of the .B positive\-time\-to\-live attribute. -.PP +.P Please consider the following advice carefully: .IP \[bu] 3 If your application will make a second request for the same name, @@ -325,7 +325,7 @@ to is almost never a good idea, as it will result in a cache that never expires entries and puts never-ending additional load on the backing name service. -.PP +.P Some distributions have an init script for .BR nscd (8) with a diff --git a/man5/nss.5 b/man5/nss.5 index d53e1cd..00b9f0c 100644 --- a/man5/nss.5 +++ b/man5/nss.5 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH nss 5 2023-02-05 "Linux man-pages 6.05.01" +.TH nss 5 2023-10-31 "Linux man-pages 6.7" .SH NAME nss \- Name Service Switch configuration file .SH DESCRIPTION @@ -13,7 +13,7 @@ Switch implementation in the GNU C library. The various services provided are implemented by independent modules, each of which naturally varies widely from the other. -.PP +.P The default implementations coming with the GNU C library are by default conservative and do not use unsafe data. This might be very costly in some situations, especially when the databases @@ -22,11 +22,11 @@ Some modules allow the system administrator to request taking shortcuts if these are known to be safe. It is then the system administrator's responsibility to ensure the assumption is correct. -.PP +.P There are other modules where the implementation changed over time. If an implementation used to sacrifice speed for memory consumption, it might create problems if the preference is switched. -.PP +.P The .I /etc/default/nss file contains a number of variable assignments. @@ -35,7 +35,7 @@ NSS modules. White spaces are ignored. Lines beginning with \[aq]#\[aq] are treated as comments. -.PP +.P The variables currently recognized are: .TP \fBNETID_AUTHORITATIVE =\fR \fITRUE\fR|\fIFALSE\fR @@ -86,7 +86,7 @@ the next entry. \fI/etc/default/nss\fR .SH EXAMPLES The default configuration corresponds to the following configuration file: -.PP +.P .in +4n .EX NETID_AUTHORITATIVE=FALSE diff --git a/man5/nsswitch.conf.5 b/man5/nsswitch.conf.5 index 49b288e..34dd7d7 100644 --- a/man5/nsswitch.conf.5 +++ b/man5/nsswitch.conf.5 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH nsswitch.conf 5 2023-05-03 "Linux man-pages 6.05.01" +.TH nsswitch.conf 5 2023-10-31 "Linux man-pages 6.7" .SH NAME nsswitch.conf \- Name Service Switch configuration file .SH DESCRIPTION @@ -14,13 +14,13 @@ the sources from which to obtain name-service information in a range of categories, and in what order. Each category of information is identified by a database name. -.PP +.P The file is plain ASCII text, with columns separated by spaces or tab characters. The first column specifies the database name. The remaining columns describe the order of sources to query and a limited set of actions that can be performed by lookup result. -.PP +.P The following databases are understood by the GNU C Library: .TP 12 .B aliases @@ -82,7 +82,7 @@ and related functions. Shadow user passwords, used by .BR getspnam (3) and related functions. -.PP +.P The GNU C Library ignores databases with unknown names. Some applications use this to implement special handling for their own databases. @@ -100,11 +100,11 @@ Refer to and .BR subgid (5) for more details. -.PP +.P Here is an example .I /etc/nsswitch.conf file: -.PP +.P .in +4n .EX passwd: compat @@ -119,7 +119,7 @@ rpc: nis [NOTFOUND=return] files services: nis [NOTFOUND=return] files .EE .in -.PP +.P The first column is the database name. The remaining columns specify: .IP \[bu] 3 @@ -129,7 +129,7 @@ those services will be queried, in turn, until a result is found. .IP \[bu] Optional actions to perform if a particular result is obtained from the preceding service, for example, "[NOTFOUND=return]". -.PP +.P The service specifications supported on your system depend on the presence of shared libraries, and are therefore extensible. Libraries called @@ -155,20 +155,20 @@ The version number may be 1 for glibc 2.0, or 2 for glibc 2.1 and later. On systems with additional libraries installed, you may have access to further services such as "hesiod", "ldap", "winbind", and "wins". -.PP +.P An action may also be specified following a service specification. The action modifies the behavior following a result obtained from the preceding data source. Action items take the general form: -.PP +.P .RS 4 .RI [ STATUS = ACTION ] .br .RI [! STATUS = ACTION ] .RE -.PP +.P where -.PP +.P .RS 4 .I STATUS => @@ -188,11 +188,11 @@ where | .B merge .RE -.PP +.P The ! negates the test, matching all possible results except the one specified. The case of the keywords is not significant. -.PP +.P The .I STATUS value is matched against the result of the lookup function called by @@ -220,7 +220,7 @@ This could mean a file is locked or a server currently cannot accept more connections. The default action for this condition is "continue". .RE -.PP +.P The .I ACTION value can be one of: @@ -261,7 +261,7 @@ additionally permits special entries in corresponding files for granting users or members of netgroups access to the system. The following entries are valid in this mode: .RS 4 -.PP +.P For .B passwd and @@ -291,7 +291,7 @@ Exclude all users in the given Include every user, except previously excluded ones, from the NIS passwd/shadow map. .RE -.PP +.P For .B group database: @@ -312,7 +312,7 @@ Include every group, except previously excluded ones, from the NIS group map. .RE .RE -.PP +.P By default, the source is "nis", but this may be overridden by specifying any NSS service except "compat" itself as the source for the pseudo-databases @@ -355,7 +355,7 @@ implements "nis" source. implements "nisplus" source. .PD .RE -.PP +.P The following files are read when "files" source is specified for respective databases: .RS 4 @@ -409,7 +409,7 @@ is automatically reloaded if the file is changed. In earlier versions, the entire file was read only once within each process. If the file was later changed, the process would continue using the old configuration. -.PP +.P Traditionally, there was only a single source for service information, often in the form of a single configuration file (e.g., \fI/etc/passwd\fP). diff --git a/man5/passwd.5 b/man5/passwd.5 index 9b9a136..1570383 100644 --- a/man5/passwd.5 +++ b/man5/passwd.5 @@ -8,7 +8,7 @@ .\" Modified Sun Jun 18 01:53:57 1995 by Andries Brouwer (aeb@cwi.nl) .\" Modified Mon Jan 5 20:24:40 MET 1998 by Michael Haardt .\" (michael@cantor.informatik.rwth-aachen.de) -.TH passwd 5 2023-02-05 "Linux man-pages 6.05.01" +.TH passwd 5 2023-10-31 "Linux man-pages 6.7" .SH NAME passwd \- password file .SH DESCRIPTION @@ -19,7 +19,7 @@ It should have read permission allowed for all users (many utilities, like .BR ls (1) use it to map user IDs to usernames), but write access only for the superuser. -.PP +.P In the good old days there was no great problem with this general read permission. Everybody could read the encrypted passwords, but the @@ -31,7 +31,7 @@ has an \[aq]x\[aq] character in the password field, and the encrypted passwords are in .IR /etc/shadow , which is readable by the superuser only. -.PP +.P If the encrypted password, whether in .I /etc/passwd or in @@ -44,32 +44,32 @@ or .RB \[dq] nonull \[dq] arguments to .BR pam_unix (8)). -.PP +.P If the encrypted password in .I /etc/passwd is "\fI*NP*\fP" (without the quotes), the shadow record should be obtained from an NIS+ server. -.PP +.P Regardless of whether shadow passwords are used, many system administrators use an asterisk (*) in the encrypted password field to make sure that this user can not authenticate themself using a password. (But see NOTES below.) -.PP +.P If you create a new login, first put an asterisk (*) in the password field, then use .BR passwd (1) to set it. -.PP +.P Each line of the file describes a single user, and contains seven colon-separated fields: -.PP +.P .in +4n .EX name:password:UID:GID:GECOS:directory:shell .EE .in -.PP +.P The field are as follows: .TP 12 .I name @@ -132,7 +132,7 @@ environment variable. If you want to create user groups, there must be an entry in .IR /etc/group , or no group will exist. -.PP +.P If the encrypted password is set to an asterisk (*), the user will be unable to login using .BR login (1), diff --git a/man5/proc.5 b/man5/proc.5 index 9a48841..ce072ee 100644 --- a/man5/proc.5 +++ b/man5/proc.5 @@ -1,40 +1,10 @@ -'\" t -.\" Copyright (C) 1994, 1995 by Daniel Quinlan (quinlan@yggdrasil.com) -.\" and Copyright (C) 2002-2008,2017 Michael Kerrisk -.\" with networking additions from Alan Cox (A.Cox@swansea.ac.uk) -.\" and scsi additions from Michael Neuffer (neuffer@mail.uni-mainz.de) -.\" and sysctl additions from Andries Brouwer (aeb@cwi.nl) -.\" and System V IPC (as well as various other) additions from -.\" Michael Kerrisk +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar .\" -.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" SPDX-License-Identifier: GPL-3.0-or-later .\" -.\" Modified 1995-05-17 by faith@cs.unc.edu -.\" Minor changes by aeb and Marty Leisner (leisner@sdsp.mc.xerox.com). -.\" Modified 1996-04-13, 1996-07-22 by aeb@cwi.nl -.\" Modified 2001-12-16 by rwhron@earthlink.net -.\" Modified 2002-07-13 by jbelton@shaw.ca -.\" Modified 2002-07-22, 2003-05-27, 2004-04-06, 2004-05-25 -.\" by Michael Kerrisk -.\" 2004-11-17, mtk -- updated notes on /proc/loadavg -.\" 2004-12-01, mtk, rtsig-max and rtsig-nr went away in Linux 2.6.8 -.\" 2004-12-14, mtk, updated 'statm', and fixed error in order of list -.\" 2005-05-12, mtk, updated 'stat' -.\" 2005-07-13, mtk, added /proc/sys/fs/mqueue/* -.\" 2005-09-16, mtk, Added /proc/sys/fs/suid_dumpable -.\" 2005-09-19, mtk, added /proc/zoneinfo -.\" 2005-03-01, mtk, moved /proc/sys/fs/mqueue/* material to mq_overview.7. -.\" 2008-06-05, mtk, Added /proc/[pid]/oom_score, /proc/[pid]/oom_adj, -.\" /proc/[pid]/limits, /proc/[pid]/mountinfo, /proc/[pid]/mountstats, -.\" and /proc/[pid]/fdinfo/*. -.\" 2008-06-19, mtk, Documented /proc/[pid]/status. -.\" 2008-07-15, mtk, added /proc/config.gz -.\" -.\" FIXME cross check against Documentation/filesystems/proc.txt -.\" to see what information could be imported from that file -.\" into this file. -.\" -.TH proc 5 2023-07-08 "Linux man-pages 6.05.01" +.TH proc 5 2023-10-31 "Linux man-pages 6.7" .SH NAME proc \- process information, system information, and sysctl pseudo-filesystem .SH DESCRIPTION @@ -46,13 +16,13 @@ It is commonly mounted at .IR /proc . Typically, it is mounted automatically by the system, but it can also be mounted manually using a command such as: -.PP +.P .in +4n .EX mount \-t proc proc /proc .EE .in -.PP +.P Most of the files in the .B proc filesystem are read-only, @@ -205,6723 +175,47 @@ directory. Various other files and subdirectories under .I /proc expose system-wide information. -.PP +.P All of the above are described in more detail below. .\" -.SS Files and directories -The following list provides details of many of the files and directories -under the -.I /proc -hierarchy. -.TP -.IR /proc/ pid -There is a numerical subdirectory for each running process; the -subdirectory is named by the process ID. -Each -.IR /proc/ pid -subdirectory contains the pseudo-files and directories described below. -.IP -The files inside each -.IR /proc/ pid -directory are normally owned by the effective user and -effective group ID of the process. -However, as a security measure, the ownership is made -.I root:root -if the process's "dumpable" attribute is set to a value other than 1. -.IP -Before Linux 4.11, -.\" commit 68eb94f16227336a5773b83ecfa8290f1d6b78ce -.I root:root -meant the "global" root user ID and group ID -(i.e., UID 0 and GID 0 in the initial user namespace). -Since Linux 4.11, -if the process is in a noninitial user namespace that has a -valid mapping for user (group) ID 0 inside the namespace, then -the user (group) ownership of the files under -.IR /proc/ pid -is instead made the same as the root user (group) ID of the namespace. -This means that inside a container, -things work as expected for the container "root" user. -.IP -The process's "dumpable" attribute may change for the following reasons: -.RS -.IP \[bu] 3 -The attribute was explicitly set via the -.BR prctl (2) -.B PR_SET_DUMPABLE -operation. -.IP \[bu] -The attribute was reset to the value in the file -.I /proc/sys/fs/suid_dumpable -(described below), for the reasons described in -.BR prctl (2). -.RE -.IP -Resetting the "dumpable" attribute to 1 reverts the ownership of the -.IR /proc/ pid /* -files to the process's effective UID and GID. -Note, however, that if the effective UID or GID is subsequently modified, -then the "dumpable" attribute may be reset, as described in -.BR prctl (2). -Therefore, it may be desirable to reset the "dumpable" attribute -.I after -making any desired changes to the process's effective UID or GID. -.TP -.IR /proc/ pid /attr -.\" https://lwn.net/Articles/28222/ -.\" From: Stephen Smalley -.\" To: LKML and others -.\" Subject: [RFC][PATCH] Process Attribute API for Security Modules -.\" Date: 08 Apr 2003 16:17:52 -0400 +.\" .SH FILES +.\" FIXME Describe /proc/[pid]/sessionid +.\" commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc +.\" CONFIG_AUDITSYSCALL +.\" Added in Linux 2.6.25; read-only; only readable by real UID .\" -.\" http://www.nsa.gov/research/_files/selinux/papers/module/x362.shtml +.\" FIXME Describe /proc/[pid]/sched +.\" Added in Linux 2.6.23 +.\" CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS +.\" Displays various scheduling parameters +.\" This file can be written, to reset stats +.\" The set of fields exposed by this file have changed +.\" significantly over time. +.\" commit 43ae34cb4cd650d1eb4460a8253a8e747ba052ac .\" -The files in this directory provide an API for security modules. -The contents of this directory are files that can be read and written -in order to set security-related attributes. -This directory was added to support SELinux, -but the intention was that the API be general enough to support -other security modules. -For the purpose of explanation, -examples of how SELinux uses these files are provided below. -.IP -This directory is present only if the kernel was configured with -.BR CONFIG_SECURITY . -.TP -.IR /proc/ pid /attr/current " (since Linux 2.6.0)" -The contents of this file represent the current -security attributes of the process. -.IP -In SELinux, this file is used to get the security context of a process. -Prior to Linux 2.6.11, this file could not be used to set the security -context (a write was always denied), since SELinux limited process security -transitions to -.BR execve (2) -(see the description of -.IR /proc/ pid /attr/exec , -below). -Since Linux 2.6.11, SELinux lifted this restriction and began supporting -"set" operations via writes to this node if authorized by policy, -although use of this operation is only suitable for applications that are -trusted to maintain any desired separation between the old and new security -contexts. -.IP -Prior to Linux 2.6.28, SELinux did not allow threads within a -multithreaded process to set their security context via this node -as it would yield an inconsistency among the security contexts of the -threads sharing the same memory space. -Since Linux 2.6.28, SELinux lifted -this restriction and began supporting "set" operations for threads within -a multithreaded process if the new security context is bounded by the old -security context, where the bounded relation is defined in policy and -guarantees that the new security context has a subset of the permissions -of the old security context. -.IP -Other security modules may choose to support "set" operations via -writes to this node. -.TP -.IR /proc/ pid /attr/exec " (since Linux 2.6.0)" -This file represents the attributes to assign to the -process upon a subsequent -.BR execve (2). -.IP -In SELinux, -this is needed to support role/domain transitions, and -.BR execve (2) -is the preferred point to make such transitions because it offers better -control over the initialization of the process in the new security label -and the inheritance of state. -In SELinux, this attribute is reset on -.BR execve (2) -so that the new program reverts to the default behavior for any -.BR execve (2) -calls that it may make. -In SELinux, a process can set -only its own -.IR /proc/ pid /attr/exec -attribute. -.TP -.IR /proc/ pid /attr/fscreate " (since Linux 2.6.0)" -This file represents the attributes to assign to files -created by subsequent calls to -.BR open (2), -.BR mkdir (2), -.BR symlink (2), -and -.BR mknod (2) -.IP -SELinux employs this file to support creation of a file -(using the aforementioned system calls) -in a secure state, -so that there is no risk of inappropriate access being obtained -between the time of creation and the time that attributes are set. -In SELinux, this attribute is reset on -.BR execve (2), -so that the new program reverts to the default behavior for -any file creation calls it may make, but the attribute will persist -across multiple file creation calls within a program unless it is -explicitly reset. -In SELinux, a process can set only its own -.IR /proc/ pid /attr/fscreate -attribute. -.TP -.IR /proc/ pid /attr/keycreate " (since Linux 2.6.18)" -.\" commit 4eb582cf1fbd7b9e5f466e3718a59c957e75254e -If a process writes a security context into this file, -all subsequently created keys -.RB ( add_key (2)) -will be labeled with this context. -For further information, see the kernel source file -.I Documentation/security/keys/core.rst -(or file -.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 -.I Documentation/security/keys.txt -between Linux 3.0 and Linux 4.13, or -.\" commit d410fa4ef99112386de5f218dd7df7b4fca910b4 -.I Documentation/keys.txt -before Linux 3.0). -.TP -.IR /proc/ pid /attr/prev " (since Linux 2.6.0)" -This file contains the security context of the process before the last -.BR execve (2); -that is, the previous value of -.IR /proc/ pid /attr/current . -.TP -.IR /proc/ pid /attr/socketcreate " (since Linux 2.6.18)" -.\" commit 42c3e03ef6b298813557cdb997bd6db619cd65a2 -If a process writes a security context into this file, -all subsequently created sockets will be labeled with this context. -.TP -.IR /proc/ pid /autogroup " (since Linux 2.6.38)" -.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a -See -.BR sched (7). -.TP -.IR /proc/ pid /auxv " (since Linux 2.6.0)" -.\" Precisely: Linux 2.6.0-test7 -This contains the contents of the ELF interpreter information passed -to the process at exec time. -The format is one \fIunsigned long\fP ID -plus one \fIunsigned long\fP value for each entry. -The last entry contains two zeros. -See also -.BR getauxval (3). -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /cgroup " (since Linux 2.6.24)" -See -.BR cgroups (7). -.TP -.IR /proc/ pid /clear_refs " (since Linux 2.6.22)" -.\" commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22) -.\" commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32) -.\" commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11) +.\" FIXME Describe /proc/[pid]/schedstats and +.\" /proc/[pid]/task/[tid]/schedstats +.\" Added in Linux 2.6.9 +.\" CONFIG_SCHEDSTATS +.\" FIXME Document /proc/sched_debug (since Linux 2.6.23) +.\" See also /proc/[pid]/sched +.\" FIXME 2.6.13 seems to have /proc/vmcore implemented; document this +.\" See Documentation/kdump/kdump.txt +.\" commit 666bfddbe8b8fd4fd44617d6c55193d5ac7edb29 +.\" Needs CONFIG_VMCORE .\" -.\" "Clears page referenced bits shown in smaps output" -.\" write-only, writable only by the owner of the process -.IP -This is a write-only file, writable only by owner of the process. -.IP -The following values may be written to the file: -.RS -.TP -1 (since Linux 2.6.22) -.\" Internally: CLEAR_REFS_ALL -Reset the PG_Referenced and ACCESSED/YOUNG -bits for all the pages associated with the process. -(Before Linux 2.6.32, writing any nonzero value to this file -had this effect.) -.TP -2 (since Linux 2.6.32) -.\" Internally: CLEAR_REFS_ANON -Reset the PG_Referenced and ACCESSED/YOUNG -bits for all anonymous pages associated with the process. -.TP -3 (since Linux 2.6.32) -.\" Internally: CLEAR_REFS_MAPPED -Reset the PG_Referenced and ACCESSED/YOUNG -bits for all file-mapped pages associated with the process. -.RE -.IP -Clearing the PG_Referenced and ACCESSED/YOUNG bits provides a method -to measure approximately how much memory a process is using. -One first inspects the values in the "Referenced" fields -for the VMAs shown in -.IR /proc/ pid /smaps -to get an idea of the memory footprint of the -process. -One then clears the PG_Referenced and ACCESSED/YOUNG bits -and, after some measured time interval, -once again inspects the values in the "Referenced" fields -to get an idea of the change in memory footprint of the -process during the measured interval. -If one is interested only in inspecting the selected mapping types, -then the value 2 or 3 can be used instead of 1. -.IP -Further values can be written to affect different properties: -.RS -.TP -4 (since Linux 3.11) -Clear the soft-dirty bit for all the pages associated with the process. -.\" Internally: CLEAR_REFS_SOFT_DIRTY -This is used (in conjunction with -.IR /proc/ pid /pagemap ) -by the check-point restore system to discover which pages of a process -have been dirtied since the file -.IR /proc/ pid /clear_refs -was written to. -.TP -5 (since Linux 4.0) -.\" Internally: CLEAR_REFS_MM_HIWATER_RSS -Reset the peak resident set size ("high water mark") to the process's -current resident set size value. -.RE -.IP -Writing any value to -.IR /proc/ pid /clear_refs -other than those listed above has no effect. -.IP -The -.IR /proc/ pid /clear_refs -file is present only if the -.B CONFIG_PROC_PAGE_MONITOR -kernel configuration option is enabled. -.TP -.IR /proc/ pid /cmdline -This read-only file holds the complete command line for the process, -unless the process is a zombie. -.\" In Linux 2.3.26, this also used to be true if the process was swapped out. -In the latter case, there is nothing in this file: -that is, a read on this file will return 0 characters. -.IP -For processes which are still running, -the command-line arguments appear in this file -in the same layout as they do in process memory: -If the process is well-behaved, -it is a set of strings separated by null bytes (\[aq]\e0\[aq]), -with a further null byte after the last string. -.IP -This is the common case, -but processes have the freedom to -override the memory region and -break assumptions about the contents or format of the -.IR /proc/ pid /cmdline -file. -.IP -If, after an -.BR execve (2), -the process modifies its -.I argv -strings, those changes will show up here. -This is not the same thing as modifying the -.I argv -array. -.IP -Furthermore, a process may change the memory location that this file refers via -.BR prctl (2) -operations such as -.BR PR_SET_MM_ARG_START . -.IP -Think of this file as the command line that the process wants you to see. -.TP -.IR /proc/ pid /comm " (since Linux 2.6.33)" -.\" commit 4614a696bd1c3a9af3a08f0e5874830a85b889d4 -This file exposes the process's -.I comm -value\[em]that is, the command name associated with the process. -Different threads in the same process may have different -.I comm -values, accessible via -.IR /proc/ pid /task/ tid /comm . -A thread may modify its -.I comm -value, or that of any of other thread in the same thread group (see -the discussion of -.B CLONE_THREAD -in -.BR clone (2)), -by writing to the file -.IR /proc/self/task/ tid /comm . -Strings longer than -.B TASK_COMM_LEN -(16) characters (including the terminating null byte) are silently truncated. -.IP -This file provides a superset of the -.BR prctl (2) -.B PR_SET_NAME -and -.B PR_GET_NAME -operations, and is employed by -.BR pthread_setname_np (3) -when used to rename threads other than the caller. -The value in this file is used for the -.I %e -specifier in -.IR /proc/sys/kernel/core_pattern ; -see -.BR core (5). -.TP -.IR /proc/ pid /coredump_filter " (since Linux 2.6.23)" -See -.BR core (5). -.TP -.IR /proc/ pid /cpuset " (since Linux 2.6.12)" -.\" and/proc/[pid]/task/[tid]/cpuset -See -.BR cpuset (7). -.TP -.IR /proc/ pid /cwd -This is a symbolic link to the current working directory of the process. -To find out the current working directory of process 20, -for instance, you can do this: -.IP -.in +4n -.EX -.RB "$" " cd /proc/20/cwd; pwd \-P" -.EE -.in -.IP -.\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of this symbolic link -are not available if the main thread has already terminated -(typically by calling -.BR pthread_exit (3)). -.IP -Permission to dereference or read -.RB ( readlink (2)) -this symbolic link is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /environ -This file contains the initial environment that was set -when the currently executing program was started via -.BR execve (2). -The entries are separated by null bytes (\[aq]\e0\[aq]), -and there may be a null byte at the end. -Thus, to print out the environment of process 1, you would do: -.IP -.in +4n -.EX -.RB "$" " cat /proc/1/environ | tr \[aq]\e000\[aq] \[aq]\en\[aq]" -.EE -.in -.IP -If, after an -.BR execve (2), -the process modifies its environment -(e.g., by calling functions such as -.BR putenv (3) -or modifying the -.BR environ (7) -variable directly), -this file will -.I not -reflect those changes. -.IP -Furthermore, a process may change the memory location that this file refers via -.BR prctl (2) -operations such as -.BR PR_SET_MM_ENV_START . -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /exe -Under Linux 2.2 and later, this file is a symbolic link -containing the actual pathname of the executed command. -This symbolic link can be dereferenced normally; attempting to open -it will open the executable. -You can even type -.IR /proc/ pid /exe -to run another copy of the same executable that is being run by -process -.IR pid . -If the pathname has been unlinked, the symbolic link will contain the -string \[aq]\ (deleted)\[aq] appended to the original pathname. -.\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of this symbolic link -are not available if the main thread has already terminated -(typically by calling -.BR pthread_exit (3)). -.IP -Permission to dereference or read -.RB ( readlink (2)) -this symbolic link is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.IP -Under Linux 2.0 and earlier, -.IR /proc/ pid /exe -is a pointer to the binary which was executed, -and appears as a symbolic link. -A -.BR readlink (2) -call on this file under Linux 2.0 returns a string in the format: -.IP -.in +4n -.EX -[device]:inode -.EE -.in -.IP -For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, -MFM, etc. drives) minor 01 (first partition on the first drive). -.IP -.BR find (1) -with the -.I \-inum -option can be used to locate the file. -.TP -.IR /proc/ pid /fd/ -This is a subdirectory containing one entry for each file which the -process has open, named by its file descriptor, and which is a -symbolic link to the actual file. -Thus, 0 is standard input, 1 standard output, 2 standard error, and so on. -.IP -For file descriptors for pipes and sockets, -the entries will be symbolic links whose content is the -file type with the inode. -A -.BR readlink (2) -call on this file returns a string in the format: -.IP -.in +4n -.EX -type:[inode] -.EE -.in -.IP -For example, -.I socket:[2248868] -will be a socket and its inode is 2248868. -For sockets, that inode can be used to find more information -in one of the files under -.IR /proc/net/ . -.IP -For file descriptors that have no corresponding inode -(e.g., file descriptors produced by -.BR bpf (2), -.BR epoll_create (2), -.BR eventfd (2), -.BR inotify_init (2), -.BR perf_event_open (2), -.BR signalfd (2), -.BR timerfd_create (2), -and -.BR userfaultfd (2)), -the entry will be a symbolic link with contents of the form -.IP -.in +4n -.EX -.RI anon_inode: file-type -.EE -.in -.IP -In many cases (but not all), the -.I file-type -is surrounded by square brackets. -.IP -For example, an epoll file descriptor will have a symbolic link -whose content is the string -.IR "anon_inode:[eventpoll]" . -.IP -.\"The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of this directory -are not available if the main thread has already terminated -(typically by calling -.BR pthread_exit (3)). -.IP -Programs that take a filename as a command-line argument, -but don't take input from standard input if no argument is supplied, -and programs that write to a file named as a command-line argument, -but don't send their output to standard output -if no argument is supplied, can nevertheless be made to use -standard input or standard output by using -.IR /proc/ pid /fd -files as command-line arguments. -For example, assuming that -.I \-i -is the flag designating an input file and -.I \-o -is the flag designating an output file: -.IP -.in +4n -.EX -.RB "$" " foobar \-i /proc/self/fd/0 \-o /proc/self/fd/1 ..." -.EE -.in -.IP -and you have a working filter. -.\" The following is not true in my tests (MTK): -.\" Note that this will not work for -.\" programs that seek on their files, as the files in the fd directory -.\" are not seekable. -.IP -.I /proc/self/fd/N -is approximately the same as -.I /dev/fd/N -in some UNIX and UNIX-like systems. -Most Linux MAKEDEV scripts symbolically link -.I /dev/fd -to -.IR /proc/self/fd , -in fact. -.IP -Most systems provide symbolic links -.IR /dev/stdin , -.IR /dev/stdout , -and -.IR /dev/stderr , -which respectively link to the files -.IR 0 , -.IR 1 , -and -.I 2 -in -.IR /proc/self/fd . -Thus the example command above could be written as: -.IP -.in +4n -.EX -.RB "$" " foobar \-i /dev/stdin \-o /dev/stdout ..." -.EE -.in -.IP -Permission to dereference or read -.RB ( readlink (2)) -the symbolic links in this directory is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.IP -Note that for file descriptors referring to inodes -(pipes and sockets, see above), -those inodes still have permission bits and ownership information -distinct from those of the -.IR /proc/ pid /fd -entry, -and that the owner may differ from the user and group IDs of the process. -An unprivileged process may lack permissions to open them, as in this example: -.IP -.in +4n -.EX -.RB "$" " echo test | sudo \-u nobody cat" -test -.RB "$" " echo test | sudo \-u nobody cat /proc/self/fd/0" -cat: /proc/self/fd/0: Permission denied -.EE -.in -.IP -File descriptor 0 refers to the pipe created by the shell -and owned by that shell's user, which is not -.IR nobody , -so -.B cat -does not have permission -to create a new file descriptor to read from that inode, -even though it can still read from its existing file descriptor 0. -.TP -.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)" -This is a subdirectory containing one entry for each file which the -process has open, named by its file descriptor. -The files in this directory are readable only by the owner of the process. -The contents of each file can be read to obtain information -about the corresponding file descriptor. -The content depends on the type of file referred to by the -corresponding file descriptor. -.IP -For regular files and directories, we see something like: -.IP -.in +4n -.EX -.RB "$" " cat /proc/12015/fdinfo/4" -pos: 1000 -flags: 01002002 -mnt_id: 21 -.EE -.in -.IP -The fields are as follows: -.RS -.TP -.I pos -This is a decimal number showing the file offset. -.TP -.I flags -This is an octal number that displays the -file access mode and file status flags (see -.BR open (2)). -If the close-on-exec file descriptor flag is set, then -.I flags -will also include the value -.BR O_CLOEXEC . -.IP -Before Linux 3.1, -.\" commit 1117f72ea0217ba0cc19f05adbbd8b9a397f5ab7 -this field incorrectly displayed the setting of -.B O_CLOEXEC -at the time the file was opened, -rather than the current setting of the close-on-exec flag. -.TP -.I -.I mnt_id -This field, present since Linux 3.15, -.\" commit 49d063cb353265c3af701bab215ac438ca7df36d -is the ID of the mount containing this file. -See the description of -.IR /proc/ pid /mountinfo . -.RE -.IP -For eventfd file descriptors (see -.BR eventfd (2)), -we see (since Linux 3.8) -.\" commit cbac5542d48127b546a23d816380a7926eee1c25 -the following fields: -.IP -.in +4n -.EX -pos: 0 -flags: 02 -mnt_id: 10 -eventfd\-count: 40 -.EE -.in -.IP -.I eventfd\-count -is the current value of the eventfd counter, in hexadecimal. -.IP -For epoll file descriptors (see -.BR epoll (7)), -we see (since Linux 3.8) -.\" commit 138d22b58696c506799f8de759804083ff9effae -the following fields: -.IP -.in +4n -.EX -pos: 0 -flags: 02 -mnt_id: 10 -tfd: 9 events: 19 data: 74253d2500000009 -tfd: 7 events: 19 data: 74253d2500000007 -.EE -.in -.IP -Each of the lines beginning -.I tfd -describes one of the file descriptors being monitored via -the epoll file descriptor (see -.BR epoll_ctl (2) -for some details). -The -.I tfd -field is the number of the file descriptor. -The -.I events -field is a hexadecimal mask of the events being monitored for this file -descriptor. -The -.I data -field is the data value associated with this file descriptor. -.IP -For signalfd file descriptors (see -.BR signalfd (2)), -we see (since Linux 3.8) -.\" commit 138d22b58696c506799f8de759804083ff9effae -the following fields: -.IP -.in +4n -.EX -pos: 0 -flags: 02 -mnt_id: 10 -sigmask: 0000000000000006 -.EE -.in -.IP -.I sigmask -is the hexadecimal mask of signals that are accepted via this -signalfd file descriptor. -(In this example, bits 2 and 3 are set, corresponding to the signals -.B SIGINT -and -.BR SIGQUIT ; -see -.BR signal (7).) -.IP -For inotify file descriptors (see -.BR inotify (7)), -we see (since Linux 3.8) -the following fields: -.IP -.in +4n -.EX -pos: 0 -flags: 00 -mnt_id: 11 -inotify wd:2 ino:7ef82a sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:2af87e00220ffd73 -inotify wd:1 ino:192627 sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:27261900802dfd73 -.EE -.in -.IP -Each of the lines beginning with "inotify" displays information about -one file or directory that is being monitored. -The fields in this line are as follows: -.RS -.TP -.I wd -A watch descriptor number (in decimal). -.TP -.I ino -The inode number of the target file (in hexadecimal). -.TP -.I sdev -The ID of the device where the target file resides (in hexadecimal). -.TP -.I mask -The mask of events being monitored for the target file (in hexadecimal). -.RE -.IP -If the kernel was built with exportfs support, the path to the target -file is exposed as a file handle, via three hexadecimal fields: -.IR fhandle\-bytes , -.IR fhandle\-type , -and -.IR f_handle . -.IP -For fanotify file descriptors (see -.BR fanotify (7)), -we see (since Linux 3.8) -the following fields: -.IP -.in +4n -.EX -pos: 0 -flags: 02 -mnt_id: 11 -fanotify flags:0 event\-flags:88002 -fanotify ino:19264f sdev:800001 mflags:0 mask:1 ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:4f261900a82dfd73 -.EE -.in -.IP -The fourth line displays information defined when the fanotify group -was created via -.BR fanotify_init (2): -.RS -.TP -.I flags -The -.I flags -argument given to -.BR fanotify_init (2) -(expressed in hexadecimal). -.TP -.I event\-flags -The -.I event_f_flags -argument given to -.BR fanotify_init (2) -(expressed in hexadecimal). -.RE -.IP -Each additional line shown in the file contains information -about one of the marks in the fanotify group. -Most of these fields are as for inotify, except: -.RS -.TP -.I mflags -The flags associated with the mark -(expressed in hexadecimal). -.TP -.I mask -The events mask for this mark -(expressed in hexadecimal). -.TP -.I ignored_mask -The mask of events that are ignored for this mark -(expressed in hexadecimal). -.RE -.IP -For details on these fields, see -.BR fanotify_mark (2). -.IP -For timerfd file descriptors (see -.BR timerfd (2)), -we see (since Linux 3.17) -.\" commit af9c4957cf212ad9cf0bee34c95cb11de5426e85 -the following fields: -.IP -.in +4n -.EX -pos: 0 -flags: 02004002 -mnt_id: 13 -clockid: 0 -ticks: 0 -settime flags: 03 -it_value: (7695568592, 640020877) -it_interval: (0, 0) -.EE -.in -.RS -.TP -.I clockid -This is the numeric value of the clock ID -(corresponding to one of the -.B CLOCK_* -constants defined via -.IR ) -that is used to mark the progress of the timer (in this example, 0 is -.BR CLOCK_REALTIME ). -.TP -.I ticks -This is the number of timer expirations that have occurred, -(i.e., the value that -.BR read (2) -on it would return). -.TP -.I settime flags -This field lists the flags with which the timerfd was last armed (see -.BR timerfd_settime (2)), -in octal -(in this example, both -.B TFD_TIMER_ABSTIME -and -.B TFD_TIMER_CANCEL_ON_SET -are set). -.TP -.I it_value -This field contains the amount of time until the timer will next expire, -expressed in seconds and nanoseconds. -This is always expressed as a relative value, -regardless of whether the timer was created using the -.B TFD_TIMER_ABSTIME -flag. -.TP -.I it_interval -This field contains the interval of the timer, -in seconds and nanoseconds. -(The -.I it_value -and -.I it_interval -fields contain the values that -.BR timerfd_gettime (2) -on this file descriptor would return.) -.RE -.TP -.IR /proc/ pid /gid_map " (since Linux 3.5)" -See -.BR user_namespaces (7). -.TP -.IR /proc/ pid /io " (since Linux 2.6.20)" -.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2 -This file contains I/O statistics for the process, for example: -.IP -.in +4n -.EX -.RB "#" " cat /proc/3828/io" -rchar: 323934931 -wchar: 323929600 -syscr: 632687 -syscw: 632675 -read_bytes: 0 -write_bytes: 323932160 -cancelled_write_bytes: 0 -.EE -.in -.IP -The fields are as follows: -.RS -.TP -.IR rchar ": characters read" -The number of bytes which this task has caused to be read from storage. -This is simply the sum of bytes which this process passed to -.BR read (2) -and similar system calls. -It includes things such as terminal I/O and -is unaffected by whether or not actual -physical disk I/O was required (the read might have been satisfied from -pagecache). -.TP -.IR wchar ": characters written" -The number of bytes which this task has caused, or shall cause to be written -to disk. -Similar caveats apply here as with -.IR rchar . -.TP -.IR syscr ": read syscalls" -Attempt to count the number of read I/O operations\[em]that is, -system calls such as -.BR read (2) -and -.BR pread (2). -.TP -.IR syscw ": write syscalls" -Attempt to count the number of write I/O operations\[em]that is, -system calls such as -.BR write (2) -and -.BR pwrite (2). -.TP -.IR read_bytes ": bytes read" -Attempt to count the number of bytes which this process really did cause to -be fetched from the storage layer. -This is accurate for block-backed filesystems. -.TP -.IR write_bytes ": bytes written" -Attempt to count the number of bytes which this process caused to be sent to -the storage layer. -.TP -.IR cancelled_write_bytes : -The big inaccuracy here is truncate. -If a process writes 1 MB to a file and then deletes the file, -it will in fact perform no writeout. -But it will have been accounted as having caused 1 MB of write. -In other words: this field represents the number of bytes which this process -caused to not happen, by truncating pagecache. -A task can cause "negative" I/O too. -If this task truncates some dirty pagecache, -some I/O which another task has been accounted for -(in its -.IR write_bytes ) -will not be happening. -.RE -.IP -.IR Note : -In the current implementation, things are a bit racy on 32-bit systems: -if process A reads process B's -.IR /proc/ pid /io -while process B is updating one of these 64-bit counters, -process A could see an intermediate result. -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /limits " (since Linux 2.6.24)" -This file displays the soft limit, hard limit, and units of measurement -for each of the process's resource limits (see -.BR getrlimit (2)). -Up to and including Linux 2.6.35, -this file is protected to allow reading only by the real UID of the process. -Since Linux 2.6.36, -.\" commit 3036e7b490bf7878c6dae952eec5fb87b1106589 -this file is readable by all users on the system. -.\" FIXME Describe /proc/[pid]/loginuid -.\" Added in Linux 2.6.11; updating requires CAP_AUDIT_CONTROL -.\" CONFIG_AUDITSYSCALL -.TP -.IR /proc/ pid /map_files/ " (since Linux 3.3)" -.\" commit 640708a2cff7f81e246243b0073c66e6ece7e53e -This subdirectory contains entries corresponding to memory-mapped -files (see -.BR mmap (2)). -Entries are named by memory region start and end -address pair (expressed as hexadecimal numbers), -and are symbolic links to the mapped files themselves. -Here is an example, -with the output wrapped and reformatted to fit on an 80-column display: -.IP -.in +4n -.EX -.RB "#" " ls \-l /proc/self/map_files/" -lr\-\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:31 - 3252e00000\-3252e20000 \-> /usr/lib64/ld\-2.15.so -\&... -.EE -.in -.IP -Although these entries are present for memory regions that were -mapped with the -.B MAP_FILE -flag, the way anonymous shared memory (regions created with the -.B MAP_ANON | MAP_SHARED -flags) -is implemented in Linux -means that such regions also appear on this directory. -Here is an example where the target file is the deleted -.I /dev/zero -one: -.IP -.in +4n -.EX -lrw\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:33 - 7fc075d2f000\-7fc075e6f000 \-> /dev/zero (deleted) -.EE -.in -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.IP -Until Linux 4.3, -.\" commit bdb4d100afe9818aebd1d98ced575c5ef143456c -this directory appeared only if the -.B CONFIG_CHECKPOINT_RESTORE -kernel configuration option was enabled. -.IP -Capabilities are required to read the contents of the symbolic links in -this directory: before Linux 5.9, the reading process requires -.B CAP_SYS_ADMIN -in the initial user namespace; -since Linux 5.9, the reading process must have either -.B CAP_SYS_ADMIN -or -.B CAP_CHECKPOINT_RESTORE -in the initial (i.e. root) user namespace. -.TP -.IR /proc/ pid /maps -A file containing the currently mapped memory regions and their access -permissions. -See -.BR mmap (2) -for some further information about memory mappings. -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.IP -The format of the file is: -.IP -.in +4n -.EX -.I "address perms offset dev inode pathname" -00400000\-00452000 r\-xp 00000000 08:02 173521 /usr/bin/dbus\-daemon -00651000\-00652000 r\-\-p 00051000 08:02 173521 /usr/bin/dbus\-daemon -00652000\-00655000 rw\-p 00052000 08:02 173521 /usr/bin/dbus\-daemon -00e03000\-00e24000 rw\-p 00000000 00:00 0 [heap] -00e24000\-011f7000 rw\-p 00000000 00:00 0 [heap] -\&... -35b1800000\-35b1820000 r\-xp 00000000 08:02 135522 /usr/lib64/ld\-2.15.so -35b1a1f000\-35b1a20000 r\-\-p 0001f000 08:02 135522 /usr/lib64/ld\-2.15.so -35b1a20000\-35b1a21000 rw\-p 00020000 08:02 135522 /usr/lib64/ld\-2.15.so -35b1a21000\-35b1a22000 rw\-p 00000000 00:00 0 -35b1c00000\-35b1dac000 r\-xp 00000000 08:02 135870 /usr/lib64/libc\-2.15.so -35b1dac000\-35b1fac000 \-\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so -35b1fac000\-35b1fb0000 r\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so -35b1fb0000\-35b1fb2000 rw\-p 001b0000 08:02 135870 /usr/lib64/libc\-2.15.so -\&... -f2c6ff8c000\-7f2c7078c000 rw\-p 00000000 00:00 0 [stack:986] -\&... -7fffb2c0d000\-7fffb2c2e000 rw\-p 00000000 00:00 0 [stack] -7fffb2d48000\-7fffb2d49000 r\-xp 00000000 00:00 0 [vdso] -.EE -.in -.IP -The -.I address -field is the address space in the process that the mapping occupies. -The -.I perms -field is a set of permissions: -.IP -.in +4n -.EX -r = read -w = write -x = execute -s = shared -p = private (copy on write) -.EE -.in -.IP -The -.I offset -field is the offset into the file/whatever; -.I dev -is the device -(major:minor); -.I inode -is the inode on that device. -0 indicates that no inode is associated with the memory region, -as would be the case with BSS (uninitialized data). -.IP -The -.I pathname -field will usually be the file that is backing the mapping. -For ELF files, -you can easily coordinate with the -.I offset -field by looking at the -Offset field in the ELF program headers -.RI ( "readelf\ \-l" ). -.IP -There are additional helpful pseudo-paths: -.RS -.TP -.I [stack] -The initial process's (also known as the main thread's) stack. -.TP -.IR [stack: tid ] " (from Linux 3.4 to Linux 4.4)" -.\" commit b76437579d1344b612cf1851ae610c636cec7db0 (added) -.\" commit 65376df582174ffcec9e6471bf5b0dd79ba05e4a (removed) -A thread's stack (where the -.I tid -is a thread ID). -It corresponds to the -.IR /proc/ pid /task/ tid / -path. -This field was removed in Linux 4.5, since providing this information -for a process with large numbers of threads is expensive. -.TP -.I [vdso] -The virtual dynamically linked shared object. -See -.BR vdso (7). -.TP -.I [heap] -The process's heap. -.TP -.IR [anon: name ] " (since Linux 5.17)" -.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b -A named private anonymous mapping. -Set with -.BR prctl (2) -.BR PR_SET_VMA_ANON_NAME . -.TP -.IR [anon_shmem: name ] " (since Linux 6.2)" -.\" Commit d09e8ca6cb93bb4b97517a18fbbf7eccb0e9ff43 -A named shared anonymous mapping. -Set with -.BR prctl (2) -.BR PR_SET_VMA_ANON_NAME . -.in -.RE -.IP -If the -.I pathname -field is blank, -this is an anonymous mapping as obtained via -.BR mmap (2). -There is no easy way to coordinate this back to a process's source, -short of running it through -.BR gdb (1), -.BR strace (1), -or similar. -.IP -.I pathname -is shown unescaped except for newline characters, which are replaced -with an octal escape sequence. -As a result, it is not possible to determine whether the original -pathname contained a newline character or the literal -.I \e012 -character sequence. -.IP -If the mapping is file-backed and the file has been deleted, the string -" (deleted)" is appended to the pathname. -Note that this is ambiguous too. -.IP -Under Linux 2.0, there is no field giving pathname. -.TP -.IR /proc/ pid /mem -This file can be used to access the pages of a process's memory through -.BR open (2), -.BR read (2), -and -.BR lseek (2). -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_ATTACH_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /mountinfo " (since Linux 2.6.26)" -.\" This info adapted from Documentation/filesystems/proc.txt -.\" commit 2d4d4864ac08caff5c204a752bd004eed4f08760 -This file contains information about mounts -in the process's mount namespace (see -.BR mount_namespaces (7)). -It supplies various information -(e.g., propagation state, root of mount for bind mounts, -identifier for each mount and its parent) that is missing from the (older) -.IR /proc/ pid /mounts -file, and fixes various other problems with that file -(e.g., nonextensibility, -failure to distinguish per-mount versus per-superblock options). -.IP -The file contains lines of the form: -.IP -.EX -36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 \- ext3 /dev/root rw,errors=continue -(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11) -.EE -.IP -The numbers in parentheses are labels for the descriptions below: -.RS 7 -.TP 5 -(1) -mount ID: a unique ID for the mount (may be reused after -.BR umount (2)). -.TP -(2) -parent ID: the ID of the parent mount -(or of self for the root of this mount namespace's mount tree). -.IP -If a new mount is stacked on top of a previous existing mount -(so that it hides the existing mount) at pathname P, -then the parent of the new mount is the previous mount at that location. -Thus, when looking at all the mounts stacked at a particular location, -the top-most mount is the one that is not the parent -of any other mount at the same location. -(Note, however, that this top-most mount will be accessible only if -the longest path subprefix of P that is a mount point -is not itself hidden by a stacked mount.) -.IP -If the parent mount lies outside the process's root directory (see -.BR chroot (2)), -the ID shown here won't have a corresponding record in -.I mountinfo -whose mount ID (field 1) matches this parent mount ID -(because mounts that lie outside the process's root directory -are not shown in -.IR mountinfo ). -As a special case of this point, -the process's root mount may have a parent mount -(for the initramfs filesystem) that lies -.\" Miklos Szeredi, Nov 2017: The hidden one is the initramfs, I believe -.\" mtk: In the initial mount namespace, this hidden ID has the value 0 -outside the process's root directory, -and an entry for that mount will not appear in -.IR mountinfo . -.TP -(3) -major:minor: the value of -.I st_dev -for files on this filesystem (see -.BR stat (2)). -.TP -(4) -root: the pathname of the directory in the filesystem -which forms the root of this mount. -.TP -(5) -mount point: the pathname of the mount point relative -to the process's root directory. -.TP -(6) -mount options: per-mount options (see -.BR mount (2)). -.TP -(7) -optional fields: zero or more fields of the form "tag[:value]"; see below. -.TP -(8) -separator: the end of the optional fields is marked by a single hyphen. -.TP -(9) -filesystem type: the filesystem type in the form "type[.subtype]". -.TP -(10) -mount source: filesystem-specific information or "none". -.TP -(11) -super options: per-superblock options (see -.BR mount (2)). -.RE -.IP -Currently, the possible optional fields are -.IR shared , -.IR master , -.IR propagate_from , -and -.IR unbindable . -See -.BR mount_namespaces (7) -for a description of these fields. -Parsers should ignore all unrecognized optional fields. -.IP -For more information on mount propagation see -.I Documentation/filesystems/sharedsubtree.rst -(or -.I Documentation/filesystems/sharedsubtree.txt -before Linux 5.8) -in the Linux kernel source tree. -.TP -.IR /proc/ pid /mounts " (since Linux 2.4.19)" -This file lists all the filesystems currently mounted in the -process's mount namespace (see -.BR mount_namespaces (7)). -The format of this file is documented in -.BR fstab (5). -.IP -Since Linux 2.6.15, this file is pollable: -after opening the file for reading, a change in this file -(i.e., a filesystem mount or unmount) causes -.BR select (2) -to mark the file descriptor as having an exceptional condition, and -.BR poll (2) -and -.BR epoll_wait (2) -mark the file as having a priority event -.RB ( POLLPRI ). -(Before Linux 2.6.30, -a change in this file was indicated by the file descriptor -being marked as readable for -.BR select (2), -and being marked as having an error condition for -.BR poll (2) -and -.BR epoll_wait (2).) -.TP -.IR /proc/ pid /mountstats " (since Linux 2.6.17)" -This file exports information (statistics, configuration information) -about the mounts in the process's mount namespace (see -.BR mount_namespaces (7)). -Lines in this file have the form: -.IP -.in +4n -.EX -device /dev/sda7 mounted on /home with fstype ext3 [stats] -( 1 ) ( 2 ) (3 ) ( 4 ) -.EE -.in -.IP -The fields in each line are: -.RS 7 -.TP 5 -(1) -The name of the mounted device -(or "nodevice" if there is no corresponding device). -.TP -(2) -The mount point within the filesystem tree. -.TP -(3) -The filesystem type. -.TP -(4) -Optional statistics and configuration information. -Currently (as at Linux 2.6.26), only NFS filesystems export -information via this field. -.RE -.IP -This file is readable only by the owner of the process. -.TP -.IR /proc/ pid /net " (since Linux 2.6.25)" -See the description of -.IR /proc/net . -.TP -.IR /proc/ pid /ns/ " (since Linux 3.0)" -.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f -This is a subdirectory containing one entry for each namespace that -supports being manipulated by -.BR setns (2). -For more information, see -.BR namespaces (7). -.TP -.IR /proc/ pid /numa_maps " (since Linux 2.6.14)" -See -.BR numa (7). -.TP -.IR /proc/ pid /oom_adj " (since Linux 2.6.11)" -This file can be used to adjust the score used to select which process -should be killed in an out-of-memory (OOM) situation. -The kernel uses this value for a bit-shift operation of the process's -.I oom_score -value: -valid values are in the range \-16 to +15, -plus the special value \-17, -which disables OOM-killing altogether for this process. -A positive score increases the likelihood of this -process being killed by the OOM-killer; -a negative score decreases the likelihood. -.IP -The default value for this file is 0; -a new process inherits its parent's -.I oom_adj -setting. -A process must be privileged -.RB ( CAP_SYS_RESOURCE ) -to update this file, -although a process can always increase its own -.I oom_adj -setting (since Linux 2.6.20). -.IP -Since Linux 2.6.36, use of this file is deprecated in favor of -.IR /proc/ pid /oom_score_adj , -and finally removed in Linux 3.7. -.TP -.IR /proc/ pid /oom_score " (since Linux 2.6.11)" -.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources -.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 -.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 -This file displays the current score that the kernel gives to -this process for the purpose of selecting a process -for the OOM-killer. -A higher score means that the process is more likely to be -selected by the OOM-killer. -The basis for this score is the amount of memory used by the process, -with increases (+) or decreases (\-) for factors including: -.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources -.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 -.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 -.RS -.IP \[bu] 3 -whether the process is privileged (\-). -.\" More precisely, if it has CAP_SYS_ADMIN or (pre 2.6.36) CAP_SYS_RESOURCE -.RE -.IP -Before Linux 2.6.36 -the following factors were also used in the calculation of oom_score: -.RS -.IP \[bu] 3 -whether the process creates a lot of children using -.BR fork (2) -(+); -.IP \[bu] -whether the process has been running a long time, -or has used a lot of CPU time (\-); -.IP \[bu] -whether the process has a low nice value (i.e., > 0) (+); and -.IP \[bu] -whether the process is making direct hardware access (\-). -.\" More precisely, if it has CAP_SYS_RAWIO -.RE -.IP -The -.I oom_score -also reflects the adjustment specified by the -.I oom_score_adj -or -.I oom_adj -setting for the process. -.TP -.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)" -.\" Text taken from Linux 3.7 Documentation/filesystems/proc.txt -This file can be used to adjust the badness heuristic used to select which -process gets killed in out-of-memory conditions. -.IP -The badness heuristic assigns a value to each candidate task ranging from 0 -(never kill) to 1000 (always kill) to determine which process is targeted. -The units are roughly a proportion along that range of -allowed memory the process may allocate from, -based on an estimation of its current memory and swap use. -For example, if a task is using all allowed memory, -its badness score will be 1000. -If it is using half of its allowed memory, its score will be 500. -.IP -There is an additional factor included in the badness score: root -processes are given 3% extra memory over other tasks. -.IP -The amount of "allowed" memory depends on the context -in which the OOM-killer was called. -If it is due to the memory assigned to the allocating task's cpuset -being exhausted, -the allowed memory represents the set of mems assigned to that -cpuset (see -.BR cpuset (7)). -If it is due to a mempolicy's node(s) being exhausted, -the allowed memory represents the set of mempolicy nodes. -If it is due to a memory limit (or swap limit) being reached, -the allowed memory is that configured limit. -Finally, if it is due to the entire system being out of memory, the -allowed memory represents all allocatable resources. -.IP -The value of -.I oom_score_adj -is added to the badness score before it -is used to determine which task to kill. -Acceptable values range from \-1000 -(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). -This allows user space to control the preference for OOM-killing, -ranging from always preferring a certain -task or completely disabling it from OOM-killing. -The lowest possible value, \-1000, is -equivalent to disabling OOM-killing entirely for that task, -since it will always report a badness score of 0. -.IP -Consequently, it is very simple for user space to define -the amount of memory to consider for each task. -Setting an -.I oom_score_adj -value of +500, for example, -is roughly equivalent to allowing the remainder of tasks sharing the -same system, cpuset, mempolicy, or memory controller resources -to use at least 50% more memory. -A value of \-500, on the other hand, would be roughly -equivalent to discounting 50% of the task's -allowed memory from being considered as scoring against the task. -.IP -For backward compatibility with previous kernels, -.IR /proc/ pid /oom_adj -can still be used to tune the badness score. -Its value is -scaled linearly with -.IR oom_score_adj . -.IP -Writing to -.IR /proc/ pid /oom_score_adj -or -.IR /proc/ pid /oom_adj -will change the other with its scaled value. -.IP -The -.BR choom (1) -program provides a command-line interface for adjusting the -.I oom_score_adj -value of a running process or a newly executed command. -.TP -.IR /proc/ pid /pagemap " (since Linux 2.6.25)" -This file shows the mapping of each of the process's virtual pages -into physical page frames or swap area. -It contains one 64-bit value for each virtual page, -with the bits set as follows: -.RS -.TP -63 -If set, the page is present in RAM. -.TP -62 -If set, the page is in swap space -.TP -61 (since Linux 3.5) -The page is a file-mapped page or a shared anonymous page. -.TP -60\[en]58 (since Linux 3.11) -Zero -.\" Not quite true; see commit 541c237c0923f567c9c4cabb8a81635baadc713f -.TP -57 (since Linux 5.14) -If set, the page is write-protected through -.BR userfaultfd (2). -.TP -56 (since Linux 4.2) -.\" commit 77bb499bb60f4b79cca7d139c8041662860fcf87 -.\" commit 83b4b0bb635eee2b8e075062e4e008d1bc110ed7 -The page is exclusively mapped. -.TP -55 (since Linux 3.11) -PTE is soft-dirty -(see the kernel source file -.IR Documentation/admin\-guide/mm/soft\-dirty.rst ). -.TP -54\[en]0 -If the page is present in RAM (bit 63), then these bits -provide the page frame number, which can be used to index -.I /proc/kpageflags -and -.IR /proc/kpagecount . -If the page is present in swap (bit 62), -then bits 4\[en]0 give the swap type, and bits 54\[en]5 encode the swap offset. -.RE -.IP -Before Linux 3.11, bits 60\[en]55 were -used to encode the base-2 log of the page size. -.IP -To employ -.IR /proc/ pid /pagemap -efficiently, use -.IR /proc/ pid /maps -to determine which areas of memory are actually mapped and seek -to skip over unmapped regions. -.IP -The -.IR /proc/ pid /pagemap -file is present only if the -.B CONFIG_PROC_PAGE_MONITOR -kernel configuration option is enabled. -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /personality " (since Linux 2.6.28)" -.\" commit 478307230810d7e2a753ed220db9066dfdf88718 -This read-only file exposes the process's execution domain, as set by -.BR personality (2). -The value is displayed in hexadecimal notation. -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_ATTACH_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /root -UNIX and Linux support the idea of a per-process root of the -filesystem, set by the -.BR chroot (2) -system call. -This file is a symbolic link that points to the process's -root directory, and behaves in the same way as -.IR exe , -and -.IR fd/* . -.IP -Note however that this file is not merely a symbolic link. -It provides the same view of the filesystem (including namespaces and the -set of per-process mounts) as the process itself. -An example illustrates this point. -In one terminal, we start a shell in new user and mount namespaces, -and in that shell we create some new mounts: -.IP -.in +4n -.EX -$ \fBPS1=\[aq]sh1# \[aq] unshare \-Urnm\fP -sh1# \fBmount \-t tmpfs tmpfs /etc\fP # Mount empty tmpfs at /etc -sh1# \fBmount \-\-bind /usr /dev\fP # Mount /usr at /dev -sh1# \fBecho $$\fP -27123 -.EE -.in -.IP -In a second terminal window, in the initial mount namespace, -we look at the contents of the corresponding mounts in -the initial and new namespaces: -.IP -.in +4n -.EX -$ \fBPS1=\[aq]sh2# \[aq] sudo sh\fP -sh2# \fBls /etc | wc \-l\fP # In initial NS -309 -sh2# \fBls /proc/27123/root/etc | wc \-l\fP # /etc in other NS -0 # The empty tmpfs dir -sh2# \fBls /dev | wc \-l\fP # In initial NS -205 -sh2# \fBls /proc/27123/root/dev | wc \-l\fP # /dev in other NS -11 # Actually bind - # mounted to /usr -sh2# \fBls /usr | wc \-l\fP # /usr in initial NS -11 -.EE -.in -.IP -.\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of the -.IR /proc/ pid /root -symbolic link are not available if the main thread has already terminated -(typically by calling -.BR pthread_exit (3)). -.IP -Permission to dereference or read -.RB ( readlink (2)) -this symbolic link is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /projid_map " (since Linux 3.7)" -.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d -See -.BR user_namespaces (7). -.TP -.IR /proc/ pid /seccomp " (Linux 2.6.12 to Linux 2.6.22)" -This file can be used to read and change the process's -secure computing (seccomp) mode setting. -It contains the value 0 if the process is not in seccomp mode, -and 1 if the process is in strict seccomp mode (see -.BR seccomp (2)). -Writing 1 to this file places the process irreversibly in strict seccomp mode. -(Further attempts to write to the file fail with the -.B EPERM -error.) -.IP -In Linux 2.6.23, -this file went away, to be replaced by the -.BR prctl (2) -.B PR_GET_SECCOMP -and -.B PR_SET_SECCOMP -operations (and later by -.BR seccomp (2) -and the -.I Seccomp -field in -.IR /proc/ pid /status ). -.\" FIXME Describe /proc/[pid]/sessionid -.\" commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc -.\" CONFIG_AUDITSYSCALL -.\" Added in Linux 2.6.25; read-only; only readable by real UID -.\" -.\" FIXME Describe /proc/[pid]/sched -.\" Added in Linux 2.6.23 -.\" CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS -.\" Displays various scheduling parameters -.\" This file can be written, to reset stats -.\" The set of fields exposed by this file have changed -.\" significantly over time. -.\" commit 43ae34cb4cd650d1eb4460a8253a8e747ba052ac -.\" -.\" FIXME Describe /proc/[pid]/schedstats and -.\" /proc/[pid]/task/[tid]/schedstats -.\" Added in Linux 2.6.9 -.\" CONFIG_SCHEDSTATS -.TP -.IR /proc/ pid /setgroups " (since Linux 3.19)" -See -.BR user_namespaces (7). -.TP -.IR /proc/ pid /smaps " (since Linux 2.6.14)" -This file shows memory consumption for each of the process's mappings. -(The -.BR pmap (1) -command displays similar information, -in a form that may be easier for parsing.) -For each mapping there is a series of lines such as the following: -.IP -.in +4n -.EX -00400000\-0048a000 r\-xp 00000000 fd:03 960637 /bin/bash -Size: 552 kB -Rss: 460 kB -Pss: 100 kB -Shared_Clean: 452 kB -Shared_Dirty: 0 kB -Private_Clean: 8 kB -Private_Dirty: 0 kB -Referenced: 460 kB -Anonymous: 0 kB -AnonHugePages: 0 kB -ShmemHugePages: 0 kB -ShmemPmdMapped: 0 kB -Swap: 0 kB -KernelPageSize: 4 kB -MMUPageSize: 4 kB -Locked: 0 kB -ProtectionKey: 0 -VmFlags: rd ex mr mw me dw -.EE -.in -.IP -The first of these lines shows the same information as is displayed -for the mapping in -.IR /proc/ pid /maps . -The following lines show the size of the mapping, -the amount of the mapping that is currently resident in RAM ("Rss"), -the process's proportional share of this mapping ("Pss"), -the number of clean and dirty shared pages in the mapping, -and the number of clean and dirty private pages in the mapping. -"Referenced" indicates the amount of memory currently marked as -referenced or accessed. -"Anonymous" shows the amount of memory -that does not belong to any file. -"Swap" shows how much -would-be-anonymous memory is also used, but out on swap. -.IP -The "KernelPageSize" line (available since Linux 2.6.29) -is the page size used by the kernel to back the virtual memory area. -This matches the size used by the MMU in the majority of cases. -However, one counter-example occurs on PPC64 kernels -whereby a kernel using 64 kB as a base page size may still use 4 kB -pages for the MMU on older processors. -To distinguish the two attributes, the "MMUPageSize" line -(also available since Linux 2.6.29) -reports the page size used by the MMU. -.IP -The "Locked" indicates whether the mapping is locked in memory -or not. -.IP -The "ProtectionKey" line (available since Linux 4.9, on x86 only) -contains the memory protection key (see -.BR pkeys (7)) -associated with the virtual memory area. -This entry is present only if the kernel was built with the -.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS -configuration option (since Linux 4.6). -.IP -The "VmFlags" line (available since Linux 3.8) -represents the kernel flags associated with the virtual memory area, -encoded using the following two-letter codes: -.RS -.IP -.TS -l l l. -rd - readable -wr - writable -ex - executable -sh - shared -mr - may read -mw - may write -me - may execute -ms - may share -gd - stack segment grows down -pf - pure PFN range -dw - disabled write to the mapped file -lo - pages are locked in memory -io - memory mapped I/O area -sr - sequential read advise provided -rr - random read advise provided -dc - do not copy area on fork -de - do not expand area on remapping -ac - area is accountable -nr - swap space is not reserved for the area -ht - area uses huge tlb pages -sf - perform synchronous page faults (since Linux 4.15) -nl - non-linear mapping (removed in Linux 4.0) -ar - architecture specific flag -wf - wipe on fork (since Linux 4.14) -dd - do not include area into core dump -sd - soft-dirty flag (since Linux 3.13) -mm - mixed map area -hg - huge page advise flag -nh - no-huge page advise flag -mg - mergeable advise flag -um - userfaultfd missing pages tracking (since Linux 4.3) -uw - userfaultfd wprotect pages tracking (since Linux 4.3) -.TE -.RE -.IP -The -.IR /proc/ pid /smaps -file is present only if the -.B CONFIG_PROC_PAGE_MONITOR -kernel configuration option is enabled. -.TP -.IR /proc/ pid /stack " (since Linux 2.6.29)" -.\" 2ec220e27f5040aec1e88901c1b6ea3d135787ad -This file provides a symbolic trace of the function calls in this -process's kernel stack. -This file is provided only if the kernel was built with the -.B CONFIG_STACKTRACE -configuration option. -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_ATTACH_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /stat -Status information about the process. -This is used by -.BR ps (1). -It is defined in the kernel source file -.IR fs/proc/array.c "." -.IP -The fields, in order, with their proper -.BR scanf (3) -format specifiers, are listed below. -Whether or not certain of these fields display valid information is governed by -a ptrace access mode -.BR PTRACE_MODE_READ_FSCREDS " | " PTRACE_MODE_NOAUDIT -check (refer to -.BR ptrace (2)). -If the check denies access, then the field value is displayed as 0. -The affected fields are indicated with the marking [PT]. -.RS -.TP -(1) \fIpid\fP \ %d -.br -The process ID. -.TP -(2) \fIcomm\fP \ %s -The filename of the executable, in parentheses. -Strings longer than -.B TASK_COMM_LEN -(16) characters (including the terminating null byte) are silently truncated. -This is visible whether or not the executable is swapped out. -.TP -(3) \fIstate\fP \ %c -One of the following characters, indicating process state: -.RS -.TP -R -Running -.TP -S -Sleeping in an interruptible wait -.TP -D -Waiting in uninterruptible -disk sleep -.TP -Z -Zombie -.TP -T -Stopped (on a signal) or (before Linux 2.6.33) trace stopped -.TP -t -.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 -Tracing stop (Linux 2.6.33 onward) -.TP -W -Paging (only before Linux 2.6.0) -.TP -X -Dead (from Linux 2.6.0 onward) -.TP -x -.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 -Dead (Linux 2.6.33 to -.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 -3.13 only) -.TP -K -.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 -Wakekill (Linux 2.6.33 to -.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 -3.13 only) -.TP -W -.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 -Waking (Linux 2.6.33 to -.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 -3.13 only) -.TP -P -.\" commit f2530dc71cf0822f90bb63ea4600caaef33a66bb -Parked (Linux 3.9 to -.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 -3.13 only) -.TP -I -.\" commit 06eb61844d841d0032a9950ce7f8e783ee49c0d0 -Idle (Linux 4.14 onward) -.RE -.TP -(4) \fIppid\fP \ %d -The PID of the parent of this process. -.TP -(5) \fIpgrp\fP \ %d -The process group ID of the process. -.TP -(6) \fIsession\fP \ %d -The session ID of the process. -.TP -(7) \fItty_nr\fP \ %d -The controlling terminal of the process. -(The minor device number is contained in the combination of bits -31 to 20 and 7 to 0; -the major device number is in bits 15 to 8.) -.TP -(8) \fItpgid\fP \ %d -.\" This field and following, up to and including wchan added 0.99.1 -The ID of the foreground process group of the controlling -terminal of the process. -.TP -(9) \fIflags\fP \ %u -The kernel flags word of the process. -For bit meanings, -see the PF_* defines in the Linux kernel source file -.IR include/linux/sched.h . -Details depend on the kernel version. -.IP -The format for this field was %lu before Linux 2.6. -.TP -(10) \fIminflt\fP \ %lu -The number of minor faults the process has made which have not -required loading a memory page from disk. -.TP -(11) \fIcminflt\fP \ %lu -The number of minor faults that the process's -waited-for children have made. -.TP -(12) \fImajflt\fP \ %lu -The number of major faults the process has made which have -required loading a memory page from disk. -.TP -(13) \fIcmajflt\fP \ %lu -The number of major faults that the process's -waited-for children have made. -.TP -(14) \fIutime\fP \ %lu -Amount of time that this process has been scheduled in user mode, -measured in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -This includes guest time, \fIguest_time\fP -(time spent running a virtual CPU, see below), -so that applications that are not aware of the guest time field -do not lose that time from their calculations. -.TP -(15) \fIstime\fP \ %lu -Amount of time that this process has been scheduled in kernel mode, -measured in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -.TP -(16) \fIcutime\fP \ %ld -Amount of time that this process's -waited-for children have been scheduled in user mode, -measured in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -(See also -.BR times (2).) -This includes guest time, \fIcguest_time\fP -(time spent running a virtual CPU, see below). -.TP -(17) \fIcstime\fP \ %ld -Amount of time that this process's -waited-for children have been scheduled in kernel mode, -measured in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -.TP -(18) \fIpriority\fP \ %ld -(Explanation for Linux 2.6) -For processes running a real-time scheduling policy -.RI ( policy -below; see -.BR sched_setscheduler (2)), -this is the negated scheduling priority, minus one; -that is, a number in the range \-2 to \-100, -corresponding to real-time priorities 1 to 99. -For processes running under a non-real-time scheduling policy, -this is the raw nice value -.RB ( setpriority (2)) -as represented in the kernel. -The kernel stores nice values as numbers -in the range 0 (high) to 39 (low), -corresponding to the user-visible nice range of \-20 to 19. -.IP -Before Linux 2.6, this was a scaled value based on -the scheduler weighting given to this process. -.\" And back in Linux 1.2 days things were different again. -.TP -(19) \fInice\fP \ %ld -The nice value (see -.BR setpriority (2)), -a value in the range 19 (low priority) to \-20 (high priority). -.\" Back in Linux 1.2 days things were different. -.\" .TP -.\" \fIcounter\fP %ld -.\" The current maximum size in jiffies of the process's next timeslice, -.\" or what is currently left of its current timeslice, if it is the -.\" currently running process. -.\" .TP -.\" \fItimeout\fP %u -.\" The time in jiffies of the process's next timeout. -.\" timeout was removed sometime around 2.1/2.2 -.TP -(20) \fInum_threads\fP \ %ld -Number of threads in this process (since Linux 2.6). -Before Linux 2.6, this field was hard coded to 0 as a placeholder -for an earlier removed field. -.TP -(21) \fIitrealvalue\fP \ %ld -The time in jiffies before the next -.B SIGALRM -is sent to the process due to an interval timer. -Since Linux 2.6.17, this field is no longer maintained, -and is hard coded as 0. -.TP -(22) \fIstarttime\fP \ %llu -The time the process started after system boot. -Before Linux 2.6, this value was expressed in jiffies. -Since Linux 2.6, the value is expressed in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -.IP -The format for this field was %lu before Linux 2.6. -.TP -(23) \fIvsize\fP \ %lu -Virtual memory size in bytes. -.TP -(24) \fIrss\fP \ %ld -Resident Set Size: number of pages the process has in real memory. -This is just the pages which -count toward text, data, or stack space. -This does not include pages -which have not been demand-loaded in, or which are swapped out. -This value is inaccurate; see -.IR /proc/ pid /statm -below. -.TP -(25) \fIrsslim\fP \ %lu -Current soft limit in bytes on the rss of the process; -see the description of -.B RLIMIT_RSS -in -.BR getrlimit (2). -.TP -(26) \fIstartcode\fP \ %lu \ [PT] -The address above which program text can run. -.TP -(27) \fIendcode\fP \ %lu \ [PT] -The address below which program text can run. -.TP -(28) \fIstartstack\fP \ %lu \ [PT] -The address of the start (i.e., bottom) of the stack. -.TP -(29) \fIkstkesp\fP \ %lu \ [PT] -The current value of ESP (stack pointer), as found in the -kernel stack page for the process. -.TP -(30) \fIkstkeip\fP \ %lu \ [PT] -The current EIP (instruction pointer). -.TP -(31) \fIsignal\fP \ %lu -The bitmap of pending signals, displayed as a decimal number. -Obsolete, because it does not provide information on real-time signals; use -.IR /proc/ pid /status -instead. -.TP -(32) \fIblocked\fP \ %lu -The bitmap of blocked signals, displayed as a decimal number. -Obsolete, because it does not provide information on real-time signals; use -.IR /proc/ pid /status -instead. -.TP -(33) \fIsigignore\fP \ %lu -The bitmap of ignored signals, displayed as a decimal number. -Obsolete, because it does not provide information on real-time signals; use -.IR /proc/ pid /status -instead. -.TP -(34) \fIsigcatch\fP \ %lu -The bitmap of caught signals, displayed as a decimal number. -Obsolete, because it does not provide information on real-time signals; use -.IR /proc/ pid /status -instead. -.TP -(35) \fIwchan\fP \ %lu \ [PT] -This is the "channel" in which the process is waiting. -It is the address of a location in the kernel where the process is sleeping. -The corresponding symbolic name can be found in -.IR /proc/ pid /wchan . -.TP -(36) \fInswap\fP \ %lu -.\" nswap was added in Linux 2.0 -Number of pages swapped (not maintained). -.TP -(37) \fIcnswap\fP \ %lu -.\" cnswap was added in Linux 2.0 -Cumulative \fInswap\fP for child processes (not maintained). -.TP -(38) \fIexit_signal\fP \ %d \ (since Linux 2.1.22) -Signal to be sent to parent when we die. -.TP -(39) \fIprocessor\fP \ %d \ (since Linux 2.2.8) -CPU number last executed on. -.TP -(40) \fIrt_priority\fP \ %u \ (since Linux 2.5.19) -Real-time scheduling priority, a number in the range 1 to 99 for -processes scheduled under a real-time policy, -or 0, for non-real-time processes (see -.BR sched_setscheduler (2)). -.TP -(41) \fIpolicy\fP \ %u \ (since Linux 2.5.19) -Scheduling policy (see -.BR sched_setscheduler (2)). -Decode using the SCHED_* constants in -.IR linux/sched.h . -.IP -The format for this field was %lu before Linux 2.6.22. -.TP -(42) \fIdelayacct_blkio_ticks\fP \ %llu \ (since Linux 2.6.18) -Aggregated block I/O delays, measured in clock ticks (centiseconds). -.TP -(43) \fIguest_time\fP \ %lu \ (since Linux 2.6.24) -Guest time of the process (time spent running a virtual CPU -for a guest operating system), measured in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -.TP -(44) \fIcguest_time\fP \ %ld \ (since Linux 2.6.24) -Guest time of the process's children, measured in clock ticks (divide by -.IR sysconf(_SC_CLK_TCK) ). -.TP -(45) \fIstart_data\fP \ %lu \ (since Linux 3.3) \ [PT] -.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff -Address above which program initialized and -uninitialized (BSS) data are placed. -.TP -(46) \fIend_data\fP \ %lu \ (since Linux 3.3) \ [PT] -.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff -Address below which program initialized and -uninitialized (BSS) data are placed. -.TP -(47) \fIstart_brk\fP \ %lu \ (since Linux 3.3) \ [PT] -.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff -Address above which program heap can be expanded with -.BR brk (2). -.TP -(48) \fIarg_start\fP \ %lu \ (since Linux 3.5) \ [PT] -.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 -Address above which program command-line arguments -.RI ( argv ) -are placed. -.TP -(49) \fIarg_end\fP \ %lu \ (since Linux 3.5) \ [PT] -.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 -Address below program command-line arguments -.RI ( argv ) -are placed. -.TP -(50) \fIenv_start\fP \ %lu \ (since Linux 3.5) \ [PT] -.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 -Address above which program environment is placed. -.TP -(51) \fIenv_end\fP \ %lu \ (since Linux 3.5) \ [PT] -.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 -Address below which program environment is placed. -.TP -(52) \fIexit_code\fP \ %d \ (since Linux 3.5) \ [PT] -.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 -The thread's exit status in the form reported by -.BR waitpid (2). -.RE -.TP -.IR /proc/ pid /statm -Provides information about memory usage, measured in pages. -The columns are: -.IP -.in +4n -.EX -size (1) total program size - (same as VmSize in \fI/proc/\fPpid\fI/status\fP) -resident (2) resident set size - (inaccurate; same as VmRSS in \fI/proc/\fPpid\fI/status\fP) -shared (3) number of resident shared pages - (i.e., backed by a file) - (inaccurate; same as RssFile+RssShmem in - \fI/proc/\fPpid\fI/status\fP) -text (4) text (code) -.\" (not including libs; broken, includes data segment) -lib (5) library (unused since Linux 2.6; always 0) -data (6) data + stack -.\" (including libs; broken, includes library text) -dt (7) dirty pages (unused since Linux 2.6; always 0) -.EE -.in -.IP -.\" See SPLIT_RSS_COUNTING in the kernel. -.\" Inaccuracy is bounded by TASK_RSS_EVENTS_THRESH. -Some of these values are inaccurate because -of a kernel-internal scalability optimization. -If accurate values are required, use -.IR /proc/ pid /smaps -or -.IR /proc/ pid /smaps_rollup -instead, which are much slower but provide accurate, detailed information. -.TP -.IR /proc/ pid /status -Provides much of the information in -.IR /proc/ pid /stat -and -.IR /proc/ pid /statm -in a format that's easier for humans to parse. -Here's an example: -.IP -.in +4n -.EX -.RB "$" " cat /proc/$$/status" -Name: bash -Umask: 0022 -State: S (sleeping) -Tgid: 17248 -Ngid: 0 -Pid: 17248 -PPid: 17200 -TracerPid: 0 -Uid: 1000 1000 1000 1000 -Gid: 100 100 100 100 -FDSize: 256 -Groups: 16 33 100 -NStgid: 17248 -NSpid: 17248 -NSpgid: 17248 -NSsid: 17200 -VmPeak: 131168 kB -VmSize: 131168 kB -VmLck: 0 kB -VmPin: 0 kB -VmHWM: 13484 kB -VmRSS: 13484 kB -RssAnon: 10264 kB -RssFile: 3220 kB -RssShmem: 0 kB -VmData: 10332 kB -VmStk: 136 kB -VmExe: 992 kB -VmLib: 2104 kB -VmPTE: 76 kB -VmPMD: 12 kB -VmSwap: 0 kB -HugetlbPages: 0 kB # 4.4 -CoreDumping: 0 # 4.15 -Threads: 1 -SigQ: 0/3067 -SigPnd: 0000000000000000 -ShdPnd: 0000000000000000 -SigBlk: 0000000000010000 -SigIgn: 0000000000384004 -SigCgt: 000000004b813efb -CapInh: 0000000000000000 -CapPrm: 0000000000000000 -CapEff: 0000000000000000 -CapBnd: ffffffffffffffff -CapAmb: 0000000000000000 -NoNewPrivs: 0 -Seccomp: 0 -Speculation_Store_Bypass: vulnerable -Cpus_allowed: 00000001 -Cpus_allowed_list: 0 -Mems_allowed: 1 -Mems_allowed_list: 0 -voluntary_ctxt_switches: 150 -nonvoluntary_ctxt_switches: 545 -.EE -.in -.IP -The fields are as follows: -.RS -.TP -.I Name -Command run by this process. -Strings longer than -.B TASK_COMM_LEN -(16) characters (including the terminating null byte) are silently truncated. -.TP -.I Umask -Process umask, expressed in octal with a leading zero; see -.BR umask (2). -(Since Linux 4.7.) -.TP -.I State -Current state of the process. -One of -"R (running)", -"S (sleeping)", -"D (disk sleep)", -"T (stopped)", -"t (tracing stop)", -"Z (zombie)", -or -"X (dead)". -.TP -.I Tgid -Thread group ID (i.e., Process ID). -.TP -.I Ngid -NUMA group ID (0 if none; since Linux 3.13). -.TP -.I Pid -Thread ID (see -.BR gettid (2)). -.TP -.I PPid -PID of parent process. -.TP -.I TracerPid -PID of process tracing this process (0 if not being traced). -.TP -.IR Uid ", " Gid -Real, effective, saved set, and filesystem UIDs (GIDs). -.TP -.I FDSize -Number of file descriptor slots currently allocated. -.TP -.I Groups -Supplementary group list. -.TP -.I NStgid -Thread group ID (i.e., PID) in each of the PID namespaces of which -.I pid -is a member. -The leftmost entry shows the value with respect to the PID namespace -of the process that mounted this procfs (or the root namespace -if mounted by the kernel), -followed by the value in successively nested inner namespaces. -.\" commit e4bc33245124db69b74a6d853ac76c2976f472d5 -(Since Linux 4.1.) -.TP -.I NSpid -Thread ID in each of the PID namespaces of which -.I pid -is a member. -The fields are ordered as for -.IR NStgid . -(Since Linux 4.1.) -.TP -.I NSpgid -Process group ID in each of the PID namespaces of which -.I pid -is a member. -The fields are ordered as for -.IR NStgid . -(Since Linux 4.1.) -.TP -.I NSsid -descendant namespace session ID hierarchy -Session ID in each of the PID namespaces of which -.I pid -is a member. -The fields are ordered as for -.IR NStgid . -(Since Linux 4.1.) -.TP -.I VmPeak -Peak virtual memory size. -.TP -.I VmSize -Virtual memory size. -.TP -.I VmLck -Locked memory size (see -.BR mlock (2)). -.TP -.I VmPin -Pinned memory size -.\" commit bc3e53f682d93df677dbd5006a404722b3adfe18 -(since Linux 3.2). -These are pages that can't be moved because something needs to -directly access physical memory. -.TP -.I VmHWM -Peak resident set size ("high water mark"). -This value is inaccurate; see -.IR /proc/ pid /statm -above. -.TP -.I VmRSS -Resident set size. -Note that the value here is the sum of -.IR RssAnon , -.IR RssFile , -and -.IR RssShmem . -This value is inaccurate; see -.IR /proc/ pid /statm -above. -.TP -.I RssAnon -Size of resident anonymous memory. -.\" commit bf9683d6990589390b5178dafe8fd06808869293 -(since Linux 4.5). -This value is inaccurate; see -.IR /proc/ pid /statm -above. -.TP -.I RssFile -Size of resident file mappings. -.\" commit bf9683d6990589390b5178dafe8fd06808869293 -(since Linux 4.5). -This value is inaccurate; see -.IR /proc/ pid /statm -above. -.TP -.I RssShmem -Size of resident shared memory (includes System V shared memory, -mappings from -.BR tmpfs (5), -and shared anonymous mappings). -.\" commit bf9683d6990589390b5178dafe8fd06808869293 -(since Linux 4.5). -.TP -.IR VmData ", " VmStk ", " VmExe -Size of data, stack, and text segments. -This value is inaccurate; see -.IR /proc/ pid /statm -above. -.TP -.I VmLib -Shared library code size. -.TP -.I VmPTE -Page table entries size (since Linux 2.6.10). -.TP -.I VmPMD -.\" commit dc6c9a35b66b520cf67e05d8ca60ebecad3b0479 -Size of second-level page tables (added in Linux 4.0; removed in Linux 4.15). -.TP -.I VmSwap -.\" commit b084d4353ff99d824d3bc5a5c2c22c70b1fba722 -Swapped-out virtual memory size by anonymous private pages; -shmem swap usage is not included (since Linux 2.6.34). -This value is inaccurate; see -.IR /proc/ pid /statm -above. -.TP -.I HugetlbPages -Size of hugetlb memory portions -.\" commit 5d317b2b6536592a9b51fe65faed43d65ca9158e -(since Linux 4.4). -.TP -.I CoreDumping -Contains the value 1 if the process is currently dumping core, -and 0 if it is not -.\" commit c643401218be0f4ab3522e0c0a63016596d6e9ca -(since Linux 4.15). -This information can be used by a monitoring process to avoid killing -a process that is currently dumping core, -which could result in a corrupted core dump file. -.TP -.I Threads -Number of threads in process containing this thread. -.TP -.I SigQ -This field contains two slash-separated numbers that relate to -queued signals for the real user ID of this process. -The first of these is the number of currently queued -signals for this real user ID, and the second is the -resource limit on the number of queued signals for this process -(see the description of -.B RLIMIT_SIGPENDING -in -.BR getrlimit (2)). -.TP -.IR SigPnd ", " ShdPnd -Mask (expressed in hexadecimal) -of signals pending for thread and for process as a whole (see -.BR pthreads (7) -and -.BR signal (7)). -.TP -.IR SigBlk ", " SigIgn ", " SigCgt -Masks (expressed in hexadecimal) -indicating signals being blocked, ignored, and caught (see -.BR signal (7)). -.TP -.IR CapInh ", " CapPrm ", " CapEff -Masks (expressed in hexadecimal) -of capabilities enabled in inheritable, permitted, and effective sets -(see -.BR capabilities (7)). -.TP -.I CapBnd -Capability bounding set, expressed in hexadecimal -(since Linux 2.6.26, see -.BR capabilities (7)). -.TP -.I CapAmb -Ambient capability set, expressed in hexadecimal -(since Linux 4.3, see -.BR capabilities (7)). -.TP -.I NoNewPrivs -.\" commit af884cd4a5ae62fcf5e321fecf0ec1014730353d -Value of the -.I no_new_privs -bit -(since Linux 4.10, see -.BR prctl (2)). -.TP -.I Seccomp -.\" commit 2f4b3bf6b2318cfaa177ec5a802f4d8d6afbd816 -Seccomp mode of the process -(since Linux 3.8, see -.BR seccomp (2)). -0 means -.BR SECCOMP_MODE_DISABLED ; -1 means -.BR SECCOMP_MODE_STRICT ; -2 means -.BR SECCOMP_MODE_FILTER . -This field is provided only if the kernel was built with the -.B CONFIG_SECCOMP -kernel configuration option enabled. -.TP -.I Speculation_Store_Bypass -.\" commit fae1fa0fc6cca8beee3ab8ed71d54f9a78fa3f64 -Speculation flaw mitigation state -(since Linux 4.17, see -.BR prctl (2)). -.TP -.I Cpus_allowed -Hexadecimal mask of CPUs on which this process may run -(since Linux 2.6.24, see -.BR cpuset (7)). -.TP -.I Cpus_allowed_list -Same as previous, but in "list format" -(since Linux 2.6.26, see -.BR cpuset (7)). -.TP -.I Mems_allowed -Mask of memory nodes allowed to this process -(since Linux 2.6.24, see -.BR cpuset (7)). -.TP -.I Mems_allowed_list -Same as previous, but in "list format" -(since Linux 2.6.26, see -.BR cpuset (7)). -.TP -.IR voluntary_ctxt_switches ", " nonvoluntary_ctxt_switches -Number of voluntary and involuntary context switches (since Linux 2.6.23). -.RE -.TP -.IR /proc/ pid /syscall " (since Linux 2.6.27)" -.\" commit ebcb67341fee34061430f3367f2e507e52ee051b -This file exposes the system call number and argument registers for the -system call currently being executed by the process, -followed by the values of the stack pointer and program counter registers. -The values of all six argument registers are exposed, -although most system calls use fewer registers. -.IP -If the process is blocked, but not in a system call, -then the file displays \-1 in place of the system call number, -followed by just the values of the stack pointer and program counter. -If process is not blocked, then the file contains just the string "running". -.IP -This file is present only if the kernel was configured with -.BR CONFIG_HAVE_ARCH_TRACEHOOK . -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_ATTACH_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ pid /task " (since Linux 2.6.0)" -.\" Precisely: Linux 2.6.0-test6 -This is a directory that contains one subdirectory -for each thread in the process. -The name of each subdirectory is the numerical thread ID -.RI ( tid ) -of the thread (see -.BR gettid (2)). -.IP -Within each of these subdirectories, there is a set of -files with the same names and contents as under the -.IR /proc/ pid -directories. -For attributes that are shared by all threads, the contents for -each of the files under the -.IR task/ tid -subdirectories will be the same as in the corresponding -file in the parent -.IR /proc/ pid -directory -(e.g., in a multithreaded process, all of the -.IR task/ tid /cwd -files will have the same value as the -.IR /proc/ pid /cwd -file in the parent directory, since all of the threads in a process -share a working directory). -For attributes that are distinct for each thread, -the corresponding files under -.IR task/ tid -may have different values (e.g., various fields in each of the -.IR task/ tid /status -files may be different for each thread), -.\" in particular: "children" :/ -or they might not exist in -.IR /proc/ pid -at all. -.IP -.\" The following was still true as at kernel 2.6.13 -In a multithreaded process, the contents of the -.IR /proc/ pid /task -directory are not available if the main thread has already terminated -(typically by calling -.BR pthread_exit (3)). -.TP -.IR /proc/ pid /task/ tid /children " (since Linux 3.5)" -.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7 -A space-separated list of child tasks of this task. -Each child task is represented by its TID. -.IP -.\" see comments in get_children_pid() in fs/proc/array.c -This option is intended for use by the checkpoint-restore (CRIU) system, -and reliably provides a list of children only if all of the child processes -are stopped or frozen. -It does not work properly if children of the target task exit while -the file is being read! -Exiting children may cause non-exiting children to be omitted from the list. -This makes this interface even more unreliable than classic PID-based -approaches if the inspected task and its children aren't frozen, -and most code should probably not use this interface. -.IP -Until Linux 4.2, the presence of this file was governed by the -.B CONFIG_CHECKPOINT_RESTORE -kernel configuration option. -Since Linux 4.2, -.\" commit 2e13ba54a2682eea24918b87ad3edf70c2cf085b -it is governed by the -.B CONFIG_PROC_CHILDREN -option. -.TP -.IR /proc/ pid /timers " (since Linux 3.10)" -.\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5 -.\" commit 48f6a7a511ef8823fdff39afee0320092d43a8a0 -A list of the POSIX timers for this process. -Each timer is listed with a line that starts with the string "ID:". -For example: -.IP -.in +4n -.EX -ID: 1 -signal: 60/00007fff86e452a8 -notify: signal/pid.2634 -ClockID: 0 -ID: 0 -signal: 60/00007fff86e452a8 -notify: signal/pid.2634 -ClockID: 1 -.EE -.in -.IP -The lines shown for each timer have the following meanings: -.RS -.TP -.I ID -The ID for this timer. -This is not the same as the timer ID returned by -.BR timer_create (2); -rather, it is the same kernel-internal ID that is available via the -.I si_timerid -field of the -.I siginfo_t -structure (see -.BR sigaction (2)). -.TP -.I signal -This is the signal number that this timer uses to deliver notifications -followed by a slash, and then the -.I sigev_value -value supplied to the signal handler. -Valid only for timers that notify via a signal. -.TP -.I notify -The part before the slash specifies the mechanism -that this timer uses to deliver notifications, -and is one of "thread", "signal", or "none". -Immediately following the slash is either the string "tid" for timers -with -.B SIGEV_THREAD_ID -notification, or "pid" for timers that notify by other mechanisms. -Following the "." is the PID of the process -(or the kernel thread ID of the thread) that will be delivered -a signal if the timer delivers notifications via a signal. -.TP -.I ClockID -This field identifies the clock that the timer uses for measuring time. -For most clocks, this is a number that matches one of the user-space -.B CLOCK_* -constants exposed via -.IR . -.B CLOCK_PROCESS_CPUTIME_ID -timers display with a value of \-6 -in this field. -.B CLOCK_THREAD_CPUTIME_ID -timers display with a value of \-2 -in this field. -.RE -.IP -This file is available only when the kernel was configured with -.BR CONFIG_CHECKPOINT_RESTORE . -.TP -.IR /proc/ pid /timerslack_ns " (since Linux 4.6)" -.\" commit da8b44d5a9f8bf26da637b7336508ca534d6b319 -.\" commit 5de23d435e88996b1efe0e2cebe242074ce67c9e -This file exposes the process's "current" timer slack value, -expressed in nanoseconds. -The file is writable, -allowing the process's timer slack value to be changed. -Writing 0 to this file resets the "current" timer slack to the -"default" timer slack value. -For further details, see the discussion of -.B PR_SET_TIMERSLACK -in -.BR prctl (2). -.IP -Initially, -permission to access this file was governed by a ptrace access mode -.B PTRACE_MODE_ATTACH_FSCREDS -check (see -.BR ptrace (2)). -However, this was subsequently deemed too strict a requirement -(and had the side effect that requiring a process to have the -.B CAP_SYS_PTRACE -capability would also allow it to view and change any process's memory). -Therefore, since Linux 4.9, -.\" commit 7abbaf94049914f074306d960b0f968ffe52e59f -only the (weaker) -.B CAP_SYS_NICE -capability is required to access this file. -.TP -.IR /proc/ pid /uid_map " (since Linux 3.5)" -See -.BR user_namespaces (7). -.TP -.IR /proc/ pid /wchan " (since Linux 2.6.0)" -The symbolic name corresponding to the location -in the kernel where the process is sleeping. -.IP -Permission to access this file is governed by a ptrace access mode -.B PTRACE_MODE_READ_FSCREDS -check; see -.BR ptrace (2). -.TP -.IR /proc/ tid -There is a numerical subdirectory for each running thread -that is not a thread group leader -(i.e., a thread whose thread ID is not the same as its process ID); -the subdirectory is named by the thread ID. -Each one of these subdirectories contains files and subdirectories -exposing information about the thread with the thread ID -.IR tid . -The contents of these directories are the same as the corresponding -.IR /proc/ pid /task/ tid -directories. -.IP -The -.IR /proc/ tid -subdirectories are -.I not -visible when iterating through -.I /proc -with -.BR getdents (2) -(and thus are -.I not -visible when one uses -.BR ls (1) -to view the contents of -.IR /proc ). -However, the pathnames of these directories are visible to -(i.e., usable as arguments in) -system calls that operate on pathnames. -.TP -.I /proc/apm -Advanced power management version and battery information when -.B CONFIG_APM -is defined at kernel compilation time. -.TP -.I /proc/buddyinfo -This file contains information which is used for diagnosing memory -fragmentation issues. -Each line starts with the identification of the node and the name -of the zone which together identify a memory region. -This is then -followed by the count of available chunks of a certain order in -which these zones are split. -The size in bytes of a certain order is given by the formula: -.IP -.in +4n -.EX -(2\[ha]order)\ *\ PAGE_SIZE -.EE -.in -.IP -The binary buddy allocator algorithm inside the kernel will split -one chunk into two chunks of a smaller order (thus with half the -size) or combine two contiguous chunks into one larger chunk of -a higher order (thus with double the size) to satisfy allocation -requests and to counter memory fragmentation. -The order matches the column number, when starting to count at zero. -.IP -For example on an x86-64 system: -.RS -12 -.EX -Node 0, zone DMA 1 1 1 0 2 1 1 0 1 1 3 -Node 0, zone DMA32 65 47 4 81 52 28 13 10 5 1 404 -Node 0, zone Normal 216 55 189 101 84 38 37 27 5 3 587 -.EE -.RE -.IP -In this example, there is one node containing three zones and there -are 11 different chunk sizes. -If the page size is 4 kilobytes, then the first zone called -.I DMA -(on x86 the first 16 megabyte of memory) has 1 chunk of 4 kilobytes -(order 0) available and has 3 chunks of 4 megabytes (order 10) available. -.IP -If the memory is heavily fragmented, the counters for higher -order chunks will be zero and allocation of large contiguous areas -will fail. -.IP -Further information about the zones can be found in -.IR /proc/zoneinfo . -.TP -.I /proc/bus -Contains subdirectories for installed buses. -.TP -.I /proc/bus/pccard -Subdirectory for PCMCIA devices when -.B CONFIG_PCMCIA -is set at kernel compilation time. -.TP -.I /proc/bus/pccard/drivers -.TP -.I /proc/bus/pci -Contains various bus subdirectories and pseudo-files containing -information about PCI buses, installed devices, and device -drivers. -Some of these files are not ASCII. -.TP -.I /proc/bus/pci/devices -Information about PCI devices. -They may be accessed through -.BR lspci (8) -and -.BR setpci (8). -.TP -.IR /proc/cgroups " (since Linux 2.6.24)" -See -.BR cgroups (7). -.TP -.I /proc/cmdline -Arguments passed to the Linux kernel at boot time. -Often done via a boot manager such as -.BR lilo (8) -or -.BR grub (8). -Any arguments embedded in the kernel image or initramfs via -.B CONFIG_BOOT_CONFIG -will also be displayed. -.TP -.IR /proc/config.gz " (since Linux 2.6)" -This file exposes the configuration options that were used -to build the currently running kernel, -in the same format as they would be shown in the -.I .config -file that resulted when configuring the kernel (using -.IR "make xconfig" , -.IR "make config" , -or similar). -The file contents are compressed; view or search them using -.BR zcat (1) -and -.BR zgrep (1). -As long as no changes have been made to the following file, -the contents of -.I /proc/config.gz -are the same as those provided by: -.IP -.in +4n -.EX -cat /lib/modules/$(uname \-r)/build/.config -.EE -.in -.IP -.I /proc/config.gz -is provided only if the kernel is configured with -.BR CONFIG_IKCONFIG_PROC . -.TP -.I /proc/crypto -A list of the ciphers provided by the kernel crypto API. -For details, see the kernel -.I "Linux Kernel Crypto API" -documentation available under the kernel source directory -.I Documentation/crypto/ -.\" commit 3b72c814a8e8cd638e1ba0da4dfce501e9dff5af -(or -.I Documentation/DocBook -before Linux 4.10; -the documentation can be built using a command such as -.I make htmldocs -in the root directory of the kernel source tree). -.TP -.I /proc/cpuinfo -This is a collection of CPU and system architecture dependent items, -for each supported architecture a different list. -Two common entries are \fIprocessor\fP which gives CPU number and -\fIbogomips\fP; a system constant that is calculated -during kernel initialization. -SMP machines have information for -each CPU. -The -.BR lscpu (1) -command gathers its information from this file. -.TP -.I /proc/devices -Text listing of major numbers and device groups. -This can be used by MAKEDEV scripts for consistency with the kernel. -.TP -.IR /proc/diskstats " (since Linux 2.5.69)" -This file contains disk I/O statistics for each disk device. -See the Linux kernel source file -.I Documentation/admin\-guide/iostats.rst -(or -.I Documentation/iostats.txt -before Linux 5.3) -for further information. -.TP -.I /proc/dma -This is a list of the registered \fIISA\fP DMA (direct memory access) -channels in use. -.TP -.I /proc/driver -Empty subdirectory. -.TP -.I /proc/execdomains -Used to list ABI personalities before Linux 4.1; -now contains a constant string for userspace compatibility. -.TP -.I /proc/fb -Frame buffer information when -.B CONFIG_FB -is defined during kernel compilation. -.TP -.I /proc/filesystems -A text listing of the filesystems which are supported by the kernel, -namely filesystems which were compiled into the kernel or whose kernel -modules are currently loaded. -(See also -.BR filesystems (5).) -If a filesystem is marked with "nodev", -this means that it does not require a block device to be mounted -(e.g., virtual filesystem, network filesystem). -.IP -Incidentally, this file may be used by -.BR mount (8) -when no filesystem is specified and it didn't manage to determine the -filesystem type. -Then filesystems contained in this file are tried -(excepted those that are marked with "nodev"). -.TP -.I /proc/fs -.\" FIXME Much more needs to be said about /proc/fs -.\" -Contains subdirectories that in turn contain files -with information about (certain) mounted filesystems. -.TP -.I /proc/ide -This directory -exists on systems with the IDE bus. -There are directories for each IDE channel and attached device. -Files include: -.IP -.in +4n -.EX -cache buffer size in KB -capacity number of sectors -driver driver version -geometry physical and logical geometry -identify in hexadecimal -media media type -model manufacturer\[aq]s model number -settings drive settings -smart_thresholds IDE disk management thresholds (in hex) -smart_values IDE disk management values (in hex) -.EE -.in -.IP -The -.BR hdparm (8) -utility provides access to this information in a friendly format. -.TP -.I /proc/interrupts -This is used to record the number of interrupts per CPU per IO device. -Since Linux 2.6.24, -for the i386 and x86-64 architectures, at least, this also includes -interrupts internal to the system (that is, not associated with a device -as such), such as NMI (nonmaskable interrupt), LOC (local timer interrupt), -and for SMP systems, TLB (TLB flush interrupt), RES (rescheduling -interrupt), CAL (remote function call interrupt), and possibly others. -Very easy to read formatting, done in ASCII. -.TP -.I /proc/iomem -I/O memory map in Linux 2.4. -.TP -.I /proc/ioports -This is a list of currently registered Input-Output port regions that -are in use. -.TP -.IR /proc/kallsyms " (since Linux 2.5.71)" -This holds the kernel exported symbol definitions used by the -.BR modules (X) -tools to dynamically link and bind loadable modules. -In Linux 2.5.47 and earlier, a similar file with slightly different syntax -was named -.IR ksyms . -.TP -.I /proc/kcore -This file represents the physical memory of the system and is stored -in the ELF core file format. -With this pseudo-file, and an unstripped -kernel -.RI ( /usr/src/linux/vmlinux ) -binary, GDB can be used to -examine the current state of any kernel data structures. -.IP -The total length of the file is the size of physical memory (RAM) plus -4\ KiB. -.TP -.IR /proc/keys " (since Linux 2.6.10)" -See -.BR keyrings (7). -.TP -.IR /proc/key\-users " (since Linux 2.6.10)" -See -.BR keyrings (7). -.TP -.I /proc/kmsg -This file can be used instead of the -.BR syslog (2) -system call to read kernel messages. -A process must have superuser -privileges to read this file, and only one process should read this -file. -This file should not be read if a syslog process is running -which uses the -.BR syslog (2) -system call facility to log kernel messages. -.IP -Information in this file is retrieved with the -.BR dmesg (1) -program. -.TP -.IR /proc/kpagecgroup " (since Linux 4.3)" -.\" commit 80ae2fdceba8313b0433f899bdd9c6c463291a17 -This file contains a 64-bit inode number of -the memory cgroup each page is charged to, -indexed by page frame number (see the discussion of -.IR /proc/ pid /pagemap ). -.IP -The -.I /proc/kpagecgroup -file is present only if the -.B CONFIG_MEMCG -kernel configuration option is enabled. -.TP -.IR /proc/kpagecount " (since Linux 2.6.25)" -This file contains a 64-bit count of the number of -times each physical page frame is mapped, -indexed by page frame number (see the discussion of -.IR /proc/ pid /pagemap ). -.IP -The -.I /proc/kpagecount -file is present only if the -.B CONFIG_PROC_PAGE_MONITOR -kernel configuration option is enabled. -.TP -.IR /proc/kpageflags " (since Linux 2.6.25)" -This file contains 64-bit masks corresponding to each physical page frame; -it is indexed by page frame number (see the discussion of -.IR /proc/ pid /pagemap ). -The bits are as follows: -.RS -.IP -.TS -r l l l. -0 - KPF_LOCKED -1 - KPF_ERROR -2 - KPF_REFERENCED -3 - KPF_UPTODATE -4 - KPF_DIRTY -5 - KPF_LRU -6 - KPF_ACTIVE -7 - KPF_SLAB -8 - KPF_WRITEBACK -9 - KPF_RECLAIM -10 - KPF_BUDDY -11 - KPF_MMAP (since Linux 2.6.31) -12 - KPF_ANON (since Linux 2.6.31) -13 - KPF_SWAPCACHE (since Linux 2.6.31) -14 - KPF_SWAPBACKED (since Linux 2.6.31) -15 - KPF_COMPOUND_HEAD (since Linux 2.6.31) -16 - KPF_COMPOUND_TAIL (since Linux 2.6.31) -17 - KPF_HUGE (since Linux 2.6.31) -18 - KPF_UNEVICTABLE (since Linux 2.6.31) -19 - KPF_HWPOISON (since Linux 2.6.31) -20 - KPF_NOPAGE (since Linux 2.6.31) -21 - KPF_KSM (since Linux 2.6.32) -22 - KPF_THP (since Linux 3.4) -23 - KPF_BALLOON (since Linux 3.18) -.\" KPF_BALLOON: commit 09316c09dde33aae14f34489d9e3d243ec0d5938 -24 - KPF_ZERO_PAGE (since Linux 4.0) -.\" KPF_ZERO_PAGE: commit 56873f43abdcd574b25105867a990f067747b2f4 -25 - KPF_IDLE (since Linux 4.3) -.\" KPF_IDLE: commit f074a8f49eb87cde95ac9d040ad5e7ea4f029738 -26 - KPF_PGTABLE (since Linux 4.18) -.\" KPF_PGTABLE: commit 1d40a5ea01d53251c23c7be541d3f4a656cfc537 -.TE -.RE -.IP -For further details on the meanings of these bits, -see the kernel source file -.IR Documentation/admin\-guide/mm/pagemap.rst . -Before Linux 2.6.29, -.\" commit ad3bdefe877afb47480418fdb05ecd42842de65e -.\" commit e07a4b9217d1e97d2f3a62b6b070efdc61212110 -.BR KPF_WRITEBACK , -.BR KPF_RECLAIM , -.BR KPF_BUDDY , -and -.B KPF_LOCKED -did not report correctly. -.IP -The -.I /proc/kpageflags -file is present only if the -.B CONFIG_PROC_PAGE_MONITOR -kernel configuration option is enabled. -.TP -.IR /proc/ksyms " (Linux 1.1.23\[en]2.5.47)" -See -.IR /proc/kallsyms . -.TP -.I /proc/loadavg -The first three fields in this file are load average figures -giving the number of jobs in the run queue (state R) -or waiting for disk I/O (state D) averaged over 1, 5, and 15 minutes. -They are the same as the load average numbers given by -.BR uptime (1) -and other programs. -The fourth field consists of two numbers separated by a slash (/). -The first of these is the number of currently runnable kernel -scheduling entities (processes, threads). -The value after the slash is the number of kernel scheduling entities -that currently exist on the system. -The fifth field is the PID of the process that was most -recently created on the system. -.TP -.I /proc/locks -This file shows current file locks -.RB ( flock "(2) and " fcntl (2)) -and leases -.RB ( fcntl (2)). -.IP -An example of the content shown in this file is the following: -.IP -.in +4n -.EX -1: POSIX ADVISORY READ 5433 08:01:7864448 128 128 -2: FLOCK ADVISORY WRITE 2001 08:01:7864554 0 EOF -3: FLOCK ADVISORY WRITE 1568 00:2f:32388 0 EOF -4: POSIX ADVISORY WRITE 699 00:16:28457 0 EOF -5: POSIX ADVISORY WRITE 764 00:16:21448 0 0 -6: POSIX ADVISORY READ 3548 08:01:7867240 1 1 -7: POSIX ADVISORY READ 3548 08:01:7865567 1826 2335 -8: OFDLCK ADVISORY WRITE \-1 08:01:8713209 128 191 -.EE -.in -.IP -The fields shown in each line are as follows: -.RS -.IP [1] 5 -The ordinal position of the lock in the list. -.IP [2] -The lock type. -Values that may appear here include: -.RS -.TP -.B FLOCK -This is a BSD file lock created using -.BR flock (2). -.TP -.B OFDLCK -This is an open file description (OFD) lock created using -.BR fcntl (2). -.TP -.B POSIX -This is a POSIX byte-range lock created using -.BR fcntl (2). -.RE -.IP [3] -Among the strings that can appear here are the following: -.RS -.TP -.B ADVISORY -This is an advisory lock. -.TP -.B MANDATORY -This is a mandatory lock. -.RE -.IP [4] -The type of lock. -Values that can appear here are: -.RS -.TP -.B READ -This is a POSIX or OFD read lock, or a BSD shared lock. -.TP -.B WRITE -This is a POSIX or OFD write lock, or a BSD exclusive lock. -.RE -.IP [5] -The PID of the process that owns the lock. -.IP -Because OFD locks are not owned by a single process -(since multiple processes may have file descriptors that -refer to the same open file description), -the value \-1 is displayed in this field for OFD locks. -(Before Linux 4.14, -.\" commit 9d5b86ac13c573795525ecac6ed2db39ab23e2a8 -a bug meant that the PID of the process that -initially acquired the lock was displayed instead of the value \-1.) -.IP [6] -Three colon-separated subfields that identify the major and minor device -ID of the device containing the filesystem where the locked file resides, -followed by the inode number of the locked file. -.IP [7] -The byte offset of the first byte of the lock. -For BSD locks, this value is always 0. -.IP [8] -The byte offset of the last byte of the lock. -.B EOF -in this field means that the lock extends to the end of the file. -For BSD locks, the value shown is always -.IR EOF . -.RE -.IP -Since Linux 4.9, -.\" commit d67fd44f697dff293d7cdc29af929241b669affe -the list of locks shown in -.I /proc/locks -is filtered to show just the locks for the processes in the PID -namespace (see -.BR pid_namespaces (7)) -for which the -.I /proc -filesystem was mounted. -(In the initial PID namespace, -there is no filtering of the records shown in this file.) -.IP -The -.BR lslocks (8) -command provides a bit more information about each lock. -.TP -.IR /proc/malloc " (only up to and including Linux 2.2)" -.\" It looks like this only ever did something back in 1.0 days -This file is present only if -.B CONFIG_DEBUG_MALLOC -was defined during compilation. -.TP -.I /proc/meminfo -This file reports statistics about memory usage on the system. -It is used by -.BR free (1) -to report the amount of free and used memory (both physical and swap) -on the system as well as the shared memory and buffers used by the -kernel. -Each line of the file consists of a parameter name, followed by a colon, -the value of the parameter, and an option unit of measurement (e.g., "kB"). -The list below describes the parameter names and -the format specifier required to read the field value. -Except as noted below, -all of the fields have been present since at least Linux 2.6.0. -Some fields are displayed only if the kernel was configured -with various options; those dependencies are noted in the list. -.RS -.TP -.IR MemTotal " %lu" -Total usable RAM (i.e., physical RAM minus a few reserved -bits and the kernel binary code). -.TP -.IR MemFree " %lu" -The sum of -.IR LowFree + HighFree . -.TP -.IR MemAvailable " %lu (since Linux 3.14)" -An estimate of how much memory is available for starting new -applications, without swapping. -.TP -.IR Buffers " %lu" -Relatively temporary storage for raw disk blocks that -shouldn't get tremendously large (20 MB or so). -.TP -.IR Cached " %lu" -In-memory cache for files read from the disk (the page cache). -Doesn't include -.IR SwapCached . -.TP -.IR SwapCached " %lu" -Memory that once was swapped out, is swapped back in but -still also is in the swap file. -(If memory pressure is high, these pages -don't need to be swapped out again because they are already -in the swap file. -This saves I/O.) -.TP -.IR Active " %lu" -Memory that has been used more recently and usually not -reclaimed unless absolutely necessary. -.TP -.IR Inactive " %lu" -Memory which has been less recently used. -It is more eligible to be reclaimed for other purposes. -.TP -.IR Active(anon) " %lu (since Linux 2.6.28)" -[To be documented.] -.TP -.IR Inactive(anon) " %lu (since Linux 2.6.28)" -[To be documented.] -.TP -.IR Active(file) " %lu (since Linux 2.6.28)" -[To be documented.] -.TP -.IR Inactive(file) " %lu (since Linux 2.6.28)" -[To be documented.] -.TP -.IR Unevictable " %lu (since Linux 2.6.28)" -(From Linux 2.6.28 to Linux 2.6.30, -\fBCONFIG_UNEVICTABLE_LRU\fP was required.) -[To be documented.] -.TP -.IR Mlocked " %lu (since Linux 2.6.28)" -(From Linux 2.6.28 to Linux 2.6.30, -\fBCONFIG_UNEVICTABLE_LRU\fP was required.) -[To be documented.] -.TP -.IR HighTotal " %lu" -(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) -Total amount of highmem. -Highmem is all memory above \[ti]860 MB of physical memory. -Highmem areas are for use by user-space programs, -or for the page cache. -The kernel must use tricks to access -this memory, making it slower to access than lowmem. -.TP -.IR HighFree " %lu" -(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) -Amount of free highmem. -.TP -.IR LowTotal " %lu" -(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) -Total amount of lowmem. -Lowmem is memory which can be used for everything that -highmem can be used for, but it is also available for the -kernel's use for its own data structures. -Among many other things, -it is where everything from -.I Slab -is allocated. -Bad things happen when you're out of lowmem. -.TP -.IR LowFree " %lu" -(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) -Amount of free lowmem. -.TP -.IR MmapCopy " %lu (since Linux 2.6.29)" -.RB ( CONFIG_MMU -is required.) -[To be documented.] -.TP -.IR SwapTotal " %lu" -Total amount of swap space available. -.TP -.IR SwapFree " %lu" -Amount of swap space that is currently unused. -.TP -.IR Dirty " %lu" -Memory which is waiting to get written back to the disk. -.TP -.IR Writeback " %lu" -Memory which is actively being written back to the disk. -.TP -.IR AnonPages " %lu (since Linux 2.6.18)" -Non-file backed pages mapped into user-space page tables. -.TP -.IR Mapped " %lu" -Files which have been mapped into memory (with -.BR mmap (2)), -such as libraries. -.TP -.IR Shmem " %lu (since Linux 2.6.32)" -Amount of memory consumed in -.BR tmpfs (5) -filesystems. -.TP -.IR KReclaimable " %lu (since Linux 4.20)" -Kernel allocations that the kernel will attempt to reclaim -under memory pressure. -Includes -.I SReclaimable -(below), and other direct allocations with a shrinker. -.TP -.IR Slab " %lu" -In-kernel data structures cache. -(See -.BR slabinfo (5).) -.TP -.IR SReclaimable " %lu (since Linux 2.6.19)" -Part of -.IR Slab , -that might be reclaimed, such as caches. -.TP -.IR SUnreclaim " %lu (since Linux 2.6.19)" -Part of -.IR Slab , -that cannot be reclaimed on memory pressure. -.TP -.IR KernelStack " %lu (since Linux 2.6.32)" -Amount of memory allocated to kernel stacks. -.TP -.IR PageTables " %lu (since Linux 2.6.18)" -Amount of memory dedicated to the lowest level of page tables. -.TP -.IR Quicklists " %lu (since Linux 2.6.27)" -(\fBCONFIG_QUICKLIST\fP is required.) -[To be documented.] -.TP -.IR NFS_Unstable " %lu (since Linux 2.6.18)" -NFS pages sent to the server, but not yet committed to stable storage. -.TP -.IR Bounce " %lu (since Linux 2.6.18)" -Memory used for block device "bounce buffers". -.TP -.IR WritebackTmp " %lu (since Linux 2.6.26)" -Memory used by FUSE for temporary writeback buffers. -.TP -.IR CommitLimit " %lu (since Linux 2.6.10)" -This is the total amount of memory currently available to -be allocated on the system, expressed in kilobytes. -This limit is adhered to -only if strict overcommit accounting is enabled (mode 2 in -.IR /proc/sys/vm/overcommit_memory ). -The limit is calculated according to the formula described under -.IR /proc/sys/vm/overcommit_memory . -For further details, see the kernel source file -.IR Documentation/vm/overcommit\-accounting.rst . -.TP -.IR Committed_AS " %lu" -The amount of memory presently allocated on the system. -The committed memory is a sum of all of the memory which -has been allocated by processes, even if it has not been -"used" by them as of yet. -A process which allocates 1 GB of memory (using -.BR malloc (3) -or similar), but touches only 300 MB of that memory will show up -as using only 300 MB of memory even if it has the address space -allocated for the entire 1 GB. -.IP -This 1 GB is memory which has been "committed" to by the VM -and can be used at any time by the allocating application. -With strict overcommit enabled on the system (mode 2 in -.IR /proc/sys/vm/overcommit_memory ), -allocations which would exceed the -.I CommitLimit -will not be permitted. -This is useful if one needs to guarantee that processes will not -fail due to lack of memory once that memory has been successfully allocated. -.TP -.IR VmallocTotal " %lu" -Total size of vmalloc memory area. -.TP -.IR VmallocUsed " %lu" -Amount of vmalloc area which is used. -Since Linux 4.4, -.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 -this field is no longer calculated, and is hard coded as 0. -See -.IR /proc/vmallocinfo . -.TP -.IR VmallocChunk " %lu" -Largest contiguous block of vmalloc area which is free. -Since Linux 4.4, -.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 -this field is no longer calculated and is hard coded as 0. -See -.IR /proc/vmallocinfo . -.TP -.IR HardwareCorrupted " %lu (since Linux 2.6.32)" -(\fBCONFIG_MEMORY_FAILURE\fP is required.) -[To be documented.] -.TP -.IR LazyFree " %lu (since Linux 4.12)" -Shows the amount of memory marked by -.BR madvise (2) -.BR MADV_FREE . -.TP -.IR AnonHugePages " %lu (since Linux 2.6.38)" -(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) -Non-file backed huge pages mapped into user-space page tables. -.TP -.IR ShmemHugePages " %lu (since Linux 4.8)" -(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) -Memory used by shared memory (shmem) and -.BR tmpfs (5) -allocated with huge pages. -.TP -.IR ShmemPmdMapped " %lu (since Linux 4.8)" -(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) -Shared memory mapped into user space with huge pages. -.TP -.IR CmaTotal " %lu (since Linux 3.1)" -Total CMA (Contiguous Memory Allocator) pages. -(\fBCONFIG_CMA\fP is required.) -.TP -.IR CmaFree " %lu (since Linux 3.1)" -Free CMA (Contiguous Memory Allocator) pages. -(\fBCONFIG_CMA\fP is required.) -.TP -.IR HugePages_Total " %lu" -(\fBCONFIG_HUGETLB_PAGE\fP is required.) -The size of the pool of huge pages. -.TP -.IR HugePages_Free " %lu" -(\fBCONFIG_HUGETLB_PAGE\fP is required.) -The number of huge pages in the pool that are not yet allocated. -.TP -.IR HugePages_Rsvd " %lu (since Linux 2.6.17)" -(\fBCONFIG_HUGETLB_PAGE\fP is required.) -This is the number of huge pages for -which a commitment to allocate from the pool has been made, -but no allocation has yet been made. -These reserved huge pages -guarantee that an application will be able to allocate a -huge page from the pool of huge pages at fault time. -.TP -.IR HugePages_Surp " %lu (since Linux 2.6.24)" -(\fBCONFIG_HUGETLB_PAGE\fP is required.) -This is the number of huge pages in -the pool above the value in -.IR /proc/sys/vm/nr_hugepages . -The maximum number of surplus huge pages is controlled by -.IR /proc/sys/vm/nr_overcommit_hugepages . -.TP -.IR Hugepagesize " %lu" -(\fBCONFIG_HUGETLB_PAGE\fP is required.) -The size of huge pages. -.TP -.IR DirectMap4k " %lu (since Linux 2.6.27)" -Number of bytes of RAM linearly mapped by kernel in 4 kB pages. -(x86.) -.TP -.IR DirectMap4M " %lu (since Linux 2.6.27)" -Number of bytes of RAM linearly mapped by kernel in 4 MB pages. -(x86 with -.B CONFIG_X86_64 -or -.B CONFIG_X86_PAE -enabled.) -.TP -.IR DirectMap2M " %lu (since Linux 2.6.27)" -Number of bytes of RAM linearly mapped by kernel in 2 MB pages. -(x86 with neither -.B CONFIG_X86_64 -nor -.B CONFIG_X86_PAE -enabled.) -.TP -.IR DirectMap1G " %lu (since Linux 2.6.27)" -(x86 with -.B CONFIG_X86_64 -and -.B CONFIG_X86_DIRECT_GBPAGES -enabled.) -.RE -.TP -.I /proc/modules -A text list of the modules that have been loaded by the system. -See also -.BR lsmod (8). -.TP -.I /proc/mounts -Before Linux 2.4.19, this file was a list -of all the filesystems currently mounted on the system. -With the introduction of per-process mount namespaces in Linux 2.4.19 (see -.BR mount_namespaces (7)), -this file became a link to -.IR /proc/self/mounts , -which lists the mounts of the process's own mount namespace. -The format of this file is documented in -.BR fstab (5). -.TP -.I /proc/mtrr -Memory Type Range Registers. -See the Linux kernel source file -.I Documentation/x86/mtrr.rst -(or -.I Documentation/x86/mtrr.txt -.\" commit 7225e75144b9718cbbe1820d9c011c809d5773fd -before Linux 5.2, or -.I Documentation/mtrr.txt -before Linux 2.6.28) -for details. -.TP -.I /proc/net -This directory contains various files and subdirectories containing -information about the networking layer. -The files contain ASCII structures and are, -therefore, readable with -.BR cat (1). -However, the standard -.BR netstat (8) -suite provides much cleaner access to these files. -.IP -With the advent of network namespaces, -various information relating to the network stack is virtualized (see -.BR network_namespaces (7)). -Thus, since Linux 2.6.25, -.\" commit e9720acd728a46cb40daa52c99a979f7c4ff195c -.I /proc/net -is a symbolic link to the directory -.IR /proc/self/net , -which contains the same files and directories as listed below. -However, these files and directories now expose information -for the network namespace of which the process is a member. -.TP -.I /proc/net/arp -This holds an ASCII readable dump of the kernel ARP table used for -address resolutions. -It will show both dynamically learned and preprogrammed ARP entries. -The format is: -.IP -.in +4n -.EX -IP address HW type Flags HW address Mask Device -192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0 -192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0 -.EE -.in -.IP -Here "IP address" is the IPv4 address of the machine and the "HW type" -is the hardware type of the address from RFC\ 826. -The flags are the internal -flags of the ARP structure (as defined in -.IR /usr/include/linux/if_arp.h ) -and -the "HW address" is the data link layer mapping for that IP address if -it is known. -.TP -.I /proc/net/dev -The dev pseudo-file contains network device status information. -This gives -the number of received and sent packets, the number of errors and -collisions -and other basic statistics. -These are used by the -.BR ifconfig (8) -program to report device status. -The format is: -.IP -.EX -Inter\-| Receive | Transmit - face |bytes packets errs drop fifo frame compressed multicast|bytes packets errs drop fifo colls carrier compressed - lo: 2776770 11307 0 0 0 0 0 0 2776770 11307 0 0 0 0 0 0 - eth0: 1215645 2751 0 0 0 0 0 0 1782404 4324 0 0 0 427 0 0 - ppp0: 1622270 5552 1 0 0 0 0 0 354130 5669 0 0 0 0 0 0 - tap0: 7714 81 0 0 0 0 0 0 7714 81 0 0 0 0 0 0 -.EE -.\" .TP -.\" .I /proc/net/ipx -.\" No information. -.\" .TP -.\" .I /proc/net/ipx_route -.\" No information. -.TP -.I /proc/net/dev_mcast -Defined in -.IR /usr/src/linux/net/core/dev_mcast.c : -.IP -.in +4n -.EX -indx interface_name dmi_u dmi_g dmi_address -2 eth0 1 0 01005e000001 -3 eth1 1 0 01005e000001 -4 eth2 1 0 01005e000001 -.EE -.in -.TP -.I /proc/net/igmp -Internet Group Management Protocol. -Defined in -.IR /usr/src/linux/net/core/igmp.c . -.TP -.I /proc/net/rarp -This file uses the same format as the -.I arp -file and contains the current reverse mapping database used to provide -.BR rarp (8) -reverse address lookup services. -If RARP is not configured into the -kernel, -this file will not be present. -.TP -.I /proc/net/raw -Holds a dump of the RAW socket table. -Much of the information is not of -use -apart from debugging. -The "sl" value is the kernel hash slot for the -socket, -the "local_address" is the local address and protocol number pair. -\&"St" is -the internal status of the socket. -The "tx_queue" and "rx_queue" are the -outgoing and incoming data queue in terms of kernel memory usage. -The "tr", "tm\->when", and "rexmits" fields are not used by RAW. -The "uid" -field holds the effective UID of the creator of the socket. -.\" .TP -.\" .I /proc/net/route -.\" No information, but looks similar to -.\" .BR route (8). -.TP -.I /proc/net/snmp -This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP -management -information bases for an SNMP agent. -.TP -.I /proc/net/tcp -Holds a dump of the TCP socket table. -Much of the information is not -of use apart from debugging. -The "sl" value is the kernel hash slot -for the socket, the "local_address" is the local address and port number pair. -The "rem_address" is the remote address and port number pair -(if connected). -\&"St" is the internal status of the socket. -The "tx_queue" and "rx_queue" are the -outgoing and incoming data queue in terms of kernel memory usage. -The "tr", "tm\->when", and "rexmits" fields hold internal information of -the kernel socket state and are useful only for debugging. -The "uid" -field holds the effective UID of the creator of the socket. -.TP -.I /proc/net/udp -Holds a dump of the UDP socket table. -Much of the information is not of -use apart from debugging. -The "sl" value is the kernel hash slot for the -socket, the "local_address" is the local address and port number pair. -The "rem_address" is the remote address and port number pair -(if connected). -"St" is the internal status of the socket. -The "tx_queue" and "rx_queue" are the outgoing and incoming data queue -in terms of kernel memory usage. -The "tr", "tm\->when", and "rexmits" fields -are not used by UDP. -The "uid" -field holds the effective UID of the creator of the socket. -The format is: -.IP -.EX -sl local_address rem_address st tx_queue rx_queue tr rexmits tm\->when uid - 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 - 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 - 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 -.EE -.TP -.I /proc/net/unix -Lists the UNIX domain sockets present within the system and their -status. -The format is: -.IP -.EX -Num RefCount Protocol Flags Type St Inode Path - 0: 00000002 00000000 00000000 0001 03 42 - 1: 00000001 00000000 00010000 0001 01 1948 /dev/printer -.EE -.IP -The fields are as follows: -.RS -.TP 10 -.IR Num : -the kernel table slot number. -.TP -.IR RefCount : -the number of users of the socket. -.TP -.IR Protocol : -currently always 0. -.TP -.IR Flags : -the internal kernel flags holding the status of the socket. -.TP -.IR Type : -the socket type. -For -.B SOCK_STREAM -sockets, this is 0001; for -.B SOCK_DGRAM -sockets, it is 0002; and for -.B SOCK_SEQPACKET -sockets, it is 0005. -.TP -.IR St : -the internal state of the socket. -.TP -.IR Inode : -the inode number of the socket. -.TP -.IR Path : -the bound pathname (if any) of the socket. -Sockets in the abstract namespace are included in the list, -and are shown with a -.I Path -that commences with the character '@'. -.RE -.TP -.I /proc/net/netfilter/nfnetlink_queue -This file contains information about netfilter user-space queueing, if used. -Each line represents a queue. -Queues that have not been subscribed to -by user space are not shown. -.IP -.in +4n -.EX - 1 4207 0 2 65535 0 0 0 1 - (1) (2) (3)(4) (5) (6) (7) (8) -.EE -.in -.IP -The fields in each line are: -.RS 7 -.TP 5 -(1) -The ID of the queue. -This matches what is specified in the -.B \-\-queue\-num -or -.B \-\-queue\-balance -options to the -.BR iptables (8) -NFQUEUE target. -See -.BR iptables\-extensions (8) -for more information. -.TP -(2) -The netlink port ID subscribed to the queue. -.TP -(3) -The number of packets currently queued and waiting to be processed by -the application. -.TP -(4) -The copy mode of the queue. -It is either 1 (metadata only) or 2 -(also copy payload data to user space). -.TP -(5) -Copy range; that is, how many bytes of packet payload should be copied to -user space at most. -.TP -(6) -queue dropped. -Number of packets that had to be dropped by the kernel because -too many packets are already waiting for user space to send back the mandatory -accept/drop verdicts. -.TP -(7) -queue user dropped. -Number of packets that were dropped within the netlink -subsystem. -Such drops usually happen when the corresponding socket buffer is -full; that is, user space is not able to read messages fast enough. -.TP -(8) -sequence number. -Every queued packet is associated with a (32-bit) -monotonically increasing sequence number. -This shows the ID of the most recent packet queued. -.RE -.IP -The last number exists only for compatibility reasons and is always 1. -.TP -.I /proc/partitions -Contains the major and minor numbers of each partition as well as the number -of 1024-byte blocks and the partition name. -.TP -.I /proc/pci -This is a listing of all PCI devices found during kernel initialization -and their configuration. -.IP -This file has been deprecated in favor of a new -.I /proc -interface for PCI -.RI ( /proc/bus/pci ). -It became optional in Linux 2.2 (available with -.B CONFIG_PCI_OLD_PROC -set at kernel compilation). -It became once more nonoptionally enabled in Linux 2.4. -Next, it was deprecated in Linux 2.6 (still available with -.B CONFIG_PCI_LEGACY_PROC -set), and finally removed altogether since Linux 2.6.17. -.\" FIXME Document /proc/sched_debug (since Linux 2.6.23) -.\" See also /proc/[pid]/sched -.TP -.IR /proc/profile " (since Linux 2.4)" -This file is present only if the kernel was booted with the -.I profile=1 -command-line option. -It exposes kernel profiling information in a binary format for use by -.BR readprofile (1). -Writing (e.g., an empty string) to this file resets the profiling counters; -on some architectures, -writing a binary integer "profiling multiplier" of size -.I sizeof(int) -sets the profiling interrupt frequency. -.TP -.I /proc/scsi -A directory with the -.I scsi -mid-level pseudo-file and various SCSI low-level -driver directories, -which contain a file for each SCSI host in this system, all of -which give the status of some part of the SCSI IO subsystem. -These files contain ASCII structures and are, therefore, readable with -.BR cat (1). -.IP -You can also write to some of the files to reconfigure the subsystem or -switch certain features on or off. -.TP -.I /proc/scsi/scsi -This is a listing of all SCSI devices known to the kernel. -The listing is similar to the one seen during bootup. -scsi currently supports only the \fIadd\-single\-device\fP command which -allows root to add a hotplugged device to the list of known devices. -.IP -The command -.IP -.in +4n -.EX -echo \[aq]scsi add\-single\-device 1 0 5 0\[aq] > /proc/scsi/scsi -.EE -.in -.IP -will cause -host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. -If there -is already a device known on this address or the address is invalid, an -error will be returned. -.TP -.IR /proc/scsi/ drivername -\fIdrivername\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, -aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, -scsi_debug, seagate, t128, u15\-24f, ultrastore, or wd7000. -These directories show up for all drivers that registered at least one -SCSI HBA. -Every directory contains one file per registered host. -Every host-file is named after the number the host was assigned during -initialization. -.IP -Reading these files will usually show driver and host configuration, -statistics, and so on. -.IP -Writing to these files allows different things on different hosts. -For example, with the \fIlatency\fP and \fInolatency\fP commands, -root can switch on and off command latency measurement code in the -eata_dma driver. -With the \fIlockup\fP and \fIunlock\fP commands, -root can control bus lockups simulated by the scsi_debug driver. -.TP -.I /proc/self -This directory refers to the process accessing the -.I /proc -filesystem, -and is identical to the -.I /proc -directory named by the process ID of the same process. -.TP -.I /proc/slabinfo -Information about kernel caches. -See -.BR slabinfo (5) -for details. -.TP -.I /proc/stat -kernel/system statistics. -Varies with architecture. -Common -entries include: -.RS -.TP -.I cpu 10132153 290696 3084719 46828483 16683 0 25195 0 175628 0 -.TQ -.I cpu0 1393280 32966 572056 13343292 6130 0 17875 0 23933 0 -The amount of time, measured in units of -USER_HZ (1/100ths of a second on most architectures, use -.I sysconf(_SC_CLK_TCK) -to obtain the right value), -.\" 1024 on Alpha and ia64 -that the system ("cpu" line) or the specific CPU ("cpu\fIN\fR" line) -spent in various states: -.RS -.TP -.I user -(1) Time spent in user mode. -.TP -.I nice -(2) Time spent in user mode with low priority (nice). -.TP -.I system -(3) Time spent in system mode. -.TP -.I idle -(4) Time spent in the idle task. -.\" FIXME . Actually, the following info about the /proc/stat 'cpu' field -.\" does not seem to be quite right (at least in Linux 2.6.12 or Linux 3.6): -.\" the idle time in /proc/uptime does not quite match this value -This value should be USER_HZ times the -second entry in the -.I /proc/uptime -pseudo-file. -.TP -.IR iowait " (since Linux 2.5.41)" -(5) Time waiting for I/O to complete. -This value is not reliable, for the following reasons: -.\" See kernel commit 9c240d757658a3ae9968dd309e674c61f07c7f48 -.RS -.IP \[bu] 3 -The CPU will not wait for I/O to complete; -iowait is the time that a task is waiting for I/O to complete. -When a CPU goes into idle state for outstanding task I/O, -another task will be scheduled on this CPU. -.IP \[bu] -On a multi-core CPU, -the task waiting for I/O to complete is not running on any CPU, -so the iowait of each CPU is difficult to calculate. -.IP \[bu] -The value in this field may -.I decrease -in certain conditions. -.RE -.TP -.IR irq " (since Linux 2.6.0)" -.\" Precisely: Linux 2.6.0-test4 -(6) Time servicing interrupts. -.TP -.IR softirq " (since Linux 2.6.0)" -.\" Precisely: Linux 2.6.0-test4 -(7) Time servicing softirqs. -.TP -.IR steal " (since Linux 2.6.11)" -(8) Stolen time, which is the time spent in other operating systems when -running in a virtualized environment -.TP -.IR guest " (since Linux 2.6.24)" -(9) Time spent running a virtual CPU for guest -operating systems under the control of the Linux kernel. -.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de -.TP -.IR guest_nice " (since Linux 2.6.33)" -.\" commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797 -(10) Time spent running a niced guest (virtual CPU for guest -operating systems under the control of the Linux kernel). -.RE -.TP -\fIpage 5741 1808\fP -The number of pages the system paged in and the number that were paged -out (from disk). -.TP -\fIswap 1 0\fP -The number of swap pages that have been brought in and out. -.TP -.\" FIXME . The following is not the full picture for the 'intr' of -.\" /proc/stat on 2.6: -\fIintr 1462898\fP -This line shows counts of interrupts serviced since boot time, -for each of the possible system interrupts. -The first column is the total of all interrupts serviced -including unnumbered architecture specific interrupts; -each subsequent column is the total for that particular numbered interrupt. -Unnumbered interrupts are not shown, only summed into the total. -.TP -\fIdisk_io: (2,0):(31,30,5764,1,2) (3,0):\fP... -(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, blks_written) -.br -(Linux 2.4 only) -.TP -\fIctxt 115315\fP -The number of context switches that the system underwent. -.TP -\fIbtime 769041601\fP -boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.TP -\fIprocesses 86031\fP -Number of forks since boot. -.TP -\fIprocs_running 6\fP -Number of processes in runnable state. -(Linux 2.5.45 onward.) -.TP -\fIprocs_blocked 2\fP -Number of processes blocked waiting for I/O to complete. -(Linux 2.5.45 onward.) -.TP -.I softirq 229245889 94 60001584 13619 5175704 2471304 28 51212741 59130143 0 51240672 -.\" commit d3d64df21d3d0de675a0d3ffa7c10514f3644b30 -This line shows the number of softirq for all CPUs. -The first column is the total of all softirqs and -each subsequent column is the total for particular softirq. -(Linux 2.6.31 onward.) -.RE -.TP -.I /proc/swaps -Swap areas in use. -See also -.BR swapon (8). -.TP -.I /proc/sys -This directory (present since Linux 1.3.57) contains a number of files -and subdirectories corresponding to kernel variables. -These variables can be read and in some cases modified using -the \fI/proc\fP filesystem, and the (deprecated) -.BR sysctl (2) -system call. -.IP -String values may be terminated by either \[aq]\e0\[aq] or \[aq]\en\[aq]. -.IP -Integer and long values may be written either in decimal or in -hexadecimal notation (e.g., 0x3FFF). -When writing multiple integer or long values, these may be separated -by any of the following whitespace characters: -\[aq]\ \[aq], \[aq]\et\[aq], or \[aq]\en\[aq]. -Using other separators leads to the error -.BR EINVAL . -.TP -.IR /proc/sys/abi " (since Linux 2.4.10)" -This directory may contain files with application binary information. -.\" On some systems, it is not present. -See the Linux kernel source file -.I Documentation/sysctl/abi.rst -(or -.I Documentation/sysctl/abi.txt -before Linux 5.3) -for more information. -.TP -.I /proc/sys/debug -This directory may be empty. -.TP -.I /proc/sys/dev -This directory contains device-specific information (e.g., -.IR dev/cdrom/info ). -On -some systems, it may be empty. -.TP -.I /proc/sys/fs -This directory contains the files and subdirectories for kernel variables -related to filesystems. -.TP -.IR /proc/sys/fs/aio\-max\-nr " and " /proc/sys/fs/aio\-nr " (since Linux 2.6.4)" -.I aio\-nr -is the running total of the number of events specified by -.BR io_setup (2) -calls for all currently active AIO contexts. -If -.I aio\-nr -reaches -.IR aio\-max\-nr , -then -.BR io_setup (2) -will fail with the error -.BR EAGAIN . -Raising -.I aio\-max\-nr -does not result in the preallocation or resizing -of any kernel data structures. -.TP -.I /proc/sys/fs/binfmt_misc -Documentation for files in this directory can be found -in the Linux kernel source in the file -.I Documentation/admin\-guide/binfmt\-misc.rst -(or in -.I Documentation/binfmt_misc.txt -on older kernels). -.TP -.IR /proc/sys/fs/dentry\-state " (since Linux 2.2)" -This file contains information about the status of the -directory cache (dcache). -The file contains six numbers, -.IR nr_dentry , -.IR nr_unused , -.I age_limit -(age in seconds), -.I want_pages -(pages requested by system) and two dummy values. -.RS -.IP \[bu] 3 -.I nr_dentry -is the number of allocated dentries (dcache entries). -This field is unused in Linux 2.2. -.IP \[bu] -.I nr_unused -is the number of unused dentries. -.IP \[bu] -.I age_limit -.\" looks like this is unused in Linux 2.2 to Linux 2.6 -is the age in seconds after which dcache entries -can be reclaimed when memory is short. -.IP \[bu] -.I want_pages -.\" looks like this is unused in Linux 2.2 to Linux 2.6 -is nonzero when the kernel has called shrink_dcache_pages() and the -dcache isn't pruned yet. -.RE -.TP -.I /proc/sys/fs/dir\-notify\-enable -This file can be used to disable or enable the -.I dnotify -interface described in -.BR fcntl (2) -on a system-wide basis. -A value of 0 in this file disables the interface, -and a value of 1 enables it. -.TP -.I /proc/sys/fs/dquot\-max -This file shows the maximum number of cached disk quota entries. -On some (2.4) systems, it is not present. -If the number of free cached disk quota entries is very low and -you have some awesome number of simultaneous system users, -you might want to raise the limit. -.TP -.I /proc/sys/fs/dquot\-nr -This file shows the number of allocated disk quota -entries and the number of free disk quota entries. -.TP -.IR /proc/sys/fs/epoll " (since Linux 2.6.28)" -This directory contains the file -.IR max_user_watches , -which can be used to limit the amount of kernel memory consumed by the -.I epoll -interface. -For further details, see -.BR epoll (7). -.TP -.I /proc/sys/fs/file\-max -This file defines -a system-wide limit on the number of open files for all processes. -System calls that fail when encountering this limit fail with the error -.BR ENFILE . -(See also -.BR setrlimit (2), -which can be used by a process to set the per-process limit, -.BR RLIMIT_NOFILE , -on the number of files it may open.) -If you get lots -of error messages in the kernel log about running out of file handles -(open file descriptions) -(look for "VFS: file\-max limit reached"), -try increasing this value: -.IP -.in +4n -.EX -echo 100000 > /proc/sys/fs/file\-max -.EE -.in -.IP -Privileged processes -.RB ( CAP_SYS_ADMIN ) -can override the -.I file\-max -limit. -.TP -.I /proc/sys/fs/file\-nr -This (read-only) file contains three numbers: -the number of allocated file handles -(i.e., the number of open file descriptions; see -.BR open (2)); -the number of free file handles; -and the maximum number of file handles (i.e., the same value as -.IR /proc/sys/fs/file\-max ). -If the number of allocated file handles is close to the -maximum, you should consider increasing the maximum. -Before Linux 2.6, -the kernel allocated file handles dynamically, -but it didn't free them again. -Instead the free file handles were kept in a list for reallocation; -the "free file handles" value indicates the size of that list. -A large number of free file handles indicates that there was -a past peak in the usage of open file handles. -Since Linux 2.6, the kernel does deallocate freed file handles, -and the "free file handles" value is always zero. -.TP -.IR /proc/sys/fs/inode\-max " (only present until Linux 2.2)" -This file contains the maximum number of in-memory inodes. -This value should be 3\[en]4 times larger -than the value in -.IR file\-max , -since \fIstdin\fP, \fIstdout\fP -and network sockets also need an inode to handle them. -When you regularly run out of inodes, you need to increase this value. -.IP -Starting with Linux 2.4, -there is no longer a static limit on the number of inodes, -and this file is removed. -.TP -.I /proc/sys/fs/inode\-nr -This file contains the first two values from -.IR inode\-state . -.TP -.I /proc/sys/fs/inode\-state -This file -contains seven numbers: -.IR nr_inodes , -.IR nr_free_inodes , -.IR preshrink , -and four dummy values (always zero). -.IP -.I nr_inodes -is the number of inodes the system has allocated. -.\" This can be slightly more than -.\" .I inode\-max -.\" because Linux allocates them one page full at a time. -.I nr_free_inodes -represents the number of free inodes. -.IP -.I preshrink -is nonzero when the -.I nr_inodes -> -.I inode\-max -and the system needs to prune the inode list instead of allocating more; -since Linux 2.4, this field is a dummy value (always zero). -.TP -.IR /proc/sys/fs/inotify " (since Linux 2.6.13)" -This directory contains files -.IR max_queued_events ", " max_user_instances ", and " max_user_watches , -that can be used to limit the amount of kernel memory consumed by the -.I inotify -interface. -For further details, see -.BR inotify (7). -.TP -.I /proc/sys/fs/lease\-break\-time -This file specifies the grace period that the kernel grants to a process -holding a file lease -.RB ( fcntl (2)) -after it has sent a signal to that process notifying it -that another process is waiting to open the file. -If the lease holder does not remove or downgrade the lease within -this grace period, the kernel forcibly breaks the lease. -.TP -.I /proc/sys/fs/leases\-enable -This file can be used to enable or disable file leases -.RB ( fcntl (2)) -on a system-wide basis. -If this file contains the value 0, leases are disabled. -A nonzero value enables leases. -.TP -.IR /proc/sys/fs/mount\-max " (since Linux 4.9)" -.\" commit d29216842a85c7970c536108e093963f02714498 -The value in this file specifies the maximum number of mounts that may exist -in a mount namespace. -The default value in this file is 100,000. -.TP -.IR /proc/sys/fs/mqueue " (since Linux 2.6.6)" -This directory contains files -.IR msg_max ", " msgsize_max ", and " queues_max , -controlling the resources used by POSIX message queues. -See -.BR mq_overview (7) -for details. -.TP -.IR /proc/sys/fs/nr_open " (since Linux 2.6.25)" -.\" commit 9cfe015aa424b3c003baba3841a60dd9b5ad319b -This file imposes a ceiling on the value to which the -.B RLIMIT_NOFILE -resource limit can be raised (see -.BR getrlimit (2)). -This ceiling is enforced for both unprivileged and privileged process. -The default value in this file is 1048576. -(Before Linux 2.6.25, the ceiling for -.B RLIMIT_NOFILE -was hard-coded to the same value.) -.TP -.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid -These files -allow you to change the value of the fixed UID and GID. -The default is 65534. -Some filesystems support only 16-bit UIDs and GIDs, although in Linux -UIDs and GIDs are 32 bits. -When one of these filesystems is mounted -with writes enabled, any UID or GID that would exceed 65535 is translated -to the overflow value before being written to disk. -.TP -.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)" -See -.BR pipe (7). -.TP -.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)" -See -.BR pipe (7). -.TP -.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)" -See -.BR pipe (7). -.TP -.IR /proc/sys/fs/protected_fifos " (since Linux 4.19)" -The value in this file is/can be set to one of the following: -.RS -.TP 4 -0 -Writing to FIFOs is unrestricted. -.TP -1 -Don't allow -.B O_CREAT -.BR open (2) -on FIFOs that the caller doesn't own in world-writable sticky directories, -unless the FIFO is owned by the owner of the directory. -.TP -2 -As for the value 1, -but the restriction also applies to group-writable sticky directories. -.RE -.IP -The intent of the above protections is to avoid unintentional writes to an -attacker-controlled FIFO when a program expected to create a regular file. -.TP -.IR /proc/sys/fs/protected_hardlinks " (since Linux 3.6)" -.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 -When the value in this file is 0, -no restrictions are placed on the creation of hard links -(i.e., this is the historical behavior before Linux 3.6). -When the value in this file is 1, -a hard link can be created to a target file -only if one of the following conditions is true: -.RS -.IP \[bu] 3 -The calling process has the -.B CAP_FOWNER -capability in its user namespace -and the file UID has a mapping in the namespace. -.IP \[bu] -The filesystem UID of the process creating the link matches -the owner (UID) of the target file -(as described in -.BR credentials (7), -a process's filesystem UID is normally the same as its effective UID). -.IP \[bu] -All of the following conditions are true: -.RS 4 -.IP \[bu] 3 -the target is a regular file; -.IP \[bu] -the target file does not have its set-user-ID mode bit enabled; -.IP \[bu] -the target file does not have both its set-group-ID and -group-executable mode bits enabled; and -.IP \[bu] -the caller has permission to read and write the target file -(either via the file's permissions mask or because it has -suitable capabilities). -.RE -.RE -.IP -The default value in this file is 0. -Setting the value to 1 -prevents a longstanding class of security issues caused by -hard-link-based time-of-check, time-of-use races, -most commonly seen in world-writable directories such as -.IR /tmp . -The common method of exploiting this flaw -is to cross privilege boundaries when following a given hard link -(i.e., a root process follows a hard link created by another user). -Additionally, on systems without separated partitions, -this stops unauthorized users from "pinning" vulnerable set-user-ID and -set-group-ID files against being upgraded by -the administrator, or linking to special files. -.TP -.IR /proc/sys/fs/protected_regular " (since Linux 4.19)" -The value in this file is/can be set to one of the following: -.RS -.TP 4 -0 -Writing to regular files is unrestricted. -.TP -1 -Don't allow -.B O_CREAT -.BR open (2) -on regular files that the caller doesn't own in -world-writable sticky directories, -unless the regular file is owned by the owner of the directory. -.TP -2 -As for the value 1, -but the restriction also applies to group-writable sticky directories. -.RE -.IP -The intent of the above protections is similar to -.IR protected_fifos , -but allows an application to -avoid writes to an attacker-controlled regular file, -where the application expected to create one. -.TP -.IR /proc/sys/fs/protected_symlinks " (since Linux 3.6)" -.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 -When the value in this file is 0, -no restrictions are placed on following symbolic links -(i.e., this is the historical behavior before Linux 3.6). -When the value in this file is 1, symbolic links are followed only -in the following circumstances: -.RS -.IP \[bu] 3 -the filesystem UID of the process following the link matches -the owner (UID) of the symbolic link -(as described in -.BR credentials (7), -a process's filesystem UID is normally the same as its effective UID); -.IP \[bu] -the link is not in a sticky world-writable directory; or -.IP \[bu] -the symbolic link and its parent directory have the same owner (UID) -.RE -.IP -A system call that fails to follow a symbolic link -because of the above restrictions returns the error -.B EACCES -in -.IR errno . -.IP -The default value in this file is 0. -Setting the value to 1 avoids a longstanding class of security issues -based on time-of-check, time-of-use races when accessing symbolic links. -.TP -.IR /proc/sys/fs/suid_dumpable " (since Linux 2.6.13)" -.\" The following is based on text from Documentation/sysctl/kernel.txt -The value in this file is assigned to a process's "dumpable" flag -in the circumstances described in -.BR prctl (2). -In effect, -the value in this file determines whether core dump files are -produced for set-user-ID or otherwise protected/tainted binaries. -The "dumpable" setting also affects the ownership of files in a process's -.IR /proc/ pid -directory, as described above. -.IP -Three different integer values can be specified: -.RS -.TP -\fI0\ (default)\fP -.\" In kernel source: SUID_DUMP_DISABLE -This provides the traditional (pre-Linux 2.6.13) behavior. -A core dump will not be produced for a process which has -changed credentials (by calling -.BR seteuid (2), -.BR setgid (2), -or similar, or by executing a set-user-ID or set-group-ID program) -or whose binary does not have read permission enabled. -.TP -\fI1\ ("debug")\fP -.\" In kernel source: SUID_DUMP_USER -All processes dump core when possible. -(Reasons why a process might nevertheless not dump core are described in -.BR core (5).) -The core dump is owned by the filesystem user ID of the dumping process -and no security is applied. -This is intended for system debugging situations only: -this mode is insecure because it allows unprivileged users to -examine the memory contents of privileged processes. -.TP -\fI2\ ("suidsafe")\fP -.\" In kernel source: SUID_DUMP_ROOT -Any binary which normally would not be dumped (see "0" above) -is dumped readable by root only. -This allows the user to remove the core dump file but not to read it. -For security reasons core dumps in this mode will not overwrite one -another or other files. -This mode is appropriate when administrators are -attempting to debug problems in a normal environment. -.IP -Additionally, since Linux 3.6, -.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 -.I /proc/sys/kernel/core_pattern -must either be an absolute pathname -or a pipe command, as detailed in -.BR core (5). -Warnings will be written to the kernel log if -.I core_pattern -does not follow these rules, and no core dump will be produced. -.\" 54b501992dd2a839e94e76aa392c392b55080ce8 -.RE -.IP -For details of the effect of a process's "dumpable" setting -on ptrace access mode checking, see -.BR ptrace (2). -.TP -.I /proc/sys/fs/super\-max -This file -controls the maximum number of superblocks, and -thus the maximum number of mounted filesystems the kernel -can have. -You need increase only -.I super\-max -if you need to mount more filesystems than the current value in -.I super\-max -allows you to. -.TP -.I /proc/sys/fs/super\-nr -This file -contains the number of filesystems currently mounted. -.TP -.I /proc/sys/kernel -This directory contains files controlling a range of kernel parameters, -as described below. -.TP -.I /proc/sys/kernel/acct -This file -contains three numbers: -.IR highwater , -.IR lowwater , -and -.IR frequency . -If BSD-style process accounting is enabled, these values control -its behavior. -If free space on filesystem where the log lives goes below -.I lowwater -percent, accounting suspends. -If free space gets above -.I highwater -percent, accounting resumes. -.I frequency -determines -how often the kernel checks the amount of free space (value is in -seconds). -Default values are 4, 2, and 30. -That is, suspend accounting if 2% or less space is free; resume it -if 4% or more space is free; consider information about amount of free space -valid for 30 seconds. -.TP -.IR /proc/sys/kernel/auto_msgmni " (Linux 2.6.27 to Linux 3.18)" -.\" commit 9eefe520c814f6f62c5d36a2ddcd3fb99dfdb30e (introduces feature) -.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 (rendered redundant) -From Linux 2.6.27 to Linux 3.18, -this file was used to control recomputing of the value in -.I /proc/sys/kernel/msgmni -upon the addition or removal of memory or upon IPC namespace creation/removal. -Echoing "1" into this file enabled -.I msgmni -automatic recomputing (and triggered a recomputation of -.I msgmni -based on the current amount of available memory and number of IPC namespaces). -Echoing "0" disabled automatic recomputing. -(Automatic recomputing was also disabled if a value was explicitly assigned to -.IR /proc/sys/kernel/msgmni .) -The default value in -.I auto_msgmni -was 1. -.IP -Since Linux 3.19, the content of this file has no effect (because -.I msgmni -.\" FIXME Must document the 3.19 'msgmni' changes. -defaults to near the maximum value possible), -and reads from this file always return the value "0". -.TP -.IR /proc/sys/kernel/cap_last_cap " (since Linux 3.2)" -See -.BR capabilities (7). -.TP -.IR /proc/sys/kernel/cap\-bound " (from Linux 2.2 to Linux 2.6.24)" -This file holds the value of the kernel -.I "capability bounding set" -(expressed as a signed decimal number). -This set is ANDed against the capabilities permitted to a process -during -.BR execve (2). -Starting with Linux 2.6.25, -the system-wide capability bounding set disappeared, -and was replaced by a per-thread bounding set; see -.BR capabilities (7). -.TP -.I /proc/sys/kernel/core_pattern -See -.BR core (5). -.TP -.I /proc/sys/kernel/core_pipe_limit -See -.BR core (5). -.TP -.I /proc/sys/kernel/core_uses_pid -See -.BR core (5). -.TP -.I /proc/sys/kernel/ctrl\-alt\-del -This file -controls the handling of Ctrl-Alt-Del from the keyboard. -When the value in this file is 0, Ctrl-Alt-Del is trapped and -sent to the -.BR init (1) -program to handle a graceful restart. -When the value is greater than zero, Linux's reaction to a Vulcan -Nerve Pinch (tm) will be an immediate reboot, without even -syncing its dirty buffers. -Note: when a program (like dosemu) has the keyboard in "raw" -mode, the Ctrl-Alt-Del is intercepted by the program before it -ever reaches the kernel tty layer, and it's up to the program -to decide what to do with it. -.TP -.IR /proc/sys/kernel/dmesg_restrict " (since Linux 2.6.37)" -The value in this file determines who can see kernel syslog contents. -A value of 0 in this file imposes no restrictions. -If the value is 1, only privileged users can read the kernel syslog. -(See -.BR syslog (2) -for more details.) -Since Linux 3.4, -.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 -only users with the -.B CAP_SYS_ADMIN -capability may change the value in this file. -.TP -.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname -can be used to set the NIS/YP domainname and the -hostname of your box in exactly the same way as the commands -.BR domainname (1) -and -.BR hostname (1), -that is: -.IP -.in +4n -.EX -.RB "#" " echo \[aq]darkstar\[aq] > /proc/sys/kernel/hostname" -.RB "#" " echo \[aq]mydomain\[aq] > /proc/sys/kernel/domainname" -.EE -.in -.IP -has the same effect as -.IP -.in +4n -.EX -.RB "#" " hostname \[aq]darkstar\[aq]" -.RB "#" " domainname \[aq]mydomain\[aq]" -.EE -.in -.IP -Note, however, that the classic darkstar.frop.org has the -hostname "darkstar" and DNS (Internet Domain Name Server) -domainname "frop.org", not to be confused with the NIS (Network -Information Service) or YP (Yellow Pages) domainname. -These two -domain names are in general different. -For a detailed discussion -see the -.BR hostname (1) -man page. -.TP -.I /proc/sys/kernel/hotplug -This file -contains the pathname for the hotplug policy agent. -The default value in this file is -.IR /sbin/hotplug . -.TP -.\" Removed in commit 87f504e5c78b910b0c1d6ffb89bc95e492322c84 (tglx/history.git) -.IR /proc/sys/kernel/htab\-reclaim " (before Linux 2.4.9.2)" -(PowerPC only) If this file is set to a nonzero value, -the PowerPC htab -.\" removed in commit 1b483a6a7b2998e9c98ad985d7494b9b725bd228, before Linux 2.6.28 -(see kernel file -.IR Documentation/powerpc/ppc_htab.txt ) -is pruned -each time the system hits the idle loop. -.TP -.I /proc/sys/kernel/keys/* -This directory contains various files that define parameters and limits -for the key-management facility. -These files are described in -.BR keyrings (7). -.TP -.IR /proc/sys/kernel/kptr_restrict " (since Linux 2.6.38)" -.\" 455cd5ab305c90ffc422dd2e0fb634730942b257 -The value in this file determines whether kernel addresses are exposed via -.I /proc -files and other interfaces. -A value of 0 in this file imposes no restrictions. -If the value is 1, kernel pointers printed using the -.I %pK -format specifier will be replaced with zeros unless the user has the -.B CAP_SYSLOG -capability. -If the value is 2, kernel pointers printed using the -.I %pK -format specifier will be replaced with zeros regardless -of the user's capabilities. -The initial default value for this file was 1, -but the default was changed -.\" commit 411f05f123cbd7f8aa1edcae86970755a6e2a9d9 -to 0 in Linux 2.6.39. -Since Linux 3.4, -.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 -only users with the -.B CAP_SYS_ADMIN -capability can change the value in this file. -.TP -.I /proc/sys/kernel/l2cr -(PowerPC only) This file -contains a flag that controls the L2 cache of G3 processor -boards. -If 0, the cache is disabled. -Enabled if nonzero. -.TP -.I /proc/sys/kernel/modprobe -This file contains the pathname for the kernel module loader. -The default value is -.IR /sbin/modprobe . -The file is present only if the kernel is built with the -.B CONFIG_MODULES -.RB ( CONFIG_KMOD -in Linux 2.6.26 and earlier) -option enabled. -It is described by the Linux kernel source file -.I Documentation/kmod.txt -(present only in Linux 2.4 and earlier). -.TP -.IR /proc/sys/kernel/modules_disabled " (since Linux 2.6.31)" -.\" 3d43321b7015387cfebbe26436d0e9d299162ea1 -.\" From Documentation/sysctl/kernel.txt -A toggle value indicating if modules are allowed to be loaded -in an otherwise modular kernel. -This toggle defaults to off (0), but can be set true (1). -Once true, modules can be neither loaded nor unloaded, -and the toggle cannot be set back to false. -The file is present only if the kernel is built with the -.B CONFIG_MODULES -option enabled. -.TP -.IR /proc/sys/kernel/msgmax " (since Linux 2.2)" -This file defines -a system-wide limit specifying the maximum number of bytes in -a single message written on a System V message queue. -.TP -.IR /proc/sys/kernel/msgmni " (since Linux 2.4)" -This file defines the system-wide limit on the number of -message queue identifiers. -See also -.IR /proc/sys/kernel/auto_msgmni . -.TP -.IR /proc/sys/kernel/msgmnb " (since Linux 2.2)" -This file defines a system-wide parameter used to initialize the -.I msg_qbytes -setting for subsequently created message queues. -The -.I msg_qbytes -setting specifies the maximum number of bytes that may be written to the -message queue. -.TP -.IR /proc/sys/kernel/ngroups_max " (since Linux 2.6.4)" -This is a read-only file that displays the upper limit on the -number of a process's group memberships. -.TP -.IR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" -See -.BR pid_namespaces (7). -.TP -.IR /proc/sys/kernel/ostype " and " /proc/sys/kernel/osrelease -These files -give substrings of -.IR /proc/version . -.TP -.IR /proc/sys/kernel/overflowgid " and " /proc/sys/kernel/overflowuid -These files duplicate the files -.I /proc/sys/fs/overflowgid -and -.IR /proc/sys/fs/overflowuid . -.TP -.I /proc/sys/kernel/panic -This file gives read/write access to the kernel variable -.IR panic_timeout . -If this is zero, the kernel will loop on a panic; if nonzero, -it indicates that the kernel should autoreboot after this number -of seconds. -When you use the -software watchdog device driver, the recommended setting is 60. -.TP -.IR /proc/sys/kernel/panic_on_oops " (since Linux 2.5.68)" -This file controls the kernel's behavior when an oops -or BUG is encountered. -If this file contains 0, then the system -tries to continue operation. -If it contains 1, then the system -delays a few seconds (to give klogd time to record the oops output) -and then panics. -If the -.I /proc/sys/kernel/panic -file is also nonzero, then the machine will be rebooted. -.TP -.IR /proc/sys/kernel/pid_max " (since Linux 2.5.34)" -This file specifies the value at which PIDs wrap around -(i.e., the value in this file is one greater than the maximum PID). -PIDs greater than this value are not allocated; -thus, the value in this file also acts as a system-wide limit -on the total number of processes and threads. -The default value for this file, 32768, -results in the same range of PIDs as on earlier kernels. -On 32-bit platforms, 32768 is the maximum value for -.IR pid_max . -On 64-bit systems, -.I pid_max -can be set to any value up to 2\[ha]22 -.RB ( PID_MAX_LIMIT , -approximately 4 million). -.\" Prior to Linux 2.6.10, pid_max could also be raised above 32768 on 32-bit -.\" platforms, but this broke /proc/[pid] -.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2 -.TP -.IR /proc/sys/kernel/powersave\-nap " (PowerPC only)" -This file contains a flag. -If set, Linux-PPC will use the "nap" mode of -powersaving, -otherwise the "doze" mode will be used. -.TP -.I /proc/sys/kernel/printk -See -.BR syslog (2). -.TP -.IR /proc/sys/kernel/pty " (since Linux 2.6.4)" -This directory contains two files relating to the number of UNIX 98 -pseudoterminals (see -.BR pts (4)) -on the system. -.TP -.I /proc/sys/kernel/pty/max -This file defines the maximum number of pseudoterminals. -.\" FIXME Document /proc/sys/kernel/pty/reserve -.\" New in Linux 3.3 -.\" commit e9aba5158a80098447ff207a452a3418ae7ee386 -.TP -.I /proc/sys/kernel/pty/nr -This read-only file -indicates how many pseudoterminals are currently in use. -.TP -.I /proc/sys/kernel/random -This directory -contains various parameters controlling the operation of the file -.IR /dev/random . -See -.BR random (4) -for further information. -.TP -.IR /proc/sys/kernel/random/uuid " (since Linux 2.4)" -Each read from this read-only file returns a randomly generated 128-bit UUID, -as a string in the standard UUID format. -.TP -.IR /proc/sys/kernel/randomize_va_space " (since Linux 2.6.12)" -.\" Some further details can be found in Documentation/sysctl/kernel.txt -Select the address space layout randomization (ASLR) policy for the system -(on architectures that support ASLR). -Three values are supported for this file: -.RS -.TP -.B 0 -Turn ASLR off. -This is the default for architectures that don't support ASLR, -and when the kernel is booted with the -.I norandmaps -parameter. -.TP -.B 1 -Make the addresses of -.BR mmap (2) -allocations, the stack, and the VDSO page randomized. -Among other things, this means that shared libraries will be -loaded at randomized addresses. -The text segment of PIE-linked binaries will also be loaded -at a randomized address. -This value is the default if the kernel was configured with -.BR CONFIG_COMPAT_BRK . -.TP -.B 2 -(Since Linux 2.6.25) -.\" commit c1d171a002942ea2d93b4fbd0c9583c56fce0772 -Also support heap randomization. -This value is the default if the kernel was not configured with -.BR CONFIG_COMPAT_BRK . -.RE -.TP -.I /proc/sys/kernel/real\-root\-dev -This file is documented in the Linux kernel source file -.I Documentation/admin\-guide/initrd.rst -.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 -(or -.I Documentation/initrd.txt -before Linux 4.10). -.TP -.IR /proc/sys/kernel/reboot\-cmd " (Sparc only)" -This file seems to be a way to give an argument to the SPARC -ROM/Flash boot loader. -Maybe to tell it what to do after -rebooting? -.TP -.I /proc/sys/kernel/rtsig\-max -(Up to and including Linux 2.6.7; see -.BR setrlimit (2)) -This file can be used to tune the maximum number -of POSIX real-time (queued) signals that can be outstanding -in the system. -.TP -.I /proc/sys/kernel/rtsig\-nr -(Up to and including Linux 2.6.7.) -This file shows the number of POSIX real-time signals currently queued. -.TP -.IR /proc/ pid /sched_autogroup_enabled " (since Linux 2.6.38)" -.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a -See -.BR sched (7). -.TP -.IR /proc/sys/kernel/sched_child_runs_first " (since Linux 2.6.23)" -If this file contains the value zero, then, after a -.BR fork (2), -the parent is first scheduled on the CPU. -If the file contains a nonzero value, -then the child is scheduled first on the CPU. -(Of course, on a multiprocessor system, -the parent and the child might both immediately be scheduled on a CPU.) -.TP -.IR /proc/sys/kernel/sched_rr_timeslice_ms " (since Linux 3.9)" -See -.BR sched_rr_get_interval (2). -.TP -.IR /proc/sys/kernel/sched_rt_period_us " (since Linux 2.6.25)" -See -.BR sched (7). -.TP -.IR /proc/sys/kernel/sched_rt_runtime_us " (since Linux 2.6.25)" -See -.BR sched (7). -.TP -.IR /proc/sys/kernel/seccomp " (since Linux 4.14)" -.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af -This directory provides additional seccomp information and -configuration. -See -.BR seccomp (2) -for further details. -.TP -.IR /proc/sys/kernel/sem " (since Linux 2.4)" -This file contains 4 numbers defining limits for System V IPC semaphores. -These fields are, in order: -.RS -.TP -SEMMSL -The maximum semaphores per semaphore set. -.TP -SEMMNS -A system-wide limit on the number of semaphores in all semaphore sets. -.TP -SEMOPM -The maximum number of operations that may be specified in a -.BR semop (2) -call. -.TP -SEMMNI -A system-wide limit on the maximum number of semaphore identifiers. -.RE -.TP -.I /proc/sys/kernel/sg\-big\-buff -This file -shows the size of the generic SCSI device (sg) buffer. -You can't tune it just yet, but you could change it at -compile time by editing -.I include/scsi/sg.h -and changing -the value of -.BR SG_BIG_BUFF . -However, there shouldn't be any reason to change this value. -.TP -.IR /proc/sys/kernel/shm_rmid_forced " (since Linux 3.1)" -.\" commit b34a6b1da371ed8af1221459a18c67970f7e3d53 -.\" See also Documentation/sysctl/kernel.txt -If this file is set to 1, all System V shared memory segments will -be marked for destruction as soon as the number of attached processes -falls to zero; -in other words, it is no longer possible to create shared memory segments -that exist independently of any attached process. -.IP -The effect is as though a -.BR shmctl (2) -.B IPC_RMID -is performed on all existing segments as well as all segments -created in the future (until this file is reset to 0). -Note that existing segments that are attached to no process will be -immediately destroyed when this file is set to 1. -Setting this option will also destroy segments that were created, -but never attached, -upon termination of the process that created the segment with -.BR shmget (2). -.IP -Setting this file to 1 provides a way of ensuring that -all System V shared memory segments are counted against the -resource usage and resource limits (see the description of -.B RLIMIT_AS -in -.BR getrlimit (2)) -of at least one process. -.IP -Because setting this file to 1 produces behavior that is nonstandard -and could also break existing applications, -the default value in this file is 0. -Set this file to 1 only if you have a good understanding -of the semantics of the applications using -System V shared memory on your system. -.TP -.IR /proc/sys/kernel/shmall " (since Linux 2.2)" -This file -contains the system-wide limit on the total number of pages of -System V shared memory. -.TP -.IR /proc/sys/kernel/shmmax " (since Linux 2.2)" -This file -can be used to query and set the run-time limit -on the maximum (System V IPC) shared memory segment size that can be -created. -Shared memory segments up to 1 GB are now supported in the -kernel. -This value defaults to -.BR SHMMAX . -.TP -.IR /proc/sys/kernel/shmmni " (since Linux 2.4)" -This file -specifies the system-wide maximum number of System V shared memory -segments that can be created. -.TP -.IR /proc/sys/kernel/sysctl_writes_strict " (since Linux 3.16)" -.\" commit f88083005ab319abba5d0b2e4e997558245493c8 -.\" commit 2ca9bb456ada8bcbdc8f77f8fc78207653bbaa92 -.\" commit f4aacea2f5d1a5f7e3154e967d70cf3f711bcd61 -.\" commit 24fe831c17ab8149413874f2fd4e5c8a41fcd294 -The value in this file determines how the file offset affects -the behavior of updating entries in files under -.IR /proc/sys . -The file has three possible values: -.RS -.TP 4 -\-1 -This provides legacy handling, with no printk warnings. -Each -.BR write (2) -must fully contain the value to be written, -and multiple writes on the same file descriptor -will overwrite the entire value, regardless of the file position. -.TP -0 -(default) This provides the same behavior as for \-1, -but printk warnings are written for processes that -perform writes when the file offset is not 0. -.TP -1 -Respect the file offset when writing strings into -.I /proc/sys -files. -Multiple writes will -.I append -to the value buffer. -Anything written beyond the maximum length -of the value buffer will be ignored. -Writes to numeric -.I /proc/sys -entries must always be at file offset 0 and the value must be -fully contained in the buffer provided to -.BR write (2). -.\" FIXME . -.\" With /proc/sys/kernel/sysctl_writes_strict==1, writes at an -.\" offset other than 0 do not generate an error. Instead, the -.\" write() succeeds, but the file is left unmodified. -.\" This is surprising. The behavior may change in the future. -.\" See thread.gmane.org/gmane.linux.man/9197 -.\" From: Michael Kerrisk (man-pages -.\" Subject: sysctl_writes_strict documentation + an oddity? -.\" Newsgroups: gmane.linux.man, gmane.linux.kernel -.\" Date: 2015-05-09 08:54:11 GMT -.RE -.TP -.I /proc/sys/kernel/sysrq -This file controls the functions allowed to be invoked by the SysRq key. -By default, -the file contains 1 meaning that every possible SysRq request is allowed -(in older kernel versions, SysRq was disabled by default, -and you were required to specifically enable it at run-time, -but this is not the case any more). -Possible values in this file are: -.RS -.TP 5 -0 -Disable sysrq completely -.TP -1 -Enable all functions of sysrq -.TP -> 1 -Bit mask of allowed sysrq functions, as follows: -.PD 0 -.RS -.TP 5 -\ \ 2 -Enable control of console logging level -.TP -\ \ 4 -Enable control of keyboard (SAK, unraw) -.TP -\ \ 8 -Enable debugging dumps of processes etc. -.TP -\ 16 -Enable sync command -.TP -\ 32 -Enable remount read-only -.TP -\ 64 -Enable signaling of processes (term, kill, oom-kill) -.TP -128 -Allow reboot/poweroff -.TP -256 -Allow nicing of all real-time tasks -.RE -.PD -.RE -.IP -This file is present only if the -.B CONFIG_MAGIC_SYSRQ -kernel configuration option is enabled. -For further details see the Linux kernel source file -.I Documentation/admin\-guide/sysrq.rst -.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 -(or -.I Documentation/sysrq.txt -before Linux 4.10). -.TP -.I /proc/sys/kernel/version -This file contains a string such as: -.IP -.in +4n -.EX -#5 Wed Feb 25 21:49:24 MET 1998 -.EE -.in -.IP -The "#5" means that -this is the fifth kernel built from this source base and the -date following it indicates the time the kernel was built. -.TP -.IR /proc/sys/kernel/threads\-max " (since Linux 2.3.11)" -.\" The following is based on Documentation/sysctl/kernel.txt -This file specifies the system-wide limit on the number of -threads (tasks) that can be created on the system. -.IP -Since Linux 4.1, -.\" commit 230633d109e35b0a24277498e773edeb79b4a331 -the value that can be written to -.I threads\-max -is bounded. -The minimum value that can be written is 20. -The maximum value that can be written is given by the -constant -.B FUTEX_TID_MASK -(0x3fffffff). -If a value outside of this range is written to -.IR threads\-max , -the error -.B EINVAL -occurs. -.IP -The value written is checked against the available RAM pages. -If the thread structures would occupy too much (more than 1/8th) -of the available RAM pages, -.I threads\-max -is reduced accordingly. -.TP -.IR /proc/sys/kernel/yama/ptrace_scope " (since Linux 3.5)" -See -.BR ptrace (2). -.TP -.IR /proc/sys/kernel/zero\-paged " (PowerPC only)" -This file -contains a flag. -When enabled (nonzero), Linux-PPC will pre-zero pages in -the idle loop, possibly speeding up get_free_pages. -.TP -.I /proc/sys/net -This directory contains networking stuff. -Explanations for some of the files under this directory can be found in -.BR tcp (7) -and -.BR ip (7). -.TP -.I /proc/sys/net/core/bpf_jit_enable -See -.BR bpf (2). -.TP -.I /proc/sys/net/core/somaxconn -This file defines a ceiling value for the -.I backlog -argument of -.BR listen (2); -see the -.BR listen (2) -manual page for details. -.TP -.I /proc/sys/proc -This directory may be empty. -.TP -.I /proc/sys/sunrpc -This directory supports Sun remote procedure call for network filesystem -(NFS). -On some systems, it is not present. -.TP -.IR /proc/sys/user " (since Linux 4.9)" -See -.BR namespaces (7). -.TP -.I /proc/sys/vm -This directory contains files for memory management tuning, buffer, and -cache management. -.TP -.IR /proc/sys/vm/admin_reserve_kbytes " (since Linux 3.10)" -.\" commit 4eeab4f5580d11bffedc697684b91b0bca0d5009 -This file defines the amount of free memory (in KiB) on the system that -should be reserved for users with the capability -.BR CAP_SYS_ADMIN . -.IP -The default value in this file is the minimum of [3% of free pages, 8MiB] -expressed as KiB. -The default is intended to provide enough for the superuser -to log in and kill a process, if necessary, -under the default overcommit 'guess' mode (i.e., 0 in -.IR /proc/sys/vm/overcommit_memory ). -.IP -Systems running in "overcommit never" mode (i.e., 2 in -.IR /proc/sys/vm/overcommit_memory ) -should increase the value in this file to account -for the full virtual memory size of the programs used to recover (e.g., -.BR login (1) -.BR ssh (1), -and -.BR top (1)) -Otherwise, the superuser may not be able to log in to recover the system. -For example, on x86-64 a suitable value is 131072 (128MiB reserved). -.IP -Changing the value in this file takes effect whenever -an application requests memory. -.TP -.IR /proc/sys/vm/compact_memory " (since Linux 2.6.35)" -When 1 is written to this file, all zones are compacted such that free -memory is available in contiguous blocks where possible. -The effect of this action can be seen by examining -.IR /proc/buddyinfo . -.IP -Present only if the kernel was configured with -.BR CONFIG_COMPACTION . -.TP -.IR /proc/sys/vm/drop_caches " (since Linux 2.6.16)" -Writing to this file causes the kernel to drop clean caches, dentries, and -inodes from memory, causing that memory to become free. -This can be useful for memory management testing and -performing reproducible filesystem benchmarks. -Because writing to this file causes the benefits of caching to be lost, -it can degrade overall system performance. -.IP -To free pagecache, use: -.IP -.in +4n -.EX -echo 1 > /proc/sys/vm/drop_caches -.EE -.in -.IP -To free dentries and inodes, use: -.IP -.in +4n -.EX -echo 2 > /proc/sys/vm/drop_caches -.EE -.in -.IP -To free pagecache, dentries, and inodes, use: -.IP -.in +4n -.EX -echo 3 > /proc/sys/vm/drop_caches -.EE -.in -.IP -Because writing to this file is a nondestructive operation and dirty objects -are not freeable, the -user should run -.BR sync (1) -first. -.TP -.IR /proc/sys/vm/sysctl_hugetlb_shm_group " (since Linux 2.6.7)" -This writable file contains a group ID that is allowed -to allocate memory using huge pages. -If a process has a filesystem group ID or any supplementary group ID that -matches this group ID, -then it can make huge-page allocations without holding the -.B CAP_IPC_LOCK -capability; see -.BR memfd_create (2), -.BR mmap (2), -and -.BR shmget (2). -.TP -.IR /proc/sys/vm/legacy_va_layout " (since Linux 2.6.9)" -.\" The following is from Documentation/filesystems/proc.txt -If nonzero, this disables the new 32-bit memory-mapping layout; -the kernel will use the legacy (2.4) layout for all processes. -.TP -.IR /proc/sys/vm/memory_failure_early_kill " (since Linux 2.6.32)" -.\" The following is based on the text in Documentation/sysctl/vm.txt -Control how to kill processes when an uncorrected memory error -(typically a 2-bit error in a memory module) -that cannot be handled by the kernel -is detected in the background by hardware. -In some cases (like the page still having a valid copy on disk), -the kernel will handle the failure -transparently without affecting any applications. -But if there is no other up-to-date copy of the data, -it will kill processes to prevent any data corruptions from propagating. -.IP -The file has one of the following values: -.RS -.TP -.B 1 -Kill all processes that have the corrupted-and-not-reloadable page mapped -as soon as the corruption is detected. -Note that this is not supported for a few types of pages, -such as kernel internally -allocated data or the swap cache, but works for the majority of user pages. -.TP -.B 0 -Unmap the corrupted page from all processes and kill a process -only if it tries to access the page. -.RE -.IP -The kill is performed using a -.B SIGBUS -signal with -.I si_code -set to -.BR BUS_MCEERR_AO . -Processes can handle this if they want to; see -.BR sigaction (2) -for more details. -.IP -This feature is active only on architectures/platforms with advanced machine -check handling and depends on the hardware capabilities. -.IP -Applications can override the -.I memory_failure_early_kill -setting individually with the -.BR prctl (2) -.B PR_MCE_KILL -operation. -.IP -Present only if the kernel was configured with -.BR CONFIG_MEMORY_FAILURE . -.TP -.IR /proc/sys/vm/memory_failure_recovery " (since Linux 2.6.32)" -.\" The following is based on the text in Documentation/sysctl/vm.txt -Enable memory failure recovery (when supported by the platform). -.RS -.TP -.B 1 -Attempt recovery. -.TP -.B 0 -Always panic on a memory failure. -.RE -.IP -Present only if the kernel was configured with -.BR CONFIG_MEMORY_FAILURE . -.TP -.IR /proc/sys/vm/oom_dump_tasks " (since Linux 2.6.25)" -.\" The following is from Documentation/sysctl/vm.txt -Enables a system-wide task dump (excluding kernel threads) to be -produced when the kernel performs an OOM-killing. -The dump includes the following information -for each task (thread, process): -thread ID, real user ID, thread group ID (process ID), -virtual memory size, resident set size, -the CPU that the task is scheduled on, -oom_adj score (see the description of -.IR /proc/ pid /oom_adj ), -and command name. -This is helpful to determine why the OOM-killer was invoked -and to identify the rogue task that caused it. -.IP -If this contains the value zero, this information is suppressed. -On very large systems with thousands of tasks, -it may not be feasible to dump the memory state information for each one. -Such systems should not be forced to incur a performance penalty in -OOM situations when the information may not be desired. -.IP -If this is set to nonzero, this information is shown whenever the -OOM-killer actually kills a memory-hogging task. -.IP -The default value is 0. -.TP -.IR /proc/sys/vm/oom_kill_allocating_task " (since Linux 2.6.24)" -.\" The following is from Documentation/sysctl/vm.txt -This enables or disables killing the OOM-triggering task in -out-of-memory situations. -.IP -If this is set to zero, the OOM-killer will scan through the entire -tasklist and select a task based on heuristics to kill. -This normally selects a rogue memory-hogging task that -frees up a large amount of memory when killed. -.IP -If this is set to nonzero, the OOM-killer simply kills the task that -triggered the out-of-memory condition. -This avoids a possibly expensive tasklist scan. -.IP -If -.I /proc/sys/vm/panic_on_oom -is nonzero, it takes precedence over whatever value is used in -.IR /proc/sys/vm/oom_kill_allocating_task . -.IP -The default value is 0. -.TP -.IR /proc/sys/vm/overcommit_kbytes " (since Linux 3.14)" -.\" commit 49f0ce5f92321cdcf741e35f385669a421013cb7 -This writable file provides an alternative to -.I /proc/sys/vm/overcommit_ratio -for controlling the -.I CommitLimit -when -.I /proc/sys/vm/overcommit_memory -has the value 2. -It allows the amount of memory overcommitting to be specified as -an absolute value (in kB), -rather than as a percentage, as is done with -.IR overcommit_ratio . -This allows for finer-grained control of -.I CommitLimit -on systems with extremely large memory sizes. -.IP -Only one of -.I overcommit_kbytes -or -.I overcommit_ratio -can have an effect: -if -.I overcommit_kbytes -has a nonzero value, then it is used to calculate -.IR CommitLimit , -otherwise -.I overcommit_ratio -is used. -Writing a value to either of these files causes the -value in the other file to be set to zero. -.TP -.I /proc/sys/vm/overcommit_memory -This file contains the kernel virtual memory accounting mode. -Values are: -.RS -.IP -0: heuristic overcommit (this is the default) -.br -1: always overcommit, never check -.br -2: always check, never overcommit -.RE -.IP -In mode 0, calls of -.BR mmap (2) -with -.B MAP_NORESERVE -are not checked, and the default check is very weak, -leading to the risk of getting a process "OOM-killed". -.IP -In mode 1, the kernel pretends there is always enough memory, -until memory actually runs out. -One use case for this mode is scientific computing applications -that employ large sparse arrays. -Before Linux 2.6.0, any nonzero value implies mode 1. -.IP -In mode 2 (available since Linux 2.6), the total virtual address space -that can be allocated -.RI ( CommitLimit -in -.IR /proc/meminfo ) -is calculated as -.IP -.in +4n -.EX -CommitLimit = (total_RAM \- total_huge_TLB) * - overcommit_ratio / 100 + total_swap -.EE -.in -.IP -where: -.RS -.IP \[bu] 3 -.I total_RAM -is the total amount of RAM on the system; -.IP \[bu] -.I total_huge_TLB -is the amount of memory set aside for huge pages; -.IP \[bu] -.I overcommit_ratio -is the value in -.IR /proc/sys/vm/overcommit_ratio ; -and -.IP \[bu] -.I total_swap -is the amount of swap space. -.RE -.IP -For example, on a system with 16 GB of physical RAM, 16 GB -of swap, no space dedicated to huge pages, and an -.I overcommit_ratio -of 50, this formula yields a -.I CommitLimit -of 24 GB. -.IP -Since Linux 3.14, if the value in -.I /proc/sys/vm/overcommit_kbytes -is nonzero, then -.I CommitLimit -is instead calculated as: -.IP -.in +4n -.EX -CommitLimit = overcommit_kbytes + total_swap -.EE -.in -.IP -See also the description of -.I /proc/sys/vm/admin_reserve_kbytes -and -.IR /proc/sys/vm/user_reserve_kbytes . -.TP -.IR /proc/sys/vm/overcommit_ratio " (since Linux 2.6.0)" -This writable file defines a percentage by which memory -can be overcommitted. -The default value in the file is 50. -See the description of -.IR /proc/sys/vm/overcommit_memory . -.TP -.IR /proc/sys/vm/panic_on_oom " (since Linux 2.6.18)" -.\" The following is adapted from Documentation/sysctl/vm.txt -This enables or disables a kernel panic in -an out-of-memory situation. -.IP -If this file is set to the value 0, -the kernel's OOM-killer will kill some rogue process. -Usually, the OOM-killer is able to kill a rogue process and the -system will survive. -.IP -If this file is set to the value 1, -then the kernel normally panics when out-of-memory happens. -However, if a process limits allocations to certain nodes -using memory policies -.RB ( mbind (2) -.BR MPOL_BIND ) -or cpusets -.RB ( cpuset (7)) -and those nodes reach memory exhaustion status, -one process may be killed by the OOM-killer. -No panic occurs in this case: -because other nodes' memory may be free, -this means the system as a whole may not have reached -an out-of-memory situation yet. -.IP -If this file is set to the value 2, -the kernel always panics when an out-of-memory condition occurs. -.IP -The default value is 0. -1 and 2 are for failover of clustering. -Select either according to your policy of failover. -.TP -.I /proc/sys/vm/swappiness -.\" The following is from Documentation/sysctl/vm.txt -The value in this file controls how aggressively the kernel will swap -memory pages. -Higher values increase aggressiveness, lower values -decrease aggressiveness. -The default value is 60. -.TP -.IR /proc/sys/vm/user_reserve_kbytes " (since Linux 3.10)" -.\" commit c9b1d0981fcce3d9976d7b7a56e4e0503bc610dd -Specifies an amount of memory (in KiB) to reserve for user processes. -This is intended to prevent a user from starting a single memory hogging -process, such that they cannot recover (kill the hog). -The value in this file has an effect only when -.I /proc/sys/vm/overcommit_memory -is set to 2 ("overcommit never" mode). -In this case, the system reserves an amount of memory that is the minimum -of [3% of current process size, -.IR user_reserve_kbytes ]. -.IP -The default value in this file is the minimum of [3% of free pages, 128MiB] -expressed as KiB. -.IP -If the value in this file is set to zero, -then a user will be allowed to allocate all free memory with a single process -(minus the amount reserved by -.IR /proc/sys/vm/admin_reserve_kbytes ). -Any subsequent attempts to execute a command will result in -"fork: Cannot allocate memory". -.IP -Changing the value in this file takes effect whenever -an application requests memory. -.TP -.IR /proc/sys/vm/unprivileged_userfaultfd " (since Linux 5.2)" -.\" cefdca0a86be517bc390fc4541e3674b8e7803b0 -This (writable) file exposes a flag that controls whether -unprivileged processes are allowed to employ -.BR userfaultfd (2). -If this file has the value 1, then unprivileged processes may use -.BR userfaultfd (2). -If this file has the value 0, then only processes that have the -.B CAP_SYS_PTRACE -capability may employ -.BR userfaultfd (2). -The default value in this file is 1. -.TP -.IR /proc/sysrq\-trigger " (since Linux 2.4.21)" -Writing a character to this file triggers the same SysRq function as -typing ALT-SysRq- (see the description of -.IR /proc/sys/kernel/sysrq ). -This file is normally writable only by -.IR root . -For further details see the Linux kernel source file -.I Documentation/admin\-guide/sysrq.rst -.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 -(or -.I Documentation/sysrq.txt -before Linux 4.10). -.TP -.I /proc/sysvipc -Subdirectory containing the pseudo-files -.IR msg ", " sem " and " shm "." -These files list the System V Interprocess Communication (IPC) objects -(respectively: message queues, semaphores, and shared memory) -that currently exist on the system, -providing similar information to that available via -.BR ipcs (1). -These files have headers and are formatted (one IPC object per line) -for easy understanding. -.BR sysvipc (7) -provides further background on the information shown by these files. -.TP -.IR /proc/thread\-self " (since Linux 3.17)" -.\" commit 0097875bd41528922fb3bb5f348c53f17e00e2fd -This directory refers to the thread accessing the -.I /proc -filesystem, -and is identical to the -.IR /proc/self/task/ tid -directory named by the process thread ID -.RI ( tid ) -of the same thread. -.TP -.IR /proc/timer_list " (since Linux 2.6.21)" -.\" commit 289f480af87e45f7a6de6ba9b4c061c2e259fe98 -This read-only file exposes a list of all currently pending -(high-resolution) timers, -all clock-event sources, and their parameters in a human-readable form. -.TP -.IR /proc/timer_stats " (from Linux 2.6.21 until Linux 4.10)" -.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221 -.\" Date: Fri Feb 16 01:28:13 2007 -0800 -.\" Text largely derived from Documentation/timers/timer_stats.txt -.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1 -.\" Date: Wed Feb 8 11:26:59 2017 -0800 -This is a debugging facility to make timer (ab)use in a Linux -system visible to kernel and user-space developers. -It can be used by kernel and user-space developers to verify that -their code does not make undue use of timers. -The goal is to avoid unnecessary wakeups, -thereby optimizing power consumption. -.IP -If enabled in the kernel -.RB ( CONFIG_TIMER_STATS ), -but not used, -it has almost zero run-time overhead and a relatively small -data-structure overhead. -Even if collection is enabled at run time, overhead is low: -all the locking is per-CPU and lookup is hashed. -.IP -The -.I /proc/timer_stats -file is used both to control sampling facility and to read out the -sampled information. -.IP -The -.I timer_stats -functionality is inactive on bootup. -A sampling period can be started using the following command: -.IP -.in +4n -.EX -# echo 1 > /proc/timer_stats -.EE -.in -.IP -The following command stops a sampling period: -.IP -.in +4n -.EX -# echo 0 > /proc/timer_stats -.EE -.in -.IP -The statistics can be retrieved by: -.IP -.in +4n -.EX -$ cat /proc/timer_stats -.EE -.in -.IP -While sampling is enabled, each readout from -.I /proc/timer_stats -will see -newly updated statistics. -Once sampling is disabled, the sampled information -is kept until a new sample period is started. -This allows multiple readouts. -.IP -Sample output from -.IR /proc/timer_stats : -.IP -.in +4n -.EX -.RB $ " cat /proc/timer_stats" -Timer Stats Version: v0.3 -Sample period: 1.764 s -Collection: active - 255, 0 swapper/3 hrtimer_start_range_ns (tick_sched_timer) - 71, 0 swapper/1 hrtimer_start_range_ns (tick_sched_timer) - 58, 0 swapper/0 hrtimer_start_range_ns (tick_sched_timer) - 4, 1694 gnome\-shell mod_delayed_work_on (delayed_work_timer_fn) - 17, 7 rcu_sched rcu_gp_kthread (process_timeout) -\&... - 1, 4911 kworker/u16:0 mod_delayed_work_on (delayed_work_timer_fn) - 1D, 2522 kworker/0:0 queue_delayed_work_on (delayed_work_timer_fn) -1029 total events, 583.333 events/sec -.EE -.in -.IP -The output columns are: -.RS -.IP [1] 5 -a count of the number of events, -optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq] -.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers -if this is a deferrable timer; -.IP [2] -the PID of the process that initialized the timer; -.IP [3] -the name of the process that initialized the timer; -.IP [4] -the function where the timer was initialized; and -(in parentheses) -the callback function that is associated with the timer. -.RE -.IP -During the Linux 4.11 development cycle, -this file was removed because of security concerns, -as it exposes information across namespaces. -Furthermore, it is possible to obtain -the same information via in-kernel tracing facilities such as ftrace. -.TP -.I /proc/tty -Subdirectory containing the pseudo-files and subdirectories for -tty drivers and line disciplines. -.TP -.I /proc/uptime -This file contains two numbers (values in seconds): the uptime of the -system (including time spent in suspend) and the amount of time spent -in the idle process. -.TP -.I /proc/version -This string identifies the kernel version that is currently running. -It includes the contents of -.IR /proc/sys/kernel/ostype , -.IR /proc/sys/kernel/osrelease , -and -.IR /proc/sys/kernel/version . -For example: -.IP -.in +4n -.EX -Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 -.EE -.in -.\" FIXME 2.6.13 seems to have /proc/vmcore implemented; document this -.\" See Documentation/kdump/kdump.txt -.\" commit 666bfddbe8b8fd4fd44617d6c55193d5ac7edb29 -.\" Needs CONFIG_VMCORE -.\" -.TP -.IR /proc/vmstat " (since Linux 2.6.0)" -This file displays various virtual memory statistics. -Each line of this file contains a single name-value pair, -delimited by white space. -Some lines are present only if the kernel was configured with -suitable options. -(In some cases, the options required for particular files have changed -across kernel versions, so they are not listed here. -Details can be found by consulting the kernel source code.) -The following fields may be present: -.\" FIXME We need explanations for each of the following fields... -.RS -.TP -.IR nr_free_pages " (since Linux 2.6.31)" -.\" commit d23ad42324cc4378132e51f2fc5c9ba6cbe75182 -.TP -.IR nr_alloc_batch " (since Linux 3.12)" -.\" commit 81c0a2bb515fd4daae8cab64352877480792b515 -.TP -.IR nr_inactive_anon " (since Linux 2.6.28)" -.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db -.TP -.IR nr_active_anon " (since Linux 2.6.28)" -.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db -.TP -.IR nr_inactive_file " (since Linux 2.6.28)" -.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db -.TP -.IR nr_active_file " (since Linux 2.6.28)" -.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db -.TP -.IR nr_unevictable " (since Linux 2.6.28)" -.\" commit 7b854121eb3e5ba0241882ff939e2c485228c9c5 -.TP -.IR nr_mlock " (since Linux 2.6.28)" -.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 -.TP -.IR nr_anon_pages " (since Linux 2.6.18)" -.\" commit f3dbd34460ff54962d3e3244b6bcb7f5295356e6 -.TP -.IR nr_mapped " (since Linux 2.6.0)" -.TP -.IR nr_file_pages " (since Linux 2.6.18)" -.\" commit 347ce434d57da80fd5809c0c836f206a50999c26 -.TP -.IR nr_dirty " (since Linux 2.6.0)" -.TP -.IR nr_writeback " (since Linux 2.6.0)" -.TP -.IR nr_slab_reclaimable " (since Linux 2.6.19)" -.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 -.\" Linux 2.6.0 had nr_slab -.TP -.IR nr_slab_unreclaimable " (since Linux 2.6.19)" -.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 -.TP -.IR nr_page_table_pages " (since Linux 2.6.0)" -.TP -.IR nr_kernel_stack " (since Linux 2.6.32)" -.\" commit c6a7f5728a1db45d30df55a01adc130b4ab0327c -Amount of memory allocated to kernel stacks. -.TP -.IR nr_unstable " (since Linux 2.6.0)" -.TP -.IR nr_bounce " (since Linux 2.6.12)" -.\" commit edfbe2b0038723e5699ab22695ccd62b5542a5c1 -.TP -.IR nr_vmscan_write " (since Linux 2.6.19)" -.\" commit e129b5c23c2b471d47f1c5d2b8b193fc2034af43 -.TP -.IR nr_vmscan_immediate_reclaim " (since Linux 3.2)" -.\" commit 49ea7eb65e7c5060807fb9312b1ad4c3eab82e2c -.TP -.IR nr_writeback_temp " (since Linux 2.6.26)" -.\" commit fc3ba692a4d19019387c5acaea63131f9eab05dd -.TP -.IR nr_isolated_anon " (since Linux 2.6.32)" -.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 -.TP -.IR nr_isolated_file " (since Linux 2.6.32)" -.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 -.TP -.IR nr_shmem " (since Linux 2.6.32)" -.\" commit 4b02108ac1b3354a22b0d83c684797692efdc395 -Pages used by shmem and -.BR tmpfs (5). -.TP -.IR nr_dirtied " (since Linux 2.6.37)" -.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c -.TP -.IR nr_written " (since Linux 2.6.37)" -.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c -.TP -.IR nr_pages_scanned " (since Linux 3.17)" -.\" commit 0d5d823ab4e608ec7b52ac4410de4cb74bbe0edd -.TP -.IR numa_hit " (since Linux 2.6.18)" -.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_NUMA . -.TP -.IR numa_miss " (since Linux 2.6.18)" -.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_NUMA . -.TP -.IR numa_foreign " (since Linux 2.6.18)" -.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_NUMA . -.TP -.IR numa_interleave " (since Linux 2.6.18)" -.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_NUMA . -.TP -.IR numa_local " (since Linux 2.6.18)" -.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_NUMA . -.TP -.IR numa_other " (since Linux 2.6.18)" -.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_NUMA . -.TP -.IR workingset_refault " (since Linux 3.15)" -.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR workingset_activate " (since Linux 3.15)" -.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR workingset_nodereclaim " (since Linux 3.15)" -.\" commit 449dd6984d0e47643c04c807f609dd56d48d5bcc -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR nr_anon_transparent_hugepages " (since Linux 2.6.38)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR nr_free_cma " (since Linux 3.7)" -.\" commit d1ce749a0db12202b711d1aba1d29e823034648d -Number of free CMA (Contiguous Memory Allocator) pages. -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR nr_dirty_threshold " (since Linux 2.6.37)" -.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR nr_dirty_background_threshold " (since Linux 2.6.37)" -.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgpgin " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgpgout " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pswpin " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pswpout " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgalloc_dma " (since Linux 2.6.5)" -.\" Linux 2.6.0 had pgalloc -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgalloc_dma32 " (since Linux 2.6.16)" -.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgalloc_normal " (since Linux 2.6.5)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgalloc_high " (since Linux 2.6.5)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HIGHMEM . -.TP -.IR pgalloc_movable " (since Linux 2.6.23)" -.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgfree " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgactivate " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgdeactivate " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgfault " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgmajfault " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgrefill_dma " (since Linux 2.6.5)" -.\" Linux 2.6.0 had pgrefill -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgrefill_dma32 " (since Linux 2.6.16)" -.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgrefill_normal " (since Linux 2.6.5)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgrefill_high " (since Linux 2.6.5)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HIGHMEM . -.TP -.IR pgrefill_movable " (since Linux 2.6.23)" -.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.\" Formerly there were -.\" pgsteal_high -.\" pgsteal_normal -.\" pgsteal_dma32 -.\" pgsteal_dma -.\" These were split out into pgsteal_kswapd* and pgsteal_direct* -.\" in commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.TP -.IR pgsteal_kswapd_dma " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Linux 2.6.0 had pgsteal -.\" Present only if the kernel was configured with -.\" .\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgsteal_kswapd_dma32 " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgsteal_kswapd_normal " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgsteal_kswapd_high " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HIGHMEM . -.TP -.IR pgsteal_kswapd_movable " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.I pgsteal_direct_dma -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgsteal_direct_dma32 " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgsteal_direct_normal " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgsteal_direct_high " (since Linux 3.4)" -.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HIGHMEM . -.TP -.IR pgsteal_direct_movable " (since Linux 2.6.23)" -.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.I pgscan_kswapd_dma -.\" Linux 2.6.0 had pgscan -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgscan_kswapd_dma32 " (since Linux 2.6.16)" -.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgscan_kswapd_normal " (since Linux 2.6.5)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.I pgscan_kswapd_high -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HIGHMEM . -.TP -.IR pgscan_kswapd_movable " (since Linux 2.6.23)" -.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.I pgscan_direct_dma -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgscan_direct_dma32 " (since Linux 2.6.16)" -.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.I pgscan_direct_normal -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.I pgscan_direct_high -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HIGHMEM . -.TP -.IR pgscan_direct_movable " (since Linux 2.6.23)" -.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgscan_direct_throttle " (since Linux 3.6)" -.\" commit 68243e76ee343d63c6cf76978588a885951e2818 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR zone_reclaim_failed " (since linux 2.6.31)" -.\" commit 24cf72518c79cdcda486ed26074ff8151291cf65 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_NUMA . -.TP -.IR pginodesteal " (since linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR slabs_scanned " (since linux 2.6.5)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR kswapd_inodesteal " (since linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR kswapd_low_wmark_hit_quickly " (since Linux 2.6.33)" -.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR kswapd_high_wmark_hit_quickly " (since Linux 2.6.33)" -.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pageoutrun " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR allocstall " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR pgrotated " (since Linux 2.6.0)" -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR drop_pagecache " (since Linux 3.15)" -.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR drop_slab " (since Linux 3.15)" -.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR numa_pte_updates " (since Linux 3.8)" -.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_NUMA_BALANCING . -.TP -.IR numa_huge_pte_updates " (since Linux 3.13)" -.\" commit 72403b4a0fbdf433c1fe0127e49864658f6f6468 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_NUMA_BALANCING . -.TP -.IR numa_hint_faults " (since Linux 3.8)" -.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_NUMA_BALANCING . -.TP -.IR numa_hint_faults_local " (since Linux 3.8)" -.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_NUMA_BALANCING . -.TP -.IR numa_pages_migrated " (since Linux 3.8)" -.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_NUMA_BALANCING -.\" and -.\" .BR CONFIG_NUMA_BALANCING . -.TP -.IR pgmigrate_success " (since Linux 3.8)" -.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_MIGRATION . -.TP -.IR pgmigrate_fail " (since Linux 3.8)" -.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_MIGRATION . -.TP -.IR compact_migrate_scanned " (since Linux 3.8)" -.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 -.\" Linux 3.8 dropped compact_blocks_moved, compact_pages_moved, and -.\" compact_pagemigrate_failed -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_COMPACTION . -.TP -.IR compact_free_scanned " (since Linux 3.8)" -.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_COMPACTION . -.TP -.IR compact_isolated " (since Linux 3.8)" -.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_COMPACTION . -.TP -.IR compact_stall " (since Linux 2.6.35)" -.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_COMPACTION . -.TP -.IR compact_fail " (since Linux 2.6.35)" -.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_COMPACTION . -.TP -.IR compact_success " (since Linux 2.6.35)" -.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_COMPACTION . -.TP -.IR htlb_buddy_alloc_success " (since Linux 2.6.26)" -.\" commit 3b1163006332302117b1b2acf226d4014ff46525 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HUGETLB_PAGE . -.TP -.IR htlb_buddy_alloc_fail " (since Linux 2.6.26)" -.\" commit 3b1163006332302117b1b2acf226d4014ff46525 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_HUGETLB_PAGE . -.TP -.IR unevictable_pgs_culled " (since Linux 2.6.28)" -.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR unevictable_pgs_scanned " (since Linux 2.6.28)" -.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR unevictable_pgs_rescued " (since Linux 2.6.28)" -.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR unevictable_pgs_mlocked " (since Linux 2.6.28)" -.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR unevictable_pgs_munlocked " (since Linux 2.6.28)" -.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR unevictable_pgs_cleared " (since Linux 2.6.28)" -.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.TP -.IR unevictable_pgs_stranded " (since Linux 2.6.28)" -.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS . -.\" Linux 3.7 removed unevictable_pgs_mlockfreed -.TP -.IR thp_fault_alloc " (since Linux 2.6.39)" -.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR thp_fault_fallback " (since Linux 2.6.39)" -.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR thp_collapse_alloc " (since Linux 2.6.39)" -.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR thp_collapse_alloc_failed " (since Linux 2.6.39)" -.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR thp_split " (since Linux 2.6.39)" -.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR thp_zero_page_alloc " (since Linux 3.8)" -.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR thp_zero_page_alloc_failed " (since Linux 3.8)" -.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 -See the kernel source file -.IR Documentation/admin\-guide/mm/transhuge.rst . -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . -.TP -.IR balloon_inflate " (since Linux 3.18)" -.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_MEMORY_BALLOON . -.TP -.IR balloon_deflate " (since Linux 3.18)" -.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS -.\" and -.\" .BR CONFIG_MEMORY_BALLOON . -.TP -.IR balloon_migrate " (since Linux 3.18)" -.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_VM_EVENT_COUNTERS , -.\" .BR CONFIG_MEMORY_BALLOON , -.\" and -.\" .BR CONFIG_BALLOON_COMPACTION . -.TP -.IR nr_tlb_remote_flush " (since Linux 3.12)" -.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_TLBFLUSH -.\" and -.\" .BR CONFIG_SMP . -.TP -.IR nr_tlb_remote_flush_received " (since Linux 3.12)" -.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_TLBFLUSH -.\" and -.\" .BR CONFIG_SMP . -.TP -.IR nr_tlb_local_flush_all " (since Linux 3.12)" -.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_TLBFLUSH . -.TP -.IR nr_tlb_local_flush_one " (since Linux 3.12)" -.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_TLBFLUSH . -.TP -.IR vmacache_find_calls " (since Linux 3.16)" -.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_VM_VMACACHE . -.TP -.IR vmacache_find_hits " (since Linux 3.16)" -.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_VM_VMACACHE . -.TP -.IR vmacache_full_flushes " (since Linux 3.19)" -.\" commit f5f302e21257ebb0c074bbafc37606c26d28cc3d -.\" Present only if the kernel was configured with -.\" .BR CONFIG_DEBUG_VM_VMACACHE . -.RE -.TP -.IR /proc/zoneinfo " (since Linux 2.6.13)" -This file displays information about memory zones. -This is useful for analyzing virtual memory behavior. -.\" FIXME more should be said about /proc/zoneinfo .SH NOTES Many files contain strings (e.g., the environment and command line) that are in the internal format, with subfields terminated by null bytes (\[aq]\e0\[aq]). When inspecting such files, you may find that the results are more readable if you use a command of the following form to display them: -.PP +.P .in +4n .EX .RB "$" " cat \fIfile\fP | tr \[aq]\e000\[aq] \[aq]\en\[aq]" .EE .in -.PP -This manual page is incomplete, possibly inaccurate, and is the kind -of thing that needs to be updated very often. .\" .SH ACKNOWLEDGEMENTS .\" The material on /proc/sys/fs and /proc/sys/kernel is closely based on .\" kernel source documentation files written by Rik van Riel. @@ -6955,7 +249,7 @@ of thing that needs to be updated very often. .BR procinfo (8), .BR route (8), .BR sysctl (8) -.PP +.P The Linux kernel source files: .IR Documentation/filesystems/proc.rst , .IR Documentation/admin\-guide/sysctl/fs.rst , diff --git a/man5/proc_apm.5 b/man5/proc_apm.5 new file mode 100644 index 0000000..2987d2b --- /dev/null +++ b/man5/proc_apm.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_apm 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/apm \- advanced power management +.SH DESCRIPTION +.TP +.I /proc/apm +Advanced power management version and battery information when +.B CONFIG_APM +is defined at kernel compilation time. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_buddyinfo.5 b/man5/proc_buddyinfo.5 new file mode 100644 index 0000000..b98185c --- /dev/null +++ b/man5/proc_buddyinfo.5 @@ -0,0 +1,58 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_buddyinfo 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/buddyinfo \- memory fragmentation +.SH DESCRIPTION +.TP +.I /proc/buddyinfo +This file contains information which is used for diagnosing memory +fragmentation issues. +Each line starts with the identification of the node and the name +of the zone which together identify a memory region. +This is then +followed by the count of available chunks of a certain order in +which these zones are split. +The size in bytes of a certain order is given by the formula: +.IP +.in +4n +.EX +(2\[ha]order)\ *\ PAGE_SIZE +.EE +.in +.IP +The binary buddy allocator algorithm inside the kernel will split +one chunk into two chunks of a smaller order (thus with half the +size) or combine two contiguous chunks into one larger chunk of +a higher order (thus with double the size) to satisfy allocation +requests and to counter memory fragmentation. +The order matches the column number, when starting to count at zero. +.IP +For example on an x86-64 system: +.RS -12 +.EX +Node 0, zone DMA 1 1 1 0 2 1 1 0 1 1 3 +Node 0, zone DMA32 65 47 4 81 52 28 13 10 5 1 404 +Node 0, zone Normal 216 55 189 101 84 38 37 27 5 3 587 +.EE +.RE +.IP +In this example, there is one node containing three zones and there +are 11 different chunk sizes. +If the page size is 4 kilobytes, then the first zone called +.I DMA +(on x86 the first 16 megabyte of memory) has 1 chunk of 4 kilobytes +(order 0) available and has 3 chunks of 4 megabytes (order 10) available. +.IP +If the memory is heavily fragmented, the counters for higher +order chunks will be zero and allocation of large contiguous areas +will fail. +.IP +Further information about the zones can be found in +.IR /proc/zoneinfo . +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_bus.5 b/man5/proc_bus.5 new file mode 100644 index 0000000..505b8ea --- /dev/null +++ b/man5/proc_bus.5 @@ -0,0 +1,35 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_bus 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/bus/ \- installed buses +.SH DESCRIPTION +.TP +.I /proc/bus/ +Contains subdirectories for installed buses. +.TP +.I /proc/bus/pccard/ +Subdirectory for PCMCIA devices when +.B CONFIG_PCMCIA +is set at kernel compilation time. +.TP +.I /proc/bus/pccard/drivers +.TP +.I /proc/bus/pci/ +Contains various bus subdirectories and pseudo-files containing +information about PCI buses, installed devices, and device +drivers. +Some of these files are not ASCII. +.TP +.I /proc/bus/pci/devices +Information about PCI devices. +They may be accessed through +.BR lspci (8) +and +.BR setpci (8). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_cgroups.5 b/man5/proc_cgroups.5 new file mode 100644 index 0000000..b858a64 --- /dev/null +++ b/man5/proc_cgroups.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cgroups 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/cgroups \- control groups +.SH DESCRIPTION +.TP +.IR /proc/cgroups " (since Linux 2.6.24)" +See +.BR cgroups (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_cmdline.5 b/man5/proc_cmdline.5 new file mode 100644 index 0000000..55873f9 --- /dev/null +++ b/man5/proc_cmdline.5 @@ -0,0 +1,22 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cmdline 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/cmdline \- kernel boot arguments +.SH DESCRIPTION +.TP +.I /proc/cmdline +Arguments passed to the Linux kernel at boot time. +Often done via a boot manager such as +.BR lilo (8) +or +.BR grub (8). +Any arguments embedded in the kernel image or initramfs via +.B CONFIG_BOOT_CONFIG +will also be displayed. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_config.gz.5 b/man5/proc_config.gz.5 new file mode 100644 index 0000000..1d894bd --- /dev/null +++ b/man5/proc_config.gz.5 @@ -0,0 +1,40 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_config.gz 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/config.gz \- kernel build configuration +.SH DESCRIPTION +.TP +.IR /proc/config.gz " (since Linux 2.6)" +This file exposes the configuration options that were used +to build the currently running kernel, +in the same format as they would be shown in the +.I .config +file that resulted when configuring the kernel (using +.IR "make xconfig" , +.IR "make config" , +or similar). +The file contents are compressed; view or search them using +.BR zcat (1) +and +.BR zgrep (1). +As long as no changes have been made to the following file, +the contents of +.I /proc/config.gz +are the same as those provided by: +.IP +.in +4n +.EX +cat /lib/modules/$(uname \-r)/build/.config +.EE +.in +.IP +.I /proc/config.gz +is provided only if the kernel is configured with +.BR CONFIG_IKCONFIG_PROC . +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_cpuinfo.5 b/man5/proc_cpuinfo.5 new file mode 100644 index 0000000..7d620ce --- /dev/null +++ b/man5/proc_cpuinfo.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_cpuinfo 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/cpuinfo \- CPU and system architecture information +.SH DESCRIPTION +.TP +.I /proc/cpuinfo +This is a collection of CPU and system architecture dependent items, +for each supported architecture a different list. +Two common entries are \fIprocessor\fP which gives CPU number and +\fIbogomips\fP; a system constant that is calculated +during kernel initialization. +SMP machines have information for +each CPU. +The +.BR lscpu (1) +command gathers its information from this file. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_crypto.5 b/man5/proc_crypto.5 new file mode 100644 index 0000000..eeee62e --- /dev/null +++ b/man5/proc_crypto.5 @@ -0,0 +1,26 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_crypto 5 2023-11-24 "Linux man-pages 6.7" +.SH NAME +/proc/crypto \- ciphers provided by kernel crypto API +.SH DESCRIPTION +.TP +.I /proc/crypto +A list of the ciphers provided by the kernel crypto API. +For details, see the kernel +.I "Linux Kernel Crypto API" +documentation available under the kernel source directory +.I Documentation/crypto/ +.\" commit 3b72c814a8e8cd638e1ba0da4dfce501e9dff5af +(or +.I Documentation/DocBook +before Linux 4.10; +the documentation can be built using a command such as +.I make htmldocs +in the root directory of the kernel source tree). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_devices.5 b/man5/proc_devices.5 new file mode 100644 index 0000000..27280ca --- /dev/null +++ b/man5/proc_devices.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_devices 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/devices \- major numbers and device groups +.SH DESCRIPTION +.TP +.I /proc/devices +Text listing of major numbers and device groups. +This can be used by MAKEDEV scripts for consistency with the kernel. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_diskstats.5 b/man5/proc_diskstats.5 new file mode 100644 index 0000000..76f8347 --- /dev/null +++ b/man5/proc_diskstats.5 @@ -0,0 +1,21 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_diskstats 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/diskstats \- disk I/O statistics +.SH DESCRIPTION +.TP +.IR /proc/diskstats " (since Linux 2.5.69)" +This file contains disk I/O statistics for each disk device. +See the Linux kernel source file +.I Documentation/admin\-guide/iostats.rst +(or +.I Documentation/iostats.txt +before Linux 5.3) +for further information. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_dma.5 b/man5/proc_dma.5 new file mode 100644 index 0000000..6882949 --- /dev/null +++ b/man5/proc_dma.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_dma 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/dma \- ISA DMA channels +.SH DESCRIPTION +.TP +.I /proc/dma +This is a list of the registered \fIISA\fP DMA (direct memory access) +channels in use. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_driver.5 b/man5/proc_driver.5 new file mode 100644 index 0000000..ec86255 --- /dev/null +++ b/man5/proc_driver.5 @@ -0,0 +1,15 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_driver 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/driver/ \- empty dir +.SH DESCRIPTION +.TP +.I /proc/driver/ +Empty subdirectory. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_execdomains.5 b/man5/proc_execdomains.5 new file mode 100644 index 0000000..945cbf3 --- /dev/null +++ b/man5/proc_execdomains.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_execdomains 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/execdomains \- ABI personalities (obsolete) +.SH DESCRIPTION +.TP +.I /proc/execdomains +Used to list ABI personalities before Linux 4.1; +now contains a constant string for userspace compatibility. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_fb.5 b/man5/proc_fb.5 new file mode 100644 index 0000000..31ea1ce --- /dev/null +++ b/man5/proc_fb.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_fb 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/fb \- frame buffer +.SH DESCRIPTION +.TP +.I /proc/fb +Frame buffer information when +.B CONFIG_FB +is defined during kernel compilation. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_filesystems.5 b/man5/proc_filesystems.5 new file mode 100644 index 0000000..2ed6b54 --- /dev/null +++ b/man5/proc_filesystems.5 @@ -0,0 +1,33 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.\" FIXME cross check against Documentation/filesystems/proc.txt +.\" to see what information could be imported from that file +.\" into this file. +.\" +.TH proc_filesystems 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/filesystems \- supported filesystems +.SH DESCRIPTION +.TP +.I /proc/filesystems +A text listing of the filesystems which are supported by the kernel, +namely filesystems which were compiled into the kernel or whose kernel +modules are currently loaded. +(See also +.BR filesystems (5).) +If a filesystem is marked with "nodev", +this means that it does not require a block device to be mounted +(e.g., virtual filesystem, network filesystem). +.IP +Incidentally, this file may be used by +.BR mount (8) +when no filesystem is specified and it didn't manage to determine the +filesystem type. +Then filesystems contained in this file are tried +(excepted those that are marked with "nodev"). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_fs.5 b/man5/proc_fs.5 new file mode 100644 index 0000000..31fe94c --- /dev/null +++ b/man5/proc_fs.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_fs 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/fs/ \- mounted filesystems +.SH DESCRIPTION +.TP +.I /proc/fs/ +.\" FIXME Much more needs to be said about /proc/fs +.\" +Contains subdirectories that in turn contain files +with information about (certain) mounted filesystems. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_ide.5 b/man5/proc_ide.5 new file mode 100644 index 0000000..7e28acc --- /dev/null +++ b/man5/proc_ide.5 @@ -0,0 +1,37 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_ide 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/ide/ \- IDE channels and attached devices +.SH DESCRIPTION +.TP +.I /proc/ide +This directory +exists on systems with the IDE bus. +There are directories for each IDE channel and attached device. +Files include: +.IP +.in +4n +.EX +cache buffer size in KB +capacity number of sectors +driver driver version +geometry physical and logical geometry +identify in hexadecimal +media media type +model manufacturer\[aq]s model number +settings drive settings +smart_thresholds IDE disk management thresholds (in hex) +smart_values IDE disk management values (in hex) +.EE +.in +.IP +The +.BR hdparm (8) +utility provides access to this information in a friendly format. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_interrupts.5 b/man5/proc_interrupts.5 new file mode 100644 index 0000000..897399a --- /dev/null +++ b/man5/proc_interrupts.5 @@ -0,0 +1,22 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_interrupts 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/interrupts \- number of interrupts +.SH DESCRIPTION +.TP +.I /proc/interrupts +This is used to record the number of interrupts per CPU per IO device. +Since Linux 2.6.24, +for the i386 and x86-64 architectures, at least, this also includes +interrupts internal to the system (that is, not associated with a device +as such), such as NMI (nonmaskable interrupt), LOC (local timer interrupt), +and for SMP systems, TLB (TLB flush interrupt), RES (rescheduling +interrupt), CAL (remote function call interrupt), and possibly others. +Very easy to read formatting, done in ASCII. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_iomem.5 b/man5/proc_iomem.5 new file mode 100644 index 0000000..5541450 --- /dev/null +++ b/man5/proc_iomem.5 @@ -0,0 +1,15 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_iomem 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/iomem \- I/O memory map +.SH DESCRIPTION +.TP +.I /proc/iomem +I/O memory map in Linux 2.4. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_ioports.5 b/man5/proc_ioports.5 new file mode 100644 index 0000000..e07c278 --- /dev/null +++ b/man5/proc_ioports.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_ioports 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/ioports \- I/O port regions +.SH DESCRIPTION +.TP +.I /proc/ioports +This is a list of currently registered Input-Output port regions that +are in use. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_kallsyms.5 b/man5/proc_kallsyms.5 new file mode 100644 index 0000000..a4f30a4 --- /dev/null +++ b/man5/proc_kallsyms.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kallsyms 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/kallsyms \- kernel exported symbols +.SH DESCRIPTION +.TP +.IR /proc/kallsyms " (since Linux 2.5.71)" +This holds the kernel exported symbol definitions used by the +.BR modules (X) +tools to dynamically link and bind loadable modules. +In Linux 2.5.47 and earlier, a similar file with slightly different syntax +was named +.IR ksyms . +.SH HISTORY +.TP +.IR /proc/ksyms " (Linux 1.1.23\[en]2.5.47)" +See +.IR /proc/kallsyms . +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_kcore.5 b/man5/proc_kcore.5 new file mode 100644 index 0000000..9a98a95 --- /dev/null +++ b/man5/proc_kcore.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kcore 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/kcore \- physical memory +.SH DESCRIPTION +.TP +.I /proc/kcore +This file represents the physical memory of the system and is stored +in the ELF core file format. +With this pseudo-file, and an unstripped +kernel +.RI ( /usr/src/linux/vmlinux ) +binary, GDB can be used to +examine the current state of any kernel data structures. +.IP +The total length of the file is the size of physical memory (RAM) plus +4\ KiB. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_key-users.5 b/man5/proc_key-users.5 new file mode 100644 index 0000000..7f88ac3 --- /dev/null +++ b/man5/proc_key-users.5 @@ -0,0 +1 @@ +.so man5/proc_keys.5 diff --git a/man5/proc_keys.5 b/man5/proc_keys.5 new file mode 100644 index 0000000..5cdcbee --- /dev/null +++ b/man5/proc_keys.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_keys 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/keys, /proc/key\-users \- in-kernel key management +.SH DESCRIPTION +.TP +.IR /proc/keys " (since Linux 2.6.10)" +See +.BR keyrings (7). +.TP +.IR /proc/key\-users " (since Linux 2.6.10)" +See +.BR keyrings (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_kmsg.5 b/man5/proc_kmsg.5 new file mode 100644 index 0000000..1486552 --- /dev/null +++ b/man5/proc_kmsg.5 @@ -0,0 +1,28 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kmsg 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/kmsg \- kernel messages +.SH DESCRIPTION +.TP +.I /proc/kmsg +This file can be used instead of the +.BR syslog (2) +system call to read kernel messages. +A process must have superuser +privileges to read this file, and only one process should read this +file. +This file should not be read if a syslog process is running +which uses the +.BR syslog (2) +system call facility to log kernel messages. +.IP +Information in this file is retrieved with the +.BR dmesg (1) +program. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_kpagecgroup.5 b/man5/proc_kpagecgroup.5 new file mode 100644 index 0000000..41f3237 --- /dev/null +++ b/man5/proc_kpagecgroup.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpagecgroup 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/kpagecgroup \- memory cgroups +.SH DESCRIPTION +.TP +.IR /proc/kpagecgroup " (since Linux 4.3)" +.\" commit 80ae2fdceba8313b0433f899bdd9c6c463291a17 +This file contains a 64-bit inode number of +the memory cgroup each page is charged to, +indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +.IP +The +.I /proc/kpagecgroup +file is present only if the +.B CONFIG_MEMCG +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_kpagecount.5 b/man5/proc_kpagecount.5 new file mode 100644 index 0000000..16cf080 --- /dev/null +++ b/man5/proc_kpagecount.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpagecount 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/kpagecount \- count of mappings of physical pages +.SH DESCRIPTION +.TP +.IR /proc/kpagecount " (since Linux 2.6.25)" +This file contains a 64-bit count of the number of +times each physical page frame is mapped, +indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +.IP +The +.I /proc/kpagecount +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_kpageflags.5 b/man5/proc_kpageflags.5 new file mode 100644 index 0000000..5c23d02 --- /dev/null +++ b/man5/proc_kpageflags.5 @@ -0,0 +1,75 @@ +'\" t +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_kpageflags 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/kpageflags \- physical pages frame masks +.SH DESCRIPTION +.TP +.IR /proc/kpageflags " (since Linux 2.6.25)" +This file contains 64-bit masks corresponding to each physical page frame; +it is indexed by page frame number (see the discussion of +.IR /proc/ pid /pagemap ). +The bits are as follows: +.RS +.IP +.TS +r l l l. +0 - KPF_LOCKED +1 - KPF_ERROR +2 - KPF_REFERENCED +3 - KPF_UPTODATE +4 - KPF_DIRTY +5 - KPF_LRU +6 - KPF_ACTIVE +7 - KPF_SLAB +8 - KPF_WRITEBACK +9 - KPF_RECLAIM +10 - KPF_BUDDY +11 - KPF_MMAP (since Linux 2.6.31) +12 - KPF_ANON (since Linux 2.6.31) +13 - KPF_SWAPCACHE (since Linux 2.6.31) +14 - KPF_SWAPBACKED (since Linux 2.6.31) +15 - KPF_COMPOUND_HEAD (since Linux 2.6.31) +16 - KPF_COMPOUND_TAIL (since Linux 2.6.31) +17 - KPF_HUGE (since Linux 2.6.31) +18 - KPF_UNEVICTABLE (since Linux 2.6.31) +19 - KPF_HWPOISON (since Linux 2.6.31) +20 - KPF_NOPAGE (since Linux 2.6.31) +21 - KPF_KSM (since Linux 2.6.32) +22 - KPF_THP (since Linux 3.4) +23 - KPF_BALLOON (since Linux 3.18) +.\" KPF_BALLOON: commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +24 - KPF_ZERO_PAGE (since Linux 4.0) +.\" KPF_ZERO_PAGE: commit 56873f43abdcd574b25105867a990f067747b2f4 +25 - KPF_IDLE (since Linux 4.3) +.\" KPF_IDLE: commit f074a8f49eb87cde95ac9d040ad5e7ea4f029738 +26 - KPF_PGTABLE (since Linux 4.18) +.\" KPF_PGTABLE: commit 1d40a5ea01d53251c23c7be541d3f4a656cfc537 +.TE +.RE +.IP +For further details on the meanings of these bits, +see the kernel source file +.IR Documentation/admin\-guide/mm/pagemap.rst . +Before Linux 2.6.29, +.\" commit ad3bdefe877afb47480418fdb05ecd42842de65e +.\" commit e07a4b9217d1e97d2f3a62b6b070efdc61212110 +.BR KPF_WRITEBACK , +.BR KPF_RECLAIM , +.BR KPF_BUDDY , +and +.B KPF_LOCKED +did not report correctly. +.IP +The +.I /proc/kpageflags +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_ksyms.5 b/man5/proc_ksyms.5 new file mode 100644 index 0000000..e4fc2a1 --- /dev/null +++ b/man5/proc_ksyms.5 @@ -0,0 +1 @@ +.so man5/proc_kallsyms.5 diff --git a/man5/proc_loadavg.5 b/man5/proc_loadavg.5 new file mode 100644 index 0000000..fba6603 --- /dev/null +++ b/man5/proc_loadavg.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_loadavg 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/loadavg \- load average +.SH DESCRIPTION +.TP +.I /proc/loadavg +The first three fields in this file are load average figures +giving the number of jobs in the run queue (state R) +or waiting for disk I/O (state D) averaged over 1, 5, and 15 minutes. +They are the same as the load average numbers given by +.BR uptime (1) +and other programs. +The fourth field consists of two numbers separated by a slash (/). +The first of these is the number of currently runnable kernel +scheduling entities (processes, threads). +The value after the slash is the number of kernel scheduling entities +that currently exist on the system. +The fifth field is the PID of the process that was most +recently created on the system. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_locks.5 b/man5/proc_locks.5 new file mode 100644 index 0000000..c33ec82 --- /dev/null +++ b/man5/proc_locks.5 @@ -0,0 +1,122 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_locks 5 2023-11-19 "Linux man-pages 6.7" +.SH NAME +/proc/locks \- current file locks and leases +.SH DESCRIPTION +.TP +.I /proc/locks +This file shows current file locks +(\c +.BR flock (2) +and +.BR fcntl (2)) +and leases +(\c +.BR fcntl (2)). +.IP +An example of the content shown in this file is the following: +.IP +.in +4n +.EX +1: POSIX ADVISORY READ 5433 08:01:7864448 128 128 +2: FLOCK ADVISORY WRITE 2001 08:01:7864554 0 EOF +3: FLOCK ADVISORY WRITE 1568 00:2f:32388 0 EOF +4: POSIX ADVISORY WRITE 699 00:16:28457 0 EOF +5: POSIX ADVISORY WRITE 764 00:16:21448 0 0 +6: POSIX ADVISORY READ 3548 08:01:7867240 1 1 +7: POSIX ADVISORY READ 3548 08:01:7865567 1826 2335 +8: OFDLCK ADVISORY WRITE \-1 08:01:8713209 128 191 +.EE +.in +.IP +The fields shown in each line are as follows: +.RS +.IP [1] 5 +The ordinal position of the lock in the list. +.IP [2] +The lock type. +Values that may appear here include: +.RS +.TP +.B FLOCK +This is a BSD file lock created using +.BR flock (2). +.TP +.B OFDLCK +This is an open file description (OFD) lock created using +.BR fcntl (2). +.TP +.B POSIX +This is a POSIX byte-range lock created using +.BR fcntl (2). +.RE +.IP [3] +Among the strings that can appear here are the following: +.RS +.TP +.B ADVISORY +This is an advisory lock. +.TP +.B MANDATORY +This is a mandatory lock. +.RE +.IP [4] +The type of lock. +Values that can appear here are: +.RS +.TP +.B READ +This is a POSIX or OFD read lock, or a BSD shared lock. +.TP +.B WRITE +This is a POSIX or OFD write lock, or a BSD exclusive lock. +.RE +.IP [5] +The PID of the process that owns the lock. +.IP +Because OFD locks are not owned by a single process +(since multiple processes may have file descriptors that +refer to the same open file description), +the value \-1 is displayed in this field for OFD locks. +(Before Linux 4.14, +.\" commit 9d5b86ac13c573795525ecac6ed2db39ab23e2a8 +a bug meant that the PID of the process that +initially acquired the lock was displayed instead of the value \-1.) +.IP [6] +Three colon-separated subfields that identify the major and minor device +ID of the device containing the filesystem where the locked file resides, +followed by the inode number of the locked file. +.IP [7] +The byte offset of the first byte of the lock. +For BSD locks, this value is always 0. +.IP [8] +The byte offset of the last byte of the lock. +.B EOF +in this field means that the lock extends to the end of the file. +For BSD locks, the value shown is always +.IR EOF . +.RE +.IP +Since Linux 4.9, +.\" commit d67fd44f697dff293d7cdc29af929241b669affe +the list of locks shown in +.I /proc/locks +is filtered to show just the locks for the processes in the PID +namespace (see +.BR pid_namespaces (7)) +for which the +.I /proc +filesystem was mounted. +(In the initial PID namespace, +there is no filtering of the records shown in this file.) +.IP +The +.BR lslocks (8) +command provides a bit more information about each lock. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_malloc.5 b/man5/proc_malloc.5 new file mode 100644 index 0000000..d6197dc --- /dev/null +++ b/man5/proc_malloc.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_malloc 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/malloc \- debug malloc (obsolete) +.SH DESCRIPTION +.TP +.IR /proc/malloc " (only up to and including Linux 2.2)" +.\" It looks like this only ever did something back in 1.0 days +This file is present only if +.B CONFIG_DEBUG_MALLOC +was defined during compilation. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_meminfo.5 b/man5/proc_meminfo.5 new file mode 100644 index 0000000..7a2e70e --- /dev/null +++ b/man5/proc_meminfo.5 @@ -0,0 +1,327 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_meminfo 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/meminfo \- memory usage +.SH DESCRIPTION +.TP +.I /proc/meminfo +This file reports statistics about memory usage on the system. +It is used by +.BR free (1) +to report the amount of free and used memory (both physical and swap) +on the system as well as the shared memory and buffers used by the +kernel. +Each line of the file consists of a parameter name, followed by a colon, +the value of the parameter, and an option unit of measurement (e.g., "kB"). +The list below describes the parameter names and +the format specifier required to read the field value. +Except as noted below, +all of the fields have been present since at least Linux 2.6.0. +Some fields are displayed only if the kernel was configured +with various options; those dependencies are noted in the list. +.RS +.TP +.IR MemTotal " %lu" +Total usable RAM (i.e., physical RAM minus a few reserved +bits and the kernel binary code). +.TP +.IR MemFree " %lu" +The sum of +.IR LowFree + HighFree . +.TP +.IR MemAvailable " %lu (since Linux 3.14)" +An estimate of how much memory is available for starting new +applications, without swapping. +.TP +.IR Buffers " %lu" +Relatively temporary storage for raw disk blocks that +shouldn't get tremendously large (20 MB or so). +.TP +.IR Cached " %lu" +In-memory cache for files read from the disk (the page cache). +Doesn't include +.IR SwapCached . +.TP +.IR SwapCached " %lu" +Memory that once was swapped out, is swapped back in but +still also is in the swap file. +(If memory pressure is high, these pages +don't need to be swapped out again because they are already +in the swap file. +This saves I/O.) +.TP +.IR Active " %lu" +Memory that has been used more recently and usually not +reclaimed unless absolutely necessary. +.TP +.IR Inactive " %lu" +Memory which has been less recently used. +It is more eligible to be reclaimed for other purposes. +.TP +.IR Active(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(anon) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Active(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Inactive(file) " %lu (since Linux 2.6.28)" +[To be documented.] +.TP +.IR Unevictable " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to Linux 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR Mlocked " %lu (since Linux 2.6.28)" +(From Linux 2.6.28 to Linux 2.6.30, +\fBCONFIG_UNEVICTABLE_LRU\fP was required.) +[To be documented.] +.TP +.IR HighTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of highmem. +Highmem is all memory above \[ti]860 MB of physical memory. +Highmem areas are for use by user-space programs, +or for the page cache. +The kernel must use tricks to access +this memory, making it slower to access than lowmem. +.TP +.IR HighFree " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free highmem. +.TP +.IR LowTotal " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Total amount of lowmem. +Lowmem is memory which can be used for everything that +highmem can be used for, but it is also available for the +kernel's use for its own data structures. +Among many other things, +it is where everything from +.I Slab +is allocated. +Bad things happen when you're out of lowmem. +.TP +.IR LowFree " %lu" +(Starting with Linux 2.6.19, \fBCONFIG_HIGHMEM\fP is required.) +Amount of free lowmem. +.TP +.IR MmapCopy " %lu (since Linux 2.6.29)" +.RB ( CONFIG_MMU +is required.) +[To be documented.] +.TP +.IR SwapTotal " %lu" +Total amount of swap space available. +.TP +.IR SwapFree " %lu" +Amount of swap space that is currently unused. +.TP +.IR Dirty " %lu" +Memory which is waiting to get written back to the disk. +.TP +.IR Writeback " %lu" +Memory which is actively being written back to the disk. +.TP +.IR AnonPages " %lu (since Linux 2.6.18)" +Non-file backed pages mapped into user-space page tables. +.TP +.IR Mapped " %lu" +Files which have been mapped into memory (with +.BR mmap (2)), +such as libraries. +.TP +.IR Shmem " %lu (since Linux 2.6.32)" +Amount of memory consumed in +.BR tmpfs (5) +filesystems. +.TP +.IR KReclaimable " %lu (since Linux 4.20)" +Kernel allocations that the kernel will attempt to reclaim +under memory pressure. +Includes +.I SReclaimable +(below), and other direct allocations with a shrinker. +.TP +.IR Slab " %lu" +In-kernel data structures cache. +(See +.BR slabinfo (5).) +.TP +.IR SReclaimable " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that might be reclaimed, such as caches. +.TP +.IR SUnreclaim " %lu (since Linux 2.6.19)" +Part of +.IR Slab , +that cannot be reclaimed on memory pressure. +.TP +.IR KernelStack " %lu (since Linux 2.6.32)" +Amount of memory allocated to kernel stacks. +.TP +.IR PageTables " %lu (since Linux 2.6.18)" +Amount of memory dedicated to the lowest level of page tables. +.TP +.IR Quicklists " %lu (since Linux 2.6.27)" +(\fBCONFIG_QUICKLIST\fP is required.) +[To be documented.] +.TP +.IR NFS_Unstable " %lu (since Linux 2.6.18)" +NFS pages sent to the server, but not yet committed to stable storage. +.TP +.IR Bounce " %lu (since Linux 2.6.18)" +Memory used for block device "bounce buffers". +.TP +.IR WritebackTmp " %lu (since Linux 2.6.26)" +Memory used by FUSE for temporary writeback buffers. +.TP +.IR CommitLimit " %lu (since Linux 2.6.10)" +This is the total amount of memory currently available to +be allocated on the system, expressed in kilobytes. +This limit is adhered to +only if strict overcommit accounting is enabled (mode 2 in +.IR /proc/sys/vm/overcommit_memory ). +The limit is calculated according to the formula described under +.IR /proc/sys/vm/overcommit_memory . +For further details, see the kernel source file +.IR Documentation/vm/overcommit\-accounting.rst . +.TP +.IR Committed_AS " %lu" +The amount of memory presently allocated on the system. +The committed memory is a sum of all of the memory which +has been allocated by processes, even if it has not been +"used" by them as of yet. +A process which allocates 1 GB of memory (using +.BR malloc (3) +or similar), but touches only 300 MB of that memory will show up +as using only 300 MB of memory even if it has the address space +allocated for the entire 1 GB. +.IP +This 1 GB is memory which has been "committed" to by the VM +and can be used at any time by the allocating application. +With strict overcommit enabled on the system (mode 2 in +.IR /proc/sys/vm/overcommit_memory ), +allocations which would exceed the +.I CommitLimit +will not be permitted. +This is useful if one needs to guarantee that processes will not +fail due to lack of memory once that memory has been successfully allocated. +.TP +.IR VmallocTotal " %lu" +Total size of vmalloc memory area. +.TP +.IR VmallocUsed " %lu" +Amount of vmalloc area which is used. +Since Linux 4.4, +.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 +this field is no longer calculated, and is hard coded as 0. +See +.IR /proc/vmallocinfo . +.TP +.IR VmallocChunk " %lu" +Largest contiguous block of vmalloc area which is free. +Since Linux 4.4, +.\" commit a5ad88ce8c7fae7ddc72ee49a11a75aa837788e0 +this field is no longer calculated and is hard coded as 0. +See +.IR /proc/vmallocinfo . +.TP +.IR HardwareCorrupted " %lu (since Linux 2.6.32)" +(\fBCONFIG_MEMORY_FAILURE\fP is required.) +[To be documented.] +.TP +.IR LazyFree " %lu (since Linux 4.12)" +Shows the amount of memory marked by +.BR madvise (2) +.BR MADV_FREE . +.TP +.IR AnonHugePages " %lu (since Linux 2.6.38)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Non-file backed huge pages mapped into user-space page tables. +.TP +.IR ShmemHugePages " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Memory used by shared memory (shmem) and +.BR tmpfs (5) +allocated with huge pages. +.TP +.IR ShmemPmdMapped " %lu (since Linux 4.8)" +(\fBCONFIG_TRANSPARENT_HUGEPAGE\fP is required.) +Shared memory mapped into user space with huge pages. +.TP +.IR CmaTotal " %lu (since Linux 3.1)" +Total CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR CmaFree " %lu (since Linux 3.1)" +Free CMA (Contiguous Memory Allocator) pages. +(\fBCONFIG_CMA\fP is required.) +.TP +.IR HugePages_Total " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of the pool of huge pages. +.TP +.IR HugePages_Free " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The number of huge pages in the pool that are not yet allocated. +.TP +.IR HugePages_Rsvd " %lu (since Linux 2.6.17)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages for +which a commitment to allocate from the pool has been made, +but no allocation has yet been made. +These reserved huge pages +guarantee that an application will be able to allocate a +huge page from the pool of huge pages at fault time. +.TP +.IR HugePages_Surp " %lu (since Linux 2.6.24)" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +This is the number of huge pages in +the pool above the value in +.IR /proc/sys/vm/nr_hugepages . +The maximum number of surplus huge pages is controlled by +.IR /proc/sys/vm/nr_overcommit_hugepages . +.TP +.IR Hugepagesize " %lu" +(\fBCONFIG_HUGETLB_PAGE\fP is required.) +The size of huge pages. +.TP +.IR DirectMap4k " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4 kB pages. +(x86.) +.TP +.IR DirectMap4M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 4 MB pages. +(x86 with +.B CONFIG_X86_64 +or +.B CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap2M " %lu (since Linux 2.6.27)" +Number of bytes of RAM linearly mapped by kernel in 2 MB pages. +(x86 with neither +.B CONFIG_X86_64 +nor +.B CONFIG_X86_PAE +enabled.) +.TP +.IR DirectMap1G " %lu (since Linux 2.6.27)" +(x86 with +.B CONFIG_X86_64 +and +.B CONFIG_X86_DIRECT_GBPAGES +enabled.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_modules.5 b/man5/proc_modules.5 new file mode 100644 index 0000000..d040fde --- /dev/null +++ b/man5/proc_modules.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_modules 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/modules \- loaded modules +.SH DESCRIPTION +.TP +.I /proc/modules +A text list of the modules that have been loaded by the system. +See also +.BR lsmod (8). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_mounts.5 b/man5/proc_mounts.5 new file mode 100644 index 0000000..7da5a66 --- /dev/null +++ b/man5/proc_mounts.5 @@ -0,0 +1 @@ +.so man5/proc_pid_mounts.5 diff --git a/man5/proc_mtrr.5 b/man5/proc_mtrr.5 new file mode 100644 index 0000000..d2d1991 --- /dev/null +++ b/man5/proc_mtrr.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_mtrr 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/mtrr \- memory type range registers +.SH DESCRIPTION +.TP +.I /proc/mtrr +Memory Type Range Registers. +See the Linux kernel source file +.I Documentation/x86/mtrr.rst +(or +.I Documentation/x86/mtrr.txt +.\" commit 7225e75144b9718cbbe1820d9c011c809d5773fd +before Linux 5.2, or +.I Documentation/mtrr.txt +before Linux 2.6.28) +for details. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_net.5 b/man5/proc_net.5 new file mode 100644 index 0000000..85a0dbd --- /dev/null +++ b/man5/proc_net.5 @@ -0,0 +1 @@ +.so man5/proc_pid_net.5 diff --git a/man5/proc_partitions.5 b/man5/proc_partitions.5 new file mode 100644 index 0000000..ff58779 --- /dev/null +++ b/man5/proc_partitions.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_partitions 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/partitions \- major and minor numbers of partitions +.SH DESCRIPTION +.TP +.I /proc/partitions +Contains the major and minor numbers of each partition as well as the number +of 1024-byte blocks and the partition name. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pci.5 b/man5/proc_pci.5 new file mode 100644 index 0000000..6977571 --- /dev/null +++ b/man5/proc_pci.5 @@ -0,0 +1,28 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pci 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pci \- PCI devices +.SH DESCRIPTION +.TP +.I /proc/pci +This is a listing of all PCI devices found during kernel initialization +and their configuration. +.IP +This file has been deprecated in favor of a new +.I /proc +interface for PCI +.RI ( /proc/bus/pci ). +It became optional in Linux 2.2 (available with +.B CONFIG_PCI_OLD_PROC +set at kernel compilation). +It became once more nonoptionally enabled in Linux 2.4. +Next, it was deprecated in Linux 2.6 (still available with +.B CONFIG_PCI_LEGACY_PROC +set), and finally removed altogether since Linux 2.6.17. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid.5 b/man5/proc_pid.5 new file mode 100644 index 0000000..0d8cdaf --- /dev/null +++ b/man5/proc_pid.5 @@ -0,0 +1,73 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/, /proc/self/ \- process information +.SH DESCRIPTION +.TP +.IR /proc/ pid / +There is a numerical subdirectory for each running process; the +subdirectory is named by the process ID. +Each +.IR /proc/ pid +subdirectory contains the pseudo-files and directories described below. +.IP +The files inside each +.IR /proc/ pid +directory are normally owned by the effective user and +effective group ID of the process. +However, as a security measure, the ownership is made +.I root:root +if the process's "dumpable" attribute is set to a value other than 1. +.IP +Before Linux 4.11, +.\" commit 68eb94f16227336a5773b83ecfa8290f1d6b78ce +.I root:root +meant the "global" root user ID and group ID +(i.e., UID 0 and GID 0 in the initial user namespace). +Since Linux 4.11, +if the process is in a noninitial user namespace that has a +valid mapping for user (group) ID 0 inside the namespace, then +the user (group) ownership of the files under +.IR /proc/ pid +is instead made the same as the root user (group) ID of the namespace. +This means that inside a container, +things work as expected for the container "root" user. +.IP +The process's "dumpable" attribute may change for the following reasons: +.RS +.IP \[bu] 3 +The attribute was explicitly set via the +.BR prctl (2) +.B PR_SET_DUMPABLE +operation. +.IP \[bu] +The attribute was reset to the value in the file +.I /proc/sys/fs/suid_dumpable +(described below), for the reasons described in +.BR prctl (2). +.RE +.IP +Resetting the "dumpable" attribute to 1 reverts the ownership of the +.IR /proc/ pid /* +files to the process's effective UID and GID. +Note, however, that if the effective UID or GID is subsequently modified, +then the "dumpable" attribute may be reset, as described in +.BR prctl (2). +Therefore, it may be desirable to reset the "dumpable" attribute +.I after +making any desired changes to the process's effective UID or GID. +.TP +.I /proc/self/ +This directory refers to the process accessing the +.I /proc +filesystem, +and is identical to the +.I /proc +directory named by the process ID of the same process. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_attr.5 b/man5/proc_pid_attr.5 new file mode 100644 index 0000000..33993a8 --- /dev/null +++ b/man5/proc_pid_attr.5 @@ -0,0 +1,137 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_attr 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/attr/ \- security-related attributes +.SH DESCRIPTION +.TP +.IR /proc/ pid /attr/ +.\" https://lwn.net/Articles/28222/ +.\" From: Stephen Smalley +.\" To: LKML and others +.\" Subject: [RFC][PATCH] Process Attribute API for Security Modules +.\" Date: 08 Apr 2003 16:17:52 -0400 +.\" +.\" http://www.nsa.gov/research/_files/selinux/papers/module/x362.shtml +.\" +The files in this directory provide an API for security modules. +The contents of this directory are files that can be read and written +in order to set security-related attributes. +This directory was added to support SELinux, +but the intention was that the API be general enough to support +other security modules. +For the purpose of explanation, +examples of how SELinux uses these files are provided below. +.IP +This directory is present only if the kernel was configured with +.BR CONFIG_SECURITY . +.TP +.IR /proc/ pid /attr/current " (since Linux 2.6.0)" +The contents of this file represent the current +security attributes of the process. +.IP +In SELinux, this file is used to get the security context of a process. +Prior to Linux 2.6.11, this file could not be used to set the security +context (a write was always denied), since SELinux limited process security +transitions to +.BR execve (2) +(see the description of +.IR /proc/ pid /attr/exec , +below). +Since Linux 2.6.11, SELinux lifted this restriction and began supporting +"set" operations via writes to this node if authorized by policy, +although use of this operation is only suitable for applications that are +trusted to maintain any desired separation between the old and new security +contexts. +.IP +Prior to Linux 2.6.28, SELinux did not allow threads within a +multithreaded process to set their security context via this node +as it would yield an inconsistency among the security contexts of the +threads sharing the same memory space. +Since Linux 2.6.28, SELinux lifted +this restriction and began supporting "set" operations for threads within +a multithreaded process if the new security context is bounded by the old +security context, where the bounded relation is defined in policy and +guarantees that the new security context has a subset of the permissions +of the old security context. +.IP +Other security modules may choose to support "set" operations via +writes to this node. +.TP +.IR /proc/ pid /attr/exec " (since Linux 2.6.0)" +This file represents the attributes to assign to the +process upon a subsequent +.BR execve (2). +.IP +In SELinux, +this is needed to support role/domain transitions, and +.BR execve (2) +is the preferred point to make such transitions because it offers better +control over the initialization of the process in the new security label +and the inheritance of state. +In SELinux, this attribute is reset on +.BR execve (2) +so that the new program reverts to the default behavior for any +.BR execve (2) +calls that it may make. +In SELinux, a process can set +only its own +.IR /proc/ pid /attr/exec +attribute. +.TP +.IR /proc/ pid /attr/fscreate " (since Linux 2.6.0)" +This file represents the attributes to assign to files +created by subsequent calls to +.BR open (2), +.BR mkdir (2), +.BR symlink (2), +and +.BR mknod (2) +.IP +SELinux employs this file to support creation of a file +(using the aforementioned system calls) +in a secure state, +so that there is no risk of inappropriate access being obtained +between the time of creation and the time that attributes are set. +In SELinux, this attribute is reset on +.BR execve (2), +so that the new program reverts to the default behavior for +any file creation calls it may make, but the attribute will persist +across multiple file creation calls within a program unless it is +explicitly reset. +In SELinux, a process can set only its own +.IR /proc/ pid /attr/fscreate +attribute. +.TP +.IR /proc/ pid /attr/keycreate " (since Linux 2.6.18)" +.\" commit 4eb582cf1fbd7b9e5f466e3718a59c957e75254e +If a process writes a security context into this file, +all subsequently created keys +.RB ( add_key (2)) +will be labeled with this context. +For further information, see the kernel source file +.I Documentation/security/keys/core.rst +(or file +.\" commit b68101a1e8f0263dbc7b8375d2a7c57c6216fb76 +.I Documentation/security/keys.txt +between Linux 3.0 and Linux 4.13, or +.\" commit d410fa4ef99112386de5f218dd7df7b4fca910b4 +.I Documentation/keys.txt +before Linux 3.0). +.TP +.IR /proc/ pid /attr/prev " (since Linux 2.6.0)" +This file contains the security context of the process before the last +.BR execve (2); +that is, the previous value of +.IR /proc/ pid /attr/current . +.TP +.IR /proc/ pid /attr/socketcreate " (since Linux 2.6.18)" +.\" commit 42c3e03ef6b298813557cdb997bd6db619cd65a2 +If a process writes a security context into this file, +all subsequently created sockets will be labeled with this context. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_autogroup.5 b/man5/proc_pid_autogroup.5 new file mode 100644 index 0000000..cbf8e4d --- /dev/null +++ b/man5/proc_pid_autogroup.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_autogroup 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +proc_pid_autogroup \- group tasks for the scheduler +.SH DESCRIPTION +.TP +.IR /proc/ pid /autogroup " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_auxv.5 b/man5/proc_pid_auxv.5 new file mode 100644 index 0000000..524414d --- /dev/null +++ b/man5/proc_pid_auxv.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_auxv 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/auxv \- exec(3) information +.SH DESCRIPTION +.TP +.IR /proc/ pid /auxv " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test7 +This contains the contents of the ELF interpreter information passed +to the process at exec time. +The format is one \fIunsigned long\fP ID +plus one \fIunsigned long\fP value for each entry. +The last entry contains two zeros. +See also +.BR getauxval (3). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_cgroup.5 b/man5/proc_pid_cgroup.5 new file mode 100644 index 0000000..c78fde4 --- /dev/null +++ b/man5/proc_pid_cgroup.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cgroup 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/cgroup \- control group +.SH DESCRIPTION +.TP +.IR /proc/ pid /cgroup " (since Linux 2.6.24)" +See +.BR cgroups (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_clear_refs.5 b/man5/proc_pid_clear_refs.5 new file mode 100644 index 0000000..134a3b9 --- /dev/null +++ b/man5/proc_pid_clear_refs.5 @@ -0,0 +1,87 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_clear_refs 5 2023-09-07 "Linux man-pages 6.7" +.SH NAME +/proc/pid/clear_refs \- reset the PG_Referenced and ACCESSED/YOUNG bits +.SH DESCRIPTION +.TP +.IR /proc/ pid /clear_refs " (since Linux 2.6.22)" +.\" commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22) +.\" commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32) +.\" commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11) +.\" +.\" "Clears page referenced bits shown in smaps output" +.\" write-only, writable only by the owner of the process +.IP +This is a write-only file, writable only by owner of the process. +.IP +The following values may be written to the file: +.RS +.TP +1 (since Linux 2.6.22) +.\" Internally: CLEAR_REFS_ALL +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all the pages associated with the process. +(Before Linux 2.6.32, writing any nonzero value to this file +had this effect.) +.TP +2 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_ANON +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all anonymous pages associated with the process. +.TP +3 (since Linux 2.6.32) +.\" Internally: CLEAR_REFS_MAPPED +Reset the PG_Referenced and ACCESSED/YOUNG +bits for all file-mapped pages associated with the process. +.RE +.IP +Clearing the PG_Referenced and ACCESSED/YOUNG bits provides a method +to measure approximately how much memory a process is using. +One first inspects the values in the "Referenced" fields +for the VMAs shown in +.IR /proc/ pid /smaps +to get an idea of the memory footprint of the +process. +One then clears the PG_Referenced and ACCESSED/YOUNG bits +and, after some measured time interval, +once again inspects the values in the "Referenced" fields +to get an idea of the change in memory footprint of the +process during the measured interval. +If one is interested only in inspecting the selected mapping types, +then the value 2 or 3 can be used instead of 1. +.IP +Further values can be written to affect different properties: +.RS +.TP +4 (since Linux 3.11) +Clear the soft-dirty bit for all the pages associated with the process. +.\" Internally: CLEAR_REFS_SOFT_DIRTY +This is used (in conjunction with +.IR /proc/ pid /pagemap ) +by the check-point restore system to discover which pages of a process +have been dirtied since the file +.IR /proc/ pid /clear_refs +was written to. +.TP +5 (since Linux 4.0) +.\" Internally: CLEAR_REFS_MM_HIWATER_RSS +Reset the peak resident set size ("high water mark") to the process's +current resident set size value. +.RE +.IP +Writing any value to +.IR /proc/ pid /clear_refs +other than those listed above has no effect. +.IP +The +.IR /proc/ pid /clear_refs +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_cmdline.5 b/man5/proc_pid_cmdline.5 new file mode 100644 index 0000000..d9e5967 --- /dev/null +++ b/man5/proc_pid_cmdline.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cmdline 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/cmdline \- command line +.SH DESCRIPTION +.TP +.IR /proc/ pid /cmdline +This read-only file holds the complete command line for the process, +unless the process is a zombie. +.\" In Linux 2.3.26, this also used to be true if the process was swapped out. +In the latter case, there is nothing in this file: +that is, a read on this file will return 0 characters. +.IP +For processes which are still running, +the command-line arguments appear in this file +in the same layout as they do in process memory: +If the process is well-behaved, +it is a set of strings separated by null bytes (\[aq]\e0\[aq]), +with a further null byte after the last string. +.IP +This is the common case, +but processes have the freedom to +override the memory region and +break assumptions about the contents or format of the +.IR /proc/ pid /cmdline +file. +.IP +If, after an +.BR execve (2), +the process modifies its +.I argv +strings, those changes will show up here. +This is not the same thing as modifying the +.I argv +array. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ARG_START . +.IP +Think of this file as the command line that the process wants you to see. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_comm.5 b/man5/proc_pid_comm.5 new file mode 100644 index 0000000..492d480 --- /dev/null +++ b/man5/proc_pid_comm.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_comm 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/comm \- command name +.SH DESCRIPTION +.TP +.IR /proc/ pid /comm " (since Linux 2.6.33)" +.\" commit 4614a696bd1c3a9af3a08f0e5874830a85b889d4 +This file exposes the process's +.I comm +value\[em]that is, the command name associated with the process. +Different threads in the same process may have different +.I comm +values, accessible via +.IR /proc/ pid /task/ tid /comm . +A thread may modify its +.I comm +value, or that of any of other thread in the same thread group (see +the discussion of +.B CLONE_THREAD +in +.BR clone (2)), +by writing to the file +.IR /proc/self/task/ tid /comm . +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +.IP +This file provides a superset of the +.BR prctl (2) +.B PR_SET_NAME +and +.B PR_GET_NAME +operations, and is employed by +.BR pthread_setname_np (3) +when used to rename threads other than the caller. +The value in this file is used for the +.I %e +specifier in +.IR /proc/sys/kernel/core_pattern ; +see +.BR core (5). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_coredump_filter.5 b/man5/proc_pid_coredump_filter.5 new file mode 100644 index 0000000..82f48ed --- /dev/null +++ b/man5/proc_pid_coredump_filter.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_coredump_filter 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/coredump_filter \- core dump filter +.SH DESCRIPTION +.TP +.IR /proc/ pid /coredump_filter " (since Linux 2.6.23)" +See +.BR core (5). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_cpuset.5 b/man5/proc_pid_cpuset.5 new file mode 100644 index 0000000..2bdf32d --- /dev/null +++ b/man5/proc_pid_cpuset.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cpuset 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/cpuset \- CPU affinity sets +.SH DESCRIPTION +.TP +.IR /proc/ pid /cpuset " (since Linux 2.6.12)" +.\" and/proc/[pid]/task/[tid]/cpuset +See +.BR cpuset (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_cwd.5 b/man5/proc_pid_cwd.5 new file mode 100644 index 0000000..df99f11 --- /dev/null +++ b/man5/proc_pid_cwd.5 @@ -0,0 +1,36 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_cwd 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/cwd \- symbolic link to current working directory +.SH DESCRIPTION +.TP +.IR /proc/ pid /cwd +This is a symbolic link to the current working directory of the process. +To find out the current working directory of process 20, +for instance, you can do this: +.IP +.in +4n +.EX +.RB "$" " cd /proc/20/cwd; pwd \-P" +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_environ.5 b/man5/proc_pid_environ.5 new file mode 100644 index 0000000..104cbe0 --- /dev/null +++ b/man5/proc_pid_environ.5 @@ -0,0 +1,48 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_environ 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/environ \- initial environment +.SH DESCRIPTION +.TP +.IR /proc/ pid /environ +This file contains the initial environment that was set +when the currently executing program was started via +.BR execve (2). +The entries are separated by null bytes (\[aq]\e0\[aq]), +and there may be a null byte at the end. +Thus, to print out the environment of process 1, you would do: +.IP +.in +4n +.EX +.RB "$" " cat /proc/1/environ | tr \[aq]\e000\[aq] \[aq]\en\[aq]" +.EE +.in +.IP +If, after an +.BR execve (2), +the process modifies its environment +(e.g., by calling functions such as +.BR putenv (3) +or modifying the +.BR environ (7) +variable directly), +this file will +.I not +reflect those changes. +.IP +Furthermore, a process may change the memory location that this file refers via +.BR prctl (2) +operations such as +.BR PR_SET_MM_ENV_START . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_exe.5 b/man5/proc_pid_exe.5 new file mode 100644 index 0000000..21d2fbc --- /dev/null +++ b/man5/proc_pid_exe.5 @@ -0,0 +1,59 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_exe 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/exe \- symbolic link to program pathname +.SH DESCRIPTION +.TP +.IR /proc/ pid /exe +Under Linux 2.2 and later, this file is a symbolic link +containing the actual pathname of the executed command. +This symbolic link can be dereferenced normally; attempting to open +it will open the executable. +You can even type +.IR /proc/ pid /exe +to run another copy of the same executable that is being run by +process +.IR pid . +If the pathname has been unlinked, the symbolic link will contain the +string \[aq]\ (deleted)\[aq] appended to the original pathname. +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this symbolic link +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Under Linux 2.0 and earlier, +.IR /proc/ pid /exe +is a pointer to the binary which was executed, +and appears as a symbolic link. +A +.BR readlink (2) +call on this file under Linux 2.0 returns a string in the format: +.IP +.in +4n +.EX +[device]:inode +.EE +.in +.IP +For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, +MFM, etc. drives) minor 01 (first partition on the first drive). +.IP +.BR find (1) +with the +.I \-inum +option can be used to locate the file. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_fd.5 b/man5/proc_pid_fd.5 new file mode 100644 index 0000000..0489169 --- /dev/null +++ b/man5/proc_pid_fd.5 @@ -0,0 +1,161 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_fd 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/fd/ \- file descriptors +.SH DESCRIPTION +.TP +.IR /proc/ pid /fd/ +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor, and which is a +symbolic link to the actual file. +Thus, 0 is standard input, 1 standard output, 2 standard error, and so on. +.IP +For file descriptors for pipes and sockets, +the entries will be symbolic links whose content is the +file type with the inode. +A +.BR readlink (2) +call on this file returns a string in the format: +.IP +.in +4n +.EX +type:[inode] +.EE +.in +.IP +For example, +.I socket:[2248868] +will be a socket and its inode is 2248868. +For sockets, that inode can be used to find more information +in one of the files under +.IR /proc/net/ . +.IP +For file descriptors that have no corresponding inode +(e.g., file descriptors produced by +.BR bpf (2), +.BR epoll_create (2), +.BR eventfd (2), +.BR inotify_init (2), +.BR perf_event_open (2), +.BR signalfd (2), +.BR timerfd_create (2), +and +.BR userfaultfd (2)), +the entry will be a symbolic link with contents of the form +.IP +.in +4n +.EX +.RI anon_inode: file-type +.EE +.in +.IP +In many cases (but not all), the +.I file-type +is surrounded by square brackets. +.IP +For example, an epoll file descriptor will have a symbolic link +whose content is the string +.IR "anon_inode:[eventpoll]" . +.IP +.\"The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of this directory +are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Programs that take a filename as a command-line argument, +but don't take input from standard input if no argument is supplied, +and programs that write to a file named as a command-line argument, +but don't send their output to standard output +if no argument is supplied, can nevertheless be made to use +standard input or standard output by using +.IR /proc/ pid /fd +files as command-line arguments. +For example, assuming that +.I \-i +is the flag designating an input file and +.I \-o +is the flag designating an output file: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /proc/self/fd/0 \-o /proc/self/fd/1 ..." +.EE +.in +.IP +and you have a working filter. +.\" The following is not true in my tests (MTK): +.\" Note that this will not work for +.\" programs that seek on their files, as the files in the fd directory +.\" are not seekable. +.IP +.I /proc/self/fd/N +is approximately the same as +.I /dev/fd/N +in some UNIX and UNIX-like systems. +Most Linux MAKEDEV scripts symbolically link +.I /dev/fd +to +.IR /proc/self/fd , +in fact. +.IP +Most systems provide symbolic links +.IR /dev/stdin , +.IR /dev/stdout , +and +.IR /dev/stderr , +which respectively link to the files +.IR 0 , +.IR 1 , +and +.I 2 +in +.IR /proc/self/fd . +Thus the example command above could be written as: +.IP +.in +4n +.EX +.RB "$" " foobar \-i /dev/stdin \-o /dev/stdout ..." +.EE +.in +.IP +Permission to dereference or read +.RB ( readlink (2)) +the symbolic links in this directory is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Note that for file descriptors referring to inodes +(pipes and sockets, see above), +those inodes still have permission bits and ownership information +distinct from those of the +.IR /proc/ pid /fd +entry, +and that the owner may differ from the user and group IDs of the process. +An unprivileged process may lack permissions to open them, as in this example: +.IP +.in +4n +.EX +.RB "$" " echo test | sudo \-u nobody cat" +test +.RB "$" " echo test | sudo \-u nobody cat /proc/self/fd/0" +cat: /proc/self/fd/0: Permission denied +.EE +.in +.IP +File descriptor 0 refers to the pipe created by the shell +and owned by that shell's user, which is not +.IR nobody , +so +.B cat +does not have permission +to create a new file descriptor to read from that inode, +even though it can still read from its existing file descriptor 0. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_fdinfo.5 b/man5/proc_pid_fdinfo.5 new file mode 100644 index 0000000..1eeb895 --- /dev/null +++ b/man5/proc_pid_fdinfo.5 @@ -0,0 +1,300 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_fdinfo 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/fdinfo/ \- information about file descriptors +.SH DESCRIPTION +.TP +.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)" +This is a subdirectory containing one entry for each file which the +process has open, named by its file descriptor. +The files in this directory are readable only by the owner of the process. +The contents of each file can be read to obtain information +about the corresponding file descriptor. +The content depends on the type of file referred to by the +corresponding file descriptor. +.IP +For regular files and directories, we see something like: +.IP +.in +4n +.EX +.RB "$" " cat /proc/12015/fdinfo/4" +pos: 1000 +flags: 01002002 +mnt_id: 21 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I pos +This is a decimal number showing the file offset. +.TP +.I flags +This is an octal number that displays the +file access mode and file status flags (see +.BR open (2)). +If the close-on-exec file descriptor flag is set, then +.I flags +will also include the value +.BR O_CLOEXEC . +.IP +Before Linux 3.1, +.\" commit 1117f72ea0217ba0cc19f05adbbd8b9a397f5ab7 +this field incorrectly displayed the setting of +.B O_CLOEXEC +at the time the file was opened, +rather than the current setting of the close-on-exec flag. +.TP +.I +.I mnt_id +This field, present since Linux 3.15, +.\" commit 49d063cb353265c3af701bab215ac438ca7df36d +is the ID of the mount containing this file. +See the description of +.IR /proc/ pid /mountinfo . +.RE +.IP +For eventfd file descriptors (see +.BR eventfd (2)), +we see (since Linux 3.8) +.\" commit cbac5542d48127b546a23d816380a7926eee1c25 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +eventfd\-count: 40 +.EE +.in +.IP +.I eventfd\-count +is the current value of the eventfd counter, in hexadecimal. +.IP +For epoll file descriptors (see +.BR epoll (7)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +tfd: 9 events: 19 data: 74253d2500000009 +tfd: 7 events: 19 data: 74253d2500000007 +.EE +.in +.IP +Each of the lines beginning +.I tfd +describes one of the file descriptors being monitored via +the epoll file descriptor (see +.BR epoll_ctl (2) +for some details). +The +.I tfd +field is the number of the file descriptor. +The +.I events +field is a hexadecimal mask of the events being monitored for this file +descriptor. +The +.I data +field is the data value associated with this file descriptor. +.IP +For signalfd file descriptors (see +.BR signalfd (2)), +we see (since Linux 3.8) +.\" commit 138d22b58696c506799f8de759804083ff9effae +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 10 +sigmask: 0000000000000006 +.EE +.in +.IP +.I sigmask +is the hexadecimal mask of signals that are accepted via this +signalfd file descriptor. +(In this example, bits 2 and 3 are set, corresponding to the signals +.B SIGINT +and +.BR SIGQUIT ; +see +.BR signal (7).) +.IP +For inotify file descriptors (see +.BR inotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 00 +mnt_id: 11 +inotify wd:2 ino:7ef82a sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:2af87e00220ffd73 +inotify wd:1 ino:192627 sdev:800001 mask:800afff ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:27261900802dfd73 +.EE +.in +.IP +Each of the lines beginning with "inotify" displays information about +one file or directory that is being monitored. +The fields in this line are as follows: +.RS +.TP +.I wd +A watch descriptor number (in decimal). +.TP +.I ino +The inode number of the target file (in hexadecimal). +.TP +.I sdev +The ID of the device where the target file resides (in hexadecimal). +.TP +.I mask +The mask of events being monitored for the target file (in hexadecimal). +.RE +.IP +If the kernel was built with exportfs support, the path to the target +file is exposed as a file handle, via three hexadecimal fields: +.IR fhandle\-bytes , +.IR fhandle\-type , +and +.IR f_handle . +.IP +For fanotify file descriptors (see +.BR fanotify (7)), +we see (since Linux 3.8) +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02 +mnt_id: 11 +fanotify flags:0 event\-flags:88002 +fanotify ino:19264f sdev:800001 mflags:0 mask:1 ignored_mask:0 fhandle\-bytes:8 fhandle\-type:1 f_handle:4f261900a82dfd73 +.EE +.in +.IP +The fourth line displays information defined when the fanotify group +was created via +.BR fanotify_init (2): +.RS +.TP +.I flags +The +.I flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.TP +.I event\-flags +The +.I event_f_flags +argument given to +.BR fanotify_init (2) +(expressed in hexadecimal). +.RE +.IP +Each additional line shown in the file contains information +about one of the marks in the fanotify group. +Most of these fields are as for inotify, except: +.RS +.TP +.I mflags +The flags associated with the mark +(expressed in hexadecimal). +.TP +.I mask +The events mask for this mark +(expressed in hexadecimal). +.TP +.I ignored_mask +The mask of events that are ignored for this mark +(expressed in hexadecimal). +.RE +.IP +For details on these fields, see +.BR fanotify_mark (2). +.IP +For timerfd file descriptors (see +.BR timerfd (2)), +we see (since Linux 3.17) +.\" commit af9c4957cf212ad9cf0bee34c95cb11de5426e85 +the following fields: +.IP +.in +4n +.EX +pos: 0 +flags: 02004002 +mnt_id: 13 +clockid: 0 +ticks: 0 +settime flags: 03 +it_value: (7695568592, 640020877) +it_interval: (0, 0) +.EE +.in +.RS +.TP +.I clockid +This is the numeric value of the clock ID +(corresponding to one of the +.B CLOCK_* +constants defined via +.IR ) +that is used to mark the progress of the timer (in this example, 0 is +.BR CLOCK_REALTIME ). +.TP +.I ticks +This is the number of timer expirations that have occurred, +(i.e., the value that +.BR read (2) +on it would return). +.TP +.I settime flags +This field lists the flags with which the timerfd was last armed (see +.BR timerfd_settime (2)), +in octal +(in this example, both +.B TFD_TIMER_ABSTIME +and +.B TFD_TIMER_CANCEL_ON_SET +are set). +.TP +.I it_value +This field contains the amount of time until the timer will next expire, +expressed in seconds and nanoseconds. +This is always expressed as a relative value, +regardless of whether the timer was created using the +.B TFD_TIMER_ABSTIME +flag. +.TP +.I it_interval +This field contains the interval of the timer, +in seconds and nanoseconds. +(The +.I it_value +and +.I it_interval +fields contain the values that +.BR timerfd_gettime (2) +on this file descriptor would return.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_gid_map.5 b/man5/proc_pid_gid_map.5 new file mode 100644 index 0000000..4637389 --- /dev/null +++ b/man5/proc_pid_gid_map.5 @@ -0,0 +1 @@ +.so man5/proc_pid_uid_map.5 diff --git a/man5/proc_pid_io.5 b/man5/proc_pid_io.5 new file mode 100644 index 0000000..4ad79f5 --- /dev/null +++ b/man5/proc_pid_io.5 @@ -0,0 +1,100 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_io 5 2024-03-18 "Linux man-pages 6.7" +.SH NAME +/proc/pid/io \- I/O statistics +.SH DESCRIPTION +.TP +.IR /proc/ pid /io " (since Linux 2.6.20)" +.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2 +This file contains I/O statistics +for the process and its waited-for children, +for example: +.IP +.in +4n +.EX +.RB "#" " cat /proc/3828/io" +rchar: 323934931 +wchar: 323929600 +syscr: 632687 +syscw: 632675 +read_bytes: 0 +write_bytes: 323932160 +cancelled_write_bytes: 0 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.IR rchar ": characters read" +The number of bytes +returned by successful +.BR read (2) +and similar system calls. +.TP +.IR wchar ": characters written" +The number of bytes +returned by successful +.BR write (2) +and similar system calls. +.TP +.IR syscr ": read syscalls" +The number of "file read" system calls\[em]those from the +.BR read (2) +family, +.BR sendfile (2), +.BR copy_file_range (2), +and +.BR ioctl (2) +.BR BTRFS_IOC_ENCODED_READ [ _32 ] +(including when invoked by the kernel as part of other syscalls). +.TP +.IR syscw ": write syscalls" +The number of "file write" system calls\[em]those from the +.BR write (2) +family, +.BR sendfile (2), +.BR copy_file_range (2), +and +.BR ioctl (2) +.BR BTRFS_IOC_ENCODED_WRITE [ _32 ] +(including when invoked by the kernel as part of other syscalls). +.TP +.IR read_bytes ": bytes read" +The number of bytes really fetched from the storage layer. +This is accurate for block-backed filesystems. +.TP +.IR write_bytes ": bytes written" +The number of bytes really sent to the storage layer. +.TP +.IR cancelled_write_bytes : +The above statistics fail to account for truncation: +if a process writes 1 MB to a regular file and then removes it, +said 1 MB will not be written, but +.I will +have nevertheless been accounted as a 1 MB write. +This field represents the number of bytes "saved" from I/O writeback. +This can yield to having done negative I/O +if caches dirtied by another process are truncated. +.I cancelled_write_bytes +applies to I/O already accounted-for in +.IR write_bytes . +.RE +.IP +Permission to access this file is governed by +.BR ptrace (2) +access mode +.BR PTRACE_MODE_READ_FSCREDS . +.SH CAVEATS +These counters are not atomic: +on systems where 64-bit integer operations may tear, +a counter could be updated simultaneously with a read, +yielding an incorrect intermediate value. +.SH SEE ALSO +.BR getrusage (2), +.BR proc (5) diff --git a/man5/proc_pid_limits.5 b/man5/proc_pid_limits.5 new file mode 100644 index 0000000..a8ab93c --- /dev/null +++ b/man5/proc_pid_limits.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_oid_limits 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/limits \- resource limits +.SH DESCRIPTION +.TP +.IR /proc/ pid /limits " (since Linux 2.6.24)" +This file displays the soft limit, hard limit, and units of measurement +for each of the process's resource limits (see +.BR getrlimit (2)). +Up to and including Linux 2.6.35, +this file is protected to allow reading only by the real UID of the process. +Since Linux 2.6.36, +.\" commit 3036e7b490bf7878c6dae952eec5fb87b1106589 +this file is readable by all users on the system. +.\" FIXME Describe /proc/[pid]/loginuid +.\" Added in Linux 2.6.11; updating requires CAP_AUDIT_CONTROL +.\" CONFIG_AUDITSYSCALL +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_map_files.5 b/man5/proc_pid_map_files.5 new file mode 100644 index 0000000..5b50c45 --- /dev/null +++ b/man5/proc_pid_map_files.5 @@ -0,0 +1,72 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_map_files 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/map_files/ \- memory-mapped files +.SH DESCRIPTION +.TP +.IR /proc/ pid /map_files/ " (since Linux 3.3)" +.\" commit 640708a2cff7f81e246243b0073c66e6ece7e53e +This subdirectory contains entries corresponding to memory-mapped +files (see +.BR mmap (2)). +Entries are named by memory region start and end +address pair (expressed as hexadecimal numbers), +and are symbolic links to the mapped files themselves. +Here is an example, +with the output wrapped and reformatted to fit on an 80-column display: +.IP +.in +4n +.EX +.RB "#" " ls \-l /proc/self/map_files/" +lr\-\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:31 + 3252e00000\-3252e20000 \-> /usr/lib64/ld\-2.15.so +\&... +.EE +.in +.IP +Although these entries are present for memory regions that were +mapped with the +.B MAP_FILE +flag, the way anonymous shared memory (regions created with the +.B MAP_ANON | MAP_SHARED +flags) +is implemented in Linux +means that such regions also appear on this directory. +Here is an example where the target file is the deleted +.I /dev/zero +one: +.IP +.in +4n +.EX +lrw\-\-\-\-\-\-\-. 1 root root 64 Apr 16 21:33 + 7fc075d2f000\-7fc075e6f000 \-> /dev/zero (deleted) +.EE +.in +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +Until Linux 4.3, +.\" commit bdb4d100afe9818aebd1d98ced575c5ef143456c +this directory appeared only if the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option was enabled. +.IP +Capabilities are required to read the contents of the symbolic links in +this directory: before Linux 5.9, the reading process requires +.B CAP_SYS_ADMIN +in the initial user namespace; +since Linux 5.9, the reading process must have either +.B CAP_SYS_ADMIN +or +.B CAP_CHECKPOINT_RESTORE +in the initial (i.e. root) user namespace. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_maps.5 b/man5/proc_pid_maps.5 new file mode 100644 index 0000000..25fbbde --- /dev/null +++ b/man5/proc_pid_maps.5 @@ -0,0 +1,156 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_maps 5 2023-09-07 "Linux man-pages 6.7" +.SH NAME +/proc/pid/maps \- mapped memory regions +.SH DESCRIPTION +.TP +.IR /proc/ pid /maps +A file containing the currently mapped memory regions and their access +permissions. +See +.BR mmap (2) +for some further information about memory mappings. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.IP +The format of the file is: +.IP +.in +4n +.EX +.I "address perms offset dev inode pathname" +00400000\-00452000 r\-xp 00000000 08:02 173521 /usr/bin/dbus\-daemon +00651000\-00652000 r\-\-p 00051000 08:02 173521 /usr/bin/dbus\-daemon +00652000\-00655000 rw\-p 00052000 08:02 173521 /usr/bin/dbus\-daemon +00e03000\-00e24000 rw\-p 00000000 00:00 0 [heap] +00e24000\-011f7000 rw\-p 00000000 00:00 0 [heap] +\&... +35b1800000\-35b1820000 r\-xp 00000000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a1f000\-35b1a20000 r\-\-p 0001f000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a20000\-35b1a21000 rw\-p 00020000 08:02 135522 /usr/lib64/ld\-2.15.so +35b1a21000\-35b1a22000 rw\-p 00000000 00:00 0 +35b1c00000\-35b1dac000 r\-xp 00000000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1dac000\-35b1fac000 \-\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fac000\-35b1fb0000 r\-\-p 001ac000 08:02 135870 /usr/lib64/libc\-2.15.so +35b1fb0000\-35b1fb2000 rw\-p 001b0000 08:02 135870 /usr/lib64/libc\-2.15.so +\&... +f2c6ff8c000\-7f2c7078c000 rw\-p 00000000 00:00 0 [stack:986] +\&... +7fffb2c0d000\-7fffb2c2e000 rw\-p 00000000 00:00 0 [stack] +7fffb2d48000\-7fffb2d49000 r\-xp 00000000 00:00 0 [vdso] +.EE +.in +.IP +The +.I address +field is the address space in the process that the mapping occupies. +The +.I perms +field is a set of permissions: +.IP +.in +4n +.EX +r = read +w = write +x = execute +s = shared +p = private (copy on write) +.EE +.in +.IP +The +.I offset +field is the offset into the file/whatever; +.I dev +is the device +(major:minor); +.I inode +is the inode on that device. +0 indicates that no inode is associated with the memory region, +as would be the case with BSS (uninitialized data). +.IP +The +.I pathname +field will usually be the file that is backing the mapping. +For ELF files, +you can easily coordinate with the +.I offset +field by looking at the +Offset field in the ELF program headers +.RI ( "readelf\ \-l" ). +.IP +There are additional helpful pseudo-paths: +.RS +.TP +.I [stack] +The initial process's (also known as the main thread's) stack. +.TP +.IR [stack: tid ] " (from Linux 3.4 to Linux 4.4)" +.\" commit b76437579d1344b612cf1851ae610c636cec7db0 (added) +.\" commit 65376df582174ffcec9e6471bf5b0dd79ba05e4a (removed) +A thread's stack (where the +.I tid +is a thread ID). +It corresponds to the +.IR /proc/ pid /task/ tid / +path. +This field was removed in Linux 4.5, since providing this information +for a process with large numbers of threads is expensive. +.TP +.I [vdso] +The virtual dynamically linked shared object. +See +.BR vdso (7). +.TP +.I [heap] +The process's heap. +.TP +.IR [anon: name ] " (since Linux 5.17)" +.\" Commit 9a10064f5625d5572c3626c1516e0bebc6c9fe9b +A named private anonymous mapping. +Set with +.BR prctl (2) +.BR PR_SET_VMA_ANON_NAME . +.TP +.IR [anon_shmem: name ] " (since Linux 6.2)" +.\" Commit d09e8ca6cb93bb4b97517a18fbbf7eccb0e9ff43 +A named shared anonymous mapping. +Set with +.BR prctl (2) +.BR PR_SET_VMA_ANON_NAME . +.in +.RE +.IP +If the +.I pathname +field is blank, +this is an anonymous mapping as obtained via +.BR mmap (2). +There is no easy way to coordinate this back to a process's source, +short of running it through +.BR gdb (1), +.BR strace (1), +or similar. +.IP +.I pathname +is shown unescaped except for newline characters, which are replaced +with an octal escape sequence. +As a result, it is not possible to determine whether the original +pathname contained a newline character or the literal +.I \e012 +character sequence. +.IP +If the mapping is file-backed and the file has been deleted, the string +" (deleted)" is appended to the pathname. +Note that this is ambiguous too. +.IP +Under Linux 2.0, there is no field giving pathname. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_mem.5 b/man5/proc_pid_mem.5 new file mode 100644 index 0000000..b54206d --- /dev/null +++ b/man5/proc_pid_mem.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mem 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/mem \- memory +.SH DESCRIPTION +.TP +.IR /proc/ pid /mem +This file can be used to access the pages of a process's memory through +.BR open (2), +.BR read (2), +and +.BR lseek (2). +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_mountinfo.5 b/man5/proc_pid_mountinfo.5 new file mode 100644 index 0000000..257c1db --- /dev/null +++ b/man5/proc_pid_mountinfo.5 @@ -0,0 +1,124 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mountinfo 5 2023-11-24 "Linux man-pages 6.7" +.SH NAME +/proc/pid/mountinfo \- mount information +.SH DESCRIPTION +.TP +.IR /proc/ pid /mountinfo " (since Linux 2.6.26)" +.\" This info adapted from Documentation/filesystems/proc.txt +.\" commit 2d4d4864ac08caff5c204a752bd004eed4f08760 +This file contains information about mounts +in the process's mount namespace (see +.BR mount_namespaces (7)). +It supplies various information +(e.g., propagation state, root of mount for bind mounts, +identifier for each mount and its parent) that is missing from the (older) +.IR /proc/ pid /mounts +file, and fixes various other problems with that file +(e.g., nonextensibility, +failure to distinguish per-mount versus per-superblock options). +.IP +The file contains lines of the form: +.IP +.EX +36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 \- ext3 /dev/root rw,errors=continue +(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11) +.EE +.IP +The numbers in parentheses are labels for the descriptions below: +.RS 7 +.TP 5 +(1) +mount ID: a unique ID for the mount (may be reused after +.BR umount (2)). +.TP +(2) +parent ID: the ID of the parent mount +(or of self for the root of this mount namespace's mount tree). +.IP +If a new mount is stacked on top of a previous existing mount +(so that it hides the existing mount) at pathname P, +then the parent of the new mount is the previous mount at that location. +Thus, when looking at all the mounts stacked at a particular location, +the top-most mount is the one that is not the parent +of any other mount at the same location. +(Note, however, that this top-most mount will be accessible only if +the longest path subprefix of P that is a mount point +is not itself hidden by a stacked mount.) +.IP +If the parent mount lies outside the process's root directory (see +.BR chroot (2)), +the ID shown here won't have a corresponding record in +.I mountinfo +whose mount ID (field 1) matches this parent mount ID +(because mounts that lie outside the process's root directory +are not shown in +.IR mountinfo ). +As a special case of this point, +the process's root mount may have a parent mount +(for the initramfs filesystem) that lies +.\" Miklos Szeredi, Nov 2017: The hidden one is the initramfs, I believe +.\" mtk: In the initial mount namespace, this hidden ID has the value 0 +outside the process's root directory, +and an entry for that mount will not appear in +.IR mountinfo . +.TP +(3) +major:minor: the value of +.I st_dev +for files on this filesystem (see +.BR stat (2)). +.TP +(4) +root: the pathname of the directory in the filesystem +which forms the root of this mount. +.TP +(5) +mount point: the pathname of the mount point relative +to the process's root directory. +.TP +(6) +mount options: per-mount options (see +.BR mount (2)). +.TP +(7) +optional fields: zero or more fields of the form "tag[:value]"; see below. +.TP +(8) +separator: the end of the optional fields is marked by a single hyphen. +.TP +(9) +filesystem type: the filesystem type in the form "type[.subtype]". +.TP +(10) +mount source: filesystem-specific information or "none". +.TP +(11) +super options: per-superblock options (see +.BR mount (2)). +.RE +.IP +Currently, the possible optional fields are +.IR shared , +.IR master , +.IR propagate_from , +and +.IR unbindable . +See +.BR mount_namespaces (7) +for a description of these fields. +Parsers should ignore all unrecognized optional fields. +.IP +For more information on mount propagation see +.I Documentation/filesystems/sharedsubtree.rst +(or +.I Documentation/filesystems/sharedsubtree.txt +before Linux 5.8) +in the Linux kernel source tree. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_mounts.5 b/man5/proc_pid_mounts.5 new file mode 100644 index 0000000..bcb32f2 --- /dev/null +++ b/man5/proc_pid_mounts.5 @@ -0,0 +1,49 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mounts 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/mounts \- mounted filesystems +.SH DESCRIPTION +.TP +.IR /proc/ pid /mounts " (since Linux 2.4.19)" +This file lists all the filesystems currently mounted in the +process's mount namespace (see +.BR mount_namespaces (7)). +The format of this file is documented in +.BR fstab (5). +.IP +Since Linux 2.6.15, this file is pollable: +after opening the file for reading, a change in this file +(i.e., a filesystem mount or unmount) causes +.BR select (2) +to mark the file descriptor as having an exceptional condition, and +.BR poll (2) +and +.BR epoll_wait (2) +mark the file as having a priority event +.RB ( POLLPRI ). +(Before Linux 2.6.30, +a change in this file was indicated by the file descriptor +being marked as readable for +.BR select (2), +and being marked as having an error condition for +.BR poll (2) +and +.BR epoll_wait (2).) +.TP +.I /proc/mounts +Before Linux 2.4.19, this file was a list +of all the filesystems currently mounted on the system. +With the introduction of per-process mount namespaces in Linux 2.4.19 (see +.BR mount_namespaces (7)), +this file became a link to +.IR /proc/self/mounts , +which lists the mounts of the process's own mount namespace. +The format of this file is documented in +.BR fstab (5). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_mountstats.5 b/man5/proc_pid_mountstats.5 new file mode 100644 index 0000000..1205b14 --- /dev/null +++ b/man5/proc_pid_mountstats.5 @@ -0,0 +1,46 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_mountstats 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/mountstats \- mount statistics +.SH DESCRIPTION +.TP +.IR /proc/ pid /mountstats " (since Linux 2.6.17)" +This file exports information (statistics, configuration information) +about the mounts in the process's mount namespace (see +.BR mount_namespaces (7)). +Lines in this file have the form: +.IP +.in +4n +.EX +device /dev/sda7 mounted on /home with fstype ext3 [stats] +( 1 ) ( 2 ) (3 ) ( 4 ) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The name of the mounted device +(or "nodevice" if there is no corresponding device). +.TP +(2) +The mount point within the filesystem tree. +.TP +(3) +The filesystem type. +.TP +(4) +Optional statistics and configuration information. +Currently (as at Linux 2.6.26), only NFS filesystems export +information via this field. +.RE +.IP +This file is readable only by the owner of the process. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_net.5 b/man5/proc_pid_net.5 new file mode 100644 index 0000000..590e87d --- /dev/null +++ b/man5/proc_pid_net.5 @@ -0,0 +1,298 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Alan Cox +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_net 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/net/, /proc/net/ \- network layer information +.SH DESCRIPTION +.TP +.IR /proc/ pid /net/ " (since Linux 2.6.25)" +See the description of +.IR /proc/net . +.TP +.I /proc/net/ +This directory contains various files and subdirectories containing +information about the networking layer. +The files contain ASCII structures and are, +therefore, readable with +.BR cat (1). +However, the standard +.BR netstat (8) +suite provides much cleaner access to these files. +.IP +With the advent of network namespaces, +various information relating to the network stack is virtualized (see +.BR network_namespaces (7)). +Thus, since Linux 2.6.25, +.\" commit e9720acd728a46cb40daa52c99a979f7c4ff195c +.I /proc/net +is a symbolic link to the directory +.IR /proc/self/net , +which contains the same files and directories as listed below. +However, these files and directories now expose information +for the network namespace of which the process is a member. +.TP +.I /proc/net/arp +This holds an ASCII readable dump of the kernel ARP table used for +address resolutions. +It will show both dynamically learned and preprogrammed ARP entries. +The format is: +.IP +.in +4n +.EX +IP address HW type Flags HW address Mask Device +192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0 +192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0 +.EE +.in +.IP +Here "IP address" is the IPv4 address of the machine and the "HW type" +is the hardware type of the address from RFC\ 826. +The flags are the internal +flags of the ARP structure (as defined in +.IR /usr/include/linux/if_arp.h ) +and +the "HW address" is the data link layer mapping for that IP address if +it is known. +.TP +.I /proc/net/dev +The dev pseudo-file contains network device status information. +This gives +the number of received and sent packets, the number of errors and +collisions +and other basic statistics. +These are used by the +.BR ifconfig (8) +program to report device status. +The format is: +.IP +.EX +Inter\-| Receive | Transmit + face |bytes packets errs drop fifo frame compressed multicast|bytes packets errs drop fifo colls carrier compressed + lo: 2776770 11307 0 0 0 0 0 0 2776770 11307 0 0 0 0 0 0 + eth0: 1215645 2751 0 0 0 0 0 0 1782404 4324 0 0 0 427 0 0 + ppp0: 1622270 5552 1 0 0 0 0 0 354130 5669 0 0 0 0 0 0 + tap0: 7714 81 0 0 0 0 0 0 7714 81 0 0 0 0 0 0 +.EE +.\" .TP +.\" .I /proc/net/ipx +.\" No information. +.\" .TP +.\" .I /proc/net/ipx_route +.\" No information. +.TP +.I /proc/net/dev_mcast +Defined in +.IR /usr/src/linux/net/core/dev_mcast.c : +.IP +.in +4n +.EX +indx interface_name dmi_u dmi_g dmi_address +2 eth0 1 0 01005e000001 +3 eth1 1 0 01005e000001 +4 eth2 1 0 01005e000001 +.EE +.in +.TP +.I /proc/net/igmp +Internet Group Management Protocol. +Defined in +.IR /usr/src/linux/net/core/igmp.c . +.TP +.I /proc/net/rarp +This file uses the same format as the +.I arp +file and contains the current reverse mapping database used to provide +.BR rarp (8) +reverse address lookup services. +If RARP is not configured into the +kernel, +this file will not be present. +.TP +.I /proc/net/raw +Holds a dump of the RAW socket table. +Much of the information is not of +use +apart from debugging. +The "sl" value is the kernel hash slot for the +socket, +the "local_address" is the local address and protocol number pair. +\&"St" is +the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields are not used by RAW. +The "uid" +field holds the effective UID of the creator of the socket. +.\" .TP +.\" .I /proc/net/route +.\" No information, but looks similar to +.\" .BR route (8). +.TP +.I /proc/net/snmp +This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP +management +information bases for an SNMP agent. +.TP +.I /proc/net/tcp +Holds a dump of the TCP socket table. +Much of the information is not +of use apart from debugging. +The "sl" value is the kernel hash slot +for the socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +\&"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the +outgoing and incoming data queue in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields hold internal information of +the kernel socket state and are useful only for debugging. +The "uid" +field holds the effective UID of the creator of the socket. +.TP +.I /proc/net/udp +Holds a dump of the UDP socket table. +Much of the information is not of +use apart from debugging. +The "sl" value is the kernel hash slot for the +socket, the "local_address" is the local address and port number pair. +The "rem_address" is the remote address and port number pair +(if connected). +"St" is the internal status of the socket. +The "tx_queue" and "rx_queue" are the outgoing and incoming data queue +in terms of kernel memory usage. +The "tr", "tm\->when", and "rexmits" fields +are not used by UDP. +The "uid" +field holds the effective UID of the creator of the socket. +The format is: +.IP +.EX +sl local_address rem_address st tx_queue rx_queue tr rexmits tm\->when uid + 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 0 + 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 0 + 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 +.EE +.TP +.I /proc/net/unix +Lists the UNIX domain sockets present within the system and their +status. +The format is: +.IP +.EX +Num RefCount Protocol Flags Type St Inode Path + 0: 00000002 00000000 00000000 0001 03 42 + 1: 00000001 00000000 00010000 0001 01 1948 /dev/printer +.EE +.IP +The fields are as follows: +.RS +.TP 10 +.IR Num : +the kernel table slot number. +.TP +.IR RefCount : +the number of users of the socket. +.TP +.IR Protocol : +currently always 0. +.TP +.IR Flags : +the internal kernel flags holding the status of the socket. +.TP +.IR Type : +the socket type. +For +.B SOCK_STREAM +sockets, this is 0001; for +.B SOCK_DGRAM +sockets, it is 0002; and for +.B SOCK_SEQPACKET +sockets, it is 0005. +.TP +.IR St : +the internal state of the socket. +.TP +.IR Inode : +the inode number of the socket. +.TP +.IR Path : +the bound pathname (if any) of the socket. +Sockets in the abstract namespace are included in the list, +and are shown with a +.I Path +that commences with the character '@'. +.RE +.TP +.I /proc/net/netfilter/nfnetlink_queue +This file contains information about netfilter user-space queueing, if used. +Each line represents a queue. +Queues that have not been subscribed to +by user space are not shown. +.IP +.in +4n +.EX + 1 4207 0 2 65535 0 0 0 1 + (1) (2) (3)(4) (5) (6) (7) (8) +.EE +.in +.IP +The fields in each line are: +.RS 7 +.TP 5 +(1) +The ID of the queue. +This matches what is specified in the +.B \-\-queue\-num +or +.B \-\-queue\-balance +options to the +.BR iptables (8) +NFQUEUE target. +See +.BR iptables\-extensions (8) +for more information. +.TP +(2) +The netlink port ID subscribed to the queue. +.TP +(3) +The number of packets currently queued and waiting to be processed by +the application. +.TP +(4) +The copy mode of the queue. +It is either 1 (metadata only) or 2 +(also copy payload data to user space). +.TP +(5) +Copy range; that is, how many bytes of packet payload should be copied to +user space at most. +.TP +(6) +queue dropped. +Number of packets that had to be dropped by the kernel because +too many packets are already waiting for user space to send back the mandatory +accept/drop verdicts. +.TP +(7) +queue user dropped. +Number of packets that were dropped within the netlink +subsystem. +Such drops usually happen when the corresponding socket buffer is +full; that is, user space is not able to read messages fast enough. +.TP +(8) +sequence number. +Every queued packet is associated with a (32-bit) +monotonically increasing sequence number. +This shows the ID of the most recent packet queued. +.RE +.IP +The last number exists only for compatibility reasons and is always 1. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_ns.5 b/man5/proc_pid_ns.5 new file mode 100644 index 0000000..bf83ab5 --- /dev/null +++ b/man5/proc_pid_ns.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_ns 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/ns/ \- namespaces +.SH DESCRIPTION +.TP +.IR /proc/ pid /ns/ " (since Linux 3.0)" +.\" See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f +This is a subdirectory containing one entry for each namespace that +supports being manipulated by +.BR setns (2). +For more information, see +.BR namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_numa_maps.5 b/man5/proc_pid_numa_maps.5 new file mode 100644 index 0000000..4b29fab --- /dev/null +++ b/man5/proc_pid_numa_maps.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_numa_maps 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/numa_maps \- NUMA memory policy and allocation +.SH DESCRIPTION +.TP +.IR /proc/ pid /numa_maps " (since Linux 2.6.14)" +See +.BR numa (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_oom_adj.5 b/man5/proc_pid_oom_adj.5 new file mode 100644 index 0000000..5112044 --- /dev/null +++ b/man5/proc_pid_oom_adj.5 @@ -0,0 +1 @@ +.so man5/proc_pid_oom_score_adj.5 diff --git a/man5/proc_pid_oom_score.5 b/man5/proc_pid_oom_score.5 new file mode 100644 index 0000000..ddaeddf --- /dev/null +++ b/man5/proc_pid_oom_score.5 @@ -0,0 +1,58 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_oom_score 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/oom_score \- OOM-killer score +.SH DESCRIPTION +.TP +.IR /proc/ pid /oom_score " (since Linux 2.6.11)" +.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +This file displays the current score that the kernel gives to +this process for the purpose of selecting a process +for the OOM-killer. +A higher score means that the process is more likely to be +selected by the OOM-killer. +The basis for this score is the amount of memory used by the process, +with increases (+) or decreases (\-) for factors including: +.\" See mm/oom_kill.c::badness() before Linux 2.6.36 sources +.\" See mm/oom_kill.c::oom_badness() after Linux 2.6.36 +.\" commit a63d83f427fbce97a6cea0db2e64b0eb8435cd10 +.RS +.IP \[bu] 3 +whether the process is privileged (\-). +.\" More precisely, if it has CAP_SYS_ADMIN or (pre 2.6.36) CAP_SYS_RESOURCE +.RE +.IP +Before Linux 2.6.36 +the following factors were also used in the calculation of oom_score: +.RS +.IP \[bu] 3 +whether the process creates a lot of children using +.BR fork (2) +(+); +.IP \[bu] +whether the process has been running a long time, +or has used a lot of CPU time (\-); +.IP \[bu] +whether the process has a low nice value (i.e., > 0) (+); and +.IP \[bu] +whether the process is making direct hardware access (\-). +.\" More precisely, if it has CAP_SYS_RAWIO +.RE +.IP +The +.I oom_score +also reflects the adjustment specified by the +.I oom_score_adj +or +.I oom_adj +setting for the process. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_oom_score_adj (5) diff --git a/man5/proc_pid_oom_score_adj.5 b/man5/proc_pid_oom_score_adj.5 new file mode 100644 index 0000000..a068e33 --- /dev/null +++ b/man5/proc_pid_oom_score_adj.5 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_oom_score_adj 5 2023-11-24 "Linux man-pages 6.7" +.SH NAME +/proc/pid/oom_score_adj \- OOM-killer score adjustment +.SH DESCRIPTION +.TP +.IR /proc/ pid /oom_score_adj " (since Linux 2.6.36)" +.\" Text taken from Linux 3.7 Documentation/filesystems/proc.txt +This file can be used to adjust the badness heuristic used to select which +process gets killed in out-of-memory conditions. +.IP +The badness heuristic assigns a value to each candidate task ranging from 0 +(never kill) to 1000 (always kill) to determine which process is targeted. +The units are roughly a proportion along that range of +allowed memory the process may allocate from, +based on an estimation of its current memory and swap use. +For example, if a task is using all allowed memory, +its badness score will be 1000. +If it is using half of its allowed memory, its score will be 500. +.IP +There is an additional factor included in the badness score: root +processes are given 3% extra memory over other tasks. +.IP +The amount of "allowed" memory depends on the context +in which the OOM-killer was called. +If it is due to the memory assigned to the allocating task's cpuset +being exhausted, +the allowed memory represents the set of mems assigned to that +cpuset (see +.BR cpuset (7)). +If it is due to a mempolicy's node(s) being exhausted, +the allowed memory represents the set of mempolicy nodes. +If it is due to a memory limit (or swap limit) being reached, +the allowed memory is that configured limit. +Finally, if it is due to the entire system being out of memory, the +allowed memory represents all allocatable resources. +.IP +The value of +.I oom_score_adj +is added to the badness score before it +is used to determine which task to kill. +Acceptable values range from \-1000 +(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). +This allows user space to control the preference for OOM-killing, +ranging from always preferring a certain +task or completely disabling it from OOM-killing. +The lowest possible value, \-1000, is +equivalent to disabling OOM-killing entirely for that task, +since it will always report a badness score of 0. +.IP +Consequently, it is very simple for user space to define +the amount of memory to consider for each task. +Setting an +.I oom_score_adj +value of +500, for example, +is roughly equivalent to allowing the remainder of tasks sharing the +same system, cpuset, mempolicy, or memory controller resources +to use at least 50% more memory. +A value of \-500, on the other hand, would be roughly +equivalent to discounting 50% of the task's +allowed memory from being considered as scoring against the task. +.IP +For backward compatibility with previous kernels, +.IR /proc/ pid /oom_adj +can still be used to tune the badness score. +Its value is +scaled linearly with +.IR oom_score_adj . +.IP +Writing to +.IR /proc/ pid /oom_score_adj +or +.IR /proc/ pid /oom_adj +will change the other with its scaled value. +.IP +The +.BR choom (1) +program provides a command-line interface for adjusting the +.I oom_score_adj +value of a running process or a newly executed command. +.SH HISTORY +.TP +.IR /proc/ pid /oom_adj " (since Linux 2.6.11)" +This file can be used to adjust the score used to select which process +should be killed in an out-of-memory (OOM) situation. +The kernel uses this value for a bit-shift operation of the process's +.I oom_score +value: +valid values are in the range \-16 to +15, +plus the special value \-17, +which disables OOM-killing altogether for this process. +A positive score increases the likelihood of this +process being killed by the OOM-killer; +a negative score decreases the likelihood. +.IP +The default value for this file is 0; +a new process inherits its parent's +.I oom_adj +setting. +A process must be privileged +.RB ( CAP_SYS_RESOURCE ) +to update this file, +although a process can always increase its own +.I oom_adj +setting (since Linux 2.6.20). +.IP +Since Linux 2.6.36, use of this file is deprecated in favor of +.IR /proc/ pid /oom_score_adj , +and finally removed in Linux 3.7. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_oom_score (5) diff --git a/man5/proc_pid_pagemap.5 b/man5/proc_pid_pagemap.5 new file mode 100644 index 0000000..436e2c5 --- /dev/null +++ b/man5/proc_pid_pagemap.5 @@ -0,0 +1,77 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_pagemap 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/pagemap \- mapping of virtual pages +.SH DESCRIPTION +.TP +.IR /proc/ pid /pagemap " (since Linux 2.6.25)" +This file shows the mapping of each of the process's virtual pages +into physical page frames or swap area. +It contains one 64-bit value for each virtual page, +with the bits set as follows: +.RS +.TP +63 +If set, the page is present in RAM. +.TP +62 +If set, the page is in swap space +.TP +61 (since Linux 3.5) +The page is a file-mapped page or a shared anonymous page. +.TP +60\[en]58 (since Linux 3.11) +Zero +.\" Not quite true; see commit 541c237c0923f567c9c4cabb8a81635baadc713f +.TP +57 (since Linux 5.14) +If set, the page is write-protected through +.BR userfaultfd (2). +.TP +56 (since Linux 4.2) +.\" commit 77bb499bb60f4b79cca7d139c8041662860fcf87 +.\" commit 83b4b0bb635eee2b8e075062e4e008d1bc110ed7 +The page is exclusively mapped. +.TP +55 (since Linux 3.11) +PTE is soft-dirty +(see the kernel source file +.IR Documentation/admin\-guide/mm/soft\-dirty.rst ). +.TP +54\[en]0 +If the page is present in RAM (bit 63), then these bits +provide the page frame number, which can be used to index +.I /proc/kpageflags +and +.IR /proc/kpagecount . +If the page is present in swap (bit 62), +then bits 4\[en]0 give the swap type, and bits 54\[en]5 encode the swap offset. +.RE +.IP +Before Linux 3.11, bits 60\[en]55 were +used to encode the base-2 log of the page size. +.IP +To employ +.IR /proc/ pid /pagemap +efficiently, use +.IR /proc/ pid /maps +to determine which areas of memory are actually mapped and seek +to skip over unmapped regions. +.IP +The +.IR /proc/ pid /pagemap +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_personality.5 b/man5/proc_pid_personality.5 new file mode 100644 index 0000000..4dccf0c --- /dev/null +++ b/man5/proc_pid_personality.5 @@ -0,0 +1,23 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_personality 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/personality \- execution domain +.SH DESCRIPTION +.TP +.IR /proc/ pid /personality " (since Linux 2.6.28)" +.\" commit 478307230810d7e2a753ed220db9066dfdf88718 +This read-only file exposes the process's execution domain, as set by +.BR personality (2). +The value is displayed in hexadecimal notation. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_projid_map.5 b/man5/proc_pid_projid_map.5 new file mode 100644 index 0000000..cf88aa4 --- /dev/null +++ b/man5/proc_pid_projid_map.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_projid_map 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/projid_map \- project ID mappings +.SH DESCRIPTION +.TP +.IR /proc/ pid /projid_map " (since Linux 3.7)" +.\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_root.5 b/man5/proc_pid_root.5 new file mode 100644 index 0000000..5263329 --- /dev/null +++ b/man5/proc_pid_root.5 @@ -0,0 +1,75 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_root 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/root/ \- symbolic link to root directory +.SH DESCRIPTION +.TP +.IR /proc/ pid /root/ +UNIX and Linux support the idea of a per-process root of the +filesystem, set by the +.BR chroot (2) +system call. +This file is a symbolic link that points to the process's +root directory, and behaves in the same way as +.IR exe , +and +.IR fd/* . +.IP +Note however that this file is not merely a symbolic link. +It provides the same view of the filesystem (including namespaces and the +set of per-process mounts) as the process itself. +An example illustrates this point. +In one terminal, we start a shell in new user and mount namespaces, +and in that shell we create some new mounts: +.IP +.in +4n +.EX +$ \fBPS1=\[aq]sh1# \[aq] unshare \-Urnm\fP +sh1# \fBmount \-t tmpfs tmpfs /etc\fP # Mount empty tmpfs at /etc +sh1# \fBmount \-\-bind /usr /dev\fP # Mount /usr at /dev +sh1# \fBecho $$\fP +27123 +.EE +.in +.IP +In a second terminal window, in the initial mount namespace, +we look at the contents of the corresponding mounts in +the initial and new namespaces: +.IP +.in +4n +.EX +$ \fBPS1=\[aq]sh2# \[aq] sudo sh\fP +sh2# \fBls /etc | wc \-l\fP # In initial NS +309 +sh2# \fBls /proc/27123/root/etc | wc \-l\fP # /etc in other NS +0 # The empty tmpfs dir +sh2# \fBls /dev | wc \-l\fP # In initial NS +205 +sh2# \fBls /proc/27123/root/dev | wc \-l\fP # /dev in other NS +11 # Actually bind + # mounted to /usr +sh2# \fBls /usr | wc \-l\fP # /usr in initial NS +11 +.EE +.in +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.IR /proc/ pid /root +symbolic link are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.IP +Permission to dereference or read +.RB ( readlink (2)) +this symbolic link is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_seccomp.5 b/man5/proc_pid_seccomp.5 new file mode 100644 index 0000000..22c582c --- /dev/null +++ b/man5/proc_pid_seccomp.5 @@ -0,0 +1,36 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_seccomp 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/seccomp \- secure computing mode +.SH DESCRIPTION +.TP +.IR /proc/ pid /seccomp " (Linux 2.6.12 to Linux 2.6.22)" +This file can be used to read and change the process's +secure computing (seccomp) mode setting. +It contains the value 0 if the process is not in seccomp mode, +and 1 if the process is in strict seccomp mode (see +.BR seccomp (2)). +Writing 1 to this file places the process irreversibly in strict seccomp mode. +(Further attempts to write to the file fail with the +.B EPERM +error.) +.IP +In Linux 2.6.23, +this file went away, to be replaced by the +.BR prctl (2) +.B PR_GET_SECCOMP +and +.B PR_SET_SECCOMP +operations (and later by +.BR seccomp (2) +and the +.I Seccomp +field in +.IR /proc/ pid /status ). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_setgroups.5 b/man5/proc_pid_setgroups.5 new file mode 100644 index 0000000..d90ad19 --- /dev/null +++ b/man5/proc_pid_setgroups.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_setgroups 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/setgroups \- allow or deny setting groups +.SH DESCRIPTION +.TP +.IR /proc/ pid /setgroups " (since Linux 3.19)" +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_smaps.5 b/man5/proc_pid_smaps.5 new file mode 100644 index 0000000..21d7d5c --- /dev/null +++ b/man5/proc_pid_smaps.5 @@ -0,0 +1,129 @@ +'\" t +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_smaps 5 2023-09-07 "Linux man-pages 6.7" +.SH NAME +/proc/pid/smaps \- XXX: What does 's' in "smaps" stand for? +.SH DESCRIPTION +.TP +.IR /proc/ pid /smaps " (since Linux 2.6.14)" +This file shows memory consumption for each of the process's mappings. +(The +.BR pmap (1) +command displays similar information, +in a form that may be easier for parsing.) +For each mapping there is a series of lines such as the following: +.IP +.in +4n +.EX +00400000\-0048a000 r\-xp 00000000 fd:03 960637 /bin/bash +Size: 552 kB +Rss: 460 kB +Pss: 100 kB +Shared_Clean: 452 kB +Shared_Dirty: 0 kB +Private_Clean: 8 kB +Private_Dirty: 0 kB +Referenced: 460 kB +Anonymous: 0 kB +AnonHugePages: 0 kB +ShmemHugePages: 0 kB +ShmemPmdMapped: 0 kB +Swap: 0 kB +KernelPageSize: 4 kB +MMUPageSize: 4 kB +Locked: 0 kB +ProtectionKey: 0 +VmFlags: rd ex mr mw me dw +.EE +.in +.IP +The first of these lines shows the same information as is displayed +for the mapping in +.IR /proc/ pid /maps . +The following lines show the size of the mapping, +the amount of the mapping that is currently resident in RAM ("Rss"), +the process's proportional share of this mapping ("Pss"), +the number of clean and dirty shared pages in the mapping, +and the number of clean and dirty private pages in the mapping. +"Referenced" indicates the amount of memory currently marked as +referenced or accessed. +"Anonymous" shows the amount of memory +that does not belong to any file. +"Swap" shows how much +would-be-anonymous memory is also used, but out on swap. +.IP +The "KernelPageSize" line (available since Linux 2.6.29) +is the page size used by the kernel to back the virtual memory area. +This matches the size used by the MMU in the majority of cases. +However, one counter-example occurs on PPC64 kernels +whereby a kernel using 64 kB as a base page size may still use 4 kB +pages for the MMU on older processors. +To distinguish the two attributes, the "MMUPageSize" line +(also available since Linux 2.6.29) +reports the page size used by the MMU. +.IP +The "Locked" indicates whether the mapping is locked in memory +or not. +.IP +The "ProtectionKey" line (available since Linux 4.9, on x86 only) +contains the memory protection key (see +.BR pkeys (7)) +associated with the virtual memory area. +This entry is present only if the kernel was built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +configuration option (since Linux 4.6). +.IP +The "VmFlags" line (available since Linux 3.8) +represents the kernel flags associated with the virtual memory area, +encoded using the following two-letter codes: +.RS +.IP +.TS +l l l. +rd - readable +wr - writable +ex - executable +sh - shared +mr - may read +mw - may write +me - may execute +ms - may share +gd - stack segment grows down +pf - pure PFN range +dw - disabled write to the mapped file +lo - pages are locked in memory +io - memory mapped I/O area +sr - sequential read advise provided +rr - random read advise provided +dc - do not copy area on fork +de - do not expand area on remapping +ac - area is accountable +nr - swap space is not reserved for the area +ht - area uses huge tlb pages +sf - perform synchronous page faults (since Linux 4.15) +nl - non-linear mapping (removed in Linux 4.0) +ar - architecture specific flag +wf - wipe on fork (since Linux 4.14) +dd - do not include area into core dump +sd - soft-dirty flag (since Linux 3.13) +mm - mixed map area +hg - huge page advise flag +nh - no-huge page advise flag +mg - mergeable advise flag +um - userfaultfd missing pages tracking (since Linux 4.3) +uw - userfaultfd wprotect pages tracking (since Linux 4.3) +.TE +.RE +.IP +The +.IR /proc/ pid /smaps +file is present only if the +.B CONFIG_PROC_PAGE_MONITOR +kernel configuration option is enabled. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_stack.5 b/man5/proc_pid_stack.5 new file mode 100644 index 0000000..bb1d3c2 --- /dev/null +++ b/man5/proc_pid_stack.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_stack 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/stack \- kernel stack +.SH DESCRIPTION +.TP +.IR /proc/ pid /stack " (since Linux 2.6.29)" +.\" 2ec220e27f5040aec1e88901c1b6ea3d135787ad +This file provides a symbolic trace of the function calls in this +process's kernel stack. +This file is provided only if the kernel was built with the +.B CONFIG_STACKTRACE +configuration option. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_stat.5 b/man5/proc_pid_stat.5 new file mode 100644 index 0000000..b08e441 --- /dev/null +++ b/man5/proc_pid_stat.5 @@ -0,0 +1,380 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_stat 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/stat \- status information +.SH DESCRIPTION +.TP +.IR /proc/ pid /stat +Status information about the process. +This is used by +.BR ps (1). +It is defined in the kernel source file +.IR fs/proc/array.c "." +.IP +The fields, in order, with their proper +.BR scanf (3) +format specifiers, are listed below. +Whether or not certain of these fields display valid information is governed by +a ptrace access mode +.BR PTRACE_MODE_READ_FSCREDS " | " PTRACE_MODE_NOAUDIT +check (refer to +.BR ptrace (2)). +If the check denies access, then the field value is displayed as 0. +The affected fields are indicated with the marking [PT]. +.RS +.TP +(1) \fIpid\fP \ %d +.br +The process ID. +.TP +(2) \fIcomm\fP \ %s +The filename of the executable, in parentheses. +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +This is visible whether or not the executable is swapped out. +.TP +(3) \fIstate\fP \ %c +One of the following characters, indicating process state: +.RS +.TP +R +Running +.TP +S +Sleeping in an interruptible wait +.TP +D +Waiting in uninterruptible +disk sleep +.TP +Z +Zombie +.TP +T +Stopped (on a signal) or (before Linux 2.6.33) trace stopped +.TP +t +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Tracing stop (Linux 2.6.33 onward) +.TP +W +Paging (only before Linux 2.6.0) +.TP +X +Dead (from Linux 2.6.0 onward) +.TP +x +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Dead (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +K +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Wakekill (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +W +.\" commit 44d90df6b757c59651ddd55f1a84f28132b50d29 +Waking (Linux 2.6.33 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +P +.\" commit f2530dc71cf0822f90bb63ea4600caaef33a66bb +Parked (Linux 3.9 to +.\" commit 74e37200de8e9c4e09b70c21c3f13c2071e77457 +3.13 only) +.TP +I +.\" commit 06eb61844d841d0032a9950ce7f8e783ee49c0d0 +Idle (Linux 4.14 onward) +.RE +.TP +(4) \fIppid\fP \ %d +The PID of the parent of this process. +.TP +(5) \fIpgrp\fP \ %d +The process group ID of the process. +.TP +(6) \fIsession\fP \ %d +The session ID of the process. +.TP +(7) \fItty_nr\fP \ %d +The controlling terminal of the process. +(The minor device number is contained in the combination of bits +31 to 20 and 7 to 0; +the major device number is in bits 15 to 8.) +.TP +(8) \fItpgid\fP \ %d +.\" This field and following, up to and including wchan added 0.99.1 +The ID of the foreground process group of the controlling +terminal of the process. +.TP +(9) \fIflags\fP \ %u +The kernel flags word of the process. +For bit meanings, +see the PF_* defines in the Linux kernel source file +.IR include/linux/sched.h . +Details depend on the kernel version. +.IP +The format for this field was %lu before Linux 2.6. +.TP +(10) \fIminflt\fP \ %lu +The number of minor faults the process has made which have not +required loading a memory page from disk. +.TP +(11) \fIcminflt\fP \ %lu +The number of minor faults that the process's +waited-for children have made. +.TP +(12) \fImajflt\fP \ %lu +The number of major faults the process has made which have +required loading a memory page from disk. +.TP +(13) \fIcmajflt\fP \ %lu +The number of major faults that the process's +waited-for children have made. +.TP +(14) \fIutime\fP \ %lu +Amount of time that this process has been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +This includes guest time, \fIguest_time\fP +(time spent running a virtual CPU, see below), +so that applications that are not aware of the guest time field +do not lose that time from their calculations. +.TP +(15) \fIstime\fP \ %lu +Amount of time that this process has been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(16) \fIcutime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in user mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +(See also +.BR times (2).) +This includes guest time, \fIcguest_time\fP +(time spent running a virtual CPU, see below). +.TP +(17) \fIcstime\fP \ %ld +Amount of time that this process's +waited-for children have been scheduled in kernel mode, +measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(18) \fIpriority\fP \ %ld +(Explanation for Linux 2.6) +For processes running a real-time scheduling policy +.RI ( policy +below; see +.BR sched_setscheduler (2)), +this is the negated scheduling priority, minus one; +that is, a number in the range \-2 to \-100, +corresponding to real-time priorities 1 to 99. +For processes running under a non-real-time scheduling policy, +this is the raw nice value +.RB ( setpriority (2)) +as represented in the kernel. +The kernel stores nice values as numbers +in the range 0 (high) to 39 (low), +corresponding to the user-visible nice range of \-20 to 19. +.IP +Before Linux 2.6, this was a scaled value based on +the scheduler weighting given to this process. +.\" And back in Linux 1.2 days things were different again. +.TP +(19) \fInice\fP \ %ld +The nice value (see +.BR setpriority (2)), +a value in the range 19 (low priority) to \-20 (high priority). +.\" Back in Linux 1.2 days things were different. +.\" .TP +.\" \fIcounter\fP %ld +.\" The current maximum size in jiffies of the process's next timeslice, +.\" or what is currently left of its current timeslice, if it is the +.\" currently running process. +.\" .TP +.\" \fItimeout\fP %u +.\" The time in jiffies of the process's next timeout. +.\" timeout was removed sometime around 2.1/2.2 +.TP +(20) \fInum_threads\fP \ %ld +Number of threads in this process (since Linux 2.6). +Before Linux 2.6, this field was hard coded to 0 as a placeholder +for an earlier removed field. +.TP +(21) \fIitrealvalue\fP \ %ld +The time in jiffies before the next +.B SIGALRM +is sent to the process due to an interval timer. +Since Linux 2.6.17, this field is no longer maintained, +and is hard coded as 0. +.TP +(22) \fIstarttime\fP \ %llu +The time the process started after system boot. +Before Linux 2.6, this value was expressed in jiffies. +Since Linux 2.6, the value is expressed in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.IP +The format for this field was %lu before Linux 2.6. +.TP +(23) \fIvsize\fP \ %lu +Virtual memory size in bytes. +.TP +(24) \fIrss\fP \ %ld +Resident Set Size: number of pages the process has in real memory. +This is just the pages which +count toward text, data, or stack space. +This does not include pages +which have not been demand-loaded in, or which are swapped out. +This value is inaccurate; see +.IR /proc/ pid /statm +below. +.TP +(25) \fIrsslim\fP \ %lu +Current soft limit in bytes on the rss of the process; +see the description of +.B RLIMIT_RSS +in +.BR getrlimit (2). +.TP +(26) \fIstartcode\fP \ %lu \ [PT] +The address above which program text can run. +.TP +(27) \fIendcode\fP \ %lu \ [PT] +The address below which program text can run. +.TP +(28) \fIstartstack\fP \ %lu \ [PT] +The address of the start (i.e., bottom) of the stack. +.TP +(29) \fIkstkesp\fP \ %lu \ [PT] +The current value of ESP (stack pointer), as found in the +kernel stack page for the process. +.TP +(30) \fIkstkeip\fP \ %lu \ [PT] +The current EIP (instruction pointer). +.TP +(31) \fIsignal\fP \ %lu +The bitmap of pending signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(32) \fIblocked\fP \ %lu +The bitmap of blocked signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(33) \fIsigignore\fP \ %lu +The bitmap of ignored signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(34) \fIsigcatch\fP \ %lu +The bitmap of caught signals, displayed as a decimal number. +Obsolete, because it does not provide information on real-time signals; use +.IR /proc/ pid /status +instead. +.TP +(35) \fIwchan\fP \ %lu \ [PT] +This is the "channel" in which the process is waiting. +It is the address of a location in the kernel where the process is sleeping. +The corresponding symbolic name can be found in +.IR /proc/ pid /wchan . +.TP +(36) \fInswap\fP \ %lu +.\" nswap was added in Linux 2.0 +Number of pages swapped (not maintained). +.TP +(37) \fIcnswap\fP \ %lu +.\" cnswap was added in Linux 2.0 +Cumulative \fInswap\fP for child processes (not maintained). +.TP +(38) \fIexit_signal\fP \ %d \ (since Linux 2.1.22) +Signal to be sent to parent when we die. +.TP +(39) \fIprocessor\fP \ %d \ (since Linux 2.2.8) +CPU number last executed on. +.TP +(40) \fIrt_priority\fP \ %u \ (since Linux 2.5.19) +Real-time scheduling priority, a number in the range 1 to 99 for +processes scheduled under a real-time policy, +or 0, for non-real-time processes (see +.BR sched_setscheduler (2)). +.TP +(41) \fIpolicy\fP \ %u \ (since Linux 2.5.19) +Scheduling policy (see +.BR sched_setscheduler (2)). +Decode using the SCHED_* constants in +.IR linux/sched.h . +.IP +The format for this field was %lu before Linux 2.6.22. +.TP +(42) \fIdelayacct_blkio_ticks\fP \ %llu \ (since Linux 2.6.18) +Aggregated block I/O delays, measured in clock ticks (centiseconds). +.TP +(43) \fIguest_time\fP \ %lu \ (since Linux 2.6.24) +Guest time of the process (time spent running a virtual CPU +for a guest operating system), measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(44) \fIcguest_time\fP \ %ld \ (since Linux 2.6.24) +Guest time of the process's children, measured in clock ticks (divide by +.IR sysconf(_SC_CLK_TCK) ). +.TP +(45) \fIstart_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program initialized and +uninitialized (BSS) data are placed. +.TP +(46) \fIend_data\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address below which program initialized and +uninitialized (BSS) data are placed. +.TP +(47) \fIstart_brk\fP \ %lu \ (since Linux 3.3) \ [PT] +.\" commit b3f7f573a20081910e34e99cbc91831f4f02f1ff +Address above which program heap can be expanded with +.BR brk (2). +.TP +(48) \fIarg_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program command-line arguments +.RI ( argv ) +are placed. +.TP +(49) \fIarg_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below program command-line arguments +.RI ( argv ) +are placed. +.TP +(50) \fIenv_start\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address above which program environment is placed. +.TP +(51) \fIenv_end\fP \ %lu \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +Address below which program environment is placed. +.TP +(52) \fIexit_code\fP \ %d \ (since Linux 3.5) \ [PT] +.\" commit 5b172087f99189416d5f47fd7ab5e6fb762a9ba3 +The thread's exit status in the form reported by +.BR waitpid (2). +.RE +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_status (5) diff --git a/man5/proc_pid_statm.5 b/man5/proc_pid_statm.5 new file mode 100644 index 0000000..5e3ca2e --- /dev/null +++ b/man5/proc_pid_statm.5 @@ -0,0 +1,46 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_statm 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/statm \- memory usage information +.SH DESCRIPTION +.TP +.IR /proc/ pid /statm +Provides information about memory usage, measured in pages. +The columns are: +.IP +.in +4n +.EX +size (1) total program size + (same as VmSize in \fI/proc/\fPpid\fI/status\fP) +resident (2) resident set size + (inaccurate; same as VmRSS in \fI/proc/\fPpid\fI/status\fP) +shared (3) number of resident shared pages + (i.e., backed by a file) + (inaccurate; same as RssFile+RssShmem in + \fI/proc/\fPpid\fI/status\fP) +text (4) text (code) +.\" (not including libs; broken, includes data segment) +lib (5) library (unused since Linux 2.6; always 0) +data (6) data + stack +.\" (including libs; broken, includes library text) +dt (7) dirty pages (unused since Linux 2.6; always 0) +.EE +.in +.IP +.\" See SPLIT_RSS_COUNTING in the kernel. +.\" Inaccuracy is bounded by TASK_RSS_EVENTS_THRESH. +Some of these values are inaccurate because +of a kernel-internal scalability optimization. +If accurate values are required, use +.IR /proc/ pid /smaps +or +.IR /proc/ pid /smaps_rollup +instead, which are much slower but provide accurate, detailed information. +.SH SEE ALSO +.BR proc (5), +.BR proc_pid_status (5) diff --git a/man5/proc_pid_status.5 b/man5/proc_pid_status.5 new file mode 100644 index 0000000..fdef477 --- /dev/null +++ b/man5/proc_pid_status.5 @@ -0,0 +1,384 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_status 5 2023-10-23 "Linux man-pages 6.7" +.SH NAME +/proc/pid/status \- memory usage and status information +.SH DESCRIPTION +.TP +.IR /proc/ pid /status +Provides much of the information in +.IR /proc/ pid /stat +and +.IR /proc/ pid /statm +in a format that's easier for humans to parse. +Here's an example: +.IP +.in +4n +.EX +.RB "$" " cat /proc/$$/status" +Name: bash +Umask: 0022 +State: S (sleeping) +Tgid: 17248 +Ngid: 0 +Pid: 17248 +PPid: 17200 +TracerPid: 0 +Uid: 1000 1000 1000 1000 +Gid: 100 100 100 100 +FDSize: 256 +Groups: 16 33 100 +NStgid: 17248 +NSpid: 17248 +NSpgid: 17248 +NSsid: 17200 +VmPeak: 131168 kB +VmSize: 131168 kB +VmLck: 0 kB +VmPin: 0 kB +VmHWM: 13484 kB +VmRSS: 13484 kB +RssAnon: 10264 kB +RssFile: 3220 kB +RssShmem: 0 kB +VmData: 10332 kB +VmStk: 136 kB +VmExe: 992 kB +VmLib: 2104 kB +VmPTE: 76 kB +VmPMD: 12 kB +VmSwap: 0 kB +HugetlbPages: 0 kB # 4.4 +CoreDumping: 0 # 4.15 +Threads: 1 +SigQ: 0/3067 +SigPnd: 0000000000000000 +ShdPnd: 0000000000000000 +SigBlk: 0000000000010000 +SigIgn: 0000000000384004 +SigCgt: 000000004b813efb +CapInh: 0000000000000000 +CapPrm: 0000000000000000 +CapEff: 0000000000000000 +CapBnd: ffffffffffffffff +CapAmb: 0000000000000000 +NoNewPrivs: 0 +Seccomp: 0 +Seccomp_filters: 0 +Speculation_Store_Bypass: vulnerable +Cpus_allowed: 00000001 +Cpus_allowed_list: 0 +Mems_allowed: 1 +Mems_allowed_list: 0 +voluntary_ctxt_switches: 150 +nonvoluntary_ctxt_switches: 545 +.EE +.in +.IP +The fields are as follows: +.RS +.TP +.I Name +Command run by this process. +Strings longer than +.B TASK_COMM_LEN +(16) characters (including the terminating null byte) are silently truncated. +.TP +.I Umask +Process umask, expressed in octal with a leading zero; see +.BR umask (2). +(Since Linux 4.7.) +.TP +.I State +Current state of the process. +One of +"R (running)", +"S (sleeping)", +"D (disk sleep)", +"T (stopped)", +"t (tracing stop)", +"Z (zombie)", +or +"X (dead)". +.TP +.I Tgid +Thread group ID (i.e., Process ID). +.TP +.I Ngid +NUMA group ID (0 if none; since Linux 3.13). +.TP +.I Pid +Thread ID (see +.BR gettid (2)). +.TP +.I PPid +PID of parent process. +.TP +.I TracerPid +PID of process tracing this process (0 if not being traced). +.TP +.I Uid +.TQ +.I Gid +Real, effective, saved set, and filesystem UIDs (GIDs). +.TP +.I FDSize +Number of file descriptor slots currently allocated. +.TP +.I Groups +Supplementary group list. +.TP +.I NStgid +Thread group ID (i.e., PID) in each of the PID namespaces of which +.I pid +is a member. +The leftmost entry shows the value with respect to the PID namespace +of the process that mounted this procfs (or the root namespace +if mounted by the kernel), +followed by the value in successively nested inner namespaces. +.\" commit e4bc33245124db69b74a6d853ac76c2976f472d5 +(Since Linux 4.1.) +.TP +.I NSpid +Thread ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I NSpgid +Process group ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I NSsid +descendant namespace session ID hierarchy +Session ID in each of the PID namespaces of which +.I pid +is a member. +The fields are ordered as for +.IR NStgid . +(Since Linux 4.1.) +.TP +.I VmPeak +Peak virtual memory size. +.TP +.I VmSize +Virtual memory size. +.TP +.I VmLck +Locked memory size (see +.BR mlock (2)). +.TP +.I VmPin +Pinned memory size +.\" commit bc3e53f682d93df677dbd5006a404722b3adfe18 +(since Linux 3.2). +These are pages that can't be moved because something needs to +directly access physical memory. +.TP +.I VmHWM +Peak resident set size ("high water mark"). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I VmRSS +Resident set size. +Note that the value here is the sum of +.IR RssAnon , +.IR RssFile , +and +.IR RssShmem . +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssAnon +Size of resident anonymous memory. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssFile +Size of resident file mappings. +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I RssShmem +Size of resident shared memory (includes System V shared memory, +mappings from +.BR tmpfs (5), +and shared anonymous mappings). +.\" commit bf9683d6990589390b5178dafe8fd06808869293 +(since Linux 4.5). +.TP +.I VmData +.TQ +.I VmStk +.TQ +.I VmExe +Size of data, stack, and text segments. +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I VmLib +Shared library code size. +.TP +.I VmPTE +Page table entries size (since Linux 2.6.10). +.TP +.I VmPMD +.\" commit dc6c9a35b66b520cf67e05d8ca60ebecad3b0479 +Size of second-level page tables (added in Linux 4.0; removed in Linux 4.15). +.TP +.I VmSwap +.\" commit b084d4353ff99d824d3bc5a5c2c22c70b1fba722 +Swapped-out virtual memory size by anonymous private pages; +shmem swap usage is not included (since Linux 2.6.34). +This value is inaccurate; see +.IR /proc/ pid /statm +above. +.TP +.I HugetlbPages +Size of hugetlb memory portions +.\" commit 5d317b2b6536592a9b51fe65faed43d65ca9158e +(since Linux 4.4). +.TP +.I CoreDumping +Contains the value 1 if the process is currently dumping core, +and 0 if it is not +.\" commit c643401218be0f4ab3522e0c0a63016596d6e9ca +(since Linux 4.15). +This information can be used by a monitoring process to avoid killing +a process that is currently dumping core, +which could result in a corrupted core dump file. +.TP +.I Threads +Number of threads in process containing this thread. +.TP +.I SigQ +This field contains two slash-separated numbers that relate to +queued signals for the real user ID of this process. +The first of these is the number of currently queued +signals for this real user ID, and the second is the +resource limit on the number of queued signals for this process +(see the description of +.B RLIMIT_SIGPENDING +in +.BR getrlimit (2)). +.TP +.I SigPnd +.TQ +.I ShdPnd +Mask (expressed in hexadecimal) +of signals pending for thread and for process as a whole (see +.BR pthreads (7) +and +.BR signal (7)). +.TP +.I SigBlk +.TQ +.I SigIgn +.TQ +.I SigCgt +Masks (expressed in hexadecimal) +indicating signals being blocked, ignored, and caught (see +.BR signal (7)). +.TP +.I CapInh +.TQ +.I CapPrm +.TQ +.I CapEff +Masks (expressed in hexadecimal) +of capabilities enabled in inheritable, permitted, and effective sets +(see +.BR capabilities (7)). +.TP +.I CapBnd +Capability bounding set, expressed in hexadecimal +(since Linux 2.6.26, see +.BR capabilities (7)). +.TP +.I CapAmb +Ambient capability set, expressed in hexadecimal +(since Linux 4.3, see +.BR capabilities (7)). +.TP +.I NoNewPrivs +.\" commit af884cd4a5ae62fcf5e321fecf0ec1014730353d +Value of the +.I no_new_privs +bit +(since Linux 4.10, see +.BR prctl (2)). +.TP +.I Seccomp +.\" commit 2f4b3bf6b2318cfaa177ec5a802f4d8d6afbd816 +Seccomp mode of the process +(since Linux 3.8, see +.BR seccomp (2)). +0 means +.BR SECCOMP_MODE_DISABLED ; +1 means +.BR SECCOMP_MODE_STRICT ; +2 means +.BR SECCOMP_MODE_FILTER . +This field is provided only if the kernel was built with the +.B CONFIG_SECCOMP +kernel configuration option enabled. +.TP +.I Seccomp_filters +.\" commit c818c03b661cd769e035e41673d5543ba2ebda64 +Number of seccomp filters attached to the process +(since Linux 5.9, see +.BR seccomp (2)). +.TP +.I Speculation_Store_Bypass +.\" commit fae1fa0fc6cca8beee3ab8ed71d54f9a78fa3f64 +Speculation flaw mitigation state +(since Linux 4.17, see +.BR prctl (2)). +.TP +.I Cpus_allowed +Hexadecimal mask of CPUs on which this process may run +(since Linux 2.6.24, see +.BR cpuset (7)). +.TP +.I Cpus_allowed_list +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.TP +.I Mems_allowed +Mask of memory nodes allowed to this process +(since Linux 2.6.24, see +.BR cpuset (7)). +.TP +.I Mems_allowed_list +Same as previous, but in "list format" +(since Linux 2.6.26, see +.BR cpuset (7)). +.TP +.I voluntary_ctxt_switches +.TQ +.I nonvoluntary_ctxt_switches +Number of voluntary and involuntary context switches (since Linux 2.6.23). +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_syscall.5 b/man5/proc_pid_syscall.5 new file mode 100644 index 0000000..c569293 --- /dev/null +++ b/man5/proc_pid_syscall.5 @@ -0,0 +1,33 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_syscall 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/syscall \- currently executed system call +.SH DESCRIPTION +.TP +.IR /proc/ pid /syscall " (since Linux 2.6.27)" +.\" commit ebcb67341fee34061430f3367f2e507e52ee051b +This file exposes the system call number and argument registers for the +system call currently being executed by the process, +followed by the values of the stack pointer and program counter registers. +The values of all six argument registers are exposed, +although most system calls use fewer registers. +.IP +If the process is blocked, but not in a system call, +then the file displays \-1 in place of the system call number, +followed by just the values of the stack pointer and program counter. +If process is not blocked, then the file contains just the string "running". +.IP +This file is present only if the kernel was configured with +.BR CONFIG_HAVE_ARCH_TRACEHOOK . +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_task.5 b/man5/proc_pid_task.5 new file mode 100644 index 0000000..70af355 --- /dev/null +++ b/man5/proc_pid_task.5 @@ -0,0 +1,97 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_task 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/task/, /proc/tid/, /proc/thread\-self/ \- thread information +.SH DESCRIPTION +.TP +.IR /proc/ pid /task/ " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test6 +This is a directory that contains one subdirectory +for each thread in the process. +The name of each subdirectory is the numerical thread ID +.RI ( tid ) +of the thread (see +.BR gettid (2)). +.IP +Within each of these subdirectories, there is a set of +files with the same names and contents as under the +.IR /proc/ pid +directories. +For attributes that are shared by all threads, the contents for +each of the files under the +.IR task/ tid +subdirectories will be the same as in the corresponding +file in the parent +.IR /proc/ pid +directory +(e.g., in a multithreaded process, all of the +.IR task/ tid /cwd +files will have the same value as the +.IR /proc/ pid /cwd +file in the parent directory, since all of the threads in a process +share a working directory). +For attributes that are distinct for each thread, +the corresponding files under +.IR task/ tid +may have different values (e.g., various fields in each of the +.IR task/ tid /status +files may be different for each thread), +.\" in particular: "children" :/ +or they might not exist in +.IR /proc/ pid +at all. +.IP +.\" The following was still true as at kernel 2.6.13 +In a multithreaded process, the contents of the +.IR /proc/ pid /task +directory are not available if the main thread has already terminated +(typically by calling +.BR pthread_exit (3)). +.TP +.IR /proc/ tid / +There is a numerical subdirectory for each running thread +that is not a thread group leader +(i.e., a thread whose thread ID is not the same as its process ID); +the subdirectory is named by the thread ID. +Each one of these subdirectories contains files and subdirectories +exposing information about the thread with the thread ID +.IR tid . +The contents of these directories are the same as the corresponding +.IR /proc/ pid /task/ tid +directories. +.IP +The +.IR /proc/ tid +subdirectories are +.I not +visible when iterating through +.I /proc +with +.BR getdents (2) +(and thus are +.I not +visible when one uses +.BR ls (1) +to view the contents of +.IR /proc ). +However, the pathnames of these directories are visible to +(i.e., usable as arguments in) +system calls that operate on pathnames. +.TP +.IR /proc/thread\-self/ " (since Linux 3.17)" +.\" commit 0097875bd41528922fb3bb5f348c53f17e00e2fd +This directory refers to the thread accessing the +.I /proc +filesystem, +and is identical to the +.IR /proc/self/task/ tid +directory named by the process thread ID +.RI ( tid ) +of the same thread. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_timers.5 b/man5/proc_pid_timers.5 new file mode 100644 index 0000000..981ba79 --- /dev/null +++ b/man5/proc_pid_timers.5 @@ -0,0 +1,82 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_timers 5 2023-09-07 "Linux man-pages 6.7" +.SH NAME +/proc/pid/timers \- POSIX timers +.SH DESCRIPTION +.TP +.IR /proc/ pid /timers " (since Linux 3.10)" +.\" commit 5ed67f05f66c41e39880a6d61358438a25f9fee5 +.\" commit 48f6a7a511ef8823fdff39afee0320092d43a8a0 +A list of the POSIX timers for this process. +Each timer is listed with a line that starts with the string "ID:". +For example: +.IP +.in +4n +.EX +ID: 1 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 0 +ID: 0 +signal: 60/00007fff86e452a8 +notify: signal/pid.2634 +ClockID: 1 +.EE +.in +.IP +The lines shown for each timer have the following meanings: +.RS +.TP +.I ID +The ID for this timer. +This is not the same as the timer ID returned by +.BR timer_create (2); +rather, it is the same kernel-internal ID that is available via the +.I si_timerid +field of the +.I siginfo_t +structure (see +.BR sigaction (2)). +.TP +.I signal +This is the signal number that this timer uses to deliver notifications +followed by a slash, and then the +.I sigev_value +value supplied to the signal handler. +Valid only for timers that notify via a signal. +.TP +.I notify +The part before the slash specifies the mechanism +that this timer uses to deliver notifications, +and is one of "thread", "signal", or "none". +Immediately following the slash is either the string "tid" for timers +with +.B SIGEV_THREAD_ID +notification, or "pid" for timers that notify by other mechanisms. +Following the "." is the PID of the process +(or the kernel thread ID of the thread) that will be delivered +a signal if the timer delivers notifications via a signal. +.TP +.I ClockID +This field identifies the clock that the timer uses for measuring time. +For most clocks, this is a number that matches one of the user-space +.B CLOCK_* +constants exposed via +.IR . +.B CLOCK_PROCESS_CPUTIME_ID +timers display with a value of \-6 +in this field. +.B CLOCK_THREAD_CPUTIME_ID +timers display with a value of \-2 +in this field. +.RE +.IP +This file is available only when the kernel was configured with +.BR CONFIG_CHECKPOINT_RESTORE . +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_timerslack_ns.5 b/man5/proc_pid_timerslack_ns.5 new file mode 100644 index 0000000..94be8eb --- /dev/null +++ b/man5/proc_pid_timerslack_ns.5 @@ -0,0 +1,41 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_timerslack_ns 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/timerslack_ns \- timer slack in nanoseconds +.SH DESCRIPTION +.TP +.IR /proc/ pid /timerslack_ns " (since Linux 4.6)" +.\" commit da8b44d5a9f8bf26da637b7336508ca534d6b319 +.\" commit 5de23d435e88996b1efe0e2cebe242074ce67c9e +This file exposes the process's "current" timer slack value, +expressed in nanoseconds. +The file is writable, +allowing the process's timer slack value to be changed. +Writing 0 to this file resets the "current" timer slack to the +"default" timer slack value. +For further details, see the discussion of +.B PR_SET_TIMERSLACK +in +.BR prctl (2). +.IP +Initially, +permission to access this file was governed by a ptrace access mode +.B PTRACE_MODE_ATTACH_FSCREDS +check (see +.BR ptrace (2)). +However, this was subsequently deemed too strict a requirement +(and had the side effect that requiring a process to have the +.B CAP_SYS_PTRACE +capability would also allow it to view and change any process's memory). +Therefore, since Linux 4.9, +.\" commit 7abbaf94049914f074306d960b0f968ffe52e59f +only the (weaker) +.B CAP_SYS_NICE +capability is required to access this file. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_uid_map.5 b/man5/proc_pid_uid_map.5 new file mode 100644 index 0000000..68fd4ff --- /dev/null +++ b/man5/proc_pid_uid_map.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_uid_map 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/gid_map, /proc/pid/uid_map \- user and group ID mappings +.SH DESCRIPTION +.TP +.IR /proc/ pid /gid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.TP +.IR /proc/ pid /uid_map " (since Linux 3.5)" +See +.BR user_namespaces (7). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_pid_wchan.5 b/man5/proc_pid_wchan.5 new file mode 100644 index 0000000..e7ab9d4 --- /dev/null +++ b/man5/proc_pid_wchan.5 @@ -0,0 +1,21 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_pid_wchan 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/pid/wchan \- wait channel +.SH DESCRIPTION +.TP +.IR /proc/ pid /wchan " (since Linux 2.6.0)" +The symbolic name corresponding to the location +in the kernel where the process is sleeping. +.IP +Permission to access this file is governed by a ptrace access mode +.B PTRACE_MODE_READ_FSCREDS +check; see +.BR ptrace (2). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_profile.5 b/man5/proc_profile.5 new file mode 100644 index 0000000..bd206b4 --- /dev/null +++ b/man5/proc_profile.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_profile 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/profile \- kernel profiling +.SH DESCRIPTION +.TP +.IR /proc/profile " (since Linux 2.4)" +This file is present only if the kernel was booted with the +.I profile=1 +command-line option. +It exposes kernel profiling information in a binary format for use by +.BR readprofile (1). +Writing (e.g., an empty string) to this file resets the profiling counters; +on some architectures, +writing a binary integer "profiling multiplier" of size +.I sizeof(int) +sets the profiling interrupt frequency. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_scsi.5 b/man5/proc_scsi.5 new file mode 100644 index 0000000..12f92aa --- /dev/null +++ b/man5/proc_scsi.5 @@ -0,0 +1,66 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Michael Neuffer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_scsi 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/scsi/ \- SCSI +.SH DESCRIPTION +.TP +.I /proc/scsi/ +A directory with the +.I scsi +mid-level pseudo-file and various SCSI low-level +driver directories, +which contain a file for each SCSI host in this system, all of +which give the status of some part of the SCSI IO subsystem. +These files contain ASCII structures and are, therefore, readable with +.BR cat (1). +.IP +You can also write to some of the files to reconfigure the subsystem or +switch certain features on or off. +.TP +.I /proc/scsi/scsi +This is a listing of all SCSI devices known to the kernel. +The listing is similar to the one seen during bootup. +scsi currently supports only the \fIadd\-single\-device\fP command which +allows root to add a hotplugged device to the list of known devices. +.IP +The command +.IP +.in +4n +.EX +echo \[aq]scsi add\-single\-device 1 0 5 0\[aq] > /proc/scsi/scsi +.EE +.in +.IP +will cause +host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. +If there +is already a device known on this address or the address is invalid, an +error will be returned. +.TP +.IR /proc/scsi/ drivername / +\fIdrivername\fP can currently be NCR53c7xx, aha152x, aha1542, aha1740, +aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, +scsi_debug, seagate, t128, u15\-24f, ultrastore, or wd7000. +These directories show up for all drivers that registered at least one +SCSI HBA. +Every directory contains one file per registered host. +Every host-file is named after the number the host was assigned during +initialization. +.IP +Reading these files will usually show driver and host configuration, +statistics, and so on. +.IP +Writing to these files allows different things on different hosts. +For example, with the \fIlatency\fP and \fInolatency\fP commands, +root can switch on and off command latency measurement code in the +eata_dma driver. +With the \fIlockup\fP and \fIunlock\fP commands, +root can control bus lockups simulated by the scsi_debug driver. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_self.5 b/man5/proc_self.5 new file mode 100644 index 0000000..fb01835 --- /dev/null +++ b/man5/proc_self.5 @@ -0,0 +1 @@ +.so man5/proc_pid.5 diff --git a/man5/proc_slabinfo.5 b/man5/proc_slabinfo.5 new file mode 100644 index 0000000..1894931 --- /dev/null +++ b/man5/proc_slabinfo.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_slabinfo 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/slabinfo \- kernel caches +.SH DESCRIPTION +.TP +.I /proc/slabinfo +Information about kernel caches. +See +.BR slabinfo (5) +for details. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_stat.5 b/man5/proc_stat.5 new file mode 100644 index 0000000..c7350f0 --- /dev/null +++ b/man5/proc_stat.5 @@ -0,0 +1,140 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_stat 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/stat \- kernel system statistics +.SH DESCRIPTION +.TP +.I /proc/stat +kernel/system statistics. +Varies with architecture. +Common +entries include: +.RS +.TP +.I cpu 10132153 290696 3084719 46828483 16683 0 25195 0 175628 0 +.TQ +.I cpu0 1393280 32966 572056 13343292 6130 0 17875 0 23933 0 +The amount of time, measured in units of +USER_HZ (1/100ths of a second on most architectures, use +.I sysconf(_SC_CLK_TCK) +to obtain the right value), +.\" 1024 on Alpha and ia64 +that the system ("cpu" line) or the specific CPU ("cpu\fIN\fR" line) +spent in various states: +.RS +.TP +.I user +(1) Time spent in user mode. +.TP +.I nice +(2) Time spent in user mode with low priority (nice). +.TP +.I system +(3) Time spent in system mode. +.TP +.I idle +(4) Time spent in the idle task. +.\" FIXME . Actually, the following info about the /proc/stat 'cpu' field +.\" does not seem to be quite right (at least in Linux 2.6.12 or Linux 3.6): +.\" the idle time in /proc/uptime does not quite match this value +This value should be USER_HZ times the +second entry in the +.I /proc/uptime +pseudo-file. +.TP +.IR iowait " (since Linux 2.5.41)" +(5) Time waiting for I/O to complete. +This value is not reliable, for the following reasons: +.\" See kernel commit 9c240d757658a3ae9968dd309e674c61f07c7f48 +.RS +.IP \[bu] 3 +The CPU will not wait for I/O to complete; +iowait is the time that a task is waiting for I/O to complete. +When a CPU goes into idle state for outstanding task I/O, +another task will be scheduled on this CPU. +.IP \[bu] +On a multi-core CPU, +the task waiting for I/O to complete is not running on any CPU, +so the iowait of each CPU is difficult to calculate. +.IP \[bu] +The value in this field may +.I decrease +in certain conditions. +.RE +.TP +.IR irq " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +(6) Time servicing interrupts. +.TP +.IR softirq " (since Linux 2.6.0)" +.\" Precisely: Linux 2.6.0-test4 +(7) Time servicing softirqs. +.TP +.IR steal " (since Linux 2.6.11)" +(8) Stolen time, which is the time spent in other operating systems when +running in a virtualized environment +.TP +.IR guest " (since Linux 2.6.24)" +(9) Time spent running a virtual CPU for guest +operating systems under the control of the Linux kernel. +.\" See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de +.TP +.IR guest_nice " (since Linux 2.6.33)" +.\" commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797 +(10) Time spent running a niced guest (virtual CPU for guest +operating systems under the control of the Linux kernel). +.RE +.TP +\fIpage 5741 1808\fP +The number of pages the system paged in and the number that were paged +out (from disk). +.TP +\fIswap 1 0\fP +The number of swap pages that have been brought in and out. +.TP +.\" FIXME . The following is not the full picture for the 'intr' of +.\" /proc/stat on 2.6: +\fIintr 1462898\fP +This line shows counts of interrupts serviced since boot time, +for each of the possible system interrupts. +The first column is the total of all interrupts serviced +including unnumbered architecture specific interrupts; +each subsequent column is the total for that particular numbered interrupt. +Unnumbered interrupts are not shown, only summed into the total. +.TP +\fIdisk_io: (2,0):(31,30,5764,1,2) (3,0):\fP... +(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, blks_written) +.br +(Linux 2.4 only) +.TP +\fIctxt 115315\fP +The number of context switches that the system underwent. +.TP +\fIbtime 769041601\fP +boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.TP +\fIprocesses 86031\fP +Number of forks since boot. +.TP +\fIprocs_running 6\fP +Number of processes in runnable state. +(Linux 2.5.45 onward.) +.TP +\fIprocs_blocked 2\fP +Number of processes blocked waiting for I/O to complete. +(Linux 2.5.45 onward.) +.TP +.I softirq 229245889 94 60001584 13619 5175704 2471304 28 51212741 59130143 0 51240672 +.\" commit d3d64df21d3d0de675a0d3ffa7c10514f3644b30 +This line shows the number of softirq for all CPUs. +The first column is the total of all softirqs and +each subsequent column is the total for particular softirq. +(Linux 2.6.31 onward.) +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_swaps.5 b/man5/proc_swaps.5 new file mode 100644 index 0000000..e956954 --- /dev/null +++ b/man5/proc_swaps.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_swaps 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/swaps \- swap areas +.SH DESCRIPTION +.TP +.I /proc/swaps +Swap areas in use. +See also +.BR swapon (8). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_sys.5 b/man5/proc_sys.5 new file mode 100644 index 0000000..f467b30 --- /dev/null +++ b/man5/proc_sys.5 @@ -0,0 +1,31 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/ \- system information, and sysctl pseudo-filesystem +.SH DESCRIPTION +.TP +.I /proc/sys/ +This directory (present since Linux 1.3.57) contains a number of files +and subdirectories corresponding to kernel variables. +These variables can be read and in some cases modified using +the \fI/proc\fP filesystem, and the (deprecated) +.BR sysctl (2) +system call. +.IP +String values may be terminated by either \[aq]\e0\[aq] or \[aq]\en\[aq]. +.IP +Integer and long values may be written either in decimal or in +hexadecimal notation (e.g., 0x3FFF). +When writing multiple integer or long values, these may be separated +by any of the following whitespace characters: +\[aq]\ \[aq], \[aq]\et\[aq], or \[aq]\en\[aq]. +Using other separators leads to the error +.BR EINVAL . +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_sys_abi.5 b/man5/proc_sys_abi.5 new file mode 100644 index 0000000..a9bfd47 --- /dev/null +++ b/man5/proc_sys_abi.5 @@ -0,0 +1,24 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_abi 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/abi/ \- application binary information +.SH DESCRIPTION +.TP +.IR /proc/sys/abi/ " (since Linux 2.4.10)" +This directory may contain files with application binary information. +.\" On some systems, it is not present. +See the Linux kernel source file +.I Documentation/sysctl/abi.rst +(or +.I Documentation/sysctl/abi.txt +before Linux 5.3) +for more information. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_debug.5 b/man5/proc_sys_debug.5 new file mode 100644 index 0000000..798da05 --- /dev/null +++ b/man5/proc_sys_debug.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_debug 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/debug/ \- debug +.SH DESCRIPTION +.TP +.I /proc/sys/debug/ +This directory may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_dev.5 b/man5/proc_sys_dev.5 new file mode 100644 index 0000000..28ca831 --- /dev/null +++ b/man5/proc_sys_dev.5 @@ -0,0 +1,20 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_dev 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/dev/ \- device-specific information +.SH DESCRIPTION +.TP +.I /proc/sys/dev/ +This directory contains device-specific information (e.g., +.IR dev/cdrom/info ). +On +some systems, it may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_fs.5 b/man5/proc_sys_fs.5 new file mode 100644 index 0000000..d6f5a4b --- /dev/null +++ b/man5/proc_sys_fs.5 @@ -0,0 +1,471 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_fs 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/fs/ \- kernel variables related to filesystems +.SH DESCRIPTION +.TP +.I /proc/sys/fs/ +This directory contains the files and subdirectories for kernel variables +related to filesystems. +.TP +.IR /proc/sys/fs/aio\-max\-nr " and " /proc/sys/fs/aio\-nr " (since Linux 2.6.4)" +.I aio\-nr +is the running total of the number of events specified by +.BR io_setup (2) +calls for all currently active AIO contexts. +If +.I aio\-nr +reaches +.IR aio\-max\-nr , +then +.BR io_setup (2) +will fail with the error +.BR EAGAIN . +Raising +.I aio\-max\-nr +does not result in the preallocation or resizing +of any kernel data structures. +.TP +.I /proc/sys/fs/binfmt_misc +Documentation for files in this directory can be found +in the Linux kernel source in the file +.I Documentation/admin\-guide/binfmt\-misc.rst +(or in +.I Documentation/binfmt_misc.txt +on older kernels). +.TP +.IR /proc/sys/fs/dentry\-state " (since Linux 2.2)" +This file contains information about the status of the +directory cache (dcache). +The file contains six numbers, +.IR nr_dentry , +.IR nr_unused , +.I age_limit +(age in seconds), +.I want_pages +(pages requested by system) and two dummy values. +.RS +.IP \[bu] 3 +.I nr_dentry +is the number of allocated dentries (dcache entries). +This field is unused in Linux 2.2. +.IP \[bu] +.I nr_unused +is the number of unused dentries. +.IP \[bu] +.I age_limit +.\" looks like this is unused in Linux 2.2 to Linux 2.6 +is the age in seconds after which dcache entries +can be reclaimed when memory is short. +.IP \[bu] +.I want_pages +.\" looks like this is unused in Linux 2.2 to Linux 2.6 +is nonzero when the kernel has called shrink_dcache_pages() and the +dcache isn't pruned yet. +.RE +.TP +.I /proc/sys/fs/dir\-notify\-enable +This file can be used to disable or enable the +.I dnotify +interface described in +.BR fcntl (2) +on a system-wide basis. +A value of 0 in this file disables the interface, +and a value of 1 enables it. +.TP +.I /proc/sys/fs/dquot\-max +This file shows the maximum number of cached disk quota entries. +On some (2.4) systems, it is not present. +If the number of free cached disk quota entries is very low and +you have some awesome number of simultaneous system users, +you might want to raise the limit. +.TP +.I /proc/sys/fs/dquot\-nr +This file shows the number of allocated disk quota +entries and the number of free disk quota entries. +.TP +.IR /proc/sys/fs/epoll/ " (since Linux 2.6.28)" +This directory contains the file +.IR max_user_watches , +which can be used to limit the amount of kernel memory consumed by the +.I epoll +interface. +For further details, see +.BR epoll (7). +.TP +.I /proc/sys/fs/file\-max +This file defines +a system-wide limit on the number of open files for all processes. +System calls that fail when encountering this limit fail with the error +.BR ENFILE . +(See also +.BR setrlimit (2), +which can be used by a process to set the per-process limit, +.BR RLIMIT_NOFILE , +on the number of files it may open.) +If you get lots +of error messages in the kernel log about running out of file handles +(open file descriptions) +(look for "VFS: file\-max limit reached"), +try increasing this value: +.IP +.in +4n +.EX +echo 100000 > /proc/sys/fs/file\-max +.EE +.in +.IP +Privileged processes +.RB ( CAP_SYS_ADMIN ) +can override the +.I file\-max +limit. +.TP +.I /proc/sys/fs/file\-nr +This (read-only) file contains three numbers: +the number of allocated file handles +(i.e., the number of open file descriptions; see +.BR open (2)); +the number of free file handles; +and the maximum number of file handles (i.e., the same value as +.IR /proc/sys/fs/file\-max ). +If the number of allocated file handles is close to the +maximum, you should consider increasing the maximum. +Before Linux 2.6, +the kernel allocated file handles dynamically, +but it didn't free them again. +Instead the free file handles were kept in a list for reallocation; +the "free file handles" value indicates the size of that list. +A large number of free file handles indicates that there was +a past peak in the usage of open file handles. +Since Linux 2.6, the kernel does deallocate freed file handles, +and the "free file handles" value is always zero. +.TP +.IR /proc/sys/fs/inode\-max " (only present until Linux 2.2)" +This file contains the maximum number of in-memory inodes. +This value should be 3\[en]4 times larger +than the value in +.IR file\-max , +since \fIstdin\fP, \fIstdout\fP +and network sockets also need an inode to handle them. +When you regularly run out of inodes, you need to increase this value. +.IP +Starting with Linux 2.4, +there is no longer a static limit on the number of inodes, +and this file is removed. +.TP +.I /proc/sys/fs/inode\-nr +This file contains the first two values from +.IR inode\-state . +.TP +.I /proc/sys/fs/inode\-state +This file +contains seven numbers: +.IR nr_inodes , +.IR nr_free_inodes , +.IR preshrink , +and four dummy values (always zero). +.IP +.I nr_inodes +is the number of inodes the system has allocated. +.\" This can be slightly more than +.\" .I inode\-max +.\" because Linux allocates them one page full at a time. +.I nr_free_inodes +represents the number of free inodes. +.IP +.I preshrink +is nonzero when the +.I nr_inodes +> +.I inode\-max +and the system needs to prune the inode list instead of allocating more; +since Linux 2.4, this field is a dummy value (always zero). +.TP +.IR /proc/sys/fs/inotify/ " (since Linux 2.6.13)" +This directory contains files +.IR max_queued_events ", " max_user_instances ", and " max_user_watches , +that can be used to limit the amount of kernel memory consumed by the +.I inotify +interface. +For further details, see +.BR inotify (7). +.TP +.I /proc/sys/fs/lease\-break\-time +This file specifies the grace period that the kernel grants to a process +holding a file lease +.RB ( fcntl (2)) +after it has sent a signal to that process notifying it +that another process is waiting to open the file. +If the lease holder does not remove or downgrade the lease within +this grace period, the kernel forcibly breaks the lease. +.TP +.I /proc/sys/fs/leases\-enable +This file can be used to enable or disable file leases +.RB ( fcntl (2)) +on a system-wide basis. +If this file contains the value 0, leases are disabled. +A nonzero value enables leases. +.TP +.IR /proc/sys/fs/mount\-max " (since Linux 4.9)" +.\" commit d29216842a85c7970c536108e093963f02714498 +The value in this file specifies the maximum number of mounts that may exist +in a mount namespace. +The default value in this file is 100,000. +.TP +.IR /proc/sys/fs/mqueue/ " (since Linux 2.6.6)" +This directory contains files +.IR msg_max ", " msgsize_max ", and " queues_max , +controlling the resources used by POSIX message queues. +See +.BR mq_overview (7) +for details. +.TP +.IR /proc/sys/fs/nr_open " (since Linux 2.6.25)" +.\" commit 9cfe015aa424b3c003baba3841a60dd9b5ad319b +This file imposes a ceiling on the value to which the +.B RLIMIT_NOFILE +resource limit can be raised (see +.BR getrlimit (2)). +This ceiling is enforced for both unprivileged and privileged process. +The default value in this file is 1048576. +(Before Linux 2.6.25, the ceiling for +.B RLIMIT_NOFILE +was hard-coded to the same value.) +.TP +.IR /proc/sys/fs/overflowgid " and " /proc/sys/fs/overflowuid +These files +allow you to change the value of the fixed UID and GID. +The default is 65534. +Some filesystems support only 16-bit UIDs and GIDs, although in Linux +UIDs and GIDs are 32 bits. +When one of these filesystems is mounted +with writes enabled, any UID or GID that would exceed 65535 is translated +to the overflow value before being written to disk. +.TP +.IR /proc/sys/fs/pipe\-max\-size " (since Linux 2.6.35)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-hard " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/pipe\-user\-pages\-soft " (since Linux 4.5)" +See +.BR pipe (7). +.TP +.IR /proc/sys/fs/protected_fifos " (since Linux 4.19)" +The value in this file is/can be set to one of the following: +.RS +.TP 4 +0 +Writing to FIFOs is unrestricted. +.TP +1 +Don't allow +.B O_CREAT +.BR open (2) +on FIFOs that the caller doesn't own in world-writable sticky directories, +unless the FIFO is owned by the owner of the directory. +.TP +2 +As for the value 1, +but the restriction also applies to group-writable sticky directories. +.RE +.IP +The intent of the above protections is to avoid unintentional writes to an +attacker-controlled FIFO when a program expected to create a regular file. +.TP +.IR /proc/sys/fs/protected_hardlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on the creation of hard links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, +a hard link can be created to a target file +only if one of the following conditions is true: +.RS +.IP \[bu] 3 +The calling process has the +.B CAP_FOWNER +capability in its user namespace +and the file UID has a mapping in the namespace. +.IP \[bu] +The filesystem UID of the process creating the link matches +the owner (UID) of the target file +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID). +.IP \[bu] +All of the following conditions are true: +.RS 4 +.IP \[bu] 3 +the target is a regular file; +.IP \[bu] +the target file does not have its set-user-ID mode bit enabled; +.IP \[bu] +the target file does not have both its set-group-ID and +group-executable mode bits enabled; and +.IP \[bu] +the caller has permission to read and write the target file +(either via the file's permissions mask or because it has +suitable capabilities). +.RE +.RE +.IP +The default value in this file is 0. +Setting the value to 1 +prevents a longstanding class of security issues caused by +hard-link-based time-of-check, time-of-use races, +most commonly seen in world-writable directories such as +.IR /tmp . +The common method of exploiting this flaw +is to cross privilege boundaries when following a given hard link +(i.e., a root process follows a hard link created by another user). +Additionally, on systems without separated partitions, +this stops unauthorized users from "pinning" vulnerable set-user-ID and +set-group-ID files against being upgraded by +the administrator, or linking to special files. +.TP +.IR /proc/sys/fs/protected_regular " (since Linux 4.19)" +The value in this file is/can be set to one of the following: +.RS +.TP 4 +0 +Writing to regular files is unrestricted. +.TP +1 +Don't allow +.B O_CREAT +.BR open (2) +on regular files that the caller doesn't own in +world-writable sticky directories, +unless the regular file is owned by the owner of the directory. +.TP +2 +As for the value 1, +but the restriction also applies to group-writable sticky directories. +.RE +.IP +The intent of the above protections is similar to +.IR protected_fifos , +but allows an application to +avoid writes to an attacker-controlled regular file, +where the application expected to create one. +.TP +.IR /proc/sys/fs/protected_symlinks " (since Linux 3.6)" +.\" commit 800179c9b8a1e796e441674776d11cd4c05d61d7 +When the value in this file is 0, +no restrictions are placed on following symbolic links +(i.e., this is the historical behavior before Linux 3.6). +When the value in this file is 1, symbolic links are followed only +in the following circumstances: +.RS +.IP \[bu] 3 +the filesystem UID of the process following the link matches +the owner (UID) of the symbolic link +(as described in +.BR credentials (7), +a process's filesystem UID is normally the same as its effective UID); +.IP \[bu] +the link is not in a sticky world-writable directory; or +.IP \[bu] +the symbolic link and its parent directory have the same owner (UID) +.RE +.IP +A system call that fails to follow a symbolic link +because of the above restrictions returns the error +.B EACCES +in +.IR errno . +.IP +The default value in this file is 0. +Setting the value to 1 avoids a longstanding class of security issues +based on time-of-check, time-of-use races when accessing symbolic links. +.TP +.IR /proc/sys/fs/suid_dumpable " (since Linux 2.6.13)" +.\" The following is based on text from Documentation/sysctl/kernel.txt +The value in this file is assigned to a process's "dumpable" flag +in the circumstances described in +.BR prctl (2). +In effect, +the value in this file determines whether core dump files are +produced for set-user-ID or otherwise protected/tainted binaries. +The "dumpable" setting also affects the ownership of files in a process's +.IR /proc/ pid +directory, as described above. +.IP +Three different integer values can be specified: +.RS +.TP +\fI0\ (default)\fP +.\" In kernel source: SUID_DUMP_DISABLE +This provides the traditional (pre-Linux 2.6.13) behavior. +A core dump will not be produced for a process which has +changed credentials (by calling +.BR seteuid (2), +.BR setgid (2), +or similar, or by executing a set-user-ID or set-group-ID program) +or whose binary does not have read permission enabled. +.TP +\fI1\ ("debug")\fP +.\" In kernel source: SUID_DUMP_USER +All processes dump core when possible. +(Reasons why a process might nevertheless not dump core are described in +.BR core (5).) +The core dump is owned by the filesystem user ID of the dumping process +and no security is applied. +This is intended for system debugging situations only: +this mode is insecure because it allows unprivileged users to +examine the memory contents of privileged processes. +.TP +\fI2\ ("suidsafe")\fP +.\" In kernel source: SUID_DUMP_ROOT +Any binary which normally would not be dumped (see "0" above) +is dumped readable by root only. +This allows the user to remove the core dump file but not to read it. +For security reasons core dumps in this mode will not overwrite one +another or other files. +This mode is appropriate when administrators are +attempting to debug problems in a normal environment. +.IP +Additionally, since Linux 3.6, +.\" 9520628e8ceb69fa9a4aee6b57f22675d9e1b709 +.I /proc/sys/kernel/core_pattern +must either be an absolute pathname +or a pipe command, as detailed in +.BR core (5). +Warnings will be written to the kernel log if +.I core_pattern +does not follow these rules, and no core dump will be produced. +.\" 54b501992dd2a839e94e76aa392c392b55080ce8 +.RE +.IP +For details of the effect of a process's "dumpable" setting +on ptrace access mode checking, see +.BR ptrace (2). +.TP +.I /proc/sys/fs/super\-max +This file +controls the maximum number of superblocks, and +thus the maximum number of mounted filesystems the kernel +can have. +You need increase only +.I super\-max +if you need to mount more filesystems than the current value in +.I super\-max +allows you to. +.TP +.I /proc/sys/fs/super\-nr +This file +contains the number of filesystems currently mounted. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_kernel.5 b/man5/proc_sys_kernel.5 new file mode 100644 index 0000000..334d3be --- /dev/null +++ b/man5/proc_sys_kernel.5 @@ -0,0 +1,691 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_kernel 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/kernel/ \- control a range of kernel parameters +.SH DESCRIPTION +.TP +.I /proc/sys/kernel/ +This directory contains files controlling a range of kernel parameters, +as described below. +.TP +.I /proc/sys/kernel/acct +This file +contains three numbers: +.IR highwater , +.IR lowwater , +and +.IR frequency . +If BSD-style process accounting is enabled, these values control +its behavior. +If free space on filesystem where the log lives goes below +.I lowwater +percent, accounting suspends. +If free space gets above +.I highwater +percent, accounting resumes. +.I frequency +determines +how often the kernel checks the amount of free space (value is in +seconds). +Default values are 4, 2, and 30. +That is, suspend accounting if 2% or less space is free; resume it +if 4% or more space is free; consider information about amount of free space +valid for 30 seconds. +.TP +.IR /proc/sys/kernel/auto_msgmni " (Linux 2.6.27 to Linux 3.18)" +.\" commit 9eefe520c814f6f62c5d36a2ddcd3fb99dfdb30e (introduces feature) +.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 (rendered redundant) +From Linux 2.6.27 to Linux 3.18, +this file was used to control recomputing of the value in +.I /proc/sys/kernel/msgmni +upon the addition or removal of memory or upon IPC namespace creation/removal. +Echoing "1" into this file enabled +.I msgmni +automatic recomputing (and triggered a recomputation of +.I msgmni +based on the current amount of available memory and number of IPC namespaces). +Echoing "0" disabled automatic recomputing. +(Automatic recomputing was also disabled if a value was explicitly assigned to +.IR /proc/sys/kernel/msgmni .) +The default value in +.I auto_msgmni +was 1. +.IP +Since Linux 3.19, the content of this file has no effect (because +.I msgmni +.\" FIXME Must document the 3.19 'msgmni' changes. +defaults to near the maximum value possible), +and reads from this file always return the value "0". +.TP +.IR /proc/sys/kernel/cap_last_cap " (since Linux 3.2)" +See +.BR capabilities (7). +.TP +.IR /proc/sys/kernel/cap\-bound " (from Linux 2.2 to Linux 2.6.24)" +This file holds the value of the kernel +.I "capability bounding set" +(expressed as a signed decimal number). +This set is ANDed against the capabilities permitted to a process +during +.BR execve (2). +Starting with Linux 2.6.25, +the system-wide capability bounding set disappeared, +and was replaced by a per-thread bounding set; see +.BR capabilities (7). +.TP +.I /proc/sys/kernel/core_pattern +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_pipe_limit +See +.BR core (5). +.TP +.I /proc/sys/kernel/core_uses_pid +See +.BR core (5). +.TP +.I /proc/sys/kernel/ctrl\-alt\-del +This file +controls the handling of Ctrl-Alt-Del from the keyboard. +When the value in this file is 0, Ctrl-Alt-Del is trapped and +sent to the +.BR init (1) +program to handle a graceful restart. +When the value is greater than zero, Linux's reaction to a Vulcan +Nerve Pinch (tm) will be an immediate reboot, without even +syncing its dirty buffers. +Note: when a program (like dosemu) has the keyboard in "raw" +mode, the Ctrl-Alt-Del is intercepted by the program before it +ever reaches the kernel tty layer, and it's up to the program +to decide what to do with it. +.TP +.IR /proc/sys/kernel/dmesg_restrict " (since Linux 2.6.37)" +The value in this file determines who can see kernel syslog contents. +A value of 0 in this file imposes no restrictions. +If the value is 1, only privileged users can read the kernel syslog. +(See +.BR syslog (2) +for more details.) +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.B CAP_SYS_ADMIN +capability may change the value in this file. +.TP +.IR /proc/sys/kernel/domainname " and " /proc/sys/kernel/hostname +can be used to set the NIS/YP domainname and the +hostname of your box in exactly the same way as the commands +.BR domainname (1) +and +.BR hostname (1), +that is: +.IP +.in +4n +.EX +.RB "#" " echo \[aq]darkstar\[aq] > /proc/sys/kernel/hostname" +.RB "#" " echo \[aq]mydomain\[aq] > /proc/sys/kernel/domainname" +.EE +.in +.IP +has the same effect as +.IP +.in +4n +.EX +.RB "#" " hostname \[aq]darkstar\[aq]" +.RB "#" " domainname \[aq]mydomain\[aq]" +.EE +.in +.IP +Note, however, that the classic darkstar.frop.org has the +hostname "darkstar" and DNS (Internet Domain Name Server) +domainname "frop.org", not to be confused with the NIS (Network +Information Service) or YP (Yellow Pages) domainname. +These two +domain names are in general different. +For a detailed discussion +see the +.BR hostname (1) +man page. +.TP +.I /proc/sys/kernel/hotplug +This file +contains the pathname for the hotplug policy agent. +The default value in this file is +.IR /sbin/hotplug . +.TP +.\" Removed in commit 87f504e5c78b910b0c1d6ffb89bc95e492322c84 (tglx/history.git) +.IR /proc/sys/kernel/htab\-reclaim " (before Linux 2.4.9.2)" +(PowerPC only) If this file is set to a nonzero value, +the PowerPC htab +.\" removed in commit 1b483a6a7b2998e9c98ad985d7494b9b725bd228, before Linux 2.6.28 +(see kernel file +.IR Documentation/powerpc/ppc_htab.txt ) +is pruned +each time the system hits the idle loop. +.TP +.I /proc/sys/kernel/keys/ +This directory contains various files that define parameters and limits +for the key-management facility. +These files are described in +.BR keyrings (7). +.TP +.IR /proc/sys/kernel/kptr_restrict " (since Linux 2.6.38)" +.\" 455cd5ab305c90ffc422dd2e0fb634730942b257 +The value in this file determines whether kernel addresses are exposed via +.I /proc +files and other interfaces. +A value of 0 in this file imposes no restrictions. +If the value is 1, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros unless the user has the +.B CAP_SYSLOG +capability. +If the value is 2, kernel pointers printed using the +.I %pK +format specifier will be replaced with zeros regardless +of the user's capabilities. +The initial default value for this file was 1, +but the default was changed +.\" commit 411f05f123cbd7f8aa1edcae86970755a6e2a9d9 +to 0 in Linux 2.6.39. +Since Linux 3.4, +.\" commit 620f6e8e855d6d447688a5f67a4e176944a084e8 +only users with the +.B CAP_SYS_ADMIN +capability can change the value in this file. +.TP +.I /proc/sys/kernel/l2cr +(PowerPC only) This file +contains a flag that controls the L2 cache of G3 processor +boards. +If 0, the cache is disabled. +Enabled if nonzero. +.TP +.I /proc/sys/kernel/modprobe +This file contains the pathname for the kernel module loader. +The default value is +.IR /sbin/modprobe . +The file is present only if the kernel is built with the +.B CONFIG_MODULES +.RB ( CONFIG_KMOD +in Linux 2.6.26 and earlier) +option enabled. +It is described by the Linux kernel source file +.I Documentation/kmod.txt +(present only in Linux 2.4 and earlier). +.TP +.IR /proc/sys/kernel/modules_disabled " (since Linux 2.6.31)" +.\" 3d43321b7015387cfebbe26436d0e9d299162ea1 +.\" From Documentation/sysctl/kernel.txt +A toggle value indicating if modules are allowed to be loaded +in an otherwise modular kernel. +This toggle defaults to off (0), but can be set true (1). +Once true, modules can be neither loaded nor unloaded, +and the toggle cannot be set back to false. +The file is present only if the kernel is built with the +.B CONFIG_MODULES +option enabled. +.TP +.IR /proc/sys/kernel/msgmax " (since Linux 2.2)" +This file defines +a system-wide limit specifying the maximum number of bytes in +a single message written on a System V message queue. +.TP +.IR /proc/sys/kernel/msgmni " (since Linux 2.4)" +This file defines the system-wide limit on the number of +message queue identifiers. +See also +.IR /proc/sys/kernel/auto_msgmni . +.TP +.IR /proc/sys/kernel/msgmnb " (since Linux 2.2)" +This file defines a system-wide parameter used to initialize the +.I msg_qbytes +setting for subsequently created message queues. +The +.I msg_qbytes +setting specifies the maximum number of bytes that may be written to the +message queue. +.TP +.IR /proc/sys/kernel/ngroups_max " (since Linux 2.6.4)" +This is a read-only file that displays the upper limit on the +number of a process's group memberships. +.TP +.IR /proc/sys/kernel/ns_last_pid " (since Linux 3.3)" +See +.BR pid_namespaces (7). +.TP +.IR /proc/sys/kernel/ostype " and " /proc/sys/kernel/osrelease +These files +give substrings of +.IR /proc/version . +.TP +.IR /proc/sys/kernel/overflowgid " and " /proc/sys/kernel/overflowuid +These files duplicate the files +.I /proc/sys/fs/overflowgid +and +.IR /proc/sys/fs/overflowuid . +.TP +.I /proc/sys/kernel/panic +This file gives read/write access to the kernel variable +.IR panic_timeout . +If this is zero, the kernel will loop on a panic; if nonzero, +it indicates that the kernel should autoreboot after this number +of seconds. +When you use the +software watchdog device driver, the recommended setting is 60. +.TP +.IR /proc/sys/kernel/panic_on_oops " (since Linux 2.5.68)" +This file controls the kernel's behavior when an oops +or BUG is encountered. +If this file contains 0, then the system +tries to continue operation. +If it contains 1, then the system +delays a few seconds (to give klogd time to record the oops output) +and then panics. +If the +.I /proc/sys/kernel/panic +file is also nonzero, then the machine will be rebooted. +.TP +.IR /proc/sys/kernel/pid_max " (since Linux 2.5.34)" +This file specifies the value at which PIDs wrap around +(i.e., the value in this file is one greater than the maximum PID). +PIDs greater than this value are not allocated; +thus, the value in this file also acts as a system-wide limit +on the total number of processes and threads. +The default value for this file, 32768, +results in the same range of PIDs as on earlier kernels. +On 32-bit platforms, 32768 is the maximum value for +.IR pid_max . +On 64-bit systems, +.I pid_max +can be set to any value up to 2\[ha]22 +.RB ( PID_MAX_LIMIT , +approximately 4 million). +.\" Prior to Linux 2.6.10, pid_max could also be raised above 32768 on 32-bit +.\" platforms, but this broke /proc/[pid] +.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2 +.TP +.IR /proc/sys/kernel/powersave\-nap " (PowerPC only)" +This file contains a flag. +If set, Linux-PPC will use the "nap" mode of +powersaving, +otherwise the "doze" mode will be used. +.TP +.I /proc/sys/kernel/printk +See +.BR syslog (2). +.TP +.IR /proc/sys/kernel/pty " (since Linux 2.6.4)" +This directory contains two files relating to the number of UNIX 98 +pseudoterminals (see +.BR pts (4)) +on the system. +.TP +.I /proc/sys/kernel/pty/max +This file defines the maximum number of pseudoterminals. +.\" FIXME Document /proc/sys/kernel/pty/reserve +.\" New in Linux 3.3 +.\" commit e9aba5158a80098447ff207a452a3418ae7ee386 +.TP +.I /proc/sys/kernel/pty/nr +This read-only file +indicates how many pseudoterminals are currently in use. +.TP +.I /proc/sys/kernel/random/ +This directory +contains various parameters controlling the operation of the file +.IR /dev/random . +See +.BR random (4) +for further information. +.TP +.IR /proc/sys/kernel/random/uuid " (since Linux 2.4)" +Each read from this read-only file returns a randomly generated 128-bit UUID, +as a string in the standard UUID format. +.TP +.IR /proc/sys/kernel/randomize_va_space " (since Linux 2.6.12)" +.\" Some further details can be found in Documentation/sysctl/kernel.txt +Select the address space layout randomization (ASLR) policy for the system +(on architectures that support ASLR). +Three values are supported for this file: +.RS +.TP +.B 0 +Turn ASLR off. +This is the default for architectures that don't support ASLR, +and when the kernel is booted with the +.I norandmaps +parameter. +.TP +.B 1 +Make the addresses of +.BR mmap (2) +allocations, the stack, and the VDSO page randomized. +Among other things, this means that shared libraries will be +loaded at randomized addresses. +The text segment of PIE-linked binaries will also be loaded +at a randomized address. +This value is the default if the kernel was configured with +.BR CONFIG_COMPAT_BRK . +.TP +.B 2 +(Since Linux 2.6.25) +.\" commit c1d171a002942ea2d93b4fbd0c9583c56fce0772 +Also support heap randomization. +This value is the default if the kernel was not configured with +.BR CONFIG_COMPAT_BRK . +.RE +.TP +.I /proc/sys/kernel/real\-root\-dev +This file is documented in the Linux kernel source file +.I Documentation/admin\-guide/initrd.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/initrd.txt +before Linux 4.10). +.TP +.IR /proc/sys/kernel/reboot\-cmd " (Sparc only)" +This file seems to be a way to give an argument to the SPARC +ROM/Flash boot loader. +Maybe to tell it what to do after +rebooting? +.TP +.I /proc/sys/kernel/rtsig\-max +(Up to and including Linux 2.6.7; see +.BR setrlimit (2)) +This file can be used to tune the maximum number +of POSIX real-time (queued) signals that can be outstanding +in the system. +.TP +.I /proc/sys/kernel/rtsig\-nr +(Up to and including Linux 2.6.7.) +This file shows the number of POSIX real-time signals currently queued. +.TP +.IR /proc/ pid /sched_autogroup_enabled " (since Linux 2.6.38)" +.\" commit 5091faa449ee0b7d73bc296a93bca9540fc51d0a +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_child_runs_first " (since Linux 2.6.23)" +If this file contains the value zero, then, after a +.BR fork (2), +the parent is first scheduled on the CPU. +If the file contains a nonzero value, +then the child is scheduled first on the CPU. +(Of course, on a multiprocessor system, +the parent and the child might both immediately be scheduled on a CPU.) +.TP +.IR /proc/sys/kernel/sched_rr_timeslice_ms " (since Linux 3.9)" +See +.BR sched_rr_get_interval (2). +.TP +.IR /proc/sys/kernel/sched_rt_period_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/sched_rt_runtime_us " (since Linux 2.6.25)" +See +.BR sched (7). +.TP +.IR /proc/sys/kernel/seccomp/ " (since Linux 4.14)" +.\" commit 8e5f1ad116df6b0de65eac458d5e7c318d1c05af +This directory provides additional seccomp information and +configuration. +See +.BR seccomp (2) +for further details. +.TP +.IR /proc/sys/kernel/sem " (since Linux 2.4)" +This file contains 4 numbers defining limits for System V IPC semaphores. +These fields are, in order: +.RS +.TP +SEMMSL +The maximum semaphores per semaphore set. +.TP +SEMMNS +A system-wide limit on the number of semaphores in all semaphore sets. +.TP +SEMOPM +The maximum number of operations that may be specified in a +.BR semop (2) +call. +.TP +SEMMNI +A system-wide limit on the maximum number of semaphore identifiers. +.RE +.TP +.I /proc/sys/kernel/sg\-big\-buff +This file +shows the size of the generic SCSI device (sg) buffer. +You can't tune it just yet, but you could change it at +compile time by editing +.I include/scsi/sg.h +and changing +the value of +.BR SG_BIG_BUFF . +However, there shouldn't be any reason to change this value. +.TP +.IR /proc/sys/kernel/shm_rmid_forced " (since Linux 3.1)" +.\" commit b34a6b1da371ed8af1221459a18c67970f7e3d53 +.\" See also Documentation/sysctl/kernel.txt +If this file is set to 1, all System V shared memory segments will +be marked for destruction as soon as the number of attached processes +falls to zero; +in other words, it is no longer possible to create shared memory segments +that exist independently of any attached process. +.IP +The effect is as though a +.BR shmctl (2) +.B IPC_RMID +is performed on all existing segments as well as all segments +created in the future (until this file is reset to 0). +Note that existing segments that are attached to no process will be +immediately destroyed when this file is set to 1. +Setting this option will also destroy segments that were created, +but never attached, +upon termination of the process that created the segment with +.BR shmget (2). +.IP +Setting this file to 1 provides a way of ensuring that +all System V shared memory segments are counted against the +resource usage and resource limits (see the description of +.B RLIMIT_AS +in +.BR getrlimit (2)) +of at least one process. +.IP +Because setting this file to 1 produces behavior that is nonstandard +and could also break existing applications, +the default value in this file is 0. +Set this file to 1 only if you have a good understanding +of the semantics of the applications using +System V shared memory on your system. +.TP +.IR /proc/sys/kernel/shmall " (since Linux 2.2)" +This file +contains the system-wide limit on the total number of pages of +System V shared memory. +.TP +.IR /proc/sys/kernel/shmmax " (since Linux 2.2)" +This file +can be used to query and set the run-time limit +on the maximum (System V IPC) shared memory segment size that can be +created. +Shared memory segments up to 1 GB are now supported in the +kernel. +This value defaults to +.BR SHMMAX . +.TP +.IR /proc/sys/kernel/shmmni " (since Linux 2.4)" +This file +specifies the system-wide maximum number of System V shared memory +segments that can be created. +.TP +.IR /proc/sys/kernel/sysctl_writes_strict " (since Linux 3.16)" +.\" commit f88083005ab319abba5d0b2e4e997558245493c8 +.\" commit 2ca9bb456ada8bcbdc8f77f8fc78207653bbaa92 +.\" commit f4aacea2f5d1a5f7e3154e967d70cf3f711bcd61 +.\" commit 24fe831c17ab8149413874f2fd4e5c8a41fcd294 +The value in this file determines how the file offset affects +the behavior of updating entries in files under +.IR /proc/sys . +The file has three possible values: +.RS +.TP 4 +\-1 +This provides legacy handling, with no printk warnings. +Each +.BR write (2) +must fully contain the value to be written, +and multiple writes on the same file descriptor +will overwrite the entire value, regardless of the file position. +.TP +0 +(default) This provides the same behavior as for \-1, +but printk warnings are written for processes that +perform writes when the file offset is not 0. +.TP +1 +Respect the file offset when writing strings into +.I /proc/sys +files. +Multiple writes will +.I append +to the value buffer. +Anything written beyond the maximum length +of the value buffer will be ignored. +Writes to numeric +.I /proc/sys +entries must always be at file offset 0 and the value must be +fully contained in the buffer provided to +.BR write (2). +.\" FIXME . +.\" With /proc/sys/kernel/sysctl_writes_strict==1, writes at an +.\" offset other than 0 do not generate an error. Instead, the +.\" write() succeeds, but the file is left unmodified. +.\" This is surprising. The behavior may change in the future. +.\" See thread.gmane.org/gmane.linux.man/9197 +.\" From: Michael Kerrisk (man-pages +.\" Subject: sysctl_writes_strict documentation + an oddity? +.\" Newsgroups: gmane.linux.man, gmane.linux.kernel +.\" Date: 2015-05-09 08:54:11 GMT +.RE +.TP +.I /proc/sys/kernel/sysrq +This file controls the functions allowed to be invoked by the SysRq key. +By default, +the file contains 1 meaning that every possible SysRq request is allowed +(in older kernel versions, SysRq was disabled by default, +and you were required to specifically enable it at run-time, +but this is not the case any more). +Possible values in this file are: +.RS +.TP 5 +0 +Disable sysrq completely +.TP +1 +Enable all functions of sysrq +.TP +> 1 +Bit mask of allowed sysrq functions, as follows: +.PD 0 +.RS +.TP 5 +\ \ 2 +Enable control of console logging level +.TP +\ \ 4 +Enable control of keyboard (SAK, unraw) +.TP +\ \ 8 +Enable debugging dumps of processes etc. +.TP +\ 16 +Enable sync command +.TP +\ 32 +Enable remount read-only +.TP +\ 64 +Enable signaling of processes (term, kill, oom-kill) +.TP +128 +Allow reboot/poweroff +.TP +256 +Allow nicing of all real-time tasks +.RE +.PD +.RE +.IP +This file is present only if the +.B CONFIG_MAGIC_SYSRQ +kernel configuration option is enabled. +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.TP +.I /proc/sys/kernel/version +This file contains a string such as: +.IP +.in +4n +.EX +#5 Wed Feb 25 21:49:24 MET 1998 +.EE +.in +.IP +The "#5" means that +this is the fifth kernel built from this source base and the +date following it indicates the time the kernel was built. +.TP +.IR /proc/sys/kernel/threads\-max " (since Linux 2.3.11)" +.\" The following is based on Documentation/sysctl/kernel.txt +This file specifies the system-wide limit on the number of +threads (tasks) that can be created on the system. +.IP +Since Linux 4.1, +.\" commit 230633d109e35b0a24277498e773edeb79b4a331 +the value that can be written to +.I threads\-max +is bounded. +The minimum value that can be written is 20. +The maximum value that can be written is given by the +constant +.B FUTEX_TID_MASK +(0x3fffffff). +If a value outside of this range is written to +.IR threads\-max , +the error +.B EINVAL +occurs. +.IP +The value written is checked against the available RAM pages. +If the thread structures would occupy too much (more than 1/8th) +of the available RAM pages, +.I threads\-max +is reduced accordingly. +.TP +.IR /proc/sys/kernel/yama/ptrace_scope " (since Linux 3.5)" +See +.BR ptrace (2). +.TP +.IR /proc/sys/kernel/zero\-paged " (PowerPC only)" +This file +contains a flag. +When enabled (nonzero), Linux-PPC will pre-zero pages in +the idle loop, possibly speeding up get_free_pages. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_net.5 b/man5/proc_sys_net.5 new file mode 100644 index 0000000..02214cc --- /dev/null +++ b/man5/proc_sys_net.5 @@ -0,0 +1,34 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_net 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/net/ \- networking +.SH DESCRIPTION +.TP +.I /proc/sys/net/ +This directory contains networking stuff. +Explanations for some of the files under this directory can be found in +.BR tcp (7) +and +.BR ip (7). +.TP +.I /proc/sys/net/core/bpf_jit_enable +See +.BR bpf (2). +.TP +.I /proc/sys/net/core/somaxconn +This file defines a ceiling value for the +.I backlog +argument of +.BR listen (2); +see the +.BR listen (2) +manual page for details. +.SH SEE ALSO +.BR proc (5), +.BR proc_net (5) diff --git a/man5/proc_sys_proc.5 b/man5/proc_sys_proc.5 new file mode 100644 index 0000000..ad9b232 --- /dev/null +++ b/man5/proc_sys_proc.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_proc 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/proc/ \- ??? +.SH DESCRIPTION +.TP +.I /proc/sys/proc/ +This directory may be empty. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_sunrpc.5 b/man5/proc_sys_sunrpc.5 new file mode 100644 index 0000000..06e90d7 --- /dev/null +++ b/man5/proc_sys_sunrpc.5 @@ -0,0 +1,19 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_sunrpc 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/sunrpc/ \- Sun remote procedure call for NFS +.SH DESCRIPTION +.TP +.I /proc/sys/sunrpc/ +This directory supports Sun remote procedure call for network filesystem +(NFS). +On some systems, it is not present. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_user.5 b/man5/proc_sys_user.5 new file mode 100644 index 0000000..34d9f88 --- /dev/null +++ b/man5/proc_sys_user.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_user 5 2023-11-24 "Linux man-pages 6.7" +.SH NAME +/proc/sys/user/ \- limits on the number of namespaces of various types +.SH DESCRIPTION +.TP +.IR /proc/sys/user/ " (since Linux 4.9)" +See +.BR namespaces (7). +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sys_vm.5 b/man5/proc_sys_vm.5 new file mode 100644 index 0000000..cbd5cf1 --- /dev/null +++ b/man5/proc_sys_vm.5 @@ -0,0 +1,420 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) , Andries Brouwer +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sys_vm 5 2023-09-30 "Linux man-pages 6.7" +.SH NAME +/proc/sys/vm/ \- virtual memory subsystem +.SH DESCRIPTION +.TP +.I /proc/sys/vm/ +This directory contains files for memory management tuning, buffer, and +cache management. +.TP +.IR /proc/sys/vm/admin_reserve_kbytes " (since Linux 3.10)" +.\" commit 4eeab4f5580d11bffedc697684b91b0bca0d5009 +This file defines the amount of free memory (in KiB) on the system that +should be reserved for users with the capability +.BR CAP_SYS_ADMIN . +.IP +The default value in this file is the minimum of [3% of free pages, 8MiB] +expressed as KiB. +The default is intended to provide enough for the superuser +to log in and kill a process, if necessary, +under the default overcommit 'guess' mode (i.e., 0 in +.IR /proc/sys/vm/overcommit_memory ). +.IP +Systems running in "overcommit never" mode (i.e., 2 in +.IR /proc/sys/vm/overcommit_memory ) +should increase the value in this file to account +for the full virtual memory size of the programs used to recover (e.g., +.BR login (1) +.BR ssh (1), +and +.BR top (1)) +Otherwise, the superuser may not be able to log in to recover the system. +For example, on x86-64 a suitable value is 131072 (128MiB reserved). +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/compact_memory " (since Linux 2.6.35)" +When 1 is written to this file, all zones are compacted such that free +memory is available in contiguous blocks where possible. +The effect of this action can be seen by examining +.IR /proc/buddyinfo . +.IP +Present only if the kernel was configured with +.BR CONFIG_COMPACTION . +.TP +.IR /proc/sys/vm/drop_caches " (since Linux 2.6.16)" +Writing to this file causes the kernel to drop clean caches, dentries, and +inodes from memory, causing that memory to become free. +This can be useful for memory management testing and +performing reproducible filesystem benchmarks. +Because writing to this file causes the benefits of caching to be lost, +it can degrade overall system performance. +.IP +To free pagecache, use: +.IP +.in +4n +.EX +echo 1 > /proc/sys/vm/drop_caches +.EE +.in +.IP +To free dentries and inodes, use: +.IP +.in +4n +.EX +echo 2 > /proc/sys/vm/drop_caches +.EE +.in +.IP +To free pagecache, dentries, and inodes, use: +.IP +.in +4n +.EX +echo 3 > /proc/sys/vm/drop_caches +.EE +.in +.IP +Because writing to this file is a nondestructive operation and dirty objects +are not freeable, the +user should run +.BR sync (1) +first. +.TP +.IR /proc/sys/vm/sysctl_hugetlb_shm_group " (since Linux 2.6.7)" +This writable file contains a group ID that is allowed +to allocate memory using huge pages. +If a process has a filesystem group ID or any supplementary group ID that +matches this group ID, +then it can make huge-page allocations without holding the +.B CAP_IPC_LOCK +capability; see +.BR memfd_create (2), +.BR mmap (2), +and +.BR shmget (2). +.TP +.IR /proc/sys/vm/legacy_va_layout " (since Linux 2.6.9)" +.\" The following is from Documentation/filesystems/proc.txt +If nonzero, this disables the new 32-bit memory-mapping layout; +the kernel will use the legacy (2.4) layout for all processes. +.TP +.IR /proc/sys/vm/memory_failure_early_kill " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Control how to kill processes when an uncorrected memory error +(typically a 2-bit error in a memory module) +that cannot be handled by the kernel +is detected in the background by hardware. +In some cases (like the page still having a valid copy on disk), +the kernel will handle the failure +transparently without affecting any applications. +But if there is no other up-to-date copy of the data, +it will kill processes to prevent any data corruptions from propagating. +.IP +The file has one of the following values: +.RS +.TP +.B 1 +Kill all processes that have the corrupted-and-not-reloadable page mapped +as soon as the corruption is detected. +Note that this is not supported for a few types of pages, +such as kernel internally +allocated data or the swap cache, but works for the majority of user pages. +.TP +.B 0 +Unmap the corrupted page from all processes and kill a process +only if it tries to access the page. +.RE +.IP +The kill is performed using a +.B SIGBUS +signal with +.I si_code +set to +.BR BUS_MCEERR_AO . +Processes can handle this if they want to; see +.BR sigaction (2) +for more details. +.IP +This feature is active only on architectures/platforms with advanced machine +check handling and depends on the hardware capabilities. +.IP +Applications can override the +.I memory_failure_early_kill +setting individually with the +.BR prctl (2) +.B PR_MCE_KILL +operation. +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/memory_failure_recovery " (since Linux 2.6.32)" +.\" The following is based on the text in Documentation/sysctl/vm.txt +Enable memory failure recovery (when supported by the platform). +.RS +.TP +.B 1 +Attempt recovery. +.TP +.B 0 +Always panic on a memory failure. +.RE +.IP +Present only if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . +.TP +.IR /proc/sys/vm/oom_dump_tasks " (since Linux 2.6.25)" +.\" The following is from Documentation/sysctl/vm.txt +Enables a system-wide task dump (excluding kernel threads) to be +produced when the kernel performs an OOM-killing. +The dump includes the following information +for each task (thread, process): +thread ID, real user ID, thread group ID (process ID), +virtual memory size, resident set size, +the CPU that the task is scheduled on, +oom_adj score (see the description of +.IR /proc/ pid /oom_adj ), +and command name. +This is helpful to determine why the OOM-killer was invoked +and to identify the rogue task that caused it. +.IP +If this contains the value zero, this information is suppressed. +On very large systems with thousands of tasks, +it may not be feasible to dump the memory state information for each one. +Such systems should not be forced to incur a performance penalty in +OOM situations when the information may not be desired. +.IP +If this is set to nonzero, this information is shown whenever the +OOM-killer actually kills a memory-hogging task. +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/oom_kill_allocating_task " (since Linux 2.6.24)" +.\" The following is from Documentation/sysctl/vm.txt +This enables or disables killing the OOM-triggering task in +out-of-memory situations. +.IP +If this is set to zero, the OOM-killer will scan through the entire +tasklist and select a task based on heuristics to kill. +This normally selects a rogue memory-hogging task that +frees up a large amount of memory when killed. +.IP +If this is set to nonzero, the OOM-killer simply kills the task that +triggered the out-of-memory condition. +This avoids a possibly expensive tasklist scan. +.IP +If +.I /proc/sys/vm/panic_on_oom +is nonzero, it takes precedence over whatever value is used in +.IR /proc/sys/vm/oom_kill_allocating_task . +.IP +The default value is 0. +.TP +.IR /proc/sys/vm/overcommit_kbytes " (since Linux 3.14)" +.\" commit 49f0ce5f92321cdcf741e35f385669a421013cb7 +This writable file provides an alternative to +.I /proc/sys/vm/overcommit_ratio +for controlling the +.I CommitLimit +when +.I /proc/sys/vm/overcommit_memory +has the value 2. +It allows the amount of memory overcommitting to be specified as +an absolute value (in kB), +rather than as a percentage, as is done with +.IR overcommit_ratio . +This allows for finer-grained control of +.I CommitLimit +on systems with extremely large memory sizes. +.IP +Only one of +.I overcommit_kbytes +or +.I overcommit_ratio +can have an effect: +if +.I overcommit_kbytes +has a nonzero value, then it is used to calculate +.IR CommitLimit , +otherwise +.I overcommit_ratio +is used. +Writing a value to either of these files causes the +value in the other file to be set to zero. +.TP +.I /proc/sys/vm/overcommit_memory +This file contains the kernel virtual memory accounting mode. +Values are: +.RS +.IP +0: heuristic overcommit (this is the default) +.br +1: always overcommit, never check +.br +2: always check, never overcommit +.RE +.IP +In mode 0, calls of +.BR mmap (2) +with +.B MAP_NORESERVE +are not checked, and the default check is very weak, +leading to the risk of getting a process "OOM-killed". +.IP +In mode 1, the kernel pretends there is always enough memory, +until memory actually runs out. +One use case for this mode is scientific computing applications +that employ large sparse arrays. +Before Linux 2.6.0, any nonzero value implies mode 1. +.IP +In mode 2 (available since Linux 2.6), the total virtual address space +that can be allocated +.RI ( CommitLimit +in +.IR /proc/meminfo ) +is calculated as +.IP +.in +4n +.EX +CommitLimit = (total_RAM \- total_huge_TLB) * + overcommit_ratio / 100 + total_swap +.EE +.in +.IP +where: +.RS +.IP \[bu] 3 +.I total_RAM +is the total amount of RAM on the system; +.IP \[bu] +.I total_huge_TLB +is the amount of memory set aside for huge pages; +.IP \[bu] +.I overcommit_ratio +is the value in +.IR /proc/sys/vm/overcommit_ratio ; +and +.IP \[bu] +.I total_swap +is the amount of swap space. +.RE +.IP +For example, on a system with 16 GB of physical RAM, 16 GB +of swap, no space dedicated to huge pages, and an +.I overcommit_ratio +of 50, this formula yields a +.I CommitLimit +of 24 GB. +.IP +Since Linux 3.14, if the value in +.I /proc/sys/vm/overcommit_kbytes +is nonzero, then +.I CommitLimit +is instead calculated as: +.IP +.in +4n +.EX +CommitLimit = overcommit_kbytes + total_swap +.EE +.in +.IP +See also the description of +.I /proc/sys/vm/admin_reserve_kbytes +and +.IR /proc/sys/vm/user_reserve_kbytes . +.TP +.IR /proc/sys/vm/overcommit_ratio " (since Linux 2.6.0)" +This writable file defines a percentage by which memory +can be overcommitted. +The default value in the file is 50. +See the description of +.IR /proc/sys/vm/overcommit_memory . +.TP +.IR /proc/sys/vm/panic_on_oom " (since Linux 2.6.18)" +.\" The following is adapted from Documentation/sysctl/vm.txt +This enables or disables a kernel panic in +an out-of-memory situation. +.IP +If this file is set to the value 0, +the kernel's OOM-killer will kill some rogue process. +Usually, the OOM-killer is able to kill a rogue process and the +system will survive. +.IP +If this file is set to the value 1, +then the kernel normally panics when out-of-memory happens. +However, if a process limits allocations to certain nodes +using memory policies +.RB ( mbind (2) +.BR MPOL_BIND ) +or cpusets +.RB ( cpuset (7)) +and those nodes reach memory exhaustion status, +one process may be killed by the OOM-killer. +No panic occurs in this case: +because other nodes' memory may be free, +this means the system as a whole may not have reached +an out-of-memory situation yet. +.IP +If this file is set to the value 2, +the kernel always panics when an out-of-memory condition occurs. +.IP +The default value is 0. +1 and 2 are for failover of clustering. +Select either according to your policy of failover. +.TP +.I /proc/sys/vm/swappiness +.\" The following is from Documentation/sysctl/vm.txt +The value in this file controls how aggressively the kernel will swap +memory pages. +Higher values increase aggressiveness, lower values +decrease aggressiveness. +The default value is 60. +.TP +.IR /proc/sys/vm/user_reserve_kbytes " (since Linux 3.10)" +.\" commit c9b1d0981fcce3d9976d7b7a56e4e0503bc610dd +Specifies an amount of memory (in KiB) to reserve for user processes. +This is intended to prevent a user from starting a single memory hogging +process, such that they cannot recover (kill the hog). +The value in this file has an effect only when +.I /proc/sys/vm/overcommit_memory +is set to 2 ("overcommit never" mode). +In this case, the system reserves an amount of memory that is the minimum +of [3% of current process size, +.IR user_reserve_kbytes ]. +.IP +The default value in this file is the minimum of [3% of free pages, 128MiB] +expressed as KiB. +.IP +If the value in this file is set to zero, +then a user will be allowed to allocate all free memory with a single process +(minus the amount reserved by +.IR /proc/sys/vm/admin_reserve_kbytes ). +Any subsequent attempts to execute a command will result in +"fork: Cannot allocate memory". +.IP +Changing the value in this file takes effect whenever +an application requests memory. +.TP +.IR /proc/sys/vm/unprivileged_userfaultfd " (since Linux 5.2)" +.\" cefdca0a86be517bc390fc4541e3674b8e7803b0 +This (writable) file exposes a flag that controls whether +unprivileged processes are allowed to employ +.BR userfaultfd (2). +If this file has the value 1, then unprivileged processes may use +.BR userfaultfd (2). +If this file has the value 0, then only processes that have the +.B CAP_SYS_PTRACE +capability may employ +.BR userfaultfd (2). +The default value in this file is 1. +.SH SEE ALSO +.BR proc (5), +.BR proc_sys (5) diff --git a/man5/proc_sysrq-trigger.5 b/man5/proc_sysrq-trigger.5 new file mode 100644 index 0000000..bca3173 --- /dev/null +++ b/man5/proc_sysrq-trigger.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sysrq-trigger 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/sysrq\-trigger \- SysRq function +.SH DESCRIPTION +.TP +.IR /proc/sysrq\-trigger " (since Linux 2.4.21)" +Writing a character to this file triggers the same SysRq function as +typing ALT-SysRq- (see the description of +.IR /proc/sys/kernel/sysrq ). +This file is normally writable only by +.IR root . +For further details see the Linux kernel source file +.I Documentation/admin\-guide/sysrq.rst +.\" commit 9d85025b0418163fae079c9ba8f8445212de8568 +(or +.I Documentation/sysrq.txt +before Linux 4.10). +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_sysvipc.5 b/man5/proc_sysvipc.5 new file mode 100644 index 0000000..9ca6701 --- /dev/null +++ b/man5/proc_sysvipc.5 @@ -0,0 +1,25 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_sysvipc 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/sysvipc/ \- System V IPC +.SH DESCRIPTION +.TP +.I /proc/sysvipc/ +Subdirectory containing the pseudo-files +.IR msg ", " sem " and " shm "." +These files list the System V Interprocess Communication (IPC) objects +(respectively: message queues, semaphores, and shared memory) +that currently exist on the system, +providing similar information to that available via +.BR ipcs (1). +These files have headers and are formatted (one IPC object per line) +for easy understanding. +.BR sysvipc (7) +provides further background on the information shown by these files. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_thread-self.5 b/man5/proc_thread-self.5 new file mode 100644 index 0000000..2c760e9 --- /dev/null +++ b/man5/proc_thread-self.5 @@ -0,0 +1 @@ +.so man5/proc_pid_task.5 diff --git a/man5/proc_tid.5 b/man5/proc_tid.5 new file mode 100644 index 0000000..2c760e9 --- /dev/null +++ b/man5/proc_tid.5 @@ -0,0 +1 @@ +.so man5/proc_pid_task.5 diff --git a/man5/proc_tid_children.5 b/man5/proc_tid_children.5 new file mode 100644 index 0000000..6cb2833 --- /dev/null +++ b/man5/proc_tid_children.5 @@ -0,0 +1,37 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_tid_children 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/tid/children \- child tasks +.SH DESCRIPTION +.TP +.IR /proc/ tid /children " (since Linux 3.5)" +.\" commit 818411616baf46ceba0cff6f05af3a9b294734f7 +A space-separated list of child tasks of this task. +Each child task is represented by its TID. +.IP +.\" see comments in get_children_pid() in fs/proc/array.c +This option is intended for use by the checkpoint-restore (CRIU) system, +and reliably provides a list of children only if all of the child processes +are stopped or frozen. +It does not work properly if children of the target task exit while +the file is being read! +Exiting children may cause non-exiting children to be omitted from the list. +This makes this interface even more unreliable than classic PID-based +approaches if the inspected task and its children aren't frozen, +and most code should probably not use this interface. +.IP +Until Linux 4.2, the presence of this file was governed by the +.B CONFIG_CHECKPOINT_RESTORE +kernel configuration option. +Since Linux 4.2, +.\" commit 2e13ba54a2682eea24918b87ad3edf70c2cf085b +it is governed by the +.B CONFIG_PROC_CHILDREN +option. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_timer_list.5 b/man5/proc_timer_list.5 new file mode 100644 index 0000000..e16fc5f --- /dev/null +++ b/man5/proc_timer_list.5 @@ -0,0 +1,18 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_timer_list 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/timer_list \- pending timers +.SH DESCRIPTION +.TP +.IR /proc/timer_list " (since Linux 2.6.21)" +.\" commit 289f480af87e45f7a6de6ba9b4c061c2e259fe98 +This read-only file exposes a list of all currently pending +(high-resolution) timers, +all clock-event sources, and their parameters in a human-readable form. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_timer_stats.5 b/man5/proc_timer_stats.5 new file mode 100644 index 0000000..3503f11 --- /dev/null +++ b/man5/proc_timer_stats.5 @@ -0,0 +1,117 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_timer_stats 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/timer_stats \- timer statistics +.SH DESCRIPTION +.TP +.IR /proc/timer_stats " (from Linux 2.6.21 until Linux 4.10)" +.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221 +.\" Date: Fri Feb 16 01:28:13 2007 -0800 +.\" Text largely derived from Documentation/timers/timer_stats.txt +.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1 +.\" Date: Wed Feb 8 11:26:59 2017 -0800 +This is a debugging facility to make timer (ab)use in a Linux +system visible to kernel and user-space developers. +It can be used by kernel and user-space developers to verify that +their code does not make undue use of timers. +The goal is to avoid unnecessary wakeups, +thereby optimizing power consumption. +.IP +If enabled in the kernel +.RB ( CONFIG_TIMER_STATS ), +but not used, +it has almost zero run-time overhead and a relatively small +data-structure overhead. +Even if collection is enabled at run time, overhead is low: +all the locking is per-CPU and lookup is hashed. +.IP +The +.I /proc/timer_stats +file is used both to control sampling facility and to read out the +sampled information. +.IP +The +.I timer_stats +functionality is inactive on bootup. +A sampling period can be started using the following command: +.IP +.in +4n +.EX +# echo 1 > /proc/timer_stats +.EE +.in +.IP +The following command stops a sampling period: +.IP +.in +4n +.EX +# echo 0 > /proc/timer_stats +.EE +.in +.IP +The statistics can be retrieved by: +.IP +.in +4n +.EX +$ cat /proc/timer_stats +.EE +.in +.IP +While sampling is enabled, each readout from +.I /proc/timer_stats +will see +newly updated statistics. +Once sampling is disabled, the sampled information +is kept until a new sample period is started. +This allows multiple readouts. +.IP +Sample output from +.IR /proc/timer_stats : +.IP +.in +4n +.EX +.RB $ " cat /proc/timer_stats" +Timer Stats Version: v0.3 +Sample period: 1.764 s +Collection: active + 255, 0 swapper/3 hrtimer_start_range_ns (tick_sched_timer) + 71, 0 swapper/1 hrtimer_start_range_ns (tick_sched_timer) + 58, 0 swapper/0 hrtimer_start_range_ns (tick_sched_timer) + 4, 1694 gnome\-shell mod_delayed_work_on (delayed_work_timer_fn) + 17, 7 rcu_sched rcu_gp_kthread (process_timeout) +\&... + 1, 4911 kworker/u16:0 mod_delayed_work_on (delayed_work_timer_fn) + 1D, 2522 kworker/0:0 queue_delayed_work_on (delayed_work_timer_fn) +1029 total events, 583.333 events/sec +.EE +.in +.IP +The output columns are: +.RS +.IP [1] 5 +a count of the number of events, +optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq] +.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers +if this is a deferrable timer; +.IP [2] +the PID of the process that initialized the timer; +.IP [3] +the name of the process that initialized the timer; +.IP [4] +the function where the timer was initialized; and +(in parentheses) +the callback function that is associated with the timer. +.RE +.IP +During the Linux 4.11 development cycle, +this file was removed because of security concerns, +as it exposes information across namespaces. +Furthermore, it is possible to obtain +the same information via in-kernel tracing facilities such as ftrace. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_tty.5 b/man5/proc_tty.5 new file mode 100644 index 0000000..3b74471 --- /dev/null +++ b/man5/proc_tty.5 @@ -0,0 +1,16 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_tty 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/tty/ \- tty +.SH DESCRIPTION +.TP +.I /proc/tty/ +Subdirectory containing the pseudo-files and subdirectories for +tty drivers and line disciplines. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_uptime.5 b/man5/proc_uptime.5 new file mode 100644 index 0000000..0fad253 --- /dev/null +++ b/man5/proc_uptime.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_uptime 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/uptime \- system uptime +.SH DESCRIPTION +.TP +.I /proc/uptime +This file contains two numbers (values in seconds): the uptime of the +system (including time spent in suspend) and the amount of time spent +in the idle process. +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_version.5 b/man5/proc_version.5 new file mode 100644 index 0000000..0f612d8 --- /dev/null +++ b/man5/proc_version.5 @@ -0,0 +1,27 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_version 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/version \- kernel version +.SH DESCRIPTION +.TP +.I /proc/version +This string identifies the kernel version that is currently running. +It includes the contents of +.IR /proc/sys/kernel/ostype , +.IR /proc/sys/kernel/osrelease , +and +.IR /proc/sys/kernel/version . +For example: +.IP +.in +4n +.EX +Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994 +.EE +.in +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_vmstat.5 b/man5/proc_vmstat.5 new file mode 100644 index 0000000..453ef1c --- /dev/null +++ b/man5/proc_vmstat.5 @@ -0,0 +1,702 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_vmstat 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/vmstat \- virtual memory statistics +.SH DESCRIPTION +.TP +.IR /proc/vmstat " (since Linux 2.6.0)" +This file displays various virtual memory statistics. +Each line of this file contains a single name-value pair, +delimited by white space. +Some lines are present only if the kernel was configured with +suitable options. +(In some cases, the options required for particular files have changed +across kernel versions, so they are not listed here. +Details can be found by consulting the kernel source code.) +The following fields may be present: +.\" FIXME We need explanations for each of the following fields... +.RS +.TP +.IR nr_free_pages " (since Linux 2.6.31)" +.\" commit d23ad42324cc4378132e51f2fc5c9ba6cbe75182 +.TP +.IR nr_alloc_batch " (since Linux 3.12)" +.\" commit 81c0a2bb515fd4daae8cab64352877480792b515 +.TP +.IR nr_inactive_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_anon " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_inactive_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_active_file " (since Linux 2.6.28)" +.\" commit 4f98a2fee8acdb4ac84545df98cccecfd130f8db +.TP +.IR nr_unevictable " (since Linux 2.6.28)" +.\" commit 7b854121eb3e5ba0241882ff939e2c485228c9c5 +.TP +.IR nr_mlock " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.TP +.IR nr_anon_pages " (since Linux 2.6.18)" +.\" commit f3dbd34460ff54962d3e3244b6bcb7f5295356e6 +.TP +.IR nr_mapped " (since Linux 2.6.0)" +.TP +.IR nr_file_pages " (since Linux 2.6.18)" +.\" commit 347ce434d57da80fd5809c0c836f206a50999c26 +.TP +.IR nr_dirty " (since Linux 2.6.0)" +.TP +.IR nr_writeback " (since Linux 2.6.0)" +.TP +.IR nr_slab_reclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.\" Linux 2.6.0 had nr_slab +.TP +.IR nr_slab_unreclaimable " (since Linux 2.6.19)" +.\" commit 972d1a7b140569084439a81265a0f15b74e924e0 +.TP +.IR nr_page_table_pages " (since Linux 2.6.0)" +.TP +.IR nr_kernel_stack " (since Linux 2.6.32)" +.\" commit c6a7f5728a1db45d30df55a01adc130b4ab0327c +Amount of memory allocated to kernel stacks. +.TP +.IR nr_unstable " (since Linux 2.6.0)" +.TP +.IR nr_bounce " (since Linux 2.6.12)" +.\" commit edfbe2b0038723e5699ab22695ccd62b5542a5c1 +.TP +.IR nr_vmscan_write " (since Linux 2.6.19)" +.\" commit e129b5c23c2b471d47f1c5d2b8b193fc2034af43 +.TP +.IR nr_vmscan_immediate_reclaim " (since Linux 3.2)" +.\" commit 49ea7eb65e7c5060807fb9312b1ad4c3eab82e2c +.TP +.IR nr_writeback_temp " (since Linux 2.6.26)" +.\" commit fc3ba692a4d19019387c5acaea63131f9eab05dd +.TP +.IR nr_isolated_anon " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_isolated_file " (since Linux 2.6.32)" +.\" commit a731286de62294b63d8ceb3c5914ac52cc17e690 +.TP +.IR nr_shmem " (since Linux 2.6.32)" +.\" commit 4b02108ac1b3354a22b0d83c684797692efdc395 +Pages used by shmem and +.BR tmpfs (5). +.TP +.IR nr_dirtied " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_written " (since Linux 2.6.37)" +.\" commit ea941f0e2a8c02ae876cd73deb4e1557248f258c +.TP +.IR nr_pages_scanned " (since Linux 3.17)" +.\" commit 0d5d823ab4e608ec7b52ac4410de4cb74bbe0edd +.TP +.IR numa_hit " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_miss " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_foreign " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_interleave " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_local " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR numa_other " (since Linux 2.6.18)" +.\" commit ca889e6c45e0b112cb2ca9d35afc66297519b5d5 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_NUMA . +.TP +.IR workingset_refault " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_activate " (since Linux 3.15)" +.\" commit a528910e12ec7ee203095eb1711468a66b9b60b0 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR workingset_nodereclaim " (since Linux 3.15)" +.\" commit 449dd6984d0e47643c04c807f609dd56d48d5bcc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_anon_transparent_hugepages " (since Linux 2.6.38)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_free_cma " (since Linux 3.7)" +.\" commit d1ce749a0db12202b711d1aba1d29e823034648d +Number of free CMA (Contiguous Memory Allocator) pages. +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR nr_dirty_background_threshold " (since Linux 2.6.37)" +.\" commit 79da826aee6a10902ef411bc65864bd02102fa83 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgpgout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpin " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pswpout " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgalloc +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgalloc_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgalloc_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfree " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgdeactivate " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgmajfault " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma " (since Linux 2.6.5)" +.\" Linux 2.6.0 had pgrefill +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrefill_high " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgrefill_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Formerly there were +.\" pgsteal_high +.\" pgsteal_normal +.\" pgsteal_dma32 +.\" pgsteal_dma +.\" These were split out into pgsteal_kswapd* and pgsteal_direct* +.\" in commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.TP +.IR pgsteal_kswapd_dma " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Linux 2.6.0 had pgsteal +.\" Present only if the kernel was configured with +.\" .\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_kswapd_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_kswapd_movable " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgsteal_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_dma32 " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_normal " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgsteal_direct_high " (since Linux 3.4)" +.\" commit 904249aa68010c8e223263c922fcbb840a3f42e4 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgsteal_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_kswapd_dma +.\" Linux 2.6.0 had pgscan +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_kswapd_normal " (since Linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_kswapd_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_kswapd_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_dma +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_dma32 " (since Linux 2.6.16)" +.\" commit 9328b8faae922e52073785ed6c1eaa8565648a0e +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_normal +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.I pgscan_direct_high +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HIGHMEM . +.TP +.IR pgscan_direct_movable " (since Linux 2.6.23)" +.\" commit 2a1e274acf0b1c192face19a4be7c12d4503eaaf +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgscan_direct_throttle " (since Linux 3.6)" +.\" commit 68243e76ee343d63c6cf76978588a885951e2818 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR zone_reclaim_failed " (since linux 2.6.31)" +.\" commit 24cf72518c79cdcda486ed26074ff8151291cf65 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA . +.TP +.IR pginodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR slabs_scanned " (since linux 2.6.5)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_inodesteal " (since linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_low_wmark_hit_quickly " (since Linux 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR kswapd_high_wmark_hit_quickly " (since Linux 2.6.33)" +.\" commit bb3ab596832b920c703d1aea1ce76d69c0f71fb7 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pageoutrun " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR allocstall " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR pgrotated " (since Linux 2.6.0)" +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_pagecache " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR drop_slab " (since Linux 3.15)" +.\" commit 5509a5d27b971a90b940e148ca9ca53312e4fa7a +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR numa_pte_updates " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_huge_pte_updates " (since Linux 3.13)" +.\" commit 72403b4a0fbdf433c1fe0127e49864658f6f6468 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_hint_faults_local " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR numa_pages_migrated " (since Linux 3.8)" +.\" commit 03c5a6e16322c997bf8f264851bfa3f532ad515f +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_NUMA_BALANCING +.\" and +.\" .BR CONFIG_NUMA_BALANCING . +.TP +.IR pgmigrate_success " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR pgmigrate_fail " (since Linux 3.8)" +.\" commit 5647bc293ab15f66a7b1cda850c5e9d162a6c7c2 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MIGRATION . +.TP +.IR compact_migrate_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Linux 3.8 dropped compact_blocks_moved, compact_pages_moved, and +.\" compact_pagemigrate_failed +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_free_scanned " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_isolated " (since Linux 3.8)" +.\" commit 397487db696cae0b026a474a5cd66f4e372995e6 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_stall " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_fail " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR compact_success " (since Linux 2.6.35)" +.\" commit 56de7263fcf3eb10c8dcdf8d59a9cec831795f3f +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_COMPACTION . +.TP +.IR htlb_buddy_alloc_success " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR htlb_buddy_alloc_fail " (since Linux 2.6.26)" +.\" commit 3b1163006332302117b1b2acf226d4014ff46525 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_HUGETLB_PAGE . +.TP +.IR unevictable_pgs_culled " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_scanned " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_rescued " (since Linux 2.6.28)" +.\" commit bbfd28eee9fbd73e780b19beb3dc562befbb94fa +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_mlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_munlocked " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_cleared " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.TP +.IR unevictable_pgs_stranded " (since Linux 2.6.28)" +.\" commit 5344b7e648980cc2ca613ec03a56a8222ff48820 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS . +.\" Linux 3.7 removed unevictable_pgs_mlockfreed +.TP +.IR thp_fault_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_fault_fallback " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_collapse_alloc_failed " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_split " (since Linux 2.6.39)" +.\" commit 81ab4201fb7d91d6b0cd9ad5b4b16776e4bed145 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR thp_zero_page_alloc_failed " (since Linux 3.8)" +.\" commit d8a8e1f0da3d29d7268b3300c96a059d63901b76 +See the kernel source file +.IR Documentation/admin\-guide/mm/transhuge.rst . +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_TRANSPARENT_HUGEPAGE . +.TP +.IR balloon_inflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_deflate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS +.\" and +.\" .BR CONFIG_MEMORY_BALLOON . +.TP +.IR balloon_migrate " (since Linux 3.18)" +.\" commit 09316c09dde33aae14f34489d9e3d243ec0d5938 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_VM_EVENT_COUNTERS , +.\" .BR CONFIG_MEMORY_BALLOON , +.\" and +.\" .BR CONFIG_BALLOON_COMPACTION . +.TP +.IR nr_tlb_remote_flush " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_remote_flush_received " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH +.\" and +.\" .BR CONFIG_SMP . +.TP +.IR nr_tlb_local_flush_all " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR nr_tlb_local_flush_one " (since Linux 3.12)" +.\" commit 9824cf9753ecbe8f5b47aa9b2f218207defea211 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_TLBFLUSH . +.TP +.IR vmacache_find_calls " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_find_hits " (since Linux 3.16)" +.\" commit 4f115147ff802267d0aa41e361c5aa5bd933d896 +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.TP +.IR vmacache_full_flushes " (since Linux 3.19)" +.\" commit f5f302e21257ebb0c074bbafc37606c26d28cc3d +.\" Present only if the kernel was configured with +.\" .BR CONFIG_DEBUG_VM_VMACACHE . +.RE +.SH SEE ALSO +.BR proc (5) diff --git a/man5/proc_zoneinfo.5 b/man5/proc_zoneinfo.5 new file mode 100644 index 0000000..33e07a6 --- /dev/null +++ b/man5/proc_zoneinfo.5 @@ -0,0 +1,17 @@ +.\" Copyright (C) 1994, 1995, Daniel Quinlan +.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk +.\" Copyright (C) 2023, Alejandro Colomar +.\" +.\" SPDX-License-Identifier: GPL-3.0-or-later +.\" +.TH proc_zoneinfo 5 2023-08-15 "Linux man-pages 6.7" +.SH NAME +/proc/zoneinfo \- memory zones +.SH DESCRIPTION +.TP +.IR /proc/zoneinfo " (since Linux 2.6.13)" +This file displays information about memory zones. +This is useful for analyzing virtual memory behavior. +.\" FIXME more should be said about /proc/zoneinfo +.SH SEE ALSO +.BR proc (5) diff --git a/man5/protocols.5 b/man5/protocols.5 index 7939407..954f06d 100644 --- a/man5/protocols.5 +++ b/man5/protocols.5 @@ -7,7 +7,7 @@ .\" 2002-09-22 Seth W. Klein .\" * protocol numbers are now assigned by the IANA .\" -.TH protocols 5 2022-10-30 "Linux man-pages 6.05.01" +.TH protocols 5 2024-02-25 "Linux man-pages 6.7" .SH NAME protocols \- protocols definition file .SH DESCRIPTION @@ -18,24 +18,24 @@ consulted instead of using the numbers in the ARPA include files, or, even worse, just guessing them. These numbers will occur in the protocol field of any IP header. -.PP +.P Keep this file untouched since changes would result in incorrect IP packages. Protocol numbers and names are specified by the IANA (Internet Assigned Numbers Authority). .\" .. by the DDN Network Information Center. -.PP +.P Each line is of the following format: -.PP +.P .RS -.I protocol number aliases ... +.I protocol number aliases .\|.\|. .RE -.PP +.P where the fields are delimited by spaces or tabs. Empty lines are ignored. If a line contains a hash mark (#), the hash mark and the part of the line following it are ignored. -.PP +.P The field descriptions are: .TP .I protocol @@ -52,7 +52,7 @@ header. .TP .I aliases optional aliases for the protocol. -.PP +.P This file might be distributed over a network using a network-wide naming service like Yellow Pages/NIS or BIND/Hesiod. .SH FILES @@ -61,6 +61,6 @@ naming service like Yellow Pages/NIS or BIND/Hesiod. The protocols definition file. .SH SEE ALSO .BR getprotoent (3) -.PP +.P .UR http://www.iana.org\:/assignments\:/protocol\-numbers .UE diff --git a/man5/repertoiremap.5 b/man5/repertoiremap.5 index bf1238d..0a1f19e 100644 --- a/man5/repertoiremap.5 +++ b/man5/repertoiremap.5 @@ -1,6 +1,6 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH repertoiremap 5 2022-10-30 "Linux man-pages 6.05.01" +.TH repertoiremap 5 2023-10-31 "Linux man-pages 6.7" .SH NAME repertoiremap \- map symbolic character names to Unicode code points .SH DESCRIPTION @@ -23,18 +23,18 @@ is followed by a character that should be used as the escape character for the rest of the file to mark characters that should be interpreted in a special way. It defaults to the backslash (\e). -.PP +.P The mapping section starts with the keyword .I CHARIDS in the first column. -.PP +.P The mapping lines have the following form: .TP .I comment This defines exactly one mapping, .I comment being optional. -.PP +.P The mapping section ends with the string .IR "END CHARIDS" . .SH FILES @@ -47,7 +47,7 @@ POSIX.2. Repertoire maps are deprecated in favor of Unicode code points. .SH EXAMPLES A mnemonic for the Euro sign can be defined as follows: -.PP +.P .nf EURO SIGN .fi diff --git a/man5/resolv.conf.5 b/man5/resolv.conf.5 index 1ea918d..1210399 100644 --- a/man5/resolv.conf.5 +++ b/man5/resolv.conf.5 @@ -20,7 +20,7 @@ .\" .\" Added ndots remark by Bernhard R. Link - debian bug #182886 .\" -.TH resolv.conf 5 2023-05-05 "Linux man-pages 6.05.01" +.TH resolv.conf 5 2023-10-31 "Linux man-pages 6.7" .UC 4 .SH NAME resolv.conf \- resolver configuration file @@ -41,11 +41,11 @@ The configuration file is considered a trusted source of DNS information; see the .B trust-ad option below for details. -.PP +.P If this file does not exist, only the name server on the local machine will be queried, and the search list contains the local domain name determined from the hostname. -.PP +.P The different configuration options are: .TP \fBnameserver\fP Name server IP address @@ -140,7 +140,7 @@ The syntax is .RS .IP \fBoptions\fP \fIoption\fP \fI...\fP -.PP +.P where \fIoption\fP is one of the following: .TP \fBdebug\fP @@ -373,22 +373,22 @@ In glibc 2.30 and earlier, the AD is not set automatically in queries, and is passed through unchanged to applications in responses. .RE -.PP +.P The \fIsearch\fP keyword of a system's \fIresolv.conf\fP file can be overridden on a per-process basis by setting the environment variable .B LOCALDOMAIN to a space-separated list of search domains. -.PP +.P The \fIoptions\fP keyword of a system's \fIresolv.conf\fP file can be amended on a per-process basis by setting the environment variable .B RES_OPTIONS to a space-separated list of resolver options as explained above under \fBoptions\fP. -.PP +.P The keyword and value must appear on a single line, and the keyword (e.g., \fBnameserver\fP) must start the line. The value follows the keyword, separated by white space. -.PP +.P Lines that contain a semicolon (;) or hash character (#) in the first column are treated as comments. .SH FILES @@ -402,5 +402,5 @@ in the first column are treated as comments. .BR nsswitch.conf (5), .BR hostname (7), .BR named (8) -.PP +.P Name Server Operations Guide for BIND diff --git a/man5/rpc.5 b/man5/rpc.5 index 4f1fe2c..bc67a34 100644 --- a/man5/rpc.5 +++ b/man5/rpc.5 @@ -5,7 +5,7 @@ .\" %%%LICENSE_END .\" .\" @(#)rpc.5 2.2 88/08/03 4.0 RPCSRC; from 1.4 87/11/27 SMI; -.TH rpc 5 2023-02-05 "Linux man-pages 6.05.01" +.TH rpc 5 2023-10-31 "Linux man-pages 6.7" .SH NAME rpc \- RPC program number data base .SH SYNOPSIS @@ -18,7 +18,7 @@ The file contains user readable names that can be used in place of RPC program numbers. Each line has the following information: -.PP +.P .PD 0 .IP \[bu] 3 name of server for the RPC program @@ -27,17 +27,17 @@ RPC program number .IP \[bu] aliases .PD -.PP +.P Items are separated by any number of blanks and/or tab characters. A \[aq]#\[aq] indicates the beginning of a comment; characters from the \[aq]#\[aq] to the end of the line are not interpreted by routines which search the file. -.PP +.P Here is an example of the .I /etc/rpc file from the Sun RPC Source distribution. -.PP +.P .in +4n .EX # diff --git a/man5/securetty.5 b/man5/securetty.5 index a32db97..d1ffbaa 100644 --- a/man5/securetty.5 +++ b/man5/securetty.5 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sun Jul 25 11:06:27 1993 by Rik Faith (faith@cs.unc.edu) -.TH securetty 5 2022-10-30 "Linux man-pages 6.05.01" +.TH securetty 5 2023-10-31 "Linux man-pages 6.7" .SH NAME securetty \- list of terminals on which root is allowed to login .SH DESCRIPTION @@ -15,7 +15,7 @@ contains the names of terminals .IR /dev/ ) which are considered secure for the transmission of certain authentication tokens. -.PP +.P It is used by (some versions of) .BR login (1) to restrict the terminals @@ -23,7 +23,7 @@ on which root is allowed to login. See .BR login.defs (5) if you use the shadow suite. -.PP +.P On PAM enabled systems, it is used for the same purpose by .BR pam_securetty (8) to restrict the terminals on which empty passwords are accepted. diff --git a/man5/services.5 b/man5/services.5 index 5003f61..eb83b3e 100644 --- a/man5/services.5 +++ b/man5/services.5 @@ -11,7 +11,7 @@ .\" Thu Jan 11 12:14:41 1996 Austin Donnelly .\" * Merged two services(5) manpages .\" -.TH services 5 2022-10-30 "Linux man-pages 6.05.01" +.TH services 5 2023-10-31 "Linux man-pages 6.7" .SH NAME services \- Internet network services list .SH DESCRIPTION @@ -29,13 +29,13 @@ The C library routines and .BR endservent (3) support querying this file from programs. -.PP +.P Port numbers are assigned by the IANA (Internet Assigned Numbers Authority), and their current policy is to assign both TCP and UDP protocols when assigning a port number. Therefore, most entries will have two entries, even for TCP-only services. -.PP +.P Port numbers below 1024 (so-called "low numbered" ports) can be bound to only by root (see .BR bind (2), @@ -47,7 +47,7 @@ that the service running on the port is the standard implementation, and not a rogue service run by a user of the machine. Well-known port numbers specified by the IANA are normally located in this root-only space. -.PP +.P The presence of an entry for a service in the .B services file does not necessarily mean that the service is currently running @@ -62,7 +62,7 @@ and so won't appear in .BR inetd.conf (5). In particular, news (NNTP) and mail (SMTP) servers are often initialized from the system boot scripts. -.PP +.P The location of the .B services file is defined by @@ -71,7 +71,7 @@ in .IR "." This is usually set to .IR /etc/services "." -.PP +.P Each line describes one service, and is of the form: .IP \f2service-name\ \ \ port\f3/\f2protocol\ \ \ \f1[\f2aliases ...\f1] @@ -103,13 +103,13 @@ is an optional space or tab separated list of other names for this service. Again, the names are case sensitive. -.PP +.P Either spaces or tabs may be used to separate the fields. -.PP +.P Comments are started by the hash sign (#) and continue until the end of the line. Blank lines are skipped. -.PP +.P The .I service-name should begin in the first column of the file, since leading spaces are @@ -120,7 +120,7 @@ However, a conservative choice of characters should be used to minimize compatibility problems. For example, a\-z, 0\-9, and hyphen (\-) would seem a sensible choice. -.PP +.P Lines not matching this format should not be present in the file. (Currently, they are silently skipped by @@ -129,7 +129,7 @@ file. and .BR getservbyport (3). However, this behavior should not be relied on.) -.PP +.P .\" The following is not true as at glibc 2.8 (a line with a comma is .\" ignored by getservent()); it's not clear if/when it was ever true. .\" As a backward compatibility feature, the slash (/) between the @@ -142,11 +142,11 @@ However, this behavior should not be relied on.) .\" This file might be distributed over a network using a network-wide naming service like Yellow Pages/NIS or BIND/Hesiod. -.PP +.P A sample .B services file might look like this: -.PP +.P .in +4n .EX netstat 15/tcp @@ -195,5 +195,5 @@ Definition of .BR inetd.conf (5), .BR protocols (5), .BR inetd (8) -.PP +.P Assigned Numbers RFC, most recently RFC\ 1700, (AKA STD0002). diff --git a/man5/shells.5 b/man5/shells.5 index fcbbd22..aaeaed7 100644 --- a/man5/shells.5 +++ b/man5/shells.5 @@ -6,7 +6,7 @@ .\" Modified Sat Jul 24 17:11:07 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Sun Nov 21 10:49:38 1993 by Michael Haardt .\" Modified Sun Feb 26 15:09:15 1995 by Rik Faith (faith@cs.unc.edu) -.TH shells 5 2022-10-30 "Linux man-pages 6.05.01" +.TH shells 5 2023-10-31 "Linux man-pages 6.7" .SH NAME shells \- pathnames of valid login shells .SH DESCRIPTION @@ -15,7 +15,7 @@ is a text file which contains the full pathnames of valid login shells. This file is consulted by .BR chsh (1) and available to be queried by other programs. -.PP +.P Be aware that there are programs which consult this file to find out if a user is a normal user; for example, @@ -26,7 +26,7 @@ disallow access to users with shells not included in this file. .SH EXAMPLES .I /etc/shells may contain the following paths: -.PP +.P .in +4n .EX .I /bin/sh diff --git a/man5/slabinfo.5 b/man5/slabinfo.5 index e27ff80..73f7f9e 100644 --- a/man5/slabinfo.5 +++ b/man5/slabinfo.5 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH slabinfo 5 2023-02-05 "Linux man-pages 6.05.01" +.TH slabinfo 5 2023-10-31 "Linux man-pages 6.7" .SH NAME slabinfo \- kernel slab allocator statistics .SH SYNOPSIS @@ -19,7 +19,7 @@ The file gives statistics on these caches. The following (edited) output shows an example of the contents of this file: -.PP +.P .EX $ \fBsudo cat /proc/slabinfo\fP slabinfo \- version: 2.1 @@ -29,13 +29,13 @@ sighand_cache 355 405 2112 15 8 : tunables 0 0 0 : slabdata 27 27 0 kmalloc\-8192 96 96 8192 4 8 : tunables 0 0 0 : slabdata 24 24 0 \&... .EE -.PP +.P The first line of output includes a version number, which allows an application that is reading the file to handle changes in the file format. (See VERSIONS, below.) The next line lists the names of the columns in the remaining lines. -.PP +.P Each of the remaining lines displays information about a specified cache. Following the cache name, the output shown in each line shows three components for each cache: @@ -45,7 +45,7 @@ statistics tunables .IP \[bu] slabdata -.PP +.P The statistics are as follows: .TP .I active_objs @@ -63,7 +63,7 @@ The number of objects stored in each slab. .TP .I pagesperslab The number of pages allocated for each slab. -.PP +.P The .I tunables entries in each line show tunable parameters for the corresponding cache. @@ -74,13 +74,13 @@ When using the older SLAB allocator, the tunables for a particular cache can be set by writing lines of the following form to .IR /proc/slabinfo : -.PP +.P .in +4n .EX # \fBecho \[aq]name limit batchcount sharedfactor\[aq] > /proc/slabinfo\fP .EE .in -.PP +.P Here, .I name is the cache name, and @@ -100,7 +100,7 @@ and should be nonnegative. If any of the specified values is invalid, the cache settings are left unchanged. -.PP +.P The .I tunables entries in each line contain the following fields: @@ -121,7 +121,7 @@ when refilling the available object list. .I sharedfactor [To be documented] .\" -.PP +.P The .I slabdata entries in each line contain the following fields: @@ -134,12 +134,12 @@ The total number of slabs. .TP .I sharedavail [To be documented] -.PP +.P Note that because of object alignment and slab cache overhead, objects are not normally packed tightly into pages. Pages with even one in-use object are considered in-use and cannot be freed. -.PP +.P Kernels configured with .B CONFIG_DEBUG_SLAB will also have additional statistics fields in each line, @@ -206,14 +206,14 @@ Only root can read and (if the kernel was configured with write the .I /proc/slabinfo file. -.PP +.P The total amount of memory allocated to the SLAB/SLUB cache is shown in the .I Slab field of .IR /proc/meminfo . .SH SEE ALSO .BR slabtop (1) -.PP +.P The kernel source file .I Documentation/vm/slub.txt and diff --git a/man5/sysfs.5 b/man5/sysfs.5 index 2edd582..5a5237c 100644 --- a/man5/sysfs.5 +++ b/man5/sysfs.5 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sysfs 5 2023-03-30 "Linux man-pages 6.05.01" +.TH sysfs 5 2023-10-31 "Linux man-pages 6.7" .SH NAME sysfs \- a filesystem for exporting kernel objects .SH DESCRIPTION @@ -19,20 +19,20 @@ The files under .B sysfs provide information about devices, kernel modules, filesystems, and other kernel components. -.PP +.P The .B sysfs filesystem is commonly mounted at .IR /sys . Typically, it is mounted automatically by the system, but it can also be mounted manually using a command such as: -.PP +.P .in +4n .EX mount \-t sysfs sysfs /sys .EE .in -.PP +.P Many of the files in the .B sysfs filesystem are read-only, @@ -261,12 +261,12 @@ of thing that needs to be updated very often. .SH SEE ALSO .BR proc (5), .BR udev (7) -.PP +.P P.\& Mochel. (2005). .IR "The sysfs filesystem" . Proceedings of the 2005 Ottawa Linux Symposium. .\" https://www.kernel.org/pub/linux/kernel/people/mochel/doc/papers/ols-2005/mochel.pdf -.PP +.P The kernel source file .I Documentation/filesystems/sysfs.txt and various other files in diff --git a/man5/termcap.5 b/man5/termcap.5 index 880c957..8aefa68 100644 --- a/man5/termcap.5 +++ b/man5/termcap.5 @@ -9,7 +9,7 @@ .\" If mistakes in the capabilities are found, please send a bug report to: .\" michael@moria.de .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond (esr@thyrsus.com) -.TH termcap 5 2023-03-08 "Linux man-pages 6.05.01" +.TH termcap 5 2023-10-31 "Linux man-pages 6.7" .SH NAME termcap \- terminal capability database .SH DESCRIPTION @@ -19,7 +19,7 @@ It is retained only for compatibility with old programs; new programs should use the .BR terminfo (5) database and associated libraries. -.PP +.P .I /etc/termcap is an ASCII file (the database master) that lists the capabilities of many different types of terminals. @@ -32,18 +32,18 @@ handled by The termcap database is indexed on the .B TERM environment variable. -.PP +.P Termcap entries must be defined on a single logical line, with \[aq]\e\[aq] used to suppress the newline. Fields are separated by \[aq]:\[aq]. The first field of each entry starts at the left-hand margin, and contains a list of names for the terminal, separated by \[aq]|\[aq]. -.PP +.P The first subfield may (in BSD termcap entries from 4.3BSD and earlier) contain a short name consisting of two characters. This short name may consist of capital or small letters. In 4.4BSD, termcap entries this field is omitted. -.PP +.P The second subfield (first, in the newer 4.4BSD format) contains the name used by the environment variable .BR TERM . @@ -56,18 +56,18 @@ Usual suffixes are w (more than 80 characters wide), am display). The third subfield contains a long and descriptive name for this termcap entry. -.PP +.P Subsequent fields contain the terminal capabilities; any continued capability lines must be indented one tab from the left margin. -.PP +.P Although there is no defined order, it is suggested to write first boolean, then numeric, and then string capabilities, each sorted alphabetically without looking at lower or upper spelling. Capabilities of similar functions can be written in one line. -.PP +.P Example for: .nf -.PP +.P Head line: vt|vt101|DEC VT 101 terminal in 80 character mode:\e Head line: Vt|vt101-w|DEC VT 101 terminal in (wide) 132 character mode:\e Boolean: :bs:\e @@ -358,15 +358,15 @@ vs Standout cursor wi Set window from line %1 to %2 and column %3 to %4 XF XOFF character if not \fB\[ha]S\fP .fi -.PP +.P There are several ways of defining the control codes for string capabilities: -.PP +.P Every normal character represents itself, except \[aq]\[ha]\[aq], \[aq]\e\[aq], and \[aq]%\[aq]. -.PP +.P A \fB\[ha]x\fP means Control-x. Control-A equals 1 decimal. -.PP +.P \ex means a special code. x can be one of the following characters: .RS @@ -403,7 +403,7 @@ Do ASCII output of this parameter with a field with of 3 .TP % Print a \[aq]%\[aq] -.PP +.P If you use binary output, then you should avoid the null character (\[aq]\e0\[aq]) because it terminates the string. @@ -413,7 +413,7 @@ if a tabulator can be the binary output of a parameter. Warning: The above metacharacters for parameters may be wrong: they document Minix termcap which may not be compatible with Linux termcap. -.PP +.P The block graphic characters can be specified by three string capabilities: .TP as @@ -426,9 +426,9 @@ ac pairs of characters. The first character is the name of the block graphic symbol and the second characters is its definition. -.PP +.P The following names are available: -.PP +.P .nf + right arrow (>) , left arrow (<) @@ -456,7 +456,7 @@ w normal tee (+) x vertical line (|) \[ti] paragraph (???) .fi -.PP +.P The values in parentheses are suggested defaults which are used by the .I curses library, if the capabilities are missing. diff --git a/man5/tmpfs.5 b/man5/tmpfs.5 index 8e4d063..55fc826 100644 --- a/man5/tmpfs.5 +++ b/man5/tmpfs.5 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH tmpfs 5 2023-07-28 "Linux man-pages 6.05.01" +.TH tmpfs 5 2023-10-31 "Linux man-pages 6.7" .SH NAME tmpfs \- a virtual memory filesystem .SH DESCRIPTION @@ -12,18 +12,18 @@ facility allows the creation of filesystems whose contents reside in virtual memory. Since the files on such filesystems typically reside in RAM, file access is extremely fast. -.PP +.P The filesystem is automatically created when mounting a filesystem with the type .B tmpfs via a command such as the following: -.PP +.P .in +4n .EX $ sudo mount \-t tmpfs \-o size=10M tmpfs /mnt/mytmpfs .EE .in -.PP +.P A .B tmpfs filesystem has the following properties: @@ -38,7 +38,7 @@ During a remount operation .RI ( "mount\ \-o\ remount" ), the filesystem size can be changed (without losing the existing contents of the filesystem). -.PP +.P If a .B tmpfs filesystem is unmounted, its contents are discarded (lost). @@ -51,6 +51,8 @@ filesystem supports the following mount options: .BR size "=\fIbytes\fP" Specify an upper limit on the size of the filesystem. The size is given in bytes, and rounded up to entire pages. +The limit is removed if the size is +.BR 0 . .IP The size may have a .BR k , @@ -89,6 +91,8 @@ but not a % suffix. The maximum number of inodes for this instance. The default is half of the number of your physical RAM pages, or (on a machine with highmem) the number of lowmem RAM pages, whichever is smaller. +The limit is removed if the number is +.BR 0 . .IP Inodes may be specified with .BR k , @@ -99,6 +103,12 @@ suffixes like .BR size , but not a % suffix. .TP +.BR noswap "(since Linux 6.4)" +.\" commit 2c6efe9cf2d7841b75fe38ed1adbd41a90f51ba0 +Disables swap. +Remounts must respect the original settings. +By default swap is enabled. +.TP .BR mode "=\fImode\fP" Set initial permissions of the root directory. .TP @@ -208,7 +218,7 @@ In order for user-space tools and applications to create filesystems, the kernel must be configured with the .B CONFIG_TMPFS option. -.PP +.P The .B tmpfs filesystem supports extended attributes (see @@ -216,7 +226,7 @@ filesystem supports extended attributes (see but .I user extended attributes are not permitted. -.PP +.P An internal shared memory filesystem is used for System V shared memory .RB ( shmget (2)) @@ -231,7 +241,7 @@ This filesystem is available regardless of whether the kernel was configured with the .B CONFIG_TMPFS option. -.PP +.P A .B tmpfs filesystem mounted at @@ -240,7 +250,7 @@ is used for the implementation of POSIX shared memory .RB ( shm_overview (7)) and POSIX semaphores .RB ( sem_overview (7)). -.PP +.P The amount of memory consumed by all .B tmpfs filesystems is shown in the @@ -251,7 +261,7 @@ and in the .I shared field displayed by .BR free (1). -.PP +.P The .B tmpfs facility was formerly called @@ -264,7 +274,7 @@ facility was formerly called .BR set_mempolicy (2), .BR shm_open (3), .BR mount (8) -.PP +.P The kernel source files .I Documentation/filesystems/tmpfs.txt and diff --git a/man5/ttytype.5 b/man5/ttytype.5 index 94030e8..ebe0866 100644 --- a/man5/ttytype.5 +++ b/man5/ttytype.5 @@ -7,7 +7,7 @@ .\" Modified Thu Oct 19 21:25:21 MET 1995 by Martin Schulze .\" Modified Mon Oct 21 17:47:19 EDT 1996 by Eric S. Raymond .\" xk -.TH ttytype 5 2023-01-22 "Linux man-pages 6.05.01" +.TH ttytype 5 2023-10-31 "Linux man-pages 6.7" .SH NAME ttytype \- terminal device to default terminal type mapping .SH DESCRIPTION @@ -23,14 +23,14 @@ Each line consists of a terminal type, followed by whitespace, followed by a tty name (a device name without the .I /dev/ prefix). -.PP +.P This association is used by the program .BR tset (1) to set the environment variable .B TERM to the default terminal name for the user's current tty. -.PP +.P This facility was designed for a traditional time-sharing environment featuring character-cell terminals hardwired to a UNIX minicomputer. It is little used on modern workstation and personal UNIX systems. @@ -42,7 +42,7 @@ the tty definitions file. A typical .I /etc/ttytype is: -.PP +.P .in +4n .EX con80x25 tty1 diff --git a/man5/tzfile.5 b/man5/tzfile.5 index 59d9f6b..4aa3f6c 100644 --- a/man5/tzfile.5 +++ b/man5/tzfile.5 @@ -26,23 +26,24 @@ a signed binary integer is represented using two's complement, and a boolean is represented by a one-byte binary integer that is either 0 (false) or 1 (true). The format begins with a 44-byte header containing the following fields: -.IP * 2 +.RS 2 +.IP \(bu 3 The magic four-byte ASCII sequence .q "TZif" identifies the file as a timezone information file. -.IP * +.IP \(bu A byte identifying the version of the file's format (as of 2021, either an ASCII NUL, .q "2", .q "3", or .q "4" ). -.IP * +.IP \(bu Fifteen bytes containing zeros reserved for future use. -.IP * +.IP \(bu Six four-byte integer values, in the following order: .RS -.TP +.TP 2 .B tzh_ttisutcnt The number of UT/local indicators stored in the file. (UT is Universal Time.) @@ -65,17 +66,19 @@ in the file (must not be zero). The number of bytes of time zone abbreviation strings stored in the file. .RE +.RE .PP The above header is followed by the following fields, whose lengths depend on the contents of the header: -.IP * 2 +.RS 2 +.IP \(bu 3 .B tzh_timecnt four-byte signed integer values sorted in ascending order. These values are written in network byte order. Each is used as a transition time (as returned by .BR time (2)) at which the rules for computing local time change. -.IP * +.IP \(bu .B tzh_timecnt one-byte unsigned integer values; each one but the last tells which of the different types of local time types @@ -83,22 +86,22 @@ described in the file is associated with the time period starting with the same-indexed transition time and continuing up to but not including the next transition time. (The last time type is present only for consistency checking with the -POSIX-style TZ string described below.) +POSIX.1-2017-style TZ string described below.) These values serve as indices into the next field. -.IP * +.IP \(bu .B tzh_typecnt .B ttinfo entries, each defined as follows: -.in +.5i +.in +2 .sp .nf -.ta .5i +\w'unsigned char\0\0'u +.ta \w'\0\0\0\0'u +\w'unsigned char\0'u struct ttinfo { int32_t tt_utoff; unsigned char tt_isdst; unsigned char tt_desigidx; }; -.in -.5i +.in .fi .sp Each structure is written as a four-byte signed integer value for @@ -132,7 +135,7 @@ Also, in realistic applications is in the range [\-89999, 93599] (i.e., more than \-25 hours and less than 26 hours); this allows easy support by implementations that already support the POSIX-required range [\-24:59:59, 25:59:59]. -.IP * +.IP \(bu .B tzh_charcnt bytes that represent time zone designations, which are null-terminated byte strings, each indexed by the @@ -140,7 +143,7 @@ which are null-terminated byte strings, each indexed by the values mentioned above. The byte strings can overlap if one is a suffix of the other. The encoding of these strings is not specified. -.IP * +.IP \(bu .B tzh_leapcnt pairs of four-byte values, written in network byte order; the first value of each pair gives the nonnegative time @@ -167,22 +170,24 @@ otherwise, for timestamps before the first occurrence time, the leap-second correction is zero if the first pair's correction is 1 or \-1, and is unspecified otherwise (which can happen only in files truncated at the start). -.IP * +.IP \(bu .B tzh_ttisstdcnt standard/wall indicators, each stored as a one-byte boolean; they tell whether the transition times associated with local time types were specified as standard time or local (wall clock) time. -.IP * +.IP \(bu .B tzh_ttisutcnt UT/local indicators, each stored as a one-byte boolean; they tell whether the transition times associated with local time types were specified as UT or local time. If a UT/local indicator is set, the corresponding standard/wall indicator must also be set. +.RE .PP The standard/wall and UT/local indicators were designed for transforming a TZif file's transition times into transitions appropriate -for another time zone specified via a POSIX-style TZ string that lacks rules. +for another time zone specified via +a POSIX.1-2017-style TZ string that lacks rules. For example, when TZ="EET\*-2EEST" and there is no TZif file "EET\*-2EEST", the idea was to adapt the transition times from a TZif file with the well-known name "posixrules" that is present only for this purpose and @@ -211,13 +216,14 @@ the above header and data are followed by a second header and data, identical in format except that eight bytes are used for each transition time or leap second time. (Leap second counts remain four bytes.) -After the second header and data comes a newline-enclosed, -POSIX-TZ-environment-variable-style string for use in handling instants +After the second header and data comes a newline-enclosed string +in the style of the contents of a POSIX.1-2017 TZ environment variable, +for use in handling instants after the last transition time stored in the file or for all instants if the file has no transitions. -The POSIX-style TZ string is empty (i.e., nothing between the newlines) -if there is no POSIX-style representation for such instants. -If nonempty, the POSIX-style TZ string must agree with the local time +The TZ string is empty (i.e., nothing between the newlines) +if there is no POSIX.1-2017-style representation for such instants. +If nonempty, the TZ string must agree with the local time type after the last transition time if present in the eight-byte data; for example, given the string .q "WET0WEST,M3.5.0/1,M10.5.0" @@ -229,8 +235,8 @@ Also, if there is at least one transition, time type 0 is associated with the time period from the indefinite past up to but not including the earliest transition time. .SS Version 3 format -For version-3-format timezone files, the POSIX-TZ-style string may -use two minor extensions to the POSIX TZ format, as described in +For version-3-format timezone files, the TZ string may +use two minor extensions to the POSIX.1-2017 TZ format, as described in .BR newtzset (3). First, the hours part of its transition times may be signed and range from \-167 through 167 instead of the POSIX-required unsigned values @@ -312,15 +318,17 @@ This section documents common problems in reading or writing TZif files. Most of these are problems in generating TZif files for use by older readers. The goals of this section are: -.IP * 2 +.RS 2 +.IP \(bu 3 to help TZif writers output files that avoid common pitfalls in older or buggy TZif readers, -.IP * +.IP \(bu to help TZif readers avoid common pitfalls when reading files generated by future TZif writers, and -.IP * +.IP \(bu to help any future specification authors see what sort of problems arise when the TZif format is changed. +.RE .PP When new versions of the TZif format have been defined, a design goal has been that a reader can successfully use a TZif @@ -335,21 +343,22 @@ workarounds, as well as to document other common bugs in readers. .PP Interoperability problems with TZif include the following: -.IP * 2 +.RS 2 +.IP \(bu 3 Some readers examine only version 1 data. As a partial workaround, a writer can output as much version 1 data as possible. However, a reader should ignore version 1 data, and should use version 2+ data even if the reader's native timestamps have only 32 bits. -.IP * +.IP \(bu Some readers designed for version 2 might mishandle timestamps after a version 3 or higher file's last transition, because -they cannot parse extensions to POSIX in the TZ-like string. +they cannot parse extensions to POSIX.1-2017 in the TZ-like string. As a partial workaround, a writer can output more transitions than necessary, so that only far-future timestamps are mishandled by version 2 readers. -.IP * +.IP \(bu Some readers designed for version 2 do not support permanent daylight saving time with transitions after 24:00 \(en e.g., a TZ string @@ -367,22 +376,22 @@ for the next time zone east \(en e.g., .q "AST4" for permanent Atlantic Standard Time (\-04). -.IP * +.IP \(bu Some readers designed for version 2 or 3, and that require strict conformance to RFC 8536, reject version 4 files whose leap second tables are truncated at the start or that end in expiration times. -.IP * +.IP \(bu Some readers ignore the footer, and instead predict future timestamps from the time type of the last transition. As a partial workaround, a writer can output more transitions than necessary. -.IP * +.IP \(bu Some readers do not use time type 0 for timestamps before the first transition, in that they infer a time type using a heuristic that does not always select time type 0. As a partial workaround, a writer can output a dummy (no-op) first transition at an early time. -.IP * +.IP \(bu Some readers mishandle timestamps before the first transition that has a timestamp not less than \-2**31. Readers that support only 32-bit timestamps are likely to be @@ -391,12 +400,12 @@ more prone to this problem, for example, when they process bits. As a partial workaround, a writer can output a dummy transition at timestamp \-2**31. -.IP * +.IP \(bu Some readers mishandle a transition if its timestamp has the minimum possible signed 64-bit value. Timestamps less than \-2**59 are not recommended. -.IP * -Some readers mishandle POSIX-style TZ strings that +.IP \(bu +Some readers mishandle TZ strings that contain .q "<" or @@ -407,11 +416,11 @@ or .q ">" for time zone abbreviations containing only alphabetic characters. -.IP * +.IP \(bu Many readers mishandle time zone abbreviations that contain non-ASCII characters. These characters are not recommended. -.IP * +.IP \(bu Some readers may mishandle time zone abbreviations that contain fewer than 3 or more than 6 characters, or that contain ASCII characters other than alphanumerics, @@ -419,23 +428,23 @@ contain ASCII characters other than alphanumerics, and .q "+". These abbreviations are not recommended. -.IP * +.IP \(bu Some readers mishandle TZif files that specify daylight-saving time UT offsets that are less than the UT offsets for the corresponding standard time. These readers do not support locations like Ireland, which -uses the equivalent of the POSIX TZ string +uses the equivalent of the TZ string .q "IST\*-1GMT0,M10.5.0,M3.5.0/1", observing standard time (IST, +01) in summer and daylight saving time (GMT, +00) in winter. As a partial workaround, a writer can output data for the -equivalent of the POSIX TZ string +equivalent of the TZ string .q "GMT0IST,M3.5.0/1,M10.5.0", thus swapping standard and daylight saving time. Although this workaround misidentifies which part of the year uses daylight saving time, it records UT offsets and time zone abbreviations correctly. -.IP * +.IP \(bu Some readers generate ambiguous timestamps for positive leap seconds that occur when the UTC offset is not a multiple of 60 seconds. For example, in a timezone with UTC offset +01:23:45 and with @@ -446,38 +455,41 @@ instead of mapping the latter to 01:23:46, and they will map 78796815 to This has not yet been a practical problem, since no civil authority has observed such UTC offsets since leap seconds were introduced in 1972. +.RE .PP Some interoperability problems are reader bugs that are listed here mostly as warnings to developers of readers. -.IP * 2 +.RS 2 +.IP \(bu 3 Some readers do not support negative timestamps. Developers of distributed applications should keep this in mind if they need to deal with pre-1970 data. -.IP * +.IP \(bu Some readers mishandle timestamps before the first transition that has a nonnegative timestamp. Readers that do not support negative timestamps are likely to be more prone to this problem. -.IP * +.IP \(bu Some readers mishandle time zone abbreviations like .q "\*-08" that contain .q "+", .q "\*-", or digits. -.IP * +.IP \(bu Some readers mishandle UT offsets that are out of the traditional range of \-12 through +12 hours, and so do not support locations like Kiritimati that are outside this range. -.IP * +.IP \(bu Some readers mishandle UT offsets in the range [\-3599, \-1] seconds from UT, because they integer-divide the offset by 3600 to get 0 and then display the hour part as .q "+00". -.IP * +.IP \(bu Some readers mishandle UT offsets that are not a multiple of one hour, or of 15 minutes, or of 1 minute. +.RE .SH SEE ALSO .BR time (2), .BR localtime (3), diff --git a/man5/utmp.5 b/man5/utmp.5 index 4a02964..48f300e 100644 --- a/man5/utmp.5 +++ b/man5/utmp.5 @@ -8,7 +8,7 @@ .\" Modified 1996-07-20 by Michael Haardt .\" Modified 1997-07-02 by Nicolás Lichtmaier .\" Modified 2004-10-31 by aeb, following Gwenole Beauchesne -.TH utmp 5 2023-05-03 "Linux man-pages 6.05.01" +.TH utmp 5 2023-10-31 "Linux man-pages 6.7" .SH NAME utmp, wtmp \- login records .SH SYNOPSIS @@ -22,7 +22,7 @@ file allows one to discover information about who is currently using the system. There may be more users currently using the system, because not all programs use utmp logging. -.PP +.P .B Warning: .I utmp must not be writable by the user class "other", @@ -32,7 +32,7 @@ You risk faked system logfiles and modifications of system files if you leave .I utmp writable to any user other than the owner and group owner of the file. -.PP +.P The file is a sequence of .I utmp structures, @@ -40,7 +40,7 @@ declared as follows in .I (note that this is only one of several definitions around; details depend on the version of libc): -.PP +.P .in +4n .EX /* Values for ut_type field, below */ @@ -112,7 +112,7 @@ struct utmp { #define ut_addr ut_addr_v6[0] .EE .in -.PP +.P This structure gives the name of the special file associated with the user's terminal, the user's login name, and the time of login in the form of @@ -120,7 +120,7 @@ of String fields are terminated by a null byte (\[aq]\e0\[aq]) if they are shorter than the size of the field. -.PP +.P The first entries ever created result from .BR init (1) processing @@ -137,7 +137,7 @@ with the needed \fIut_id\fP can be found, creates a new one. It sets \fIut_id\fP from the inittab, \fIut_pid\fP and \fIut_time\fP to the current values, and \fIut_type\fP to \fBINIT_PROCESS\fP. -.PP +.P .BR mingetty (8) (or .BR agetty (8)) @@ -156,7 +156,7 @@ and .BR login (1), records may be located by \fIut_line\fP instead of the preferable \fIut_pid\fP. -.PP +.P When .BR init (1) finds that a process has exited, it locates its utmp entry by @@ -171,7 +171,7 @@ and clears and .I ut_time with null bytes. -.PP +.P .BR xterm (1) and other terminal emulators directly create a \fBUSER_PROCESS\fP record and generate the \fIut_id\fP by using the @@ -184,7 +184,7 @@ If they can, they will mark it as \fBDEAD_PROCESS\fP on exiting and it is advised that they null \fIut_line\fP, \fIut_time\fP, \fIut_user\fP, and \fIut_host\fP as well. -.PP +.P .BR telnetd (8) sets up a \fBLOGIN_PROCESS\fP entry and leaves the rest to .BR login (1) @@ -192,7 +192,7 @@ as usual. After the telnet session ends, .BR telnetd (8) cleans up utmp in the described way. -.PP +.P The \fIwtmp\fP file records all logins and logouts. Its format is exactly like \fIutmp\fP except that a null username indicates a logout @@ -237,7 +237,7 @@ POSIX.1 does not specify the lengths of the and .I ut_user fields. -.PP +.P Linux defines the .I utmpx structure to be the same as the @@ -248,14 +248,14 @@ Linux. .SH HISTORY Linux utmp entries conform neither to v7/BSD nor to System V; they are a mix of the two. -.PP +.P v7/BSD has fewer fields; most importantly it lacks \fIut_type\fP, which causes native v7/BSD-like programs to display (for example) dead or login entries. Further, there is no configuration file which allocates slots to sessions. BSD does so because it lacks \fIut_id\fP fields. -.PP +.P In Linux (as in System V), the \fIut_id\fP field of a record will never change once it has been set, which reserves that slot without needing a configuration file. @@ -267,7 +267,7 @@ with null bytes is not required by System V semantics, but makes it possible to run many programs which assume BSD semantics and which do not modify utmp. Linux uses the BSD conventions for line contents, as documented above. -.PP +.P .\" mtk: What is the referrent of "them" in the following sentence? .\" System V only uses the type field to mark them and logs .\" informative messages such as \fB"new time"\fP in the line field. @@ -279,10 +279,10 @@ must always exist on Linux. If you want to disable .BR who (1), then do not make utmp world readable. -.PP +.P The file format is machine-dependent, so it is recommended that it be processed only on the machine architecture where it was created. -.PP +.P Note that on \fIbiarch\fP platforms, that is, systems which can run both 32-bit and 64-bit applications (x86-64, ppc64, s390x, etc.), \fIut_tv\fP is the same size in 32-bit mode as in 64-bit mode. @@ -303,15 +303,15 @@ and .IR tv_usec . Since \fIut_tv\fP may not be the same as \fIstruct timeval\fP, then instead of the call: -.PP +.P .in +4n .EX gettimeofday((struct timeval *) &ut.ut_tv, NULL); .EE .in -.PP +.P the following method of setting this field is recommended: -.PP +.P .in +4n .EX struct utmp ut; @@ -322,7 +322,7 @@ ut.ut_tv.tv_sec = tv.tv_sec; ut.ut_tv.tv_usec = tv.tv_usec; .EE .in -.\" .PP +.\" .P .\" Note that the \fIutmp\fP struct from libc5 has changed in libc6. .\" Because of this, .\" binaries using the old libc5 struct will corrupt diff --git a/man6/intro.6 b/man6/intro.6 index 97f23ae..9a2fefb 100644 --- a/man6/intro.6 +++ b/man6/intro.6 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" Modified Sat Jul 24 17:19:57 1993 by Rik Faith (faith@cs.unc.edu) -.TH intro 6 2022-10-30 "Linux man-pages 6.05.01" +.TH intro 6 2022-10-30 "Linux man-pages 6.7" .SH NAME intro \- introduction to games .SH DESCRIPTION diff --git a/man7/address_families.7 b/man7/address_families.7 index 4a75b72..14464be 100644 --- a/man7/address_families.7 +++ b/man7/address_families.7 @@ -3,14 +3,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH address_families 7 2023-01-22 "Linux man-pages 6.05.01" +.TH address_families 7 2024-01-28 "Linux man-pages 6.7" .SH NAME address_families \- socket address families (domains) .SH SYNOPSIS .nf .BR "#include " " /* See NOTES */" .B #include -.PP +.P .BI "int socket(int " domain ", int " type ", int " protocol ); .fi .SH DESCRIPTION @@ -24,7 +24,9 @@ These families are defined in .IR . The formats currently understood by the Linux kernel include: .TP -.BR AF_UNIX ", " AF_LOCAL +.B AF_UNIX +.TQ +.B AF_LOCAL Local communication. For further information, see .BR unix (7). @@ -77,7 +79,7 @@ For further information, see the .UE . .TP .B AF_X25 -ITU-T X.25 / ISO-8208 protocol. +ITU-T X.25 / ISO/IEC\~8208 protocol. For further information, see .BR x25 (7). .TP diff --git a/man7/aio.7 b/man7/aio.7 index 64c0db1..d371831 100644 --- a/man7/aio.7 +++ b/man7/aio.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH AIO 7 2023-05-03 "Linux man-pages 6.05.01" +.TH AIO 7 2023-10-31 "Linux man-pages 6.7" .SH NAME aio \- POSIX asynchronous I/O overview .SH DESCRIPTION @@ -13,7 +13,7 @@ The application can elect to be notified of completion of the I/O operation in a variety of ways: by delivery of a signal, by instantiation of a thread, or no notification at all. -.PP +.P The POSIX AIO interface consists of the following functions: .TP .BR aio_read (3) @@ -49,14 +49,14 @@ file descriptor. .TP .BR lio_listio (3) Enqueue multiple I/O requests using a single function call. -.PP +.P The .I aiocb ("asynchronous I/O control block") structure defines parameters that control an I/O operation. An argument of this type is employed with all of the functions listed above. This structure has the following form: -.PP +.P .in +4n .EX #include @@ -81,7 +81,7 @@ struct aiocb { enum { LIO_READ, LIO_WRITE, LIO_NOP }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I aio_fildes @@ -117,13 +117,13 @@ are and .BR SIGEV_THREAD . See -.BR sigevent (7) +.BR sigevent (3type) for further details. .TP .I aio_lio_opcode The type of operation to be performed; used only for .BR lio_listio (3). -.PP +.P In addition to the standard functions listed above, the GNU C library provides the following extension to the POSIX AIO API: .TP @@ -151,11 +151,11 @@ The control block buffer and the buffer pointed to by .I aio_buf must not be changed while the I/O operation is in progress. These buffers must remain valid until the I/O operation completes. -.PP +.P Simultaneous asynchronous read or write operations using the same .I aiocb structure yield undefined results. -.PP +.P The current Linux POSIX AIO implementation is provided in user space by glibc. This has a number of limitations, most notably that maintaining multiple threads to perform I/O operations is expensive and scales poorly. @@ -186,18 +186,18 @@ of a signal. After all I/O requests have completed, the program retrieves their status using .BR aio_return (3). -.PP +.P The .B SIGQUIT signal (generated by typing control-\e) causes the program to request cancelation of each of the outstanding requests using .BR aio_cancel (3). -.PP +.P Here is an example of what we might see when running this program. In this example, the program queues two requests to standard input, and these are satisfied by two lines of input containing "abc" and "x". -.PP +.P .in +4n .EX $ \fB./a.out /dev/stdin /dev/stdin\fP @@ -438,7 +438,7 @@ main(int argc, char *argv[]) .BR aio_return (3), .BR aio_write (3), .BR lio_listio (3) -.PP +.P "Asynchronous I/O Support in Linux 2.5", Bhattacharya, Pratt, Pulavarty, and Morgan, Proceedings of the Linux Symposium, 2003, diff --git a/man7/armscii-8.7 b/man7/armscii-8.7 index 2ef36ab..633c8d6 100644 --- a/man7/armscii-8.7 +++ b/man7/armscii-8.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ARMSCII-8 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ARMSCII-8 7 2022-12-15 "Linux man-pages 6.7" .SH NAME armscii-8 \- Armenian character set encoded in octal, decimal, and hexadecimal diff --git a/man7/arp.7 b/man7/arp.7 index a4ca6a6..9de545c 100644 --- a/man7/arp.7 +++ b/man7/arp.7 @@ -6,7 +6,7 @@ .\" Modified June 1999 Andi Kleen .\" $Id: arp.7,v 1.10 2000/04/27 19:31:38 ak Exp $ .\" -.TH arp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH arp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME arp \- Linux ARP kernel module. .SH DESCRIPTION @@ -17,7 +17,7 @@ and IPv4 protocol addresses on directly connected networks. The user normally doesn't interact directly with this module except to configure it; instead it provides a service for other protocols in the kernel. -.PP +.P A user process can receive ARP packets by using .BR packet (7) sockets. @@ -30,7 +30,7 @@ The ARP table can also be controlled via on any .B AF_INET socket. -.PP +.P The ARP module maintains a cache of mappings between hardware addresses and protocol addresses. The cache has a limited size so old and less @@ -42,7 +42,7 @@ be directly manipulated by the use of ioctls and its behavior can be tuned by the .I /proc interfaces described below. -.PP +.P When there is no positive feedback for an existing mapping after some time (see the .I /proc @@ -65,7 +65,7 @@ If that fails too, it will broadcast a new ARP request to the network. Requests are sent only when there is data queued for sending. -.PP +.P Linux will automatically add a nonpermanent proxy arp entry when it receives a request for an address it forwards to and proxy arp is enabled on the receiving interface. @@ -77,7 +77,7 @@ sockets. They take a pointer to a .I struct arpreq as their argument. -.PP +.P .in +4n .EX struct arpreq { @@ -89,14 +89,14 @@ struct arpreq { }; .EE .in -.PP +.P .BR SIOCSARP ", " SIOCDARP " and " SIOCGARP respectively set, delete, and get an ARP mapping. Setting and deleting ARP maps are privileged operations and may be performed only by a process with the .B CAP_NET_ADMIN capability or an effective UID of 0. -.PP +.P .I arp_pa must be an .B AF_INET @@ -121,7 +121,7 @@ ATF_NETMASK:Use a netmask ATF_DONTPUB:Don't answer .TE .RE -.PP +.P If the .B ATF_NETMASK flag is set, then @@ -272,13 +272,13 @@ changed in Linux 2.0 to include the .I arp_dev member and the ioctl numbers changed at the same time. Support for the old ioctls was dropped in Linux 2.2. -.PP +.P Support for proxy arp entries for networks (netmask not equal 0xffffffff) was dropped in Linux 2.2. It is replaced by automatic proxy arp setup by the kernel for all reachable hosts on other interfaces (when forwarding and proxy arp is enabled for the interface). -.PP +.P The .I neigh/* interfaces did not exist before Linux 2.2. @@ -286,20 +286,20 @@ interfaces did not exist before Linux 2.2. Some timer settings are specified in jiffies, which is architecture- and kernel version-dependent; see .BR time (7). -.PP +.P There is no way to signal positive feedback from user space. This means connection-oriented protocols implemented in user space will generate excessive ARP traffic, because ndisc will regularly reprobe the MAC address. The same problem applies for some kernel protocols (e.g., NFS over UDP). -.PP +.P This man page mashes together functionality that is IPv4-specific with functionality that is shared between IPv4 and IPv6. .SH SEE ALSO .BR capabilities (7), .BR ip (7), .BR arpd (8) -.PP +.P RFC\ 826 for a description of ARP. RFC\ 2461 for a description of IPv6 neighbor discovery and the base algorithms used. diff --git a/man7/ascii.7 b/man7/ascii.7 index 13f5578..19193e1 100644 --- a/man7/ascii.7 +++ b/man7/ascii.7 @@ -13,20 +13,20 @@ .\" Modified 1999-08-08 by Michael Haardt (michael@moria.de) .\" Modified 2004-04-01 by aeb .\" -.TH ascii 7 2023-05-02 "Linux man-pages 6.05.01" +.TH ascii 7 2024-01-28 "Linux man-pages 6.7" .SH NAME ascii \- ASCII character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION ASCII is the American Standard Code for Information Interchange. It is a 7-bit code. -Many 8-bit codes (e.g., ISO 8859-1) contain ASCII as their lower half. -The international counterpart of ASCII is known as ISO 646-IRV. -.PP +Many 8-bit codes (e.g., ISO/IEC\~8859-1) contain ASCII as their lower half. +The international counterpart of ASCII is known as ISO/IEC\~646-IRV. +.P The following table contains the 128 ASCII characters. -.PP +.P C program \f(CW\[aq]\eX\[aq]\fP escapes are noted. -.PP +.P .EX .TS l l l l | l l l l. @@ -100,7 +100,7 @@ _ .EE .SS Tables For convenience, below are more compact tables in hex and decimal. -.PP +.P .EX 2 3 4 5 6 7 30 40 50 60 70 80 90 100 110 120 ------------- --------------------------------- @@ -124,17 +124,17 @@ F: / ? O _ o DEL .SH NOTES .SS History /etc/ascii (VII) appears in the UNIX Programmer's Manual. -.PP +.P On older terminals, the underscore code is displayed as a left arrow, called backarrow, the caret is displayed as an up-arrow and the vertical bar has a hole in the middle. -.PP +.P Uppercase and lowercase characters differ by just one bit and the ASCII character 2 differs from the double quote by just one bit, too. That made it much easier to encode characters mechanically or with a non-microcontroller-based electronic keyboard and that pairing was found on old teletypes. -.PP +.P The ASCII standard was published by the United States of America Standards Institute (USASI) in 1968. .\" diff --git a/man7/attributes.7 b/man7/attributes.7 index b32fe54..838f039 100644 --- a/man7/attributes.7 +++ b/man7/attributes.7 @@ -2,7 +2,7 @@ .\" Written by Alexandre Oliva .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH attributes 7 2023-03-18 "Linux man-pages 6.05.01" +.TH attributes 7 2023-11-01 "Linux man-pages 6.7" .SH NAME attributes \- POSIX safety concepts .SH DESCRIPTION @@ -13,7 +13,7 @@ the text of this man page is based on the material taken from the "POSIX Safety Concepts" section of the GNU C Library manual. Further details on the topics described here can be found in that manual. -.PP +.P Various function manual pages include a section ATTRIBUTES that describes the safety of calling the function in various contexts. This section annotates functions with the following safety markings: @@ -145,7 +145,7 @@ functions are not safe to call in a multithreaded programs. .\" keyword from safety notes. .\" As long as the keyword remains, however, .\" they are not to be regarded as a promise of future behavior. -.PP +.P Other keywords that appear in safety notes are defined in subsequent sections. .\" .\" @@ -470,7 +470,7 @@ in others, they are not even exposed to users. .\" In some cases, such as .\" .BR tmpname (3), .\" the variant is chosen not by calling an alternate entry point, -.\" but by passing a non-NULL pointer to the buffer in which the +.\" but by passing a non-null pointer to the buffer in which the .\" returned values are to be stored. .\" These variants are generally preferable in multi-threaded programs, .\" although some of them are not MT-Safe because of other internal buffers, diff --git a/man7/boot.7 b/man7/boot.7 index f69e8c1..3aa0341 100644 --- a/man7/boot.7 +++ b/man7/boot.7 @@ -10,7 +10,7 @@ .\" .\" Modified 2004-11-03 patch from Martin Schulze .\" -.TH boot 7 2023-07-08 "Linux man-pages 6.05.01" +.TH boot 7 2023-10-31 "Linux man-pages 6.7" .SH NAME boot \- System bootup process based on UNIX System V Release 4 .SH DESCRIPTION @@ -27,14 +27,14 @@ kernel root user-space process (\fIinit\fR and \fIinittab\fR) .IP (5) boot scripts -.PP +.P Each of these is described below in more detail. .SS Hardware After power-on or hard reset, control is given to a program stored in read-only memory (normally PROM); for historical reasons involving the personal computer, this program is often called "the \fBBIOS\fR". -.PP +.P This program normally performs a basic self-test of the machine and accesses nonvolatile memory to read further parameters. @@ -43,7 +43,7 @@ battery-backed CMOS memory, so most people refer to it as "the \fBCMOS\fR"; outside of the PC world, it is usually called "the \fBNVRAM\fR" (nonvolatile RAM). -.PP +.P The parameters stored in the NVRAM vary among systems, but as a minimum, they should specify which device can supply an OS loader, or at least which @@ -64,11 +64,11 @@ interactive use, in order to enable specification of an alternative kernel (maybe a backup in case the one last compiled isn't functioning) and to pass optional parameters to the kernel. -.PP +.P In a traditional PC, the OS loader is located in the initial 512-byte block of the boot device; this block is known as "the \fBMBR\fR" (Master Boot Record). -.PP +.P In most systems, the OS loader is very limited due to various constraints. Even on non-PC systems, @@ -76,12 +76,12 @@ there are some limitations on the size and complexity of this loader, but the size limitation of the PC MBR (512 bytes, including the partition table) makes it almost impossible to squeeze much functionality into it. -.PP +.P Therefore, most systems split the role of loading the OS between a primary OS loader and a secondary OS loader; this secondary OS loader may be located within a larger portion of persistent storage, such as a disk partition. -.PP +.P In Linux, the OS loader is often .BR grub (8) (an alternative is @@ -95,13 +95,13 @@ The kernel starts the virtual memory swapper (it is a kernel process, called "kswapd" in a modern Linux kernel), and mounts some filesystem at the root path, .IR / . -.PP +.P Some of the parameters that may be passed to the kernel relate to these activities (for example, the default root filesystem can be overridden); for further information on Linux kernel parameters, read .BR bootparam (7). -.PP +.P Only then does the kernel create the initial userland process, which is given the number 1 as its .B PID @@ -120,7 +120,7 @@ fundamentally different approach known as .BR systemd (1), for which the bootup process is detailed in its associated .BR bootup (7). -.PP +.P When .I /sbin/init starts, it reads @@ -137,12 +137,12 @@ is single-user mode, and run level .B 2 entails running most network services). -.PP +.P The administrator may change the current run level via .BR init (1), and query the current run level via .BR runlevel (8). -.PP +.P However, since it is not convenient to manage individual services by editing this file, .I /etc/inittab @@ -154,7 +154,7 @@ Note: The following description applies to an OS based on UNIX System V Release 4. However, a number of widely used systems (Slackware Linux, FreeBSD, OpenBSD) have a somewhat different scheme for boot scripts. -.PP +.P For each managed service (mail, nfs server, cron, etc.), there is a single startup script located in a specific directory .RI ( /etc/init.d @@ -174,7 +174,7 @@ of the form \fI/etc/rc[0\-6S].d\fR. In each of these directories, there are links (usually symbolic) to the scripts in the \fI/etc/init.d\fR directory. -.PP +.P A primary script (usually \fI/etc/rc\fR) is called from .BR inittab (5); this primary script calls each service's script via a link in the @@ -183,7 +183,7 @@ Each link whose name begins with \[aq]S\[aq] is called with the argument "start" (thereby starting the service). Each link whose name begins with \[aq]K\[aq] is called with the argument "stop" (thereby stopping the service). -.PP +.P To define the starting or stopping order within the same run level, the name of a link contains an \fBorder-number\fR. Also, for clarity, the name of a link usually @@ -195,7 +195,7 @@ service on run level 2. This happens after \fI/etc/rc2.d/S12syslog\fR is run but before \fI/etc/rc2.d/S90xfs\fR is run. -.PP +.P To manage these links is to manage the boot order and run levels; under many systems, there are tools to help with this task (e.g., @@ -209,7 +209,7 @@ inputs without editing an entire boot script, some separate configuration file is used, and is located in a specific directory where an associated boot script may find it (\fI/etc/sysconfig\fR on older Red Hat systems). -.PP +.P In older UNIX systems, such a file contained the actual command line options for a daemon, but in modern Linux systems (and also in HP-UX), it just contains shell variables. diff --git a/man7/bootparam.7 b/man7/bootparam.7 index 5514aca..f9d3c10 100644 --- a/man7/bootparam.7 +++ b/man7/bootparam.7 @@ -6,7 +6,7 @@ .\" (dated v1.0.1, 15/08/95). .\" Major update, aeb, 970114. .\" -.TH bootparam 7 2023-02-05 "Linux man-pages 6.05.01" +.TH bootparam 7 2023-10-31 "Linux man-pages 6.7" .SH NAME bootparam \- introduction to boot time parameters of the Linux kernel .SH DESCRIPTION @@ -16,7 +16,7 @@ In general, this is used to supply the kernel with information about hardware parameters that the kernel would not be able to determine on its own, or to avoid/override the values that the kernel would otherwise detect. -.PP +.P When the kernel is booted directly by the BIOS, you have no opportunity to specify any parameters. So, in order to take advantage of this possibility you have to @@ -25,13 +25,13 @@ use a boot loader that is able to pass parameters, such as GRUB. The kernel command line is parsed into a list of strings (boot arguments) separated by spaces. Most of the boot arguments have the form: -.PP +.P .in +4n .EX name[=value_1][,value_2]...[,value_10] .EE .in -.PP +.P where 'name' is a unique keyword that is used to identify what part of the kernel the associated values (if any) are to be given to. Note the limit of 10 is real, as the present code handles only 10 comma @@ -39,14 +39,14 @@ separated parameters per keyword. (However, you can reuse the same keyword with up to an additional 10 parameters in unusually complicated situations, assuming the setup function supports it.) -.PP +.P Most of the sorting is coded in the kernel source file .IR init/main.c . First, the kernel checks to see if the argument is any of the special arguments 'root=', \&'nfsroot=', 'nfsaddrs=', 'ro', 'rw', 'debug', or 'init'. The meaning of these special arguments is described below. -.PP +.P Then it walks a list of setup functions to see if the specified argument string (such as 'foo') has been associated with a setup function ('foo_setup()') for a particular @@ -57,13 +57,13 @@ if 'foo' was registered. If it was, then it would call the setup function associated with 'foo' (foo_setup()) and hand it the arguments 3, 4, 5, and 6 as given on the kernel command line. -.PP +.P Anything of the form 'foo=bar' that is not accepted as a setup function as described above is then interpreted as an environment variable to be set. A (useless?) example would be to use 'TERM=vt100' as a boot argument. -.PP +.P Any remaining arguments that were not picked up by the kernel and were not interpreted as environment variables are then passed onto PID 1, which is usually the @@ -376,12 +376,12 @@ the last process that used it has closed .IR /dev/initrd .) .SS Boot arguments for SCSI devices General notation for this section: -.PP +.P .I iobase -- the first I/O port that the SCSI host occupies. These are specified in hexadecimal notation, and usually lie in the range from 0x200 to 0x3ff. -.PP +.P .I irq -- the hardware interrupt that the card is configured to use. Valid values will be dependent on the card in question, but will @@ -389,7 +389,7 @@ usually be 5, 7, 9, 10, 11, 12, and 15. The other values are usually used for common peripherals like IDE hard disks, floppies, serial ports, and so on. -.PP +.P .I scsi\-id -- the ID that the host adapter uses to identify itself on the SCSI bus. @@ -397,7 +397,7 @@ Only some host adapters allow you to change this value, as most have it permanently specified internally. The usual default value is 7, but the Seagate and Future Domain TMC-950 boards use 6. -.PP +.P .I parity -- whether the SCSI host adapter expects the attached devices to supply a parity value with all information exchanges. @@ -553,33 +553,33 @@ geometry parameters of the second disk. Different drivers make use of different parameters, but they all at least share having an IRQ, an I/O port base value, and a name. In its most generic form, it looks something like this: -.PP +.P .in +4n .EX ether=irq,iobase[,param_1[,...param_8]],name .EE .in -.PP +.P The first nonnumeric argument is taken as the name. The param_n values (if applicable) usually have different meanings for each different card/driver. Typical param_n values are used to specify things like shared memory address, interface selection, DMA channel and the like. -.PP +.P The most common use of this parameter is to force probing for a second ethercard, as the default is to probe only for one. This can be accomplished with a simple: -.PP +.P .in +4n .EX ether=0,0,eth1 .EE .in -.PP +.P Note that the values of zero for the IRQ and I/O base in the above example tell the driver(s) to autoprobe. -.PP +.P The Ethernet-HowTo has extensive documentation on using multiple cards and on the card/driver-specific implementation of the param_n values where used. @@ -604,25 +604,25 @@ It is described in the Linux kernel source file in older kernel versions). It accepts a boot argument of the form: -.PP +.P .in +4n .EX sound=device1[,device2[,device3...[,device10]]] .EE .in -.PP +.P where each deviceN value is of the following format 0xTaaaId and the bytes are used as follows: -.PP +.P T \- device type: 1=FM, 2=SB, 3=PAS, 4=GUS, 5=MPU401, 6=SB16, 7=SB16-MPU401 -.PP +.P aaa \- I/O address in hex. -.PP +.P I \- interrupt line in hex (i.e., 10=a, 11=b, ...) -.PP +.P d \- DMA channel. -.PP +.P As you can see, it gets pretty messy, and you are better off to compile in your own personal values as recommended. Using a boot argument of @@ -659,6 +659,6 @@ lp=0. .SH SEE ALSO .BR klogd (8), .BR mount (8) -.PP +.P For up-to-date information, see the kernel source file .IR Documentation/admin\-guide/kernel\-parameters.txt . diff --git a/man7/bpf-helpers.7 b/man7/bpf-helpers.7 index 26ddf83..b4236f1 100644 --- a/man7/bpf-helpers.7 +++ b/man7/bpf-helpers.7 @@ -27,18 +27,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BPF-HELPERS" 7 "2023-04-11" "Linux v6.2" +.TH "BPF-HELPERS" 7 "2023-11-10" "Linux v6.8" .SH NAME BPF-HELPERS \- list of eBPF helper functions .\" Copyright (C) All BPF authors and contributors from 2014 to present. . .\" See git log include/uapi/linux/bpf.h in kernel tree for details. . -.\" +.\" . -.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" SPDX-License-Identifier: Linux-man-pages-copyleft . -.\" +.\" . .\" Please do not edit this file. It was generated from the documentation . @@ -156,27 +156,25 @@ Current \fIktime\fP\&. .B Description This helper is a \(dqprintk()\-like\(dq facility for debugging. It prints a message defined by format \fIfmt\fP (of size \fIfmt_size\fP) -to file \fI/sys/kernel/debug/tracing/trace\fP from DebugFS, if +to file \fI/sys/kernel/tracing/trace\fP from TraceFS, if available. It can take up to three additional \fBu64\fP arguments (as an eBPF helpers, the total number of arguments is limited to five). .sp Each time the helper is called, it appends a line to the trace. -Lines are discarded while \fI/sys/kernel/debug/tracing/trace\fP is -open, use \fI/sys/kernel/debug/tracing/trace_pipe\fP to avoid this. +Lines are discarded while \fI/sys/kernel/tracing/trace\fP is +open, use \fI/sys/kernel/tracing/trace_pipe\fP to avoid this. The format of the trace is customizable, and the exact output one will get depends on the options set in -\fI/sys/kernel/debug/tracing/trace_options\fP (see also the +\fI/sys/kernel/tracing/trace_options\fP (see also the \fIREADME\fP file under the same directory). However, it usually defaults to something like: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C -telnet\-470 [001] .N.. 419421.045894: 0x00000001: -.ft P -.fi +.EX +telnet\-470 [001] .N.. 419421.045894: 0x00000001: +.EE .UNINDENT .UNINDENT .sp @@ -204,7 +202,8 @@ are set. \fB0x00000001\fP is a fake value used by BPF for the instruction pointer register. .IP \(bu 2 -\fB\fP is the message formatted with \fIfmt\fP\&. +\fB\fP is the message formatted with +\fIfmt\fP\&. .UNINDENT .UNINDENT .UNINDENT @@ -404,7 +403,9 @@ performed again, if the helper is used in combination with direct packet access. .TP .B Return -0 on success, or a negative error in case of failure. +0 on success, or a negative error in case of failure. Positive +error indicates a potential drop or congestion in the target +device. The particular positive error codes are not defined. .UNINDENT .TP .B \fBu64 bpf_get_current_pid_tgid(void)\fP @@ -541,8 +542,7 @@ remote ends with IPv4 address other than 10.0.0.1: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX int ret; struct bpf_tunnel_key key = {}; @@ -554,8 +554,7 @@ if (key.remote_ipv4 != 0x0a000001) return TC_ACT_SHOT; // drop packet return TC_ACT_OK; // accept packet -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -600,20 +599,22 @@ sequence number should be added to tunnel header before sending the packet. This flag was added for GRE encapsulation, but might be used with other protocols as well in the future. +.TP +.B \fBBPF_F_NO_TUNNEL_KEY\fP +Add a flag to tunnel metadata indicating that no tunnel +key should be set in the resulting tunnel header. .UNINDENT .sp Here is a typical usage on the transmit path: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX struct bpf_tunnel_key key; populate key ... bpf_skb_set_tunnel_key(skb, &key, sizeof(key), 0); bpf_clone_redirect(skb, vxlan_dev_ifindex, 0); -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -827,11 +828,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack= -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -1334,8 +1333,8 @@ The option value of length \fIoptlen\fP is pointed by \fIoptval\fP\&. .IP \(bu 2 \fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp This helper actually implements a subset of \fBsetsockopt()\fP\&. @@ -1417,6 +1416,11 @@ type; \fIlen\fP is the length of the inner MAC header. \fBBPF_F_ADJ_ROOM_ENCAP_L2_ETH\fP: Use with BPF_F_ADJ_ROOM_ENCAP_L2 flag to further specify the L2 type as Ethernet. +.IP \(bu 2 +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV4\fP, +\fBBPF_F_ADJ_ROOM_DECAP_L3_IPV6\fP: +Indicate the new IP header version after decapsulating the outer +IP header. Used when the inner and outer IP versions are different. .UNINDENT .sp A call to this helper is susceptible to change the underlying @@ -1572,11 +1576,9 @@ as follows. .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX normalized_counter = counter * t_enabled / t_running -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -1596,7 +1598,7 @@ value and do the calculation inside the eBPF program. .INDENT 7.0 .TP .B Description -For en eBPF program attached to a perf event, retrieve the +For an eBPF program attached to a perf event, retrieve the value of the event counter associated to \fIctx\fP and store it in the structure pointed by \fIbuf\fP and of size \fIbuf_size\fP\&. Enabled and running times are also stored in the structure (see @@ -1623,8 +1625,8 @@ The retrieved value is stored in the structure pointed by .IP \(bu 2 \fBstruct bpf_sock_ops\fP for \fBBPF_PROG_TYPE_SOCK_OPS\fP\&. .IP \(bu 2 -\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP -and \fBBPF_CGROUP_INET6_CONNECT\fP\&. +\fBstruct bpf_sock_addr\fP for \fBBPF_CGROUP_INET4_CONNECT\fP, +\fBBPF_CGROUP_INET6_CONNECT\fP and \fBBPF_CGROUP_UNIX_CONNECT\fP\&. .UNINDENT .sp This helper actually implements a subset of \fBgetsockopt()\fP\&. @@ -1945,11 +1947,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack= -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -2010,9 +2010,26 @@ following values: Do a direct table lookup vs full lookup using FIB rules. .TP +.B \fBBPF_FIB_LOOKUP_TBID\fP +Used with BPF_FIB_LOOKUP_DIRECT. +Use the routing table ID present in \fIparams\fP\->tbid +for the fib lookup. +.TP .B \fBBPF_FIB_LOOKUP_OUTPUT\fP Perform lookup from an egress perspective (default is ingress). +.TP +.B \fBBPF_FIB_LOOKUP_SKIP_NEIGH\fP +Skip the neighbour table lookup. \fIparams\fP\->dmac +and \fIparams\fP\->smac will not be set as output. A common +use case is to call \fBbpf_redirect_neigh\fP() after +doing \fBbpf_fib_lookup\fP(). +.TP +.B \fBBPF_FIB_LOOKUP_SRC\fP +Derive and set source IP addr in \fIparams\fP\->ipv{4,6}_src +for the nexthop. If the src addr cannot be derived, +\fBBPF_FIB_LKUP_RET_NO_SRC_ADDR\fP is returned. In this +case, \fIparams\fP\->dmac and \fIparams\fP\->smac are not set either. .UNINDENT .sp \fIctx\fP is either \fBstruct xdp_md\fP for XDP programs or @@ -3029,24 +3046,20 @@ get its length at runtime. See the following snippet: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX SEC(\(dqkprobe/sys_open\(dq) void bpf_sys_open(struct pt_regs *ctx) { char buf[PATHLEN]; // PATHLEN is defined to 256 - int res; - - res = bpf_probe_read_user_str(buf, sizeof(buf), - ctx\->di); + int res = bpf_probe_read_user_str(buf, sizeof(buf), + ctx\->di); // Consume buf, for example push it to // userspace via bpf_perf_event_output(); we // can use res (the string length) as event // size, after checking its boundaries. } -.ft P -.fi +.EE .UNINDENT .UNINDENT .sp @@ -3253,9 +3266,6 @@ The \fIflags\fP argument must be zero. .sp \fB\-EOPNOTSUPP\fP if the operation is not supported, for example a call from outside of TC ingress. -.sp -\fB\-ESOCKTNOSUPPORT\fP if the socket type is not supported -(reuseport). .UNINDENT .TP .B \fBlong bpf_sk_assign(struct bpf_sk_lookup *\fP\fIctx\fP\fB, struct bpf_sock *\fP\fIsk\fP\fB, u64\fP \fIflags\fP\fB)\fP @@ -3605,6 +3615,8 @@ Dynamically cast a \fIsk\fP pointer to a \fIudp6_sock\fP pointer. .TP .B Description Return a user or a kernel stack in bpf program provided buffer. +Note: the user stack will only be populated if the \fItask\fP is +the current task; all other tasks will return \-EOPNOTSUPP. To achieve this, the helper needs \fItask\fP, which is a valid pointer to \fBstruct task_struct\fP\&. To store the stacktrace, the bpf program provides \fIbuf\fP with a nonnegative \fIsize\fP\&. @@ -3617,6 +3629,7 @@ the following flags: .TP .B \fBBPF_F_USER_STACK\fP Collect a user space stack instead of a kernel stack. +The \fItask\fP must be the current task. .TP .B \fBBPF_F_USER_BUILD_ID\fP Collect buildid+offset instead of ips for user stack, @@ -3632,11 +3645,9 @@ user stacks (such as stacks for Java programs). To do so, use: .INDENT 7.0 .INDENT 3.5 .sp -.nf -.ft C +.EX # sysctl kernel.perf_event_max_stack= -.ft P -.fi +.EE .UNINDENT .UNINDENT .TP @@ -4334,6 +4345,17 @@ The map can contain timers that invoke callback_fn\-s from different programs. The same callback_fn can serve different timers from different maps if key/value layout matches across maps. Every bpf_timer_set_callback() can have different callback_fn. +.sp +\fIflags\fP can be one of: +.INDENT 7.0 +.TP +.B \fBBPF_F_TIMER_ABS\fP +Start the timer in absolute expire value instead of the +default relative one. +.TP +.B \fBBPF_F_TIMER_CPU_PIN\fP +Timer will be pinned to the CPU of the caller. +.UNINDENT .TP .B Return 0 on success. @@ -4360,10 +4382,14 @@ own timer which would have led to a deadlock otherwise. .TP .B Description Get address of the traced function (for tracing and kprobe programs). +.sp +When called for kprobe program attached as uprobe it returns +probe address for both entry and return uprobe. .TP .B Return -Address of the traced function. +Address of the traced function for kprobe. 0 for kprobes placed within the function (not at the entry). +Address of the probe for uprobe and return uprobe. .UNINDENT .TP .B \fBu64 bpf_get_attach_cookie(void *\fP\fIctx\fP\fB)\fP @@ -4817,12 +4843,28 @@ of \fIsrc\fP\(aqs data, \-EINVAL if \fIsrc\fP is an invalid dynptr or if .B Description Write \fIlen\fP bytes from \fIsrc\fP into \fIdst\fP, starting from \fIoffset\fP into \fIdst\fP\&. -\fIflags\fP is currently unused. +.sp +\fIflags\fP must be 0 except for skb\-type dynptrs. +.INDENT 7.0 +.TP +.B For skb\-type dynptrs: +.INDENT 7.0 +.IP \(bu 2 +All data slices of the dynptr are automatically +invalidated after \fBbpf_dynptr_write\fP(). This is +because writing may pull the skb and change the +underlying packet buffer. +.IP \(bu 2 +For \fIflags\fP, please see the flags accepted by +\fBbpf_skb_store_bytes\fP(). +.UNINDENT +.UNINDENT .TP .B Return 0 on success, \-E2BIG if \fIoffset\fP + \fIlen\fP exceeds the length of \fIdst\fP\(aqs data, \-EINVAL if \fIdst\fP is an invalid dynptr or if \fIdst\fP -is a read\-only dynptr or if \fIflags\fP is not 0. +is a read\-only dynptr or if \fIflags\fP is not correct. For skb\-type dynptrs, +other errors correspond to errors returned by \fBbpf_skb_store_bytes\fP(). .UNINDENT .TP .B \fBvoid *bpf_dynptr_data(const struct bpf_dynptr *\fP\fIptr\fP\fB, u32\fP \fIoffset\fP\fB, u32\fP \fIlen\fP\fB)\fP @@ -4833,6 +4875,9 @@ Get a pointer to the underlying dynptr data. .sp \fIlen\fP must be a statically known value. The returned data slice is invalidated whenever the dynptr is invalidated. +.sp +skb and xdp type dynptrs may not use bpf_dynptr_data. They should +instead use bpf_dynptr_slice and bpf_dynptr_slice_rdwr. .TP .B Return Pointer to the underlying dynptr data, NULL if the dynptr is @@ -5049,7 +5094,7 @@ eBPF programs can have an associated license, passed along with the bytecode instructions to the kernel when the programs are loaded. The format for that string is identical to the one in use for kernel modules (Dual licenses, such as \(dqDual BSD/GPL\(dq, may be used). Some helper functions are only accessible to -programs that are compatible with the GNU Privacy License (GPL). +programs that are compatible with the GNU General Public License (GNU GPL). .sp In order to use such helpers, the eBPF program must be loaded with the correct license string passed (via \fBattr\fP) to the \fBbpf\fP() system call, and this @@ -5058,11 +5103,9 @@ similar to the following: .INDENT 0.0 .INDENT 3.5 .sp -.nf -.ft C +.EX char ____license[] __attribute__((section(\(dqlicense\(dq), used)) = \(dqGPL\(dq; -.ft P -.fi +.EE .UNINDENT .UNINDENT .SH IMPLEMENTATION diff --git a/man7/capabilities.7 b/man7/capabilities.7 index c8766d2..ad087f9 100644 --- a/man7/capabilities.7 +++ b/man7/capabilities.7 @@ -25,7 +25,7 @@ .\" other capabilities where the permitted or inheritable bit is set. .\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG .\" -.TH Capabilities 7 2023-05-03 "Linux man-pages 6.05.01" +.TH Capabilities 7 2024-02-25 "Linux man-pages 6.7" .SH NAME capabilities \- overview of Linux capabilities .SH DESCRIPTION @@ -40,7 +40,7 @@ Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (usually: effective UID, effective GID, and supplementary group list). -.PP +.P Starting with Linux 2.2, Linux divides the privileges traditionally associated with superuser into distinct units, known as .IR capabilities , @@ -832,7 +832,7 @@ be changed and retrieved. .IP \[bu] The filesystem must support attaching capabilities to an executable file, so that a process gains those capabilities when the file is executed. -.PP +.P Before Linux 2.6.24, only the first two of these requirements are met; since Linux 2.6.24, all three requirements are met. .\" @@ -961,7 +961,7 @@ capabilities to increase during an .BR execve (2), this does not trigger the secure-execution mode described in .BR ld.so (8). -.PP +.P A child created via .BR fork (2) inherits copies of its parent's capability sets. @@ -970,13 +970,13 @@ For details on how affects capabilities, see .I Transformation of capabilities during execve() below. -.PP +.P Using .BR capset (2), a thread may manipulate its own capability sets; see .I Programmatically adjusting capability sets below. -.PP +.P Since Linux 3.2, the file .I /proc/sys/kernel/cap_last_cap .\" commit 73efc0394e148d0e15583e13712637831f926720 @@ -1002,7 +1002,7 @@ The file capability sets, in conjunction with the capability sets of the thread, determine the capabilities of a thread after an .BR execve (2). -.PP +.P The three file capability sets are: .TP .IR Permitted " (formerly known as " forced ): @@ -1084,7 +1084,7 @@ with version 2 capabilities; that is, on a modern Linux system, there may be some files with version 2 capabilities while others have version 3 capabilities. -.PP +.P Before Linux 4.14, the only kind of file capability extended attribute that could be attached to a file was a @@ -1095,7 +1095,7 @@ the version of the .I security.capability extended attribute that is attached to a file depends on the circumstances in which the attribute was created. -.PP +.P Starting with Linux 4.14, a .I security.capability extended attribute is automatically created as (or converted to) @@ -1115,13 +1115,13 @@ meaning that (a) the thread has the capability in its own user namespace; and (b) the UID and GID of the file inode have mappings in the writer's user namespace. -.PP +.P When a .B VFS_CAP_REVISION_3 .I security.capability extended attribute is created, the root user ID of the creating thread's user namespace is saved in the extended attribute. -.PP +.P By contrast, creating or modifying a .I security.capability extended attribute from a privileged @@ -1132,7 +1132,7 @@ namespace where the underlying filesystem was mounted automatically results in the creation of a version 2 .RB ( VFS_CAP_REVISION_2 ) attribute. -.PP +.P Note that the creation of a version 3 .I security.capability extended attribute is automatic. @@ -1161,7 +1161,7 @@ and in order for those tools to be used to create and retrieve version 3 .I security.capability attributes. -.PP +.P Note that a file can have either a version 2 or a version 3 .I security.capability extended attribute associated with it, but not both: @@ -1176,7 +1176,7 @@ During an .BR execve (2), the kernel calculates the new capabilities of the process using the following algorithm: -.PP +.P .in +4n .EX P'(ambient) = (file is privileged) ? 0 : P(ambient) @@ -1191,7 +1191,7 @@ P'(inheritable) = P(inheritable) [i.e., unchanged] P'(bounding) = P(bounding) [i.e., unchanged] .EE .in -.PP +.P where: .RS 4 .TP @@ -1206,7 +1206,7 @@ denotes the value of a thread capability set after the F() denotes a file capability set .RE -.PP +.P Note the following details relating to the above capability transformation rules: .IP \[bu] 3 @@ -1222,7 +1222,7 @@ That system-wide value was employed to calculate the new permitted set during .BR execve (2) in the same manner as shown above for .IR P(bounding) . -.PP +.P .IR Note : during the capability transitions described above, file capabilities may be ignored (treated as empty) for the same reasons @@ -1231,7 +1231,7 @@ that the set-user-ID and set-group-ID bits are ignored; see File capabilities are similarly ignored if the kernel was booted with the .I no_file_caps option. -.PP +.P .IR Note : according to the rules above, if a process with nonzero user IDs performs an @@ -1259,7 +1259,7 @@ so that the file permitted capabilities are automatically enabled in the process effective set when executing the file. The kernel recognizes a file which has the effective capability bit set as capability-dumb for the purpose of the check described here. -.PP +.P When executing a capability-dumb binary, the kernel checks if the process obtained all permitted capabilities that were specified in the file permitted set, @@ -1288,7 +1288,7 @@ In order to mirror traditional UNIX semantics, the kernel performs special treatment of file capabilities when a process with UID 0 (root) executes a program and when a set-user-ID-root program is executed. -.PP +.P After having performed any changes to the process effective ID that were triggered by the set-user-ID mode bit of the binary\[em]e.g., switching the effective user ID to 0 (root) because @@ -1306,12 +1306,12 @@ below.) If the effective user ID of the process is 0 (root) or the file effective bit is in fact enabled, then the file effective bit is notionally defined to be one (enabled). -.PP +.P These notional values for the file's capability sets are then used as described above to calculate the transformation of the process's capabilities during .BR execve (2). -.PP +.P Thus, when a process with nonzero UIDs .BR execve (2)s a set-user-ID-root program that does not have capabilities attached, @@ -1319,7 +1319,7 @@ or when a process whose real and effective UIDs are zero .BR execve (2)s a program, the calculation of the process's new permitted capabilities simplifies to: -.PP +.P .in +4n .EX P'(permitted) = P(inheritable) | P(bounding) @@ -1327,14 +1327,14 @@ P'(permitted) = P(inheritable) | P(bounding) P'(effective) = P'(permitted) .EE .in -.PP +.P Consequently, the process gains all capabilities in its permitted and effective capability sets, except those masked out by the capability bounding set. (In the calculation of P'(permitted), the P'(ambient) term can be simplified away because it is by definition a proper subset of P(inheritable).) -.PP +.P The special treatments of user ID 0 (root) described in this subsection can be disabled using the securebits mechanism described below. .\" @@ -1358,7 +1358,7 @@ the process gains just the capabilities granted by the program (i.e., not all capabilities, as would occur when executing a set-user-ID-root program that does not have any associated file capabilities). -.PP +.P Note that one can assign empty capability sets to a program file, and thus it is possible to create a set-user-ID-root program that changes the effective and saved set-user-ID of the process @@ -1390,29 +1390,29 @@ and thereby cannot have this capability preserved in its permitted set when it .BR execve (2)s a file that has the capability in its inheritable set. -.PP +.P Note that the bounding set masks the file permitted capabilities, but not the inheritable capabilities. If a thread maintains a capability in its inheritable set that is not in its bounding set, then it can still gain that capability in its permitted set by executing a file that has the capability in its inheritable set. -.PP +.P Depending on the kernel version, the capability bounding set is either a system-wide attribute, or a per-process attribute. -.PP +.P .B "Capability bounding set from Linux 2.6.25 onward" -.PP +.P From Linux 2.6.25, the .I "capability bounding set" is a per-thread attribute. (The system-wide capability bounding set described below no longer exists.) -.PP +.P The bounding set is inherited at .BR fork (2) from the thread's parent, and is preserved across an .BR execve (2). -.PP +.P A thread may remove capabilities from its capability bounding set using the .BR prctl (2) .B PR_CAPBSET_DROP @@ -1425,7 +1425,7 @@ A thread can determine if a capability is in its bounding set using the .BR prctl (2) .B PR_CAPBSET_READ operation. -.PP +.P Removing capabilities from the bounding set is supported only if file capabilities are compiled into the kernel. Before Linux 2.6.33, @@ -1445,14 +1445,14 @@ begins with a full bounding set minus .BR CAP_SETPCAP , because this capability has a different meaning when there are no file capabilities. -.PP +.P Removing a capability from the bounding set does not remove it from the thread's inheritable set. However it does prevent the capability from being added back into the thread's inheritable set in the future. -.PP +.P .B "Capability bounding set prior to Linux 2.6.25" -.PP +.P Before Linux 2.6.25, the capability bounding set is a system-wide attribute that affects all threads on the system. The bounding set is accessible via the file @@ -1460,14 +1460,14 @@ The bounding set is accessible via the file (Confusingly, this bit mask parameter is expressed as a signed decimal number in .IR /proc/sys/kernel/cap\-bound .) -.PP +.P Only the .B init process may set capabilities in the capability bounding set; other than that, the superuser (more precisely: a process with the .B CAP_SYS_MODULE capability) may only clear capabilities from this set. -.PP +.P On a standard system the capability bounding set always masks out the .B CAP_SETPCAP capability. @@ -1476,7 +1476,7 @@ To remove this restriction (dangerous!), modify the definition of in .I include/linux/capability.h and rebuild the kernel. -.PP +.P The system-wide capability bounding set feature was added to Linux 2.2.11. .\" @@ -1521,7 +1521,7 @@ and If the filesystem UID is changed from nonzero to 0, then any of these capabilities that are enabled in the permitted set are enabled in the effective set. -.PP +.P If a thread that has a 0 value for one or more of its user IDs wants to prevent its permitted capability set being cleared when it resets all of its user IDs to nonzero values, it can do so using the @@ -1625,7 +1625,7 @@ Setting this flag disallows raising ambient capabilities via the .BR prctl (2) .B PR_CAP_AMBIENT_RAISE operation. -.PP +.P Each of the above "base" flags has a companion "locked" flag. Setting any of the "locked" flags is irreversible, and has the effect of preventing further changes to the @@ -1636,7 +1636,7 @@ The locked flags are: .BR SECBIT_NOROOT_LOCKED , and .BR SECBIT_NO_CAP_AMBIENT_RAISE_LOCKED . -.PP +.P The .I securebits flags can be modified and retrieved using the @@ -1653,7 +1653,7 @@ Note that the constants are available only after including the .I header file. -.PP +.P The .I securebits flags are inherited by child processes. @@ -1662,12 +1662,12 @@ During an all of the flags are preserved, except .B SECBIT_KEEP_CAPS which is always cleared. -.PP +.P An application can use the following call to lock itself, and all of its descendants, into an environment where the only way of gaining capabilities is by executing a program with associated file capabilities: -.PP +.P .in +4n .EX prctl(PR_SET_SECUREBITS, @@ -1683,13 +1683,13 @@ prctl(PR_SET_SECUREBITS, .in .\" .\" -.SS Per-user-namespace """set-user-ID-root""" programs +.SS Per-user-namespace \[dq]set-user-ID-root\[dq] programs A set-user-ID program whose UID matches the UID that created a user namespace will confer capabilities in the process's permitted and effective sets when executed by any process inside that namespace or any descendant user namespace. -.PP +.P The rules about the transformation of the process's capabilities during the .BR execve (2) are exactly as described in @@ -1710,7 +1710,7 @@ it gains the associated capabilities (within its user namespace) as per the rules described in .I Transformation of capabilities during execve() above. -.PP +.P Because version 2 file capabilities confer capabilities to the executing process regardless of which user namespace it resides in, only privileged processes are permitted to associate capabilities with a file. @@ -1723,7 +1723,7 @@ For example, in user-namespaced containers, it can be desirable to be able to create a binary that confers capabilities only to processes executed inside that container, but not to processes that are executed outside the container. -.PP +.P Linux 4.14 added so-called namespaced file capabilities to support such use cases. Namespaced file capabilities are recorded as version 3 (i.e., @@ -1739,7 +1739,7 @@ When a version 3 extended attribute is created, the kernel records not just the capability masks in the extended attribute, but also the namespace root user ID. -.PP +.P As with a binary that has .B VFS_CAP_REVISION_2 file capabilities, a binary with @@ -1770,13 +1770,13 @@ you may find the .I \-u option useful. Something like: -.PP +.P .in +4n .EX $ \fBsudo strace \-o trace.log \-u ceci ./myprivprog\fP .EE .in -.PP +.P From Linux 2.5.27 to Linux 2.6.26, .\" commit 5915eb53861c5776cfec33ca4fcc1fd20d66dd27 removed .\" CONFIG_SECURITY_CAPABILITIES @@ -1784,7 +1784,7 @@ capabilities were an optional kernel component, and could be enabled/disabled via the .B CONFIG_SECURITY_CAPABILITIES kernel configuration option. -.PP +.P The .IR /proc/ pid /task/TID/status file can be used to view the capability sets of a thread. @@ -1798,7 +1798,7 @@ Since Linux 3.8, all nonexistent capabilities (above .BR CAP_LAST_CAP ) are shown as disabled (0). -.PP +.P The .I libcap package provides a suite of routines for setting and @@ -1816,7 +1816,7 @@ It can be found at .br .UR https://git.kernel.org\:/pub\:/scm\:/libs\:/libcap\:/libcap.git\:/refs/ .UE . -.PP +.P Before Linux 2.6.24, and from Linux 2.6.24 to Linux 2.6.32 if file capabilities are not enabled, a thread with the .B CAP_SETPCAP @@ -1867,6 +1867,6 @@ created on the system. .BR netcap (8), \" from libcap-ng .BR pscap (8), \" from libcap-ng .BR setcap (8) -.PP +.P .I include/linux/capability.h in the Linux kernel source tree diff --git a/man7/cgroup_namespaces.7 b/man7/cgroup_namespaces.7 index c1162fe..f5c73ab 100644 --- a/man7/cgroup_namespaces.7 +++ b/man7/cgroup_namespaces.7 @@ -3,20 +3,20 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH cgroup_namespaces 7 2023-03-30 "Linux man-pages 6.05.01" +.TH cgroup_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME cgroup_namespaces \- overview of Linux cgroup namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P Cgroup namespaces virtualize the view of a process's cgroups (see .BR cgroups (7)) as seen via .IR /proc/ pid /cgroup and .IR /proc/ pid /mountinfo . -.PP +.P Each cgroup namespace has its own set of cgroup root directories. These root directories are the base points for the relative locations displayed in the corresponding records in the @@ -33,7 +33,7 @@ cgroups directories become the cgroup root directories of the new namespace. (This applies both for the cgroups version 1 hierarchies and the cgroups version 2 unified hierarchy.) -.PP +.P When reading the cgroup memberships of a "target" process from .IR /proc/ pid /cgroup , the pathname shown in the third field of each record will be @@ -44,16 +44,16 @@ the root directory of the reading process's cgroup namespace, then the pathname will show .I ../ entries for each ancestor level in the cgroup hierarchy. -.PP +.P The following shell session demonstrates the effect of creating a new cgroup namespace. -.PP +.P First, (as superuser) in a shell in the initial cgroup namespace, we create a child cgroup in the .I freezer hierarchy, and place a process in that cgroup that we will use as part of the demonstration below: -.PP +.P .in +4n .EX # \fBmkdir \-p /sys/fs/cgroup/freezer/sub2\fP @@ -62,11 +62,11 @@ use as part of the demonstration below: # \fBecho 20124 > /sys/fs/cgroup/freezer/sub2/cgroup.procs\fP .EE .in -.PP +.P We then create another child cgroup in the .I freezer hierarchy and put the shell into that cgroup: -.PP +.P .in +4n .EX # \fBmkdir \-p /sys/fs/cgroup/freezer/sub\fP @@ -77,17 +77,17 @@ hierarchy and put the shell into that cgroup: 7:freezer:/sub .EE .in -.PP +.P Next, we use .BR unshare (1) to create a process running a new shell in new cgroup and mount namespaces: -.PP +.P .in +4n .EX # \fBPS1="sh2# " unshare \-Cm bash\fP .EE .in -.PP +.P From the new shell started by .BR unshare (1), we then inspect the @@ -97,7 +97,7 @@ a process that is in the initial cgroup namespace .RI ( init , with PID 1), and the process in the sibling cgroup .RI ( sub2 ): -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/cgroup | grep freezer\fP @@ -108,7 +108,7 @@ sh2# \fBcat /proc/20124/cgroup | grep freezer\fP 7:freezer:/../sub2 .EE .in -.PP +.P From the output of the first command, we see that the freezer cgroup membership of the new shell (which is in the same cgroup as the initial shell) @@ -122,18 +122,18 @@ and the root directory of the freezer cgroup hierarchy in the new cgroup namespace is also .IR /sub . Thus, the new shell's cgroup membership is displayed as \[aq]/\[aq].) -.PP +.P However, when we look in .I /proc/self/mountinfo we see the following anomaly: -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep freezer\fP 155 145 0:32 /.. /sys/fs/cgroup/freezer ... .EE .in -.PP +.P The fourth field of this line .RI ( /.. ) should show the @@ -148,7 +148,7 @@ filesystem corresponding to the initial cgroup namespace To fix this problem, we must remount the freezer cgroup filesystem from the new shell (i.e., perform the mount from a process that is in the new cgroup namespace), after which we see the expected results: -.PP +.P .in +4n .EX sh2# \fBmount \-\-make\-rslave /\fP # Don\[aq]t propagate mount events @@ -166,7 +166,7 @@ Linux. Use of cgroup namespaces requires a kernel that is configured with the .B CONFIG_CGROUPS option. -.PP +.P The virtualization provided by cgroup namespaces serves a number of purposes: .IP \[bu] 3 It prevents information leaks whereby cgroup directory paths outside of diff --git a/man7/cgroups.7 b/man7/cgroups.7 index c070ca7..e2c3ec2 100644 --- a/man7/cgroups.7 +++ b/man7/cgroups.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH cgroups 7 2023-04-03 "Linux man-pages 6.05.01" +.TH cgroups 7 2024-03-05 "Linux man-pages 6.7" .SH NAME cgroups \- Linux control groups .SH DESCRIPTION @@ -22,7 +22,7 @@ A .I cgroup is a collection of processes that are bound to a set of limits or parameters defined via the cgroup filesystem. -.PP +.P A .I subsystem is a kernel component that modifies the behavior of @@ -34,7 +34,7 @@ and freezing and resuming execution of the processes in a cgroup. Subsystems are sometimes also known as .I resource controllers (or simply, controllers). -.PP +.P The cgroups for a controller are arranged in a .IR hierarchy . This hierarchy is defined by creating, removing, and @@ -60,7 +60,7 @@ source file (or .I Documentation/cgroup\-v2.txt in Linux 4.17 and earlier). -.PP +.P Because of the problems with the initial cgroups implementation (cgroups version 1), starting in Linux 3.10, work began on a new, @@ -74,7 +74,7 @@ The file .IR cgroup.sane_behavior , present in cgroups v1, is a relic of this mount option. The file always reports "0" and is only retained for backward compatibility. -.PP +.P Although cgroups v2 is intended as a replacement for cgroups v1, the older system continues to exist (and for compatibility reasons is unlikely to be removed). @@ -96,7 +96,7 @@ processes on the system. It is also possible to comount multiple (or even all) cgroups v1 controllers against the same cgroup filesystem, meaning that the comounted controllers manage the same hierarchical organization of processes. -.PP +.P For each mounted hierarchy, the directory tree mirrors the control group hierarchy. Each control group is represented by a directory, with each of its child @@ -123,7 +123,7 @@ In this view, a process can consist of multiple tasks and called such in the remainder of this man page). In cgroups v1, it is possible to independently manipulate the cgroup memberships of the threads in a process. -.PP +.P The cgroups v1 ability to split threads across different cgroups caused problems in some cases. For example, it made no sense for the @@ -142,7 +142,7 @@ The use of cgroups requires a kernel built with the option. In addition, each of the v1 controllers has an associated configuration option that must be set in order to employ that controller. -.PP +.P In order to use a v1 controller, it must be mounted against a cgroup filesystem. The usual place for such mounts is under a @@ -152,26 +152,26 @@ filesystem mounted at Thus, one might mount the .I cpu controller as follows: -.PP +.P .in +4n .EX mount \-t cgroup \-o cpu none /sys/fs/cgroup/cpu .EE .in -.PP +.P It is possible to comount multiple controllers against the same hierarchy. For example, here the .I cpu and .I cpuacct controllers are comounted against a single hierarchy: -.PP +.P .in +4n .EX mount \-t cgroup \-o cpu,cpuacct none /sys/fs/cgroup/cpu,cpuacct .EE .in -.PP +.P Comounting controllers has the effect that a process is in the same cgroup for all of the comounted controllers. Separately mounting controllers allows a process to @@ -180,19 +180,19 @@ be in cgroup for one controller while being in .I /foo2/foo3 for another. -.PP +.P It is possible to comount all v1 controllers against the same hierarchy: -.PP +.P .in +4n .EX mount \-t cgroup \-o all cgroup /sys/fs/cgroup .EE .in -.PP +.P (One can achieve the same result by omitting .IR "\-o all" , since it is the default if no controllers are explicitly specified.) -.PP +.P It is not possible to mount the same controller against multiple cgroup hierarchies. For example, it is not possible to mount both the @@ -206,7 +206,7 @@ It is possible to create multiple mount with exactly the same set of comounted controllers. However, in this case all that results is multiple mount points providing a view of the same hierarchy. -.PP +.P Note that on many systems, the v1 controllers are automatically mounted under .IR /sys/fs/cgroup ; in particular, @@ -217,13 +217,13 @@ automatically creates such mounts. A mounted cgroup filesystem can be unmounted using the .BR umount (8) command, as in the following example: -.PP +.P .in +4n .EX umount /sys/fs/cgroup/pids .EE .in -.PP +.P .IR "But note well" : a cgroup filesystem is unmounted only if it is not busy, that is, it has no child cgroups. @@ -409,41 +409,41 @@ in Linux 5.2 and earlier). A cgroup filesystem initially contains a single root cgroup, '/', which all processes belong to. A new cgroup is created by creating a directory in the cgroup filesystem: -.PP +.P .in +4n .EX mkdir /sys/fs/cgroup/cpu/cg1 .EE .in -.PP +.P This creates a new empty cgroup. -.PP +.P A process may be moved to this cgroup by writing its PID into the cgroup's .I cgroup.procs file: -.PP +.P .in +4n .EX echo $$ > /sys/fs/cgroup/cpu/cg1/cgroup.procs .EE .in -.PP +.P Only one PID at a time should be written to this file. -.PP +.P Writing the value 0 to a .I cgroup.procs file causes the writing process to be moved to the corresponding cgroup. -.PP +.P When writing a PID into the .IR cgroup.procs , all threads in the process are moved into the new cgroup at once. -.PP +.P Within a hierarchy, a process can be a member of exactly one cgroup. Writing a process's PID to a .I cgroup.procs file automatically removes it from the cgroup of which it was previously a member. -.PP +.P The .I cgroup.procs file can be read to obtain a list of the processes that are @@ -451,7 +451,7 @@ members of a cgroup. The returned list of PIDs is not guaranteed to be in order. Nor is it guaranteed to be free of duplicates. (For example, a PID may be recycled while reading from the list.) -.PP +.P In cgroups v1, an individual thread can be moved to another cgroup by writing its thread ID (i.e., the kernel thread ID returned by @@ -477,7 +477,7 @@ Two files can be used to determine whether the kernel provides notifications when a cgroup becomes empty. A cgroup is considered to be empty when it contains no child cgroups and no member processes. -.PP +.P A special file in the root directory of each cgroup hierarchy, .IR release_agent , can be used to register the pathname of a program that may be invoked when @@ -490,22 +490,22 @@ The .I release_agent program might remove the cgroup directory, or perhaps repopulate it with a process. -.PP +.P The default value of the .I release_agent file is empty, meaning that no release agent is invoked. -.PP +.P The content of the .I release_agent file can also be specified via a mount option when the cgroup filesystem is mounted: -.PP +.P .in +4n .EX mount \-o release_agent=pathname ... .EE .in -.PP +.P Whether or not the .I release_agent program is invoked when a particular cgroup becomes empty is determined @@ -526,13 +526,13 @@ in the parent cgroup. .SS Cgroup v1 named hierarchies In cgroups v1, it is possible to mount a cgroup hierarchy that has no attached controllers: -.PP +.P .in +4n .EX mount \-t cgroup \-o none,name=somename none /some/mount/point .EE .in -.PP +.P Multiple instances of such hierarchies can be mounted; each hierarchy must have a unique name. The only purpose of such hierarchies is to track processes. @@ -542,7 +542,7 @@ An example of this is the cgroup hierarchy that is used by .BR systemd (1) to track services and user sessions. -.PP +.P Since Linux 5.0, the .I cgroup_no_v1 kernel boot option (described below) can be used to disable cgroup v1 @@ -556,7 +556,7 @@ While (different) controllers may be simultaneously mounted under the v1 and v2 hierarchies, it is not possible to mount the same controller simultaneously under both the v1 and the v2 hierarchies. -.PP +.P The new behaviors in cgroups v2 are summarized here, and in some cases elaborated in the following subsections. .IP \[bu] 3 @@ -585,7 +585,7 @@ controller has been removed. An improved mechanism for notification of empty cgroups is provided by the .I cgroup.events file. -.PP +.P For more changes, see the .I Documentation/admin\-guide/cgroup\-v2.rst file in the kernel source @@ -593,7 +593,7 @@ file in the kernel source .I Documentation/cgroup\-v2.txt in Linux 4.17 and earlier). . -.PP +.P Some of the new behaviors listed above saw subsequent modification with the addition in Linux 4.14 of "thread mode" (described below). .\" @@ -609,13 +609,13 @@ all available controllers are mounted against a single hierarchy. The available controllers are automatically mounted, meaning that it is not necessary (or possible) to specify the controllers when mounting the cgroup v2 filesystem using a command such as the following: -.PP +.P .in +4n .EX mount \-t cgroup2 none /mnt/cgroup2 .EE .in -.PP +.P A cgroup v2 controller is available only if it is not currently in use via a mount against a cgroup v1 hierarchy. Or, to put things another way, it is not possible to employ @@ -638,7 +638,7 @@ to disable all v1 controllers. (This situation is correctly handled by .BR systemd (1), which falls back to operating without the specified controllers.) -.PP +.P Note that on many modern systems, .BR systemd (1) automatically mounts the @@ -726,7 +726,7 @@ controller. This is the same as the version 1 .I rdma controller. -.PP +.P There is no direct equivalent of the .I net_cls and @@ -736,7 +736,7 @@ Instead, support has been added to .BR iptables (8) to allow eBPF filters that hook on cgroup v2 pathnames to make decisions about network traffic on a per-cgroup basis. -.PP +.P The v2 .I devices controller provides no interface files; @@ -782,14 +782,14 @@ leads to an error when writing to the .I cgroup.subtree_control file. -.PP +.P Because the list of controllers in .I cgroup.subtree_control is a subset of those .IR cgroup.controllers , a controller that has been disabled in one cgroup in the hierarchy can never be re-enabled in the subtree below that cgroup. -.PP +.P A cgroup's .I cgroup.subtree_control file determines the set of controllers that are exercised in the @@ -805,14 +805,14 @@ then the corresponding controller-interface files (e.g., are automatically created in the children of that cgroup and can be used to exert resource control in the child cgroups. .\" -.SS Cgroups v2 """no internal processes""" rule +.SS Cgroups v2 \[dq]no internal processes\[dq] rule Cgroups v2 enforces a so-called "no internal processes" rule. Roughly speaking, this rule means that, with the exception of the root cgroup, processes may reside only in leaf nodes (cgroups that do not themselves contain child cgroups). This avoids the need to decide how to partition resources between processes which are members of cgroup A and processes in child cgroups of A. -.PP +.P For instance, if cgroup .I /cg1/cg2 exists, then a process may reside in @@ -836,7 +836,7 @@ the relationship between processes in and .IR /cg1 's other children. -.PP +.P The "no internal processes" rule is in fact more subtle than stated above. More precisely, the rule is that a (nonroot) cgroup can't both (1) have member processes, and @@ -849,7 +849,7 @@ possible for a cgroup to have both member processes and child cgroups, but before controllers can be enabled for that cgroup, the member processes must be moved out of the cgroup (e.g., perhaps into the child cgroups). -.PP +.P With the Linux 4.14 addition of "thread mode" (described below), the "no internal processes" rule has been relaxed in some cases. .\" @@ -859,7 +859,7 @@ Each nonroot cgroup in the v2 hierarchy contains a read-only file, whose contents are key-value pairs (delimited by newline characters, with the key and value separated by spaces) providing state information about the cgroup: -.PP +.P .in +4n .EX $ \fBcat mygrp/cgroup.events\fP @@ -867,7 +867,7 @@ populated 1 frozen 0 .EE .in -.PP +.P The following keys may appear in this file: .TP .I populated @@ -879,7 +879,7 @@ or otherwise 0. .\" commit 76f969e8948d82e78e1bc4beb6b9465908e7487 The value of this key is 1 if this cgroup is currently frozen, or 0 if it is not. -.PP +.P The .I cgroup.events file can be monitored, in order to receive notification when the value of @@ -915,7 +915,7 @@ meaning that the cgroup (and its descendants) contain no (nonzombie) member processes, or 1, meaning that the cgroup (or one of its descendants) contains member processes. -.PP +.P The cgroups v2 release-notification mechanism offers the following advantages over the cgroups v1 .I release_agent @@ -974,10 +974,10 @@ fails with the error .BR EAGAIN ). .IP Writing the string -.I """max""" +.I \[dq]max\[dq] to this file means that no limit is imposed. The default value in this file is -.I """max""" . +.IR \[dq]max\[dq] . .TP .IR cgroup.max.descendants " (since Linux 4.14)" .\" commit 1a926e0bbab83bae8207d05a533173425e0496d1 @@ -989,10 +989,10 @@ fails with the error .BR EAGAIN ). .IP Writing the string -.I """max""" +.I \[dq]max\[dq] to this file means that no limit is imposed. The default value in this file is -.IR """max""" . +.IR \[dq]max\[dq] . .\" .SH CGROUPS DELEGATION: DELEGATING A HIERARCHY TO A LESS PRIVILEGED USER In the context of cgroups, @@ -1004,7 +1004,7 @@ in the cgroup hierarchy but with less strict containment rules than v2 Cgroups v2 supports delegation with containment by explicit design. The focus of the discussion in this section is on delegation in cgroups v2, with some differences for cgroups v1 noted along the way. -.PP +.P Some terminology is required in order to describe delegation. A .I delegater @@ -1015,7 +1015,7 @@ is a nonprivileged user who will be granted the permissions needed to manage some subhierarchy under that parent cgroup, known as the .IR "delegated subtree" . -.PP +.P To perform delegation, the delegater makes certain directories and files writable by the delegatee, typically by changing the ownership of the objects to be the user ID @@ -1056,7 +1056,7 @@ file.) In cgroups v1, the corresponding file that should instead be delegated is the .I tasks file. -.PP +.P The delegater should .I not change the ownership of any of the controller interfaces files (e.g., @@ -1068,11 +1068,11 @@ Those files are used from the next level above the delegated subtree in order to distribute resources into the subtree, and the delegatee should not have permission to change the resources that are distributed into the delegated subtree. -.PP +.P See also the discussion of the .I /sys/kernel/cgroup/delegate file in NOTES for information about further delegatable files in cgroups v2. -.PP +.P After the aforementioned steps have been performed, the delegatee can create child cgroups within the delegated subtree (the cgroup subdirectories and the files they contain @@ -1095,7 +1095,7 @@ For example, if the cgroup v2 filesystem has already been mounted, we can remount it with the .I nsdelegate option as follows: -.PP +.P .in +4n .EX mount \-t cgroup2 \-o remount,nsdelegate \e @@ -1109,7 +1109,7 @@ mount \-t cgroup2 \-o remount,nsdelegate \e .\" .\" The effect of the latter option is to prevent systemd from employing .\" its "hybrid" cgroup mode, where it tries to make use of cgroups v2. -.PP +.P The effect of this mount option is to cause cgroup namespaces to automatically become delegation boundaries. More specifically, @@ -1133,7 +1133,7 @@ Processes inside the cgroup namespace can still move processes between cgroups .I within the subhierarchy under the namespace root. -.PP +.P The ability to define cgroup namespaces as delegation boundaries makes cgroup namespaces more useful. To understand why, suppose that we already have one cgroup hierarchy @@ -1163,17 +1163,17 @@ a process inside the child cgroup should not be allowed to modify them.) A process inside the inferior hierarchy could move processes into and out of the inferior hierarchy if the cgroups in the superior hierarchy were somehow visible. -.PP +.P Employing the .I nsdelegate mount option prevents both of these possibilities. -.PP +.P The .I nsdelegate mount option only has an effect when performed in the initial mount namespace; in other mount namespaces, the option is silently ignored. -.PP +.P .IR Note : On some systems, .BR systemd (1) @@ -1182,13 +1182,13 @@ In order to experiment with the .I nsdelegate operation, it may be useful to boot the kernel with the following command-line options: -.PP +.P .in +4n .EX cgroup_no_v1=all systemd.legacy_systemd_cgroup_controller .EE .in -.PP +.P These options cause the kernel to boot with the cgroups v1 controllers disabled (meaning that the controllers are available in the v2 hierarchy), and tells @@ -1237,7 +1237,7 @@ this requirement also applied in cgroups v2 (This was a historical requirement inherited from cgroups v1 that was later deemed unnecessary, since the other rules suffice for containment in cgroups v2.) -.PP +.P .IR Note : one consequence of these delegation containment rules is that the unprivileged delegatee can't place the first process into @@ -1255,7 +1255,7 @@ all of the threads of a process must be in the same cgroup. .IR "No internal processes" : a cgroup can't both have member processes and exercise controllers on child cgroups. -.PP +.P Both of these restrictions were added because the lack of these restrictions had caused problems in cgroups v1. @@ -1267,7 +1267,7 @@ controller: since threads share an address space, it made no sense to split threads across different .I memory cgroups.) -.PP +.P Notwithstanding the initial design decision in cgroups v2, there were use cases for certain controllers, notably the .I cpu @@ -1276,7 +1276,7 @@ for which thread-level granularity of control was meaningful and useful. To accommodate such use cases, Linux 4.14 added .I "thread mode" for cgroups v2. -.PP +.P Thread mode allows the following: .IP \[bu] 3 The creation of @@ -1293,7 +1293,7 @@ A relaxation of the "no internal processes rule", so that, within a threaded subtree, a cgroup can both contain member threads and exercise resource control over child cgroups. -.PP +.P With the addition of thread mode, each nonroot cgroup now contains a new file, .IR cgroup.type , @@ -1327,7 +1327,7 @@ The only thing that can be done with this cgroup (other than deleting it) is to convert it to a .I threaded cgroup by writing the string -.I """threaded""" +.I \[dq]threaded\[dq] to the .I cgroup.type file. @@ -1369,7 +1369,7 @@ There are two pathways that lead to the creation of a threaded subtree. The first pathway proceeds as follows: .IP (1) 5 We write the string -.I """threaded""" +.I \[dq]threaded\[dq] to the .I cgroup.type file of a cgroup @@ -1406,7 +1406,7 @@ will also have the type .RE .IP (2) We write the string -.I """threaded""" +.I \[dq]threaded\[dq] to each of the .I domain invalid cgroups under @@ -1418,10 +1418,10 @@ now have the type .I threaded and the threaded subtree is now fully usable. The requirement to write -.I """threaded""" +.I \[dq]threaded\[dq] to each of these cgroups is somewhat cumbersome, but allows for possible future extensions to the thread-mode model. -.PP +.P The second way of creating a threaded subtree is as follows: .IP (1) 5 In an existing cgroup, @@ -1441,7 +1441,7 @@ becomes .IR "domain threaded" . .IP \[bu] All of the descendant cgroups of -.I x +.I z that were not already of type .I threaded are converted to type @@ -1449,14 +1449,14 @@ are converted to type .RE .IP (2) As before, we make the threaded subtree usable by writing the string -.I """threaded""" +.I \[dq]threaded\[dq] to each of the .I domain invalid cgroups under -.IR y , +.IR z , in order to convert them to the type .IR threaded . -.PP +.P One of the consequences of the above pathways to creating a threaded subtree is that the threaded root cgroup can be a parent only to .I threaded @@ -1478,7 +1478,7 @@ in each subgroup whose type has been changed to .IR threaded ; upon doing so, the corresponding controller interface files appear in the children of that cgroup. -.PP +.P A process can be moved into a threaded subtree by writing its PID to the .I cgroup.procs file in one of the cgroups inside the tree. @@ -1492,7 +1492,7 @@ to the .I cgroup.threads files in different cgroups inside the subtree. The threads of a process must all reside in the same threaded subtree. -.PP +.P As with writing to .IR cgroup.procs , some containment rules apply when writing to the @@ -1517,7 +1517,7 @@ file in a different .I domain cgroup fails with the error .BR EOPNOTSUPP .) -.PP +.P The .I cgroup.threads file is present in each cgroup (including @@ -1526,7 +1526,7 @@ cgroups) and can be read in order to discover the set of threads that is present in the cgroup. The set of thread IDs obtained when reading this file is not guaranteed to be ordered or free of duplicates. -.PP +.P The .I cgroup.procs file in the threaded root shows the PIDs of all processes @@ -1534,7 +1534,7 @@ that are members of the threaded subtree. The .I cgroup.procs files in the other cgroups in the subtree are not readable. -.PP +.P Domain controllers can't be enabled in a threaded subtree; no controller-interface files appear inside the cgroups underneath the threaded root. @@ -1542,7 +1542,7 @@ From the point of view of a domain controller, threaded subtrees are invisible: a multithreaded process inside a threaded subtree appears to a domain controller as a process that resides in the threaded root cgroup. -.PP +.P Within a threaded subtree, the "no internal processes" rule does not apply: a cgroup can both contain member processes (or thread) and exercise controllers on child cgroups. @@ -1553,7 +1553,7 @@ A number of rules apply when writing to the file: .IP \[bu] 3 Only the string -.I """threaded""" +.I \[dq]threaded\[dq] may be written. In other words, the only explicit transition that is possible is to convert a .I domain @@ -1561,7 +1561,7 @@ cgroup to type .IR threaded . .IP \[bu] The effect of writing -.I """threaded""" +.I \[dq]threaded\[dq] depends on the current value in .IR cgroup.type , as follows: @@ -1590,7 +1590,7 @@ file if the parent's type is In other words, the cgroups of a threaded subtree must be converted to the .I threaded state in a top-down manner. -.PP +.P There are also some constraints that must be satisfied in order to create a threaded subtree rooted at the cgroup .IR x : @@ -1605,27 +1605,27 @@ No domain controllers may be enabled in .IR x 's .I cgroup.subtree_control file. -.PP +.P If any of the above constraints is violated, then an attempt to write -.I """threaded""" +.I \[dq]threaded\[dq] to a .I cgroup.type file fails with the error .BR ENOTSUP . .\" -.SS The """domain threaded""" cgroup type +.SS The \[dq]domain threaded\[dq] cgroup type According to the pathways described above, the type of a cgroup can change to .I domain threaded in either of the following cases: .IP \[bu] 3 The string -.I """threaded""" +.I \[dq]threaded\[dq] is written to a child cgroup. .IP \[bu] A threaded controller is enabled inside the cgroup and a process is made a member of the cgroup. -.PP +.P A .I domain threaded cgroup, @@ -1640,7 +1640,7 @@ are removed and either .I x no longer has threaded controllers enabled or no longer has member processes. -.PP +.P When a .I domain threaded cgroup @@ -1666,7 +1666,7 @@ and .I threaded cgroups. If the string -.I """threaded""" +.I \[dq]threaded\[dq] is written to the .I cgroup.type file of one of the children of the root cgroup, then @@ -1677,20 +1677,20 @@ The type of that cgroup becomes The type of any descendants of that cgroup that are not part of lower-level threaded subtrees changes to .IR "domain invalid" . -.PP +.P Note that in this case, there is no cgroup whose type becomes .IR "domain threaded" . (Notionally, the root cgroup can be considered as the threaded root for the cgroup whose type was changed to .IR threaded .) -.PP +.P The aim of this exceptional treatment for the root cgroup is to allow a threaded cgroup that employs the .I cpu controller to be placed as high as possible in the hierarchy, so as to minimize the (small) cost of traversing the cgroup hierarchy. .\" -.SS The cgroups v2 """cpu""" controller and realtime threads +.SS The cgroups v2 \[dq]cpu\[dq] controller and realtime threads As at Linux 4.19, the cgroups v2 .I cpu controller does not support control of realtime threads @@ -1708,12 +1708,12 @@ if all realtime threads are in the root cgroup. (If there are realtime threads in nonroot cgroups, then a .BR write (2) of the string -.I """+cpu""" +.I \[dq]+cpu\[dq] to the .I cgroup.subtree_control file fails with the error .BR EINVAL .) -.PP +.P On some systems, .BR systemd (1) places certain realtime threads in nonroot cgroups in the v2 hierarchy. @@ -1737,7 +1737,7 @@ A child process created via inherits its parent's cgroup memberships. A process's cgroup memberships are preserved across .BR execve (2). -.PP +.P The .BR clone3 (2) .B CLONE_INTO_CGROUP @@ -1909,6 +1909,6 @@ mount option. .BR namespaces (7), .BR sched (7), .BR user_namespaces (7) -.PP +.P The kernel source file .IR Documentation/admin\-guide/cgroup\-v2.rst . diff --git a/man7/charsets.7 b/man7/charsets.7 index 0692d8d..eb9f8f8 100644 --- a/man7/charsets.7 +++ b/man7/charsets.7 @@ -8,7 +8,7 @@ .\" .\" Changes also by David Starner . .\" -.TH charsets 7 2023-03-12 "Linux man-pages 6.05.01" +.TH charsets 7 2024-01-28 "Linux man-pages 6.7" .SH NAME charsets \- character set standards and internationalization .SH DESCRIPTION @@ -16,10 +16,10 @@ This manual page gives an overview on different character set standards and how they were used on Linux before Unicode became ubiquitous. Some of this information is still helpful for people working with legacy systems and documents. -.PP +.P Standards discussed include such as -ASCII, GB 2312, ISO 8859, JIS, KOI8-R, KS, and Unicode. -.PP +ASCII, GB 2312, ISO/IEC\~8859, JIS, KOI8-R, KS, and Unicode. +.P The primary emphasis is on character sets that were actually used by locale character sets, not the myriad others that could be found in data from other systems. @@ -27,9 +27,9 @@ from other systems. ASCII (American Standard Code For Information Interchange) is the original 7-bit character set, originally designed for American English. Also known as US-ASCII. -It is currently described by the ISO 646:1991 IRV +It is currently described by the ISO/IEC\~646:1991 IRV (International Reference Version) standard. -.PP +.P Various ASCII variants replacing the dollar sign with other currency symbols and replacing punctuation with non-English alphabetic characters to cover German, French, Spanish, and others in 7 bits @@ -37,30 +37,30 @@ emerged. All are deprecated; glibc does not support locales whose character sets are not true supersets of ASCII. -.PP +.P As Unicode, when using UTF-8, is ASCII-compatible, plain ASCII text still renders properly on modern UTF-8 using systems. -.SS ISO 8859 -ISO 8859 is a series of 15 8-bit character sets, all of which have ASCII +.SS ISO/IEC\~8859 +ISO/IEC\~8859 is a series of 15 8-bit character sets, all of which have ASCII in their low (7-bit) half, invisible control characters in positions 128 to 159, and 96 fixed-width graphics in positions 160\[en]255. -.PP -Of these, the most important is ISO 8859-1 +.P +Of these, the most important is ISO/IEC\~8859-1 ("Latin Alphabet No. 1" / Latin-1). It was widely adopted and supported by different systems, and is gradually being replaced with Unicode. -The ISO 8859-1 characters are also the first 256 characters of Unicode. -.PP -Console support for the other 8859 character sets is available under +The ISO/IEC\~8859-1 characters are also the first 256 characters of Unicode. +.P +Console support for the other ISO/IEC\~8859 character sets is available under Linux through user-mode utilities (such as .BR setfont (8)) that modify keyboard bindings and the EGA graphics table and employ the "user mapping" font table in the console driver. -.PP +.P Here are brief descriptions of each character set: .TP -8859-1 (Latin-1) +ISO/IEC\~8859-1 (Latin-1) Latin-1 covers many European languages such as Albanian, Basque, Danish, English, Faroese, Galician, Icelandic, Irish, Italian, Norwegian, Portuguese, Spanish, and Swedish. @@ -70,81 +70,81 @@ French œ, and „German“ quotation marks was considered tolerable. .TP -8859-2 (Latin-2) +ISO/IEC\~8859-2 (Latin-2) Latin-2 supports many Latin-written Central and East European languages such as Bosnian, Croatian, Czech, German, Hungarian, Polish, Slovak, and Slovene. Replacing Romanian ș/ț with ş/ţ was considered tolerable. .TP -8859-3 (Latin-3) +ISO/IEC\~8859-3 (Latin-3) Latin-3 was designed to cover of Esperanto, Maltese, and Turkish, but -8859-9 later superseded it for Turkish. +ISO/IEC\~8859-9 later superseded it for Turkish. .TP -8859-4 (Latin-4) +ISO/IEC\~8859-4 (Latin-4) Latin-4 introduced letters for North European languages such as -Estonian, Latvian, and Lithuanian, but was superseded by 8859-10 and -8859-13. +Estonian, Latvian, and Lithuanian, but was superseded by ISO/IEC\~8859-10 and +ISO/IEC\~8859-13. .TP -8859-5 +ISO/IEC\~8859-5 Cyrillic letters supporting Bulgarian, Byelorussian, Macedonian, Russian, Serbian, and (almost completely) Ukrainian. It was never widely used, see the discussion of KOI8-R/KOI8-U below. .TP -8859-6 +ISO/IEC\~8859-6 Was created for Arabic. -The 8859-6 glyph table is a fixed font of separate +The ISO/IEC\~8859-6 glyph table is a fixed font of separate letter forms, but a proper display engine should combine these using the proper initial, medial, and final forms. .TP -8859-7 +ISO/IEC\~8859-7 Was created for Modern Greek in 1987, updated in 2003. .TP -8859-8 +ISO/IEC\~8859-8 Supports Modern Hebrew without niqud (punctuation signs). Niqud and full-fledged Biblical Hebrew were outside the scope of this character set. .TP -8859-9 (Latin-5) +ISO/IEC\~8859-9 (Latin-5) This is a variant of Latin-1 that replaces Icelandic letters with Turkish ones. .TP -8859-10 (Latin-6) +ISO/IEC\~8859-10 (Latin-6) Latin-6 added the Inuit (Greenlandic) and Sami (Lappish) letters that were missing in Latin-4 to cover the entire Nordic area. .TP -8859-11 +ISO/IEC\~8859-11 Supports the Thai alphabet and is nearly identical to the TIS-620 standard. .TP -8859-12 +ISO/IEC\~8859-12 This character set does not exist. .TP -8859-13 (Latin-7) +ISO/IEC\~8859-13 (Latin-7) Supports the Baltic Rim languages; in particular, it includes Latvian characters not found in Latin-4. .TP -8859-14 (Latin-8) +ISO/IEC\~8859-14 (Latin-8) This is the Celtic character set, covering Old Irish, Manx, Gaelic, Welsh, Cornish, and Breton. .TP -8859-15 (Latin-9) +ISO/IEC\~8859-15 (Latin-9) Latin-9 is similar to the widely used Latin-1 but replaces some less common symbols with the Euro sign and French and Finnish letters that were missing in Latin-1. .TP -8859-16 (Latin-10) +ISO/IEC\~8859-16 (Latin-10) This character set covers many Southeast European languages, and most importantly supports Romanian more completely than Latin-2. .SS KOI8-R / KOI8-U KOI8-R is a non-ISO character set popular in Russia before Unicode. The lower half is ASCII; the upper is a Cyrillic character set somewhat better designed than -ISO 8859-5. +ISO/IEC\~8859-5. KOI8-U, based on KOI8-R, has better support for Ukrainian. -Neither of these sets are ISO-2022 compatible, -unlike the ISO 8859 series. -.PP +Neither of these sets are ISO/IEC\~2022 compatible, +unlike the ISO/IEC\~8859 series. +.P Console support for KOI8-R is available under Linux through user-mode utilities that modify keyboard bindings and the EGA graphics table, and employ the "user mapping" font table in the console driver. @@ -165,7 +165,7 @@ It is a superset of ASCII. Non-ASCII characters are expressed in two bytes. Bytes 0xa1\[en]0xfe are used as leading bytes for two-byte characters. Big5 and its extension were widely used in Taiwan and Hong Kong. -It is not ISO 2022 compliant. +It is not ISO/IEC\~2022 compliant. .\" Thanks to Tomohiro KUBOTA for the following sections about .\" national standards. .SS JIS X 0208 @@ -179,7 +179,7 @@ This means that JIS X 0208 itself is not used for expressing text data. JIS X 0208 is used as a component to construct encodings such as EUC-JP, Shift_JIS, -and ISO-2022-JP. +and ISO/IEC\~2022-JP. EUC-JP is the most important encoding for Linux and includes ASCII and JIS X 0208. In EUC-JP, JIS X 0208 @@ -190,19 +190,19 @@ KS X 1001 is a Korean national standard character set. Just as JIS X 0208, characters are mapped into a 94x94 two-byte matrix. KS X 1001 is used like JIS X 0208, as a component -to construct encodings such as EUC-KR, Johab, and ISO-2022-KR. +to construct encodings such as EUC-KR, Johab, and ISO/IEC\~2022-KR. EUC-KR is the most important encoding for Linux and includes ASCII and KS X 1001. KS C 5601 is an older name for KS X 1001. -.SS ISO 2022 and ISO 4873 -The ISO 2022 and 4873 standards describe a font-control model +.SS ISO/IEC\~2022 and ISO/IEC\~4873 +The ISO/IEC\~2022 and ISO/IEC\~4873 standards describe a font-control model based on VT100 practice. This model is (partially) supported by the Linux kernel and by .BR xterm (1). -Several ISO 2022-based character encodings have been defined, +Several ISO/IEC\~2022-based character encodings have been defined, especially for Japanese. -.PP +.P There are 4 graphic character sets, called G0, G1, G2, and G3, and one of them is the current character set for codes with high bit zero (initially G0), and one of them is the current @@ -212,7 +212,7 @@ essentially a 7-bit character set. It uses codes either 040\[en]0177 (041\[en]0176) or 0240\[en]0377 (0241\[en]0376). G0 always has size 94 and uses codes 041\[en]0176. -.PP +.P Switching between character sets is done using the shift functions \fB\[ha]N\fP (SO or LS1), \fB\[ha]O\fP (SI or LS0), ESC n (LS2), ESC o (LS3), ESC N (SS2), ESC O (SS3), ESC \[ti] (LS1R), ESC } (LS2R), ESC | (LS3R). @@ -223,32 +223,32 @@ for codes with high bit one. The function SS\fIn\fP makes character set G\fIn\fP (\fIn\fP=2 or 3) the current one for the next character only (regardless of the value of its high order bit). -.PP +.P A 94-character set is designated as G\fIn\fP character set by an escape sequence ESC ( xx (for G0), ESC ) xx (for G1), ESC * xx (for G2), ESC + xx (for G3), where xx is a symbol -or a pair of symbols found in the ISO 2375 International +or a pair of symbols found in the ISO/IEC\~2375 International Register of Coded Character Sets. -For example, ESC ( @ selects the ISO 646 character set as G0, +For example, ESC ( @ selects the ISO/IEC\~646 character set as G0, ESC ( A selects the UK standard character set (with pound instead of number sign), ESC ( B selects ASCII (with dollar instead of currency sign), ESC ( M selects a character set for African languages, ESC ( ! A selects the Cuban character set, and so on. -.PP +.P A 96-character set is designated as G\fIn\fP character set by an escape sequence ESC \- xx (for G1), ESC . xx (for G2) or ESC / xx (for G3). For example, ESC \- G selects the Hebrew alphabet as G1. -.PP +.P A multibyte character set is designated as G\fIn\fP character set by an escape sequence ESC $ xx or ESC $ ( xx (for G0), ESC $ ) xx (for G1), ESC $ * xx (for G2), ESC $ + xx (for G3). For example, ESC $ ( C selects the Korean character set for G0. The Japanese character set selected by ESC $ B has a more recent version selected by ESC & @ ESC $ B. -.PP -ISO 4873 stipulates a narrower use of character sets, where G0 +.P +ISO/IEC\~4873 stipulates a narrower use of character sets, where G0 is fixed (always ASCII), so that G1, G2, and G3 can be invoked only for codes with the high order bit set. In particular, \fB\[ha]N\fP and \fB\[ha]O\fP are not used anymore, ESC ( xx @@ -257,7 +257,7 @@ are equivalent to ESC \- xx, ESC . xx, ESC / xx, respectively. .SS TIS-620 TIS-620 is a Thai national standard character set and a superset of ASCII. -In the same fashion as the ISO 8859 series, Thai characters are mapped into +In the same fashion as the ISO/IEC\~8859 series, Thai characters are mapped into 0xa1\[en]0xfe. .SS Unicode Unicode (ISO/IEC 10646) is a standard which aims to unambiguously represent @@ -267,14 +267,14 @@ Since most computers don't include 20.1-bit integers, Unicode is usually encoded as 32-bit integers internally and either a series of 16-bit integers (UTF-16) (needing two 16-bit integers only when encoding certain rare characters) or a series of 8-bit bytes (UTF-8). -.PP +.P Linux represents Unicode using the 8-bit Unicode Transformation Format (UTF-8). UTF-8 is a variable length encoding of Unicode. It uses 1 byte to code 7 bits, 2 bytes for 11 bits, 3 bytes for 16 bits, 4 bytes for 21 bits, 5 bytes for 26 bits, 6 bytes for 31 bits. -.PP +.P Let 0,1,x stand for a zero, one, or arbitrary bit. A byte 0xxxxxxx stands for the Unicode 00000000 0xxxxxxx which codes the same symbol @@ -282,7 +282,7 @@ as the ASCII 0xxxxxxx. Thus, ASCII goes unchanged into UTF-8, and people using only ASCII do not notice any change: not in code, and not in file size. -.PP +.P A byte 110xxxxx is the start of a 2-byte code, and 110xxxxx 10yyyyyy is assembled into 00000xxx xxyyyyyy. A byte 1110xxxx is the start @@ -290,8 +290,8 @@ of a 3-byte code, and 1110xxxx 10yyyyyy 10zzzzzz is assembled into xxxxyyyy yyzzzzzz. (When UTF-8 is used to code the 31-bit ISO/IEC 10646 then this progression continues up to 6-byte codes.) -.PP -For most texts in ISO 8859 character sets, this means that the +.P +For most texts in ISO/IEC\~8859 character sets, this means that the characters outside of ASCII are now coded with two bytes. This tends to expand ordinary text files by only one or two percent. @@ -301,10 +301,10 @@ those languages is mostly outside of ASCII. For Japanese users this means that the 16-bit codes now in common use will take three bytes. While there are algorithmic conversions from some character sets -(especially ISO 8859-1) to Unicode, general conversion requires +(especially ISO/IEC\~8859-1) to Unicode, general conversion requires carrying around conversion tables, which can be quite large for 16-bit codes. -.PP +.P Note that UTF-8 is self-synchronizing: 10xxxxxx is a tail, any other byte is the head of a code. @@ -313,12 +313,12 @@ is as themselves. In particular, there are no embedded NULs (\[aq]\e0\[aq]) or \[aq]/\[aq]s that form part of some larger code. -.PP +.P Since ASCII, and, in particular, NUL and \[aq]/\[aq], are unchanged, the kernel does not notice that UTF-8 is being used. It does not care at all what the bytes it is handling stand for. -.PP +.P Rendering of Unicode data streams is typically handled through "subfont" tables which map a subset of Unicode to glyphs. Internally diff --git a/man7/complex.7 b/man7/complex.7 index 3685a8d..a61551e 100644 --- a/man7/complex.7 +++ b/man7/complex.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-1.0-or-later .\" -.TH complex 7 2023-07-18 "Linux man-pages 6.05.01" +.TH complex 7 2023-10-31 "Linux man-pages 6.7" .SH NAME complex \- basics of complex mathematics .SH LIBRARY @@ -15,7 +15,7 @@ Math library .SH DESCRIPTION Complex numbers are numbers of the form z = a+b*i, where a and b are real numbers and i = sqrt(\-1), so that i*i = \-1. -.PP +.P There are other ways to represent that number. The pair (a,b) of real numbers may be viewed as a point in the plane, given by X- and @@ -25,7 +25,7 @@ the pair of real numbers (r,phi), where r is the distance to the origin O, and phi the angle between the X-axis and the line Oz. Now z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)). -.PP +.P The basic operations are defined on z = a+b*i and w = c+d*i as: .TP .B addition: z+w = (a+c) + (b+d)*i @@ -33,13 +33,13 @@ The basic operations are defined on z = a+b*i and w = c+d*i as: .B multiplication: z*w = (a*c \- b*d) + (a*d + b*c)*i .TP .B division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c \- a*d)/(c*c + d*d))*i -.PP +.P Nearly all math function have a complex counterpart but there are some complex-only functions. .SH EXAMPLES Your C-compiler can work with complex numbers if it supports the C99 standard. The imaginary unit is represented by I. -.PP +.P .EX /* check that exp(i * pi) == \-1 */ #include /* for atan */ diff --git a/man7/cp1251.7 b/man7/cp1251.7 index 6dd88c2..6668ad7 100644 --- a/man7/cp1251.7 +++ b/man7/cp1251.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cp1251 7 2022-12-15 "Linux man-pages 6.05.01" +.TH cp1251 7 2024-01-28 "Linux man-pages 6.7" .SH NAME cp1251 \- CP\ 1251 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The Windows Code Pages include several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). +character set (also known as ISO/IEC\~646-IRV). CP\ 1251 encodes the characters used in Cyrillic scripts. .SS CP\ 1251 characters diff --git a/man7/cp1252.7 b/man7/cp1252.7 index 2522b1d..6630434 100644 --- a/man7/cp1252.7 +++ b/man7/cp1252.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH cp1252 7 2022-12-15 "Linux man-pages 6.05.01" +.TH cp1252 7 2024-01-28 "Linux man-pages 6.7" .SH NAME cp1252 \- CP\ 1252 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION The Windows Code Pages include several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). +character set (also known as ISO/IEC\~646-IRV). CP\ 1252 encodes the characters used in many West European languages. .SS CP\ 1252 characters diff --git a/man7/cpuset.7 b/man7/cpuset.7 index 800e4da..2db2bfc 100644 --- a/man7/cpuset.7 +++ b/man7/cpuset.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-only .\" -.TH cpuset 7 2023-07-18 "Linux man-pages 6.05.01" +.TH cpuset 7 2023-10-31 "Linux man-pages 6.7" .SH NAME cpuset \- confine processes to processor and memory node subsets .SH DESCRIPTION @@ -14,7 +14,7 @@ which is used to control the processor placement and memory placement of processes. It is commonly mounted at .IR /dev/cpuset . -.PP +.P On systems with kernels compiled with built in support for cpusets, all processes are attached to a cpuset, and cpusets are always present. If a system supports cpusets, then it will have the entry @@ -31,9 +31,9 @@ By default, if the cpuset configuration on a system is not modified or if the cpuset filesystem is not even mounted, then the cpuset mechanism, though present, has no effect on the system's behavior. -.PP +.P A cpuset defines a list of CPUs and memory nodes. -.PP +.P The CPUs of a system include all the logical processing units on which a process can execute, including, if present, multiple processor cores within a package and Hyper-Threads @@ -42,7 +42,7 @@ Memory nodes include all distinct banks of main memory; small and SMP systems typically have just one memory node that contains all the system's main memory, while NUMA (non-uniform memory access) systems have multiple memory nodes. -.PP +.P Cpusets are represented as directories in a hierarchical pseudo-filesystem, where the top directory in the hierarchy .RI ( /dev/cpuset ) @@ -52,7 +52,7 @@ another parent cpuset contains a subset of that parent's CPUs and memory nodes. The directories and files representing cpusets have normal filesystem permissions. -.PP +.P Every process in the system belongs to exactly one cpuset. A process is confined to run only on the CPUs in the cpuset it belongs to, and to allocate memory only @@ -63,7 +63,7 @@ the child process is placed in the same cpuset as its parent. With sufficient privilege, a process may be moved from one cpuset to another and the allowed CPUs and memory nodes of an existing cpuset may be changed. -.PP +.P When the system begins booting, a single cpuset is defined that includes all CPUs and memory nodes on the system, and all processes are in that cpuset. @@ -71,7 +71,7 @@ During the boot process, or later during normal system operation, other cpusets may be created, as subdirectories of this top cpuset, under the control of the system administrator, and processes may be placed in these other cpusets. -.PP +.P Cpusets are integrated with the .BR sched_setaffinity (2) scheduling affinity mechanism and the @@ -93,7 +93,7 @@ other calls returning an error, if for example, such a call ends up requesting an empty set of CPUs or memory nodes, after that request is restricted to the invoking process's cpuset. -.PP +.P Typically, a cpuset is used to manage the CPU and memory-node confinement for a set of cooperating processes such as a batch scheduler job, and these @@ -104,7 +104,7 @@ Each directory below .I /dev/cpuset represents a cpuset and contains a fixed set of pseudo-files describing the state of that cpuset. -.PP +.P New cpusets are created using the .BR mkdir (2) system call or the @@ -114,13 +114,13 @@ The properties of a cpuset, such as its flags, allowed CPUs and memory nodes, and attached processes, are queried and modified by reading or writing to the appropriate file in that cpuset's directory, as listed below. -.PP +.P The pseudo-files in each cpuset directory are automatically created when the cpuset is created, as a result of the .BR mkdir (2) invocation. It is not possible to directly add or remove these pseudo-files. -.PP +.P A cpuset directory that contains no child cpuset directories, and has no attached processes, can be removed using .BR rmdir (2) @@ -128,7 +128,7 @@ or .BR rmdir (1). It is not necessary, or possible, to remove the pseudo-files inside the directory before removing it. -.PP +.P The pseudo-files in each cpuset directory are small text files that may be read and written using traditional shell utilities such as @@ -142,7 +142,7 @@ such as .BR write (2), and .BR close (2). -.PP +.P The pseudo-files in a cpuset directory represent internal kernel state and do not have any persistent image on disk. Each of these per-cpuset files is listed and described below. @@ -338,7 +338,7 @@ the wider the range of CPUs over which immediate load balancing is attempted. See \fBScheduler Relax Domain Level\fR, below, for further details. .\" ================== proc cpuset ================== -.PP +.P In addition to the above pseudo-files in each directory below .IR /dev/cpuset , each process has a pseudo-file, @@ -346,7 +346,7 @@ each process has a pseudo-file, that displays the path of the process's cpuset directory relative to the root of the cpuset filesystem. .\" ================== proc status ================== -.PP +.P Also the .IR /proc/ pid /status file for each process has four added lines, @@ -357,7 +357,7 @@ displaying the process's (on which memory nodes it may obtain memory), in the two formats \fBMask Format\fR and \fBList Format\fR (see below) as shown in the following example: -.PP +.P .in +4n .EX Cpus_allowed: ffffffff,ffffffff,ffffffff,ffffffff @@ -366,7 +366,7 @@ Mems_allowed: ffffffff,ffffffff Mems_allowed_list: 0\-63 .EE .in -.PP +.P The "allowed" fields were added in Linux 2.6.24; the "allowed_list" fields were added in Linux 2.6.26. .\" ================== EXTENDED CAPABILITIES ================== @@ -385,7 +385,7 @@ or .IR mem_exclusive , no other cpuset, other than a direct ancestor or descendant, may share any of the same CPUs or memory nodes. -.PP +.P A cpuset that is .I mem_exclusive restricts kernel allocations for @@ -426,7 +426,7 @@ and other data commonly shared by the kernel across multiple users. All cpusets, whether .I hardwall or not, restrict allocations of memory for user space. -.PP +.P This enables configuring a system so that several independent jobs can share common kernel data, such as filesystem pages, while isolating each job's user allocation in its own cpuset. @@ -437,7 +437,7 @@ all the jobs, and construct child cpusets for each individual job which are not .I hardwall cpusets. -.PP +.P Only a small amount of kernel memory, such as requests from interrupt handlers, is allowed to be taken outside even a .I hardwall @@ -455,7 +455,7 @@ the kernel will run the command supplying the pathname (relative to the mount point of the cpuset filesystem) of the abandoned cpuset. This enables automatic removal of abandoned cpusets. -.PP +.P The default value of .I notify_on_release in the root cpuset at system boot is disabled (0). @@ -463,7 +463,7 @@ The default value of other cpusets at creation is the current value of their parent's .I notify_on_release setting. -.PP +.P The command .I /sbin/cpuset_release_agent is invoked, with the name @@ -471,18 +471,18 @@ is invoked, with the name relative path) of the to-be-released cpuset in .IR argv[1] . -.PP +.P The usual contents of the command .I /sbin/cpuset_release_agent is simply the shell script: -.PP +.P .in +4n .EX #!/bin/sh rmdir /dev/cpuset/$1 .EE .in -.PP +.P As with other flag values below, this flag can be changed by writing an ASCII number 0 or 1 (with optional trailing newline) @@ -494,30 +494,30 @@ The of a cpuset provides a simple per-cpuset running average of the rate that the processes in a cpuset are attempting to free up in-use memory on the nodes of the cpuset to satisfy additional memory requests. -.PP +.P This enables batch managers that are monitoring jobs running in dedicated cpusets to efficiently detect what level of memory pressure that job is causing. -.PP +.P This is useful both on tightly managed systems running a wide mix of submitted jobs, which may choose to terminate or reprioritize jobs that are trying to use more memory than allowed on the nodes assigned them, and with tightly coupled, long-running, massively parallel scientific computing jobs that will dramatically fail to meet required performance goals if they start to use more memory than allowed to them. -.PP +.P This mechanism provides a very economical way for the batch manager to monitor a cpuset for signs of memory pressure. It's up to the batch manager or other user code to decide what action to take if it detects signs of memory pressure. -.PP +.P Unless memory pressure calculation is enabled by setting the pseudo-file .IR /dev/cpuset/cpuset.memory_pressure_enabled , it is not computed for any cpuset, and reads from any .I memory_pressure always return zero, as represented by the ASCII string "0\en". See the \fBWARNINGS\fR section, below. -.PP +.P A per-cpuset, running average is employed for the following reasons: .IP \[bu] 3 Because this meter is per-cpuset rather than per-process or per virtual @@ -535,7 +535,7 @@ the batch scheduler can obtain the key information\[em]memory pressure in a cpuset\[em]with a single read, rather than having to query and accumulate results over all the (dynamically changing) set of processes in the cpuset. -.PP +.P The .I memory_pressure of a cpuset is calculated using a per-cpuset simple digital filter @@ -543,7 +543,7 @@ that is kept within the kernel. For each cpuset, this filter tracks the recent rate at which processes attached to that cpuset enter the kernel direct reclaim code. -.PP +.P The kernel direct reclaim code is entered whenever a process has to satisfy a memory page request by first finding some other page to repurpose, due to lack of any readily available already free pages. @@ -552,7 +552,7 @@ to disk. Unmodified filesystem buffer pages are repurposed by simply dropping them, though if that page is needed again, it will have to be reread from disk. -.PP +.P The .I cpuset.memory_pressure file provides an integer number representing the recent (half-life of @@ -568,14 +568,14 @@ They are called .I cpuset.memory_spread_page and .IR cpuset.memory_spread_slab . -.PP +.P If the per-cpuset Boolean flag file .I cpuset.memory_spread_page is set, then the kernel will spread the filesystem buffers (page cache) evenly over all the nodes that the faulting process is allowed to use, instead of preferring to put those pages on the node where the process is running. -.PP +.P If the per-cpuset Boolean flag file .I cpuset.memory_spread_slab is set, @@ -583,12 +583,12 @@ then the kernel will spread some filesystem-related slab caches, such as those for inodes and directory entries, evenly over all the nodes that the faulting process is allowed to use, instead of preferring to put those pages on the node where the process is running. -.PP +.P The setting of these flags does not affect the data segment (see .BR brk (2)) or stack segment pages of a process. -.PP +.P By default, both kinds of memory spreading are off and the kernel prefers to allocate memory pages on the node local to where the requesting process is running. @@ -596,10 +596,10 @@ If that node is not allowed by the process's NUMA memory policy or cpuset configuration or if there are insufficient free memory pages on that node, then the kernel looks for the nearest node that is allowed and has sufficient free memory. -.PP +.P When new cpusets are created, they inherit the memory spread settings of their parent. -.PP +.P Setting memory spreading causes allocations for the affected page or slab caches to ignore the process's NUMA memory policy and be spread instead. @@ -614,7 +614,7 @@ no cpuset-specified memory spreading is in effect, even if it is. If cpuset memory spreading is subsequently turned off, the NUMA memory policy most recently specified by these calls is automatically reapplied. -.PP +.P Both .I cpuset.memory_spread_page and @@ -623,10 +623,10 @@ are Boolean flag files. By default, they contain "0", meaning that the feature is off for that cpuset. If a "1" is written to that file, that turns the named feature on. -.PP +.P Cpuset-specified memory spreading behaves similarly to what is known (in other contexts) as round-robin or interleave memory placement. -.PP +.P Cpuset-specified memory spreading can provide substantial performance improvements for jobs that: .IP \[bu] 3 @@ -636,7 +636,7 @@ frequently access that data; but also .IP \[bu] need to access large filesystem data sets that must to be spread across the several nodes in the job's cpuset in order to fit. -.PP +.P Without this policy, the memory allocation across the nodes in the job's cpuset can become very uneven, @@ -652,19 +652,19 @@ was allocated, so long as it remains allocated, even if the cpuset's memory-placement policy .I mems subsequently changes. -.PP +.P When memory migration is enabled in a cpuset, if the .I mems setting of the cpuset is changed, then any memory page in use by any process in the cpuset that is on a memory node that is no longer allowed will be migrated to a memory node that is allowed. -.PP +.P Furthermore, if a process is moved into a cpuset with .I memory_migrate enabled, any memory pages it uses that were on memory nodes allowed in its previous cpuset, but which are not allowed in its new cpuset, will be migrated to a memory node allowed in the new cpuset. -.PP +.P The relative placement of a migrated page within the cpuset is preserved during these migration operations if possible. For example, @@ -679,7 +679,7 @@ the kernel will look for processes on other more overloaded CPUs and move those processes to the underutilized CPU, within the constraints of such placement mechanisms as cpusets and .BR sched_setaffinity (2). -.PP +.P The algorithmic cost of load balancing and its impact on key shared kernel data structures such as the process list increases more than linearly with the number of CPUs being balanced. @@ -692,17 +692,17 @@ and the cost of load balancing depends on implementation details of the kernel process scheduler, which is subject to change over time, as improved kernel scheduler algorithms are implemented.) -.PP +.P The per-cpuset flag .I sched_load_balance provides a mechanism to suppress this automatic scheduler load balancing in cases where it is not needed and suppressing it would have worthwhile performance benefits. -.PP +.P By default, load balancing is done across all CPUs, except those marked isolated using the kernel boot time "isolcpus=" argument. (See \fBScheduler Relax Domain Level\fR, below, to change this default.) -.PP +.P This default load balancing across all CPUs is not well suited to the following two situations: .IP \[bu] 3 @@ -713,7 +713,7 @@ on separate sets of CPUs, full load balancing is unnecessary. Systems supporting real-time on some CPUs need to minimize system overhead on those CPUs, including avoiding process load balancing if that is not needed. -.PP +.P When the per-cpuset flag .I sched_load_balance is enabled (the default setting), @@ -723,7 +723,7 @@ ensuring that load balancing can move a process (not otherwise pinned, as by .BR sched_setaffinity (2)) from any CPU in that cpuset to any other. -.PP +.P When the per-cpuset flag .I sched_load_balance is disabled, then the @@ -732,7 +732,7 @@ scheduler will avoid load balancing across the CPUs in that cpuset, has .I sched_load_balance enabled. -.PP +.P So, for example, if the top cpuset has the flag .I sched_load_balance enabled, then the scheduler will load balance across all @@ -740,12 +740,12 @@ CPUs, and the setting of the .I sched_load_balance flag in other cpusets has no effect, as we're already fully load balancing. -.PP +.P Therefore in the above two situations, the flag .I sched_load_balance should be disabled in the top cpuset, and only some of the smaller, child cpusets would have this flag enabled. -.PP +.P When doing this, you don't usually want to leave any unpinned processes in the top cpuset that might use nontrivial amounts of CPU, as such processes may be artificially constrained to some subset of CPUs, depending on @@ -753,7 +753,7 @@ the particulars of this flag setting in descendant cpusets. Even if such a process could use spare CPU cycles in some other CPUs, the kernel scheduler might not consider the possibility of load balancing that process to the underused CPU. -.PP +.P Of course, processes pinned to a particular CPU can be left in a cpuset that disables .I sched_load_balance @@ -780,7 +780,7 @@ In any case, of course, tasks will be scheduled to run only on CPUs allowed by their cpuset, as modified by .BR sched_setaffinity (2) system calls. -.PP +.P On small systems, such as those with just a few CPUs, immediate load balancing is useful to improve system interactivity and to minimize wasteful idle CPU cycles. @@ -788,7 +788,7 @@ But on large systems, attempting immediate load balancing across a large number of CPUs can be more costly than it is worth, depending on the particular performance characteristics of the job mix and the hardware. -.PP +.P The exact meaning of the small integer values of .I sched_relax_domain_level will depend on internal @@ -796,12 +796,12 @@ implementation details of the kernel scheduler code and on the non-uniform architecture of the hardware. Both of these will evolve over time and vary by system architecture and kernel version. -.PP +.P As of this writing, when this capability was introduced in Linux 2.6.26, on certain popular architectures, the positive values of .I sched_relax_domain_level have the following meanings. -.PP +.P .PD 0 .TP .B 1 @@ -823,7 +823,7 @@ Perform immediate load balancing across over several Perform immediate load balancing across over all CPUs in system [On NUMA systems]. .PD -.PP +.P The .I sched_relax_domain_level value of zero (0) always means @@ -831,7 +831,7 @@ don't perform immediate load balancing, hence that load balancing is done only periodically, not immediately when a CPU becomes available or another task becomes runnable. -.PP +.P The .I sched_relax_domain_level value of minus one (\-1) @@ -839,7 +839,7 @@ always means use the system default value. The system default value can vary by architecture and kernel version. This system default value can be changed by kernel boot-time "relax_domain_level=" argument. -.PP +.P In the case of multiple overlapping cpusets which have conflicting .I sched_relax_domain_level values, then the highest such value @@ -860,7 +860,7 @@ The \fBMask Format\fR is used to represent CPU and memory-node bit masks in the .IR /proc/ pid /status file. -.PP +.P This format displays each 32-bit word in hexadecimal (using ASCII characters "0" - "9" and "a" - "f"); words are filled with leading zeros, if required. @@ -868,12 +868,12 @@ For masks longer than one word, a comma separator is used between words. Words are displayed in big-endian order, which has the most significant bit first. The hex digits within a word are also in big-endian order. -.PP +.P The number of 32-bit words displayed is the minimum number needed to display all bits of the bit mask, based on the size of the bit mask. -.PP +.P Examples of the \fBMask Format\fR: -.PP +.P .in +4n .EX 00000001 # just bit 0 set @@ -883,15 +883,15 @@ Examples of the \fBMask Format\fR: 00000000,000e3862 # 1,5,6,11\-13,17\-19 set .EE .in -.PP +.P A mask with bits 0, 1, 2, 4, 8, 16, 32, and 64 set displays as: -.PP +.P .in +4n .EX 00000001,00000001,00010117 .EE .in -.PP +.P The first "1" is for bit 64, the second for bit 32, the third for bit 16, the fourth for bit 8, the fifth for bit 4, and the "7" is for bits 2, 1, and 0. @@ -903,9 +903,9 @@ and .I mems is a comma-separated list of CPU or memory-node numbers and ranges of numbers, in ASCII decimal. -.PP +.P Examples of the \fBList Format\fR: -.PP +.P .in +4n .EX 0\-4,9 # bits 0, 1, 2, 3, 4, and 9 set @@ -940,7 +940,7 @@ The permissions of a cpuset are determined by the permissions of the directories and pseudo-files in the cpuset filesystem, normally mounted at .IR /dev/cpuset . -.PP +.P For instance, a process can put itself in some other cpuset (than its current one) if it can write the .I tasks @@ -949,14 +949,14 @@ This requires execute permission on the encompassing directories and write permission on the .I tasks file. -.PP +.P An additional constraint is applied to requests to place some other process in a cpuset. One process may not attach another to a cpuset unless it would have permission to send that process a signal (see .BR kill (2)). -.PP +.P A process may create a child cpuset if it can access and write the parent cpuset directory. It can modify the CPUs or memory nodes @@ -967,7 +967,7 @@ corresponding or .I mems file. -.PP +.P There is one minor difference between the manner in which these permissions are evaluated and the manner in which normal filesystem operation permissions are evaluated. @@ -988,7 +988,7 @@ to its cpuset directory beneath which is a bit unusual) or if some user code converts the relative cpuset path to a full filesystem path. -.PP +.P In theory, this means that user code should specify cpusets using absolute pathnames, which requires knowing the mount point of the cpuset filesystem (usually, but not necessarily, @@ -1024,13 +1024,13 @@ command in some shells does not display an error message if the system call fails. .\" Gack! csh(1)'s echo does this For example, if the command: -.PP +.P .in +4n .EX echo 19 > cpuset.mems .EE .in -.PP +.P failed because memory node 19 was not allowed (perhaps the current system does not have a memory node 19), then the .B echo @@ -1041,7 +1041,7 @@ external command to change cpuset file settings, as this command will display .BR write (2) errors, as in the example: -.PP +.P .in +4n .EX /bin/echo 19 > cpuset.mems @@ -1053,7 +1053,7 @@ errors, as in the example: .SS Memory placement Not all allocations of system memory are constrained by cpusets, for the following reasons. -.PP +.P If hot-plug functionality is used to remove all the CPUs that are currently assigned to a cpuset, then the kernel will automatically update the @@ -1068,7 +1068,7 @@ rather than starving a process that has had all its allowed CPUs or memory nodes taken offline. User code should reconfigure cpusets to refer only to online CPUs and memory nodes when using hot-plug to add or remove such resources. -.PP +.P A few kernel-critical, internal memory-allocation requests, marked GFP_ATOMIC, must be satisfied immediately. The kernel may drop some @@ -1076,7 +1076,7 @@ request or malfunction if one of these allocations fail. If such a request cannot be satisfied within the current process's cpuset, then we relax the cpuset, and look for memory anywhere we can find it. It's better to violate the cpuset than stress the kernel. -.PP +.P Allocations of memory requested by kernel drivers while processing an interrupt lack any relevant process context, and are not confined by cpusets. @@ -1092,7 +1092,7 @@ a different directory is not permitted. The Linux kernel implementation of cpusets sets .I errno to specify the reason for a failed system call affecting cpusets. -.PP +.P The possible .I errno settings and their meaning when set on @@ -1359,7 +1359,7 @@ options using shell commands. .SS Creating and attaching to a cpuset. To create a new cpuset and attach the current command shell to it, the steps are: -.PP +.P .PD 0 .IP (1) 5 mkdir /dev/cpuset (if not already done) @@ -1373,11 +1373,11 @@ Assign CPUs and memory nodes to the new cpuset. .IP (5) Attach the shell to the new cpuset. .PD -.PP +.P For example, the following sequence of commands will set up a cpuset named "Charlie", containing just CPUs 2 and 3, and memory node 1, and then attach the current shell to that cpuset. -.PP +.P .in +4n .EX .RB "$" " mkdir /dev/cpuset" @@ -1399,7 +1399,7 @@ To migrate a job (the set of processes attached to a cpuset) to different CPUs and memory nodes in the system, including moving the memory pages currently allocated to that job, perform the following steps. -.PP +.P .PD 0 .IP (1) 5 Let's say we want to move the job in cpuset @@ -1424,9 +1424,9 @@ Then move each process from to .IR beta . .PD -.PP +.P The following sequence of commands accomplishes this. -.PP +.P .in +4n .EX .RB "$" " cd /dev/cpuset" @@ -1438,22 +1438,22 @@ The following sequence of commands accomplishes this. .RB "$" " while read i; do /bin/echo $i; done < ../alpha/tasks > tasks" .EE .in -.PP +.P The above should move any processes in .I alpha to .IR beta , and any memory held by these processes on memory nodes 2\[en]3 to memory nodes 8\[en]9, respectively. -.PP +.P Notice that the last step of the above sequence did not do: -.PP +.P .in +4n .EX .RB "$" " cp ../alpha/tasks tasks" .EE .in -.PP +.P The .I while loop, rather than the seemingly easier use of the @@ -1462,7 +1462,7 @@ command, was necessary because only one process PID at a time may be written to the .I tasks file. -.PP +.P The same effect (writing one PID at a time) as the .I while loop can be accomplished more efficiently, in fewer keystrokes and in @@ -1470,7 +1470,7 @@ syntax that works on any shell, but alas more obscurely, by using the .B \-u (unbuffered) option of .BR sed (1): -.PP +.P .in +4n .EX .RB "$" " sed \-un p < ../alpha/tasks > tasks" @@ -1493,7 +1493,7 @@ syntax that works on any shell, but alas more obscurely, by using the .BR sched (7), .BR migratepages (8), .BR numactl (8) -.PP +.P .I Documentation/admin\-guide/cgroup\-v1/cpusets.rst in the Linux kernel source tree .\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8 diff --git a/man7/credentials.7 b/man7/credentials.7 index 653e7a3..ddade68 100644 --- a/man7/credentials.7 +++ b/man7/credentials.7 @@ -4,7 +4,7 @@ .\" .\" 2007-06-13 Creation .\" -.TH credentials 7 2023-03-30 "Linux man-pages 6.05.01" +.TH credentials 7 2023-11-19 "Linux man-pages 6.7" .SH NAME credentials \- process identifiers .SH DESCRIPTION @@ -18,7 +18,7 @@ A PID is represented using the type .I pid_t (defined in .IR ). -.PP +.P PIDs are used in a range of system calls to identify the process affected by the call, for example: .BR kill (2), @@ -39,7 +39,7 @@ and .BR waitpid (2). .\" .BR waitid (2), .\" .BR wait4 (2), -.PP +.P A process's PID is preserved across an .BR execve (2). .SS Parent process ID (PPID) @@ -50,7 +50,7 @@ A process can obtain its PPID using .BR getppid (2). A PPID is represented using the type .IR pid_t . -.PP +.P A process's PPID is preserved across an .BR execve (2). .SS Process group ID and session ID @@ -61,13 +61,13 @@ A process can obtain its session ID using .BR getsid (2), and its process group ID using .BR getpgrp (2). -.PP +.P A child created by .BR fork (2) inherits its parent's session ID and process group ID. A process's session ID and process group ID are preserved across an .BR execve (2). -.PP +.P Sessions and process groups are abstractions devised to support shell job control. A process group (sometimes called a "job") is a collection of @@ -80,7 +80,7 @@ A process's group membership can be set using .BR setpgid (2). The process whose process ID is the same as its process group ID is the \fIprocess group leader\fP for that group. -.PP +.P A session is a collection of processes that share the same session ID. All of the members of a process group also have the same session ID (i.e., all of the members of a process group always belong to the @@ -92,7 +92,7 @@ which creates a new session whose session ID is the same as the PID of the process that called .BR setsid (2). The creator of the session is called the \fIsession leader\fP. -.PP +.P All of the processes in a session share a .IR "controlling terminal" . The controlling terminal is established when the session leader @@ -101,7 +101,7 @@ first opens a terminal (unless the flag is specified when calling .BR open (2)). A terminal may be the controlling terminal of at most one session. -.PP +.P At most one of the jobs in a session may be the .IR "foreground job" ; other jobs in the session are @@ -123,7 +123,7 @@ When terminal keys that generate a signal (such as the .I interrupt key, normally control-C) are pressed, the signal is sent to the processes in the foreground job. -.PP +.P Various system calls and library functions may operate on all members of a process group, including @@ -152,7 +152,7 @@ and .I gid_t (defined in .IR ). -.PP +.P On Linux, each process has the following user and group identifiers: .IP \[bu] 3 Real user ID and real group ID. @@ -228,7 +228,7 @@ of which a process may be a member. .\" As at 2.6.22-rc2, this file is still read-only. A process can obtain its set of supplementary group IDs using .BR getgroups (2). -.PP +.P A child process created by .BR fork (2) inherits copies of its parent's user and groups IDs. @@ -238,7 +238,7 @@ a process's real user and group ID and supplementary group IDs are preserved; the effective and saved set IDs may be changed, as described in .BR execve (2). -.PP +.P Aside from the purposes noted above, a process's user IDs are also employed in a number of other contexts: .IP \[bu] 3 @@ -267,33 +267,38 @@ that the process may create (see Subject to rules described in the relevant manual pages, a process can use the following APIs to modify its user and group IDs: .TP -.BR setuid "(2) (" setgid (2)) +.BR setuid (2)\~(\c +.BR setgid (2)) Modify the process's real (and possibly effective and saved-set) user (group) IDs. .TP -.BR seteuid "(2) (" setegid (2)) +.BR seteuid (2)\~(\c +.BR setegid (2)) Modify the process's effective user (group) ID. .TP -.BR setfsuid "(2) (" setfsgid (2)) +.BR setfsuid (2)\~(\c +.BR setfsgid (2)) Modify the process's filesystem user (group) ID. .TP -.BR setreuid "(2) (" setregid (2)) +.BR setreuid (2)\~(\c +.BR setregid (2)) Modify the process's real and effective (and possibly saved-set) user (group) IDs. .TP -.BR setresuid "(2) (" setresgid (2)) +.BR setresuid (2)\~(\c +.BR setresgid (2)) Modify the process's real, effective, and saved-set user (group) IDs. .TP .BR setgroups (2) Modify the process's supplementary group list. -.PP +.P Any changes to a process's effective user (group) ID are automatically carried over to the process's filesystem user (group) ID. Changes to a process's effective user or group ID can also affect the process "dumpable" attribute, as described in .BR prctl (2). -.PP +.P Changes to process user and group IDs can affect the capabilities of the process, as described in .BR capabilities (7). @@ -302,7 +307,7 @@ Process IDs, parent process IDs, process group IDs, and session IDs are specified in POSIX.1. The real, effective, and saved set user and groups IDs, and the supplementary group IDs, are specified in POSIX.1. -.PP +.P The filesystem user and group IDs are a Linux extension. .SH NOTES Various fields in the @@ -311,7 +316,7 @@ file show the process credentials described above. See .BR proc (5) for further information. -.PP +.P The POSIX threads specification requires that credentials are shared by all of the threads in a process. However, at the kernel level, Linux maintains separate user and group diff --git a/man7/ddp.7 b/man7/ddp.7 index 0b7eb15..2117aae 100644 --- a/man7/ddp.7 +++ b/man7/ddp.7 @@ -4,14 +4,14 @@ .\" .\" $Id: ddp.7,v 1.3 1999/05/13 11:33:22 freitag Exp $ .\" -.TH ddp 7 2023-05-26 "Linux man-pages 6.05.01" +.TH ddp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME ddp \- Linux AppleTalk protocol implementation .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .IB ddp_socket " = socket(AF_APPLETALK, SOCK_DGRAM, 0);" .IB raw_socket " = socket(AF_APPLETALK, SOCK_RAW, " protocol ");" .fi @@ -26,12 +26,12 @@ protocol libraries. This page documents the interface for those who wish or need to use the DDP layer directly. -.PP +.P The communication between AppleTalk and the user program works using a BSD-compatible socket interface. For more information on sockets, see .BR socket (7). -.PP +.P An AppleTalk socket is created by calling the .BR socket (2) function with a @@ -52,7 +52,7 @@ For .B SOCK_RAW you must specify .BR ATPROTO_DDP . -.PP +.P Raw sockets may be opened only by a process with effective user ID 0 or when the process has the .B CAP_NET_RAW @@ -60,7 +60,7 @@ capability. .SS Address format An AppleTalk socket address is defined as a combination of a network number, a node number, and a port number. -.PP +.P .in +4n .EX struct at_addr { @@ -75,7 +75,7 @@ struct sockaddr_atalk { }; .EE .in -.PP +.P .I sat_family is always set to .BR AF_APPLETALK . @@ -133,7 +133,7 @@ dead. .TP .I aarp\-tick\-time The timer rate (in seconds) for the timer driving AARP. -.PP +.P The default values match the specification and should never need to be changed. .SS Ioctls @@ -228,14 +228,14 @@ on BSD-derived systems. Many BSD systems fail to check .B SO_BROADCAST when sending broadcast frames; this can lead to compatibility problems. -.PP +.P The raw socket mode is unique to Linux and exists to support the alternative CAP package and AppleTalk monitoring tools more easily. .SH BUGS There are too many inconsistent error values. -.PP +.P The ioctls used to configure routing tables, devices, AARP tables, and other devices are not yet described. .SH SEE ALSO diff --git a/man7/environ.7 b/man7/environ.7 index 345b350..cb7a839 100644 --- a/man7/environ.7 +++ b/man7/environ.7 @@ -12,7 +12,7 @@ .\" Modified Wed Jan 24 06:37:24 2001 by Eric S. Raymond (esr@thyrsus.com) .\" Modified Thu Dec 13 23:53:27 2001 by Martin Schulze .\" -.TH environ 7 2023-02-05 "Linux man-pages 6.05.01" +.TH environ 7 2023-10-31 "Linux man-pages 6.7" .SH NAME environ \- user environment .SH SYNOPSIS @@ -32,7 +32,7 @@ When a child process is created via it inherits a .I copy of its parent's environment. -.PP +.P By convention, the strings in .I environ have the form "\fIname\fP\fB=\fP\fIvalue\fP". @@ -41,7 +41,7 @@ the character "\fB=\fP". The value can be anything that can be represented as a string. The name and the value may not contain an embedded null byte (\[aq]\e0\[aq]), since this is assumed to terminate the string. -.PP +.P Environment variables may be placed in the shell's environment by the .I export command in @@ -50,7 +50,7 @@ or by the .I setenv command if you use .BR csh (1). -.PP +.P The initial environment of the shell is populated in various ways, such as definitions from .I /etc/environment @@ -63,21 +63,21 @@ In addition, various shell initialization scripts, such as the system-wide script and per-user initializations script may include commands that add variables to the shell's environment; see the manual page of your preferred shell for details. -.PP +.P Bourne-style shells support the syntax -.PP +.P .in +4n .EX NAME=value command .EE .in -.PP +.P to create an environment variable definition only in the scope of the process that executes .IR command . Multiple variable definitions, separated by white space, may precede .IR command . -.PP +.P Arguments may also be placed in the environment at the point of an .BR exec (3). @@ -87,7 +87,7 @@ A C program can manipulate its environment using the functions .BR setenv (3), and .BR unsetenv (3). -.PP +.P What follows is a list of environment variables typically seen on a system. This list is incomplete and includes only common variables seen @@ -194,7 +194,7 @@ command shall be valid. .\" .B BROWSER .\" The user's preferred utility to browse URLs. Sequence of colon-separated .\" browser commands. See http://www.catb.org/\[ti]esr/BROWSER/ . -.PP +.P Note that the behavior of many programs and library routines is influenced by the presence or value of certain environment variables. Examples include the following: @@ -272,14 +272,14 @@ if the .B _GNU_SOURCE feature test macro is defined (see .BR feature_test_macros (7)). -.PP +.P The .BR prctl (2) .B PR_SET_MM_ENV_START and .B PR_SET_MM_ENV_END operations can be used to control the location of the process's environment. -.PP +.P The .BR HOME , .BR LOGNAME , @@ -305,7 +305,7 @@ Clearly there is a security risk here. Many a system command has been tricked into mischief by a user who specified unusual values for .BR IFS " or " LD_LIBRARY_PATH . -.PP +.P There is also the risk of name space pollution. Programs like .I make diff --git a/man7/epoll.7 b/man7/epoll.7 index 02a53e9..a93bc0b 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -4,7 +4,7 @@ .\" .\" Davide Libenzi .\" -.TH epoll 7 2023-05-03 "Linux man-pages 6.05.01" +.TH epoll 7 2023-10-31 "Linux man-pages 6.7" .SH NAME epoll \- I/O event notification facility .SH SYNOPSIS @@ -21,7 +21,7 @@ The .B epoll API can be used either as an edge-triggered or a level-triggered interface and scales well to large numbers of watched file descriptors. -.PP +.P The central concept of the .B epoll API is the @@ -45,7 +45,7 @@ The ready list is a subset of the file descriptors in the interest list. The ready list is dynamically populated by the kernel as a result of I/O activity on those file descriptors. -.PP +.P The following system calls are provided to create and manage an .B epoll @@ -104,7 +104,7 @@ The pipe reader reads 1\ kB of data from A call to .BR epoll_wait (2) is done. -.PP +.P If the .I rfd file descriptor has been added to the @@ -139,7 +139,7 @@ does not consume the whole buffer data, the call to done in step .B 5 might block indefinitely. -.PP +.P An application that employs the .B EPOLLET flag should use nonblocking file descriptors to avoid having a blocking @@ -158,7 +158,7 @@ or .BR write (2) return .BR EAGAIN . -.PP +.P By contrast, when used as a level-triggered interface (the default, when .B EPOLLET @@ -168,7 +168,7 @@ is simply a faster .BR poll (2), and can be used wherever the latter is used since it shares the same semantics. -.PP +.P Since even with edge-triggered .BR epoll , multiple events can be generated upon receipt of multiple chunks of data, @@ -185,7 +185,7 @@ it is the caller's responsibility to rearm the file descriptor using .BR epoll_ctl (2) with .BR EPOLL_CTL_MOD . -.PP +.P If multiple threads (or processes, if child processes have inherited the .B epoll @@ -214,7 +214,7 @@ it is necessary to use the .BR epoll_ctl (2) .B EPOLLWAKEUP flag. -.PP +.P When the .B EPOLLWAKEUP flag is set in the @@ -284,7 +284,7 @@ it will continue to or .BR write (2) from where it stopped before. -.PP +.P .in +4n .EX #define MAX_EVENTS 10 @@ -337,7 +337,7 @@ for (;;) { } .EE .in -.PP +.P When used as an edge-triggered interface, for performance reasons, it is possible to add the file descriptor inside the .B epoll @@ -595,7 +595,7 @@ directory. See .BR proc (5) for further details. -.PP +.P The .BR kcmp (2) .B KCMP_EPOLL_TFD diff --git a/man7/fanotify.7 b/man7/fanotify.7 index eea8835..b0b5121 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -2,7 +2,7 @@ .\" and Copyright (C) 2014, Michael Kerrisk .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft -.TH fanotify 7 2023-05-03 "Linux man-pages 6.05.01" +.TH fanotify 7 2023-10-31 "Linux man-pages 6.7" .SH NAME fanotify \- monitoring filesystem events .SH DESCRIPTION @@ -15,14 +15,14 @@ The support for those events was added in Linux 5.1. (See .BR inotify (7) for details of an API that did notify those events pre Linux 5.1.) -.PP +.P Additional capabilities compared to the .BR inotify (7) API include the ability to monitor all of the objects in a mounted filesystem, the ability to make access permission decisions, and the possibility to read or modify files before access by other applications. -.PP +.P The following system calls are used with this API: .BR fanotify_init (2), .BR fanotify_mark (2), @@ -35,11 +35,11 @@ The .BR fanotify_init (2) system call creates and initializes an fanotify notification group and returns a file descriptor referring to it. -.PP +.P An fanotify notification group is a kernel-internal object that holds a list of files, directories, filesystems, and mounts for which events shall be created. -.PP +.P For each entry in an fanotify notification group, two bit masks exist: the .I mark mask and the @@ -50,13 +50,13 @@ The ignore mask defines activities for which no event shall be generated. Having these two types of masks permits a filesystem, mount, or directory to be marked for receiving events, while at the same time ignoring events for specific objects under a mount or directory. -.PP +.P The .BR fanotify_mark (2) system call adds a file, directory, filesystem, or mount to a notification group and specifies which events shall be reported (or ignored), or removes or modifies such an entry. -.PP +.P A possible usage of the ignore mask is for a file cache. Events of interest for a file cache are modification of a file and closing of the same. @@ -69,7 +69,7 @@ is closed. Hence, the modify event can be added to the ignore mask. Upon receiving the close event, the modify event can be removed from the ignore mask and the file cache entry can be updated. -.PP +.P The entries in the fanotify notification groups refer to files and directories via their inode number and to mounts via their mount ID. If files or directories are renamed or moved within the same mount, @@ -85,7 +85,7 @@ or similar) from the fanotify file descriptor returned by .BR fanotify_init (2). -.PP +.P Two types of events are generated: .I notification events and @@ -98,7 +98,7 @@ Permission events are requests to the receiving application to decide whether permission for a file access shall be granted. For these events, the recipient must write a response which decides whether access is granted or not. -.PP +.P An event is removed from the event queue of the fanotify group when it has been read. Permission events that have been read are kept in an internal list of the @@ -117,11 +117,11 @@ is not specified in the call to until either a file event occurs or the call is interrupted by a signal (see .BR signal (7)). -.PP +.P After a successful .BR read (2), the read buffer contains one or more of the following structures: -.PP +.P .in +4n .EX struct fanotify_event_metadata { @@ -135,7 +135,7 @@ struct fanotify_event_metadata { }; .EE .in -.PP +.P Information records are supplemental pieces of information that may be provided alongside the generic @@ -193,7 +193,7 @@ It is imperative for event listeners to inspect the field of this structure in order to determine the type of information record that had been received for a given event. -.PP +.P In cases where an fanotify group identifies filesystem objects by file handles, event listeners should also expect to @@ -201,24 +201,24 @@ receive one or more of the below information record objects alongside the generic .I fanotify_event_metadata structure within the read buffer: -.PP +.P .in +4n .EX struct fanotify_event_info_fid { struct fanotify_event_info_header hdr; __kernel_fsid_t fsid; - unsigned char file_handle[0]; + unsigned char handle[]; }; .EE .in -.PP +.P In cases where an fanotify group is initialized with .BR FAN_REPORT_PIDFD , event listeners should expect to receive the below information record object alongside the generic .I fanotify_event_metadata structure within the read buffer: -.PP +.P .in +4n .EX struct fanotify_event_info_pidfd { @@ -227,7 +227,7 @@ struct fanotify_event_info_pidfd { }; .EE .in -.PP +.P In case of a .B FAN_FS_ERROR event, @@ -236,7 +236,7 @@ is returned alongside the generic .I fanotify_event_metadata structure within the read buffer. This structure is defined as follows: -.PP +.P .in +4n .EX struct fanotify_event_info_error { @@ -246,7 +246,7 @@ struct fanotify_event_info_error { }; .EE .in -.PP +.P All information records contain a nested structure of type .IR fanotify_event_info_header . This structure holds meta-information about the information record @@ -254,7 +254,7 @@ that may have been returned alongside the generic .I fanotify_event_metadata structure. This structure is defined as follows: -.PP +.P .in +4n .EX struct fanotify_event_info_header { @@ -264,17 +264,17 @@ struct fanotify_event_info_header { }; .EE .in -.PP +.P For performance reasons, it is recommended to use a large buffer size (for example, 4096 bytes), so that multiple events can be retrieved by a single .BR read (2). -.PP +.P The return value of .BR read (2) is the number of bytes placed in the buffer, or \-1 in case of an error (but see BUGS). -.PP +.P The fields of the .I fanotify_event_metadata structure are as follows: @@ -343,13 +343,13 @@ was set in .BR fanotify_init (2), this is the TID of the thread that caused the event. Otherwise, this the PID of the process that caused the event. -.PP +.P A program listening to fanotify events can compare this PID to the PID returned by .BR getpid (2), to determine whether the event is caused by the listener itself, or is due to a file access by another process. -.PP +.P The bit mask in .I mask indicates which events have occurred for a single filesystem object. @@ -359,7 +359,7 @@ In particular, consecutive events for the same filesystem object and originating from the same process may be merged into a single event, with the exception that two permission events are never merged into one queue entry. -.PP +.P The bits that may appear in .I mask are as follows: @@ -446,7 +446,7 @@ open the filesystem object for execution shall be granted. See NOTES in .BR fanotify_mark (2) for additional details. -.PP +.P To check for any close event, the following bit mask may be used: .TP .B FAN_CLOSE @@ -458,7 +458,7 @@ This is a synonym for: FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE .EE .in -.PP +.P To check for any move event, the following bit mask may be used: .TP .B FAN_MOVE @@ -470,7 +470,7 @@ This is a synonym for: FAN_MOVED_FROM | FAN_MOVED_TO .EE .in -.PP +.P The following bits may appear in .I mask only in conjunction with other event type bits: @@ -487,7 +487,7 @@ The .B FAN_ONDIR flag is reported in an event mask only if the fanotify group identifies filesystem objects by file handles. -.PP +.P Information records that are supplied alongside the generic .I fanotify_event_metadata structure will always contain a nested structure of type @@ -528,7 +528,7 @@ is not expected to be larger than .RI ( event_len \- .IR metadata_len ). -.PP +.P The fields of the .I fanotify_event_info_fid structure are as follows: @@ -576,8 +576,9 @@ and contains the same value as when calling .BR statfs (2). .TP -.I file_handle -This is a variable length structure of type struct file_handle. +.I handle +This field contains a variable-length structure of type +.IR "struct file_handle" . It is an opaque handle that corresponds to a specified object on a filesystem as returned by .BR name_to_handle_at (2). @@ -601,14 +602,14 @@ if the value of field is .BR FAN_EVENT_INFO_TYPE_FID , the -.I file_handle +.I handle identifies the object correlated to the event. If the value of .I info_type field is .BR FAN_EVENT_INFO_TYPE_DFID , the -.I file_handle +.I handle identifies the directory object correlated to the event or the parent directory of a non-directory object correlated to the event. If the value of @@ -616,13 +617,13 @@ If the value of field is .BR FAN_EVENT_INFO_TYPE_DFID_NAME , the -.I file_handle +.I handle identifies the same directory object that would be reported with .B FAN_EVENT_INFO_TYPE_DFID and the file handle is followed by a null terminated string that identifies the name of a directory entry in that directory, or '.' to identify the directory object itself. -.PP +.P The fields of the .I fanotify_event_info_pidfd structure are as follows: @@ -667,7 +668,7 @@ Once the event listener has dealt with an event and the pidfd is no longer required, the pidfd should be closed via .BR close (2). -.PP +.P The fields of the .I fanotify_event_info_error structure are as follows: @@ -686,7 +687,7 @@ Identifies the type of error that occurred. .I error_count This is a counter of the number of errors suppressed since the last error was read. -.PP +.P The following macros are provided to iterate over a buffer containing fanotify event metadata returned by a .BR read (2) @@ -719,7 +720,7 @@ has been skipped over (i.e., it subtracts .I meta\->event_len from .IR len ). -.PP +.P In addition, there is: .TP .B FAN_EVENT_METADATA_LEN @@ -739,7 +740,7 @@ For permission events, the application must .BR write (2) a structure of the following form to the fanotify file descriptor: -.PP +.P .in +4n .EX struct fanotify_response { @@ -748,7 +749,7 @@ struct fanotify_response { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I fd @@ -762,7 +763,7 @@ Its value must be either to allow the file operation or .B FAN_DENY to deny the file operation. -.PP +.P If access is denied, the requesting application call will receive an .B EPERM error. @@ -786,19 +787,19 @@ field of the existing .B FAN_FS_ERROR event record, but details about the errors are lost. -.PP +.P Errors reported by .B FAN_FS_ERROR are generic .I errno values, but not all kinds of error types are reported by all filesystems. -.PP +.P Errors not directly related to a file (i.e. super block corruption) are reported with an invalid -.IR file_handle . +.IR handle . For these errors, the -.I file_handle +.I handle will have the field .I handle_type set to @@ -823,7 +824,7 @@ of process See .BR proc (5) for details. -.PP +.P Since Linux 5.13, .\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b the following interfaces can be used to control the amount of @@ -889,7 +890,7 @@ was specified in the argument when calling .BR fanotify_init (2) and an event occurred for a monitored file that is currently being executed. -.PP +.P In addition to the usual errors for .BR write (2), the following errors can occur when writing to the fanotify file descriptor: @@ -924,19 +925,19 @@ Fanotify reports only events that a user-space program triggers through the filesystem API. As a result, it does not catch remote events that occur on network filesystems. -.PP +.P The fanotify API does not report file accesses and modifications that may occur because of .BR mmap (2), .BR msync (2), and .BR munmap (2). -.PP +.P Events for directories are created only if the directory itself is opened, read, and closed. Adding, removing, or changing children of a marked directory does not create events for the monitored directory itself. -.PP +.P Fanotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional marks must be created. @@ -951,7 +952,7 @@ Monitoring mounts offers the capability to monitor a whole directory tree in a race-free manner. Monitoring filesystems offers the capability to monitor changes made from any mount of a filesystem instance in a race-free manner. -.PP +.P The event queue can overflow. In this case, events are lost. .SH BUGS @@ -965,7 +966,7 @@ calls to generate .B FAN_MODIFY events. -.PP +.P As of Linux 3.17, the following bugs exist: .IP \[bu] 3 @@ -1010,7 +1011,7 @@ and When a permission event occurs, a .B FAN_ALLOW response is given. -.PP +.P The following shell session shows an example of running this program. This session involved editing the file @@ -1022,7 +1023,7 @@ After the file was closed, a .B FAN_CLOSE_WRITE event occurred. Execution of the program ends when the user presses the ENTER key. -.PP +.P .in +4n .EX # \fB./fanotify_example /home\fP @@ -1240,10 +1241,10 @@ The event mask indicates which type of filesystem object\[em]either a file or a directory\[em]was created. Once all events have been read from the buffer and processed accordingly, the program simply terminates. -.PP +.P The following shell sessions show two different invocations of this program, with different actions performed on a watched object. -.PP +.P The first session shows a mark being placed on .IR /home/user . This is followed by the creation of a regular file, @@ -1254,7 +1255,7 @@ event being generated and reported against the file's parent watched directory object and with the created file name. Program execution ends once all events captured within the buffer have been processed. -.PP +.P .in +4n .EX # \fB./fanotify_fid /home/user\fP @@ -1267,7 +1268,7 @@ All events processed successfully. Program exiting. $ \fBtouch /home/user/testfile.txt\fP # In another terminal .EE .in -.PP +.P The second session shows a mark being placed on .IR /home/user . This is followed by the creation of a directory, @@ -1277,7 +1278,7 @@ This specific action results in a event being generated and is reported with the .B FAN_ONDIR flag set and with the created directory name. -.PP +.P .in +4n .EX # \fB./fanotify_fid /home/user\fP diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 4e264d8..ee414dd 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -2,13 +2,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH feature_test_macros 7 2023-07-15 "Linux man-pages 6.05.01" +.TH feature_test_macros 7 2023-10-31 "Linux man-pages 6.7" .SH NAME feature_test_macros \- feature test macros .SH DESCRIPTION Feature test macros allow the programmer to control the definitions that are exposed by system header files when a program is compiled. -.PP +.P .B NOTE: In order to be effective, a feature test macro .IR "must be defined before including any header files" . @@ -25,7 +25,7 @@ macro may have no effect because the header itself includes .I (POSIX explicitly allows this): -.PP +.P .in +4n .EX #include @@ -33,12 +33,12 @@ itself includes #include .EE .in -.PP +.P Some feature test macros are useful for creating portable applications, by preventing nonstandard definitions from being exposed. Other macros can be used to expose nonstandard definitions that are not exposed by default. -.PP +.P The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I @@ -56,23 +56,23 @@ the manual page SYNOPSIS typically includes a note of the following form (this example from the .BR acct (2) manual page): -.PP +.P .RS .B #include -.PP +.P .BI "int acct(const char *" filename ); -.PP +.P .RS -4 .EX Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .EE .RE -.PP +.P .BR acct (): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) .RE -.PP +.P The .B || means that in order to obtain the declaration of @@ -82,44 +82,44 @@ from .I either of the following macro definitions must be made before including any header files: -.PP +.P .in +4n .EX #define _BSD_SOURCE #define _XOPEN_SOURCE /* or any value < 500 */ .EE .in -.PP +.P Alternatively, equivalent definitions can be included in the compilation command: -.PP +.P .in +4n .EX cc \-D_BSD_SOURCE cc \-D_XOPEN_SOURCE # Or any value < 500 .EE .in -.PP +.P Note that, as described below, .BR "some feature test macros are defined by default" , so that it may not always be necessary to explicitly specify the feature test macro(s) shown in the SYNOPSIS. -.PP +.P In a few cases, manual pages use a shorthand for expressing the feature test macro requirements (this example from .BR readahead (2)): -.PP +.P .RS +4 .EX .B #define _GNU_SOURCE .B #define _FILE_OFFSET_BITS 64 .B #include -.PP +.P .BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); .EE .RE -.PP +.P This format is employed when the feature test macros ensure that the proper function declarations are visible, and the macros are not defined by default. @@ -128,7 +128,7 @@ The paragraphs below explain how feature test macros are handled in glibc 2.\fIx\fP, .I x > 0. -.PP +.P First, though, a summary of a few details for the impatient: .IP \[bu] 3 The macros that you most likely need to use in modern source code are @@ -193,7 +193,7 @@ _XOPEN_SOURCE >= 700 .\" The details in glibc 2.0 are simpler, but combining a .\" a description of them with the details in later glibc versions .\" would make for a complicated description. -.PP +.P glibc understands the following feature test macros: .TP .B __STRICT_ANSI__ @@ -683,7 +683,7 @@ and (200112L before glibc 2.10; 199506L before glibc 2.4; 199309L before glibc 2.1). -.PP +.P If any of .BR __STRICT_ANSI__ , .BR _ISOC99_SOURCE , @@ -705,7 +705,7 @@ is explicitly defined, then and .B _DEFAULT_SOURCE are not defined by default. -.PP +.P If .B _POSIX_SOURCE and @@ -722,7 +722,7 @@ is defined with the value 1; and .IP \[bu] .B _POSIX_C_SOURCE is defined with one of the following values: -.RS 3 +.RS .IP \[bu] 3 2, if @@ -760,7 +760,7 @@ depends on the glibc version: 200112L, since glibc 2.4 to glibc 2.9; and 200809L, since glibc 2.10. .RE -.PP +.P Multiple macros can be defined; the results are additive. .SH STANDARDS POSIX.1 specifies @@ -768,11 +768,11 @@ POSIX.1 specifies .BR _POSIX_SOURCE , and .BR _XOPEN_SOURCE . -.PP +.P .B _FILE_OFFSET_BITS is not specified by any standard, but is employed on some other implementations. -.PP +.P .BR _BSD_SOURCE , .BR _SVID_SOURCE , .BR _DEFAULT_SOURCE , @@ -793,7 +793,7 @@ Other systems have an analogous file, but typically with a different name. This header file is automatically included by other header files as required: it is not necessary to explicitly include it in order to employ feature test macros. -.PP +.P According to which of the above feature test macros are defined, .I internally defines various other macros that are checked by @@ -811,7 +811,7 @@ feature test macros are set depending on the glibc version and what feature test macros are explicitly set. The following shell session, on a system with glibc 2.10, shows some examples of what we would see: -.PP +.P .in +4n .EX $ \fBcc ftm.c\fP @@ -929,9 +929,9 @@ main(int argc, char *argv[]) .BR libc (7), .BR standards (7), .BR system_data_types (7) -.PP +.P The section "Feature Test Macros" under .IR "info libc" . .\" But beware: the info libc document is out of date (Jul 07, mtk) -.PP +.P .I /usr/include/features.h diff --git a/man7/fifo.7 b/man7/fifo.7 index f27dcc7..6241a43 100644 --- a/man7/fifo.7 +++ b/man7/fifo.7 @@ -4,7 +4,7 @@ .\" .\" 990620 - page created - aeb@cwi.nl .\" -.TH fifo 7 2023-07-15 "Linux man-pages 6.05.01" +.TH fifo 7 2023-10-31 "Linux man-pages 6.7" .SH NAME fifo \- first-in first-out special file, named pipe .SH DESCRIPTION @@ -19,14 +19,14 @@ Thus, the FIFO special file has no contents on the filesystem; the filesystem entry merely serves as a reference point so that processes can access the pipe using a name in the filesystem. -.PP +.P The kernel maintains exactly one pipe object for each FIFO special file that is opened by at least one process. The FIFO must be opened on both ends (reading and writing) before data can be passed. Normally, opening the FIFO blocks until the other end is opened also. -.PP +.P A process can open a FIFO in nonblocking mode. In this case, opening for read-only succeeds even if no one has @@ -35,7 +35,7 @@ fails with .B ENXIO (no such device or address) unless the other end has already been opened. -.PP +.P Under Linux, opening a FIFO for read and write will succeed both in blocking and nonblocking mode. POSIX leaves this @@ -48,12 +48,12 @@ with itself should be very careful to avoid deadlocks. .SH NOTES For details of the semantics of I/O on FIFOs, see .BR pipe (7). -.PP +.P When a process tries to write to a FIFO that is not opened for read on the other side, the process is sent a .B SIGPIPE signal. -.PP +.P FIFO special files can be created by .BR mkfifo (3), and are indicated by diff --git a/man7/futex.7 b/man7/futex.7 index 233933b..52af91f 100644 --- a/man7/futex.7 +++ b/man7/futex.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: MIT .\" -.TH futex 7 2022-10-30 "Linux man-pages 6.05.01" +.TH futex 7 2023-10-31 "Linux man-pages 6.7" .SH NAME futex \- fast user-space locking .SH SYNOPSIS @@ -20,24 +20,24 @@ locking and semaphores. Futexes are very basic and lend themselves well for building higher-level locking abstractions such as mutexes, condition variables, read-write locks, barriers, and semaphores. -.PP +.P Most programmers will in fact not be using futexes directly but will instead rely on system libraries built on them, such as the Native POSIX Thread Library (NPTL) (see .BR pthreads (7)). -.PP +.P A futex is identified by a piece of memory which can be shared between processes or threads. In these different processes, the futex need not have identical addresses. In its bare form, a futex has semaphore semantics; it is a counter that can be incremented and decremented atomically; processes can wait for the value to become positive. -.PP +.P Futex operation occurs entirely in user space for the noncontended case. The kernel is involved only to arbitrate the contended case. As any sane design will strive for noncontention, futexes are also optimized for this situation. -.PP +.P In its bare form, a futex is an aligned integer which is touched only by atomic assembler instructions. This integer is four bytes long on all platforms. @@ -50,13 +50,13 @@ Any futex operation starts in user space, but it may be necessary to communicate with the kernel using the .BR futex (2) system call. -.PP +.P To "up" a futex, execute the proper assembler instructions that will cause the host CPU to atomically increment the integer. Afterward, check if it has in fact changed from 0 to 1, in which case there were no waiters and the operation is done. This is the noncontended case which is fast and should be common. -.PP +.P In the contended case, the atomic increment changed the counter from \-1 (or some other negative number). If this is detected, there are waiters. @@ -64,7 +64,7 @@ User space should now set the counter to 1 and instruct the kernel to wake up any waiters using the .B FUTEX_WAKE operation. -.PP +.P Waiting on a futex, to "down" it, is the reverse operation. Atomically decrement the counter and check if it changed to 0, in which case the operation is done and the futex was uncontended. @@ -73,7 +73,7 @@ and request that the kernel wait for another process to up the futex. This is done using the .B FUTEX_WAIT operation. -.PP +.P The .BR futex (2) system call can optionally be passed a timeout specifying how long @@ -95,12 +95,12 @@ abstraction for end users. Implementors are expected to be assembly literate and to have read the sources of the futex user-space library referenced below. -.PP +.P This man page illustrates the most common use of the .BR futex (2) primitives; it is by no means the only one. .\" .SH AUTHORS -.\" .PP +.\" .P .\" Futexes were designed and worked on by Hubertus Franke .\" (IBM Thomas J. Watson Research Center), .\" Matthew Kirkwood, Ingo Molnar (Red Hat) and @@ -113,7 +113,7 @@ primitives; it is by no means the only one. .BR set_robust_list (2), .BR set_tid_address (2), .BR pthreads (7) -.PP +.P .I Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux (proceedings of the Ottawa Linux Symposium 2002), futex example library, futex-*.tar.bz2 diff --git a/man7/glob.7 b/man7/glob.7 index 466701c..0130c80 100644 --- a/man7/glob.7 +++ b/man7/glob.7 @@ -4,7 +4,7 @@ .\" .\" 2003-08-24 fix for / by John Kristoff + joey .\" -.TH glob 7 2023-03-08 "Linux man-pages 6.05.01" +.TH glob 7 2023-10-31 "Linux man-pages 6.7" .SH NAME glob \- globbing pathnames .SH DESCRIPTION @@ -12,11 +12,11 @@ Long ago, in UNIX\ V6, there was a program .I /etc/glob that would expand wildcard patterns. Soon afterward this became a shell built-in. -.PP +.P These days there is also a library routine .BR glob (3) that will perform this function for a user program. -.PP +.P The rules are as follows (POSIX.2, 3.13). .SS Wildcard matching A string is a wildcard pattern if it contains one of the @@ -25,14 +25,14 @@ Globbing is the operation that expands a wildcard pattern into the list of pathnames matching the pattern. Matching is defined by: -.PP +.P A \[aq]?\[aq] (not between brackets) matches any single character. -.PP +.P A \[aq]*\[aq] (not between brackets) matches any string, including the empty string. -.PP +.P .B "Character classes" -.PP +.P An expression "\fI[...]\fP" where the first character after the leading \[aq][\[aq] is not an \[aq]!\[aq] matches a single character, namely any of the characters enclosed by the brackets. @@ -41,9 +41,9 @@ therefore \[aq]]\[aq] can be allowed between the brackets, provided that it is the first character. (Thus, "\fI[][!]\fP" matches the three characters \[aq][\[aq], \[aq]]\[aq], and \[aq]!\[aq].) -.PP +.P .B Ranges -.PP +.P There is one special convention: two characters separated by \[aq]\-\[aq] denote a range. (Thus, @@ -55,15 +55,15 @@ by making it the first or last character between the brackets. and "\fI[\-\-0]\fP" matches the three characters \[aq]\-\[aq], \[aq].\[aq], and \[aq]0\[aq], since \[aq]/\[aq] cannot be matched.) -.PP +.P .B Complementation -.PP +.P An expression "\fI[!...]\fP" matches a single character, namely any character that is not matched by the expression obtained by removing the first \[aq]!\[aq] from it. (Thus, "\fI[!]a\-]\fP" matches any single character except \[aq]]\[aq], \[aq]a\[aq], and \[aq]\-\[aq].) -.PP +.P One can remove the special meaning of \[aq]?\[aq], \[aq]*\[aq], and \[aq][\[aq] by preceding them by a backslash, or, @@ -79,7 +79,7 @@ A \[aq]/\[aq] in a pathname cannot be matched by a \[aq]?\[aq] or \[aq]*\[aq] wildcard, or by a range like "\fI[.\-0]\fP". A range containing an explicit \[aq]/\[aq] character is syntactically incorrect. (POSIX requires that syntactically incorrect patterns are left unchanged.) -.PP +.P If a filename starts with a \[aq].\[aq], this character must be matched explicitly. (Thus, \fIrm\ *\fP will not remove .profile, and \fItar\ c\ *\fP will not @@ -90,11 +90,11 @@ into the list of matching pathnames" was the original UNIX definition. It allowed one to have patterns that expand into an empty list, as in -.PP +.P .nf xv \-wait 0 *.gif *.jpg .fi -.PP +.P where perhaps no *.gif files are present (and this is not an error). However, POSIX requires that a wildcard pattern is left @@ -103,31 +103,31 @@ matching pathnames is empty. With .I bash one can force the classical behavior using this command: -.PP +.P .in +4n .EX shopt \-s nullglob .EE .in .\" In Bash v1, by setting allow_null_glob_expansion=true -.PP +.P (Similar problems occur elsewhere. For example, where old scripts have -.PP +.P .in +4n .EX rm \`find . \-name "*\[ti]"\` .EE .in -.PP +.P new scripts require -.PP +.P .in +4n .EX rm \-f nosuchfile \`find . \-name "*\[ti]"\` .EE .in -.PP +.P to avoid error messages from .I rm called with an empty argument list.) @@ -139,7 +139,7 @@ First of all, they match filenames, rather than text, and secondly, the conventions are not the same: for example, in a regular expression \[aq]*\[aq] means zero or more copies of the preceding thing. -.PP +.P Now that regular expressions have bracket expressions where the negation is indicated by a \[aq]\[ha]\[aq], POSIX has declared the effect of a wildcard pattern "\fI[\[ha]...]\fP" to be undefined. @@ -161,21 +161,21 @@ expression: namely (i) the negation, (ii) explicit single characters, and (iii) ranges. POSIX specifies ranges in an internationally more useful way and adds three more types: -.PP +.P (iii) Ranges X\-Y comprise all characters that fall between X and Y (inclusive) in the current collating sequence as defined by the .B LC_COLLATE category in the current locale. -.PP +.P (iv) Named character classes, like -.PP +.P .nf [:alnum:] [:alpha:] [:blank:] [:cntrl:] [:digit:] [:graph:] [:lower:] [:print:] [:punct:] [:space:] [:upper:] [:xdigit:] .fi -.PP +.P so that one can say "\fI[[:lower:]]\fP" instead of "\fI[a\-z]\fP", and have things work in Denmark, too, where there are three letters past \[aq]z\[aq] in the alphabet. @@ -183,13 +183,13 @@ These character classes are defined by the .B LC_CTYPE category in the current locale. -.PP +.P (v) Collating symbols, like "\fI[.ch.]\fP" or "\fI[.a-acute.]\fP", where the string between "\fI[.\fP" and "\fI.]\fP" is a collating element defined for the current locale. Note that this may be a multicharacter element. -.PP +.P (vi) Equivalence class expressions, like "\fI[=a=]\fP", where the string between "\fI[=\fP" and "\fI=]\fP" is any collating element from its equivalence class, as defined for the diff --git a/man7/hier.7 b/man7/hier.7 index 314d28a..497e0f5 100644 --- a/man7/hier.7 +++ b/man7/hier.7 @@ -8,7 +8,7 @@ .\" Modified Mon Feb 6 16:41:00 1999 by Nicolás Lichtmaier .\" Modified Tue Feb 8 16:46:45 2000 by Chris Pepper .\" Modified Fri Sep 7 20:32:45 2001 by Tammy Fox -.TH hier 7 2023-04-18 "Linux man-pages 6.05.01" +.TH hier 7 2023-10-31 "Linux man-pages 6.7" .SH NAME hier \- description of the filesystem hierarchy .SH DESCRIPTION @@ -650,5 +650,5 @@ different distributions and systems may be configured differently. .BR proc (5), .BR file\-hierarchy (7), .BR mount (8) -.PP +.P The Filesystem Hierarchy Standard diff --git a/man7/hostname.7 b/man7/hostname.7 index 60940ba..58d00d1 100644 --- a/man7/hostname.7 +++ b/man7/hostname.7 @@ -8,14 +8,14 @@ .\" .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and modified for Linux. .\" -.TH hostname 7 2022-10-30 "Linux man-pages 6.05.01" +.TH hostname 7 2023-11-11 "Linux man-pages 6.7" .SH NAME hostname \- hostname resolution description .SH DESCRIPTION Hostnames are domains, where a domain is a hierarchical, dot-separated list of subdomains; for example, the machine "monet", in the "example" subdomain of the "com" domain would be represented as "monet.example.com". -.PP +.P Each element of the hostname must be from 1 to 63 characters long and the entire hostname, including the dots, can be at most 253 characters long. Valid characters for hostnames are @@ -30,24 +30,24 @@ to .IR 9 , and the hyphen (\-). A hostname may not start with a hyphen. -.PP +.P Hostnames are often used with network client and server programs, which must generally translate the name to an address for use. (This task is generally performed by either .BR getaddrinfo (3) or the obsolete .BR gethostbyname (3).) -.PP +.P Hostnames are resolved by the NSS framework in glibc according to the .B hosts configuration in -.BR nsswitch.conf . +.BR nsswitch.conf (5). The DNS-based name resolver (in the .B dns NSS service module) resolves them in the following fashion. -.PP +.P If the name consists of a single component, that is, contains no dot, and if the environment variable .B HOSTALIASES @@ -60,11 +60,11 @@ to be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a line in the file, the substituted name is looked up with no further processing. -.PP +.P If the input name ends with a trailing dot, the trailing dot is removed, and the remaining name is looked up with no further processing. -.PP +.P If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is found. The default search list includes first the local domain, @@ -84,11 +84,11 @@ by a system-wide configuration file (see .BR resolver (5), .BR mailaddr (7), .BR named (8) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc1123.txt IETF RFC\ 1123 .UE -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc1178.txt IETF RFC\ 1178 .UE diff --git a/man7/icmp.7 b/man7/icmp.7 index cd54614..3969fe2 100644 --- a/man7/icmp.7 +++ b/man7/icmp.7 @@ -5,7 +5,7 @@ .\" .\" $Id: icmp.7,v 1.6 2000/08/14 08:03:45 ak Exp $ .\" -.TH icmp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH icmp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME icmp \- Linux IPv4 ICMP kernel module. .SH DESCRIPTION @@ -16,7 +16,7 @@ The user doesn't interact directly with this module; instead it communicates with the other protocols in the kernel and these pass the ICMP errors to the application layers. The kernel ICMP module also answers ICMP requests. -.PP +.P A user protocol may receive ICMP packets for all local sockets by opening a raw socket with the protocol .BR IPPROTO_ICMP . @@ -28,7 +28,7 @@ The types of ICMP packets passed to the socket can be filtered using the socket option. ICMP packets are always processed by the kernel too, even when passed to a user socket. -.PP +.P Linux limits the rate of ICMP error packets to each destination. .B ICMP_REDIRECT and @@ -143,7 +143,7 @@ H Address Mask Request I Address Mask Reply .TE .RE -.PP +.P The bits marked with an asterisk are rate limited by default (see the default mask above). .TP @@ -163,7 +163,7 @@ means no group is allowed to create ICMP Echo sockets. Support for the .B ICMP_ADDRESS request was removed in Linux 2.2. -.PP +.P Support for .B ICMP_SOURCE_QUENCH was removed in Linux 2.2. @@ -173,18 +173,18 @@ As many other implementations don't support raw sockets, this feature should not be relied on in portable programs. .\" not really true ATM -.\" .PP +.\" .P .\" Linux ICMP should be compliant to RFC 1122. -.PP +.P .B ICMP_REDIRECT packets are not sent when Linux is not acting as a router. They are also accepted only from the old gateway defined in the routing table and the redirect routes are expired after some time. -.PP +.P The 64-bit timestamp returned by .B ICMP_TIMESTAMP is in milliseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P Linux ICMP internally uses a raw socket to send ICMPs. This raw socket may appear in .BR netstat (8) @@ -192,5 +192,5 @@ output with a zero inode. .SH SEE ALSO .BR ip (7), .BR rdisc (8) -.PP +.P RFC\ 792 for a description of the ICMP protocol. diff --git a/man7/inode.7 b/man7/inode.7 index 3cbdeee..7054fe8 100644 --- a/man7/inode.7 +++ b/man7/inode.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inode 7 2023-07-30 "Linux man-pages 6.05.01" +.TH inode 7 2023-10-31 "Linux man-pages 6.7" .SH NAME inode \- file inode information .SH DESCRIPTION @@ -17,7 +17,7 @@ structure, or which returns a .I statx structure. -.PP +.P The following is a list of the information typically found in, or associated with, the file inode, with the names of the corresponding structure fields returned by @@ -56,7 +56,6 @@ Additional links to an existing file are created using .BR link (2). .TP User ID -.I st_uid \fIstat.st_uid\fP; \fIstatx.stx_uid\fP .IP This field records the user ID of the owner of the file. @@ -99,7 +98,7 @@ This field gives the "preferred" blocksize for efficient filesystem I/O. an inefficient read-modify-rewrite.) .TP Number of blocks allocated to the file -\fIstat.st_blocks\fP; \fIstatx.stx_size\fP +\fIstat.st_blocks\fP; \fIstatx.stx_blocks\fP .IP This field indicates the number of blocks allocated to the file, 512-byte units, @@ -185,12 +184,12 @@ Last status change timestamp (ctime) This is the file's last status change timestamp. It is changed by writing or by setting inode information (i.e., owner, group, link count, mode, etc.). -.PP +.P The timestamp fields report time measured with a zero point at the .IR Epoch , 1970-01-01 00:00:00 +0000, UTC (see .BR time (7)). -.PP +.P Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since Linux 2.6.23). .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 @@ -221,7 +220,7 @@ field (for the .I statx.stx_mode field) contains the file type and mode. -.PP +.P POSIX refers to the .I stat.st_mode bits corresponding to the mask @@ -232,7 +231,7 @@ the 12 bits corresponding to the mask 07777 as the .I file mode bits and the least significant 9 bits (0777) as the .IR "file permission bits" . -.PP +.P The following mask values are defined for the file type: .in +4n .TS @@ -248,9 +247,9 @@ S_IFCHR 0020000 character device S_IFIFO 0010000 FIFO .TE .in -.PP +.P Thus, to test for a regular file (for example), one could write: -.PP +.P .in +4n .EX stat(pathname, &sb); @@ -259,7 +258,7 @@ if ((sb.st_mode & S_IFMT) == S_IFREG) { } .EE .in -.PP +.P Because tests of the above form are common, additional macros are defined by POSIX to allow the test of the file type in .I st_mode @@ -287,9 +286,9 @@ symbolic link? (Not in POSIX.1-1996.) .BR S_ISSOCK (m) socket? (Not in POSIX.1-1996.) .RE -.PP +.P The preceding code snippet could thus be rewritten as: -.PP +.P .in +4n .EX stat(pathname, &sb); @@ -298,7 +297,7 @@ if (S_ISREG(sb.st_mode)) { } .EE .in -.PP +.P The definitions of most of the above file type test macros are provided if any of the following feature test macros is defined: .B _BSD_SOURCE @@ -315,7 +314,7 @@ and are provided if .B _XOPEN_SOURCE is defined. -.PP +.P The definition of .B S_IFSOCK can also be exposed either by defining @@ -324,7 +323,7 @@ with a value of 500 or greater or (since glibc 2.24) by defining both .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED . -.PP +.P The definition of .BR S_ISSOCK () is exposed if any of the following feature test macros is defined: @@ -339,7 +338,7 @@ with a value of 200112L or greater, or (since glibc 2.24) by defining both .B _XOPEN_SOURCE and .BR _XOPEN_SOURCE_EXTENDED . -.PP +.P The following mask values are defined for the file mode component of the .I st_mode @@ -397,7 +396,7 @@ others have execute permission T} .TE .in -.PP +.P The set-group-ID bit .RB ( S_ISGID ) has several special uses. @@ -414,7 +413,7 @@ For a file that does not have the group execution bit .RB ( S_IXGRP ) set, the set-group-ID bit indicates mandatory file/record locking. -.PP +.P The sticky bit .RB ( S_ISVTX ) on a directory means that a file @@ -425,7 +424,7 @@ process. POSIX.1-2008. .SH HISTORY POSIX.1-2001. -.PP +.P POSIX.1-1990 did not describe the .BR S_IFMT , .BR S_IFSOCK , @@ -441,7 +440,7 @@ constants, but instead specified the use of the macros .BR S_ISDIR () and so on. -.PP +.P The .BR S_ISLNK () and @@ -449,7 +448,7 @@ and macros were not in POSIX.1-1996; the former is from SVID 4, the latter from SUSv2. -.PP +.P UNIX\ V7 (and later systems) had .BR S_IREAD , .BR S_IWRITE , diff --git a/man7/inotify.7 b/man7/inotify.7 index 73a6ab0..51faaaa 100644 --- a/man7/inotify.7 +++ b/man7/inotify.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH inotify 7 2023-07-08 "Linux man-pages 6.05.01" +.TH inotify 7 2023-10-31 "Linux man-pages 6.7" .SH NAME inotify \- monitoring filesystem events .SH DESCRIPTION @@ -14,7 +14,7 @@ Inotify can be used to monitor individual files, or to monitor directories. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. -.PP +.P The following system calls are used with this API: .IP \[bu] 3 .BR inotify_init (2) @@ -56,7 +56,7 @@ instance have been closed (using the underlying object and its resources are freed for reuse by the kernel; all associated watches are automatically freed. -.PP +.P With careful programming, an application can use inotify to efficiently monitor and cache the state of a set of filesystem objects. @@ -78,11 +78,11 @@ in which case the call fails with the error .BR EINTR ; see .BR signal (7)). -.PP +.P Each successful .BR read (2) returns a buffer containing one or more of the following structures: -.PP +.P .in +4n .EX struct inotify_event { @@ -99,15 +99,15 @@ struct inotify_event { }; .EE .in -.PP +.P .I wd identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to .BR inotify_add_watch (2). -.PP +.P .I mask contains bits that describe the event that occurred (see below). -.PP +.P .I cookie is a unique integer that connects related events. Currently, this is used only for rename events, and @@ -119,7 +119,7 @@ events to be connected by the application. For all other event types, .I cookie is set to 0. -.PP +.P The .I name field is present only when an event is returned @@ -128,7 +128,7 @@ it identifies the filename within the watched directory. This filename is null-terminated, and may include further null bytes (\[aq]\e0\[aq]) to align subsequent reads to a suitable address boundary. -.PP +.P The .I len field counts all of the bytes in @@ -138,7 +138,7 @@ the length of each .I inotify_event structure is thus .IR "sizeof(struct inotify_event)+len" . -.PP +.P The behavior when the buffer given to .BR read (2) is too small to return information about the next event depends @@ -149,13 +149,13 @@ returns 0; since Linux 2.6.21, fails with the error .BR EINVAL . Specifying a buffer of size -.PP +.P .in +4n .EX sizeof(struct inotify_event) + NAME_MAX + 1 .EE .in -.PP +.P will be sufficient to read at least one event. .SS inotify events The @@ -252,12 +252,12 @@ when a file is renamed. .BR IN_OPEN " (*)" File or directory was opened. .RE -.PP +.P Inotify monitoring is inode-based: when monitoring a file (but not when monitoring the directory containing a file), an event can be generated for activity on any link to the file (in the same or a different directory). -.PP +.P When monitoring a directory: .IP \[bu] 3 the events marked above with an asterisk (*) can occur both @@ -265,19 +265,19 @@ for the directory itself and for objects inside the directory; and .IP \[bu] the events marked with a plus sign (+) occur only for objects inside the directory (not for the directory itself). -.PP +.P .IR Note : when monitoring a directory, events are not generated for the files inside the directory when the events are performed via a pathname (i.e., a link) that lies outside the monitored directory. -.PP +.P When events are generated for objects inside a watched directory, the .I name field in the returned .I inotify_event structure identifies the name of the file within the directory. -.PP +.P The .B IN_ALL_EVENTS macro is defined as a bit mask of all of the above events. @@ -285,7 +285,7 @@ This macro can be used as the .I mask argument when calling .BR inotify_add_watch (2). -.PP +.P Two additional convenience macros are defined: .RS 4 .TP @@ -297,7 +297,7 @@ Equates to Equates to .BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . .RE -.PP +.P The following further bits can be specified in .I mask when calling @@ -372,7 +372,7 @@ and multiple calls to .BR inotify_add_watch (2) without this flag may clobber existing watch masks. .RE -.PP +.P The following bits may be set in the .I mask field returned by @@ -449,7 +449,7 @@ events for both and .IR dir/myfile . .RE -.PP +.P Suppose an application is watching the directories .I dir1 and @@ -490,7 +490,7 @@ events will have the same .I cookie value. .RE -.PP +.P Suppose that .I dir1/xx and @@ -529,7 +529,7 @@ and an event for .IR dir1 . .RE -.PP +.P Suppose an application is watching the directory .I dir and (the empty) directory @@ -592,7 +592,7 @@ Inotify file descriptors can be monitored using and .BR epoll (7). When an event is available, the file descriptor indicates as readable. -.PP +.P Since Linux 2.6.25, signal-driven I/O notification is available for inotify file descriptors; see the discussion of @@ -621,7 +621,7 @@ and .B POLLIN is set in .IR si_band . -.PP +.P If successive output inotify events produced on the inotify file descriptor are identical (same .IR wd , @@ -634,13 +634,13 @@ older event has not yet been read (but see BUGS). This reduces the amount of kernel memory required for the event queue, but also means that an application can't use inotify to reliably count file events. -.PP +.P The events returned by reading from an inotify file descriptor form an ordered queue. Thus, for example, it is guaranteed that when renaming from one directory to another, events will be produced in the correct order on the inotify file descriptor. -.PP +.P The set of watch descriptors that is being monitored via an inotify file descriptor can be viewed via the entry for the inotify file descriptor in the process's @@ -661,7 +661,7 @@ In particular, there is no easy way for a process that is monitoring events via inotify to distinguish events that it triggers itself from those that are triggered by other processes. -.PP +.P Inotify reports only events that a user-space program triggers through the filesystem API. As a result, it does not catch remote events that occur @@ -674,28 +674,28 @@ Furthermore, various pseudo-filesystems such as and .I /dev/pts are not monitorable with inotify. -.PP +.P The inotify API does not report file accesses and modifications that may occur because of .BR mmap (2), .BR msync (2), and .BR munmap (2). -.PP +.P The inotify API identifies affected files by filename. However, by the time an application processes an inotify event, the filename may already have been deleted or renamed. -.PP +.P The inotify API identifies events via watch descriptors. It is the application's responsibility to cache a mapping (if one is needed) between watch descriptors and pathnames. Be aware that directory renamings may affect multiple cached pathnames. -.PP +.P Inotify monitoring of directories is not recursive: to monitor subdirectories under a directory, additional watches must be created. This can take a significant amount time for large directory trees. -.PP +.P If monitoring an entire directory subtree, and a new subdirectory is created in that tree or an existing directory is renamed into that tree, @@ -704,7 +704,7 @@ new files (and subdirectories) may already exist inside the subdirectory. Therefore, you may want to scan the contents of the subdirectory immediately after adding the watch (and, if desired, recursively add watches for any subdirectories that it contains). -.PP +.P Note that the event queue can overflow. In this case, events are lost. Robust applications should handle the possibility of @@ -716,7 +716,7 @@ approach is to close the inotify file descriptor, empty the cache, create a new inotify file descriptor, and then re-create watches and cache entries for the objects to be monitored.) -.PP +.P If a filesystem is mounted on top of a monitored directory, no event is generated, and no events are generated for objects immediately under the new mount point. @@ -733,7 +733,7 @@ event pair that is generated by .BR rename (2) can be matched up via their shared cookie value. However, the task of matching has some challenges. -.PP +.P These two events are usually consecutive in the event stream available when reading from the inotify file descriptor. However, this is not guaranteed. @@ -750,7 +750,7 @@ inserted into the queue: there may be a brief interval where the has appeared, but the .B IN_MOVED_TO has not. -.PP +.P Matching up the .B IN_MOVED_FROM and @@ -775,7 +775,7 @@ then those watch descriptors will be inconsistent with the watch descriptors in any pending events. (Re-creating the inotify file descriptor and rebuilding the cache may be useful to deal with this scenario.) -.PP +.P Applications should also allow for the possibility that the .B IN_MOVED_FROM event was the last event that could fit in the buffer @@ -803,7 +803,7 @@ calls to generate .B IN_MODIFY events. -.PP +.P .\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 .\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36 .\" @@ -811,7 +811,7 @@ Before Linux 2.6.16, the .B IN_ONESHOT .I mask flag does not work. -.PP +.P As originally designed and implemented, the .B IN_ONESHOT flag did not cause an @@ -821,7 +821,7 @@ However, as an unintended effect of other changes, since Linux 2.6.36, an .B IN_IGNORED event is generated in this case. -.PP +.P Before Linux 2.6.25, .\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 the kernel code that was intended to coalesce successive identical events @@ -830,7 +830,7 @@ if the older had not yet been read) instead checked if the most recent event could be coalesced with the .I oldest unread event. -.PP +.P When a watch descriptor is removed by calling .BR inotify_rm_watch (2) (or because a watch file is deleted or the filesystem @@ -868,7 +868,7 @@ and waits for events of type .BR IN_CLOSE_NOWRITE , and .BR IN_CLOSE_WRITE . -.PP +.P The following output was recorded while editing the file .I /home/user/temp/foo and listing directory @@ -1095,6 +1095,6 @@ main(int argc, char* argv[]) .BR read (2), .BR stat (2), .BR fanotify (7) -.PP +.P .I Documentation/filesystems/inotify.txt in the Linux kernel source tree diff --git a/man7/intro.7 b/man7/intro.7 index e12ff9d..98c8ed9 100644 --- a/man7/intro.7 +++ b/man7/intro.7 @@ -6,7 +6,7 @@ .\" .\" Modified by Thomas Koenig (ig25@rz.uni-karlsruhe.de) 24 Apr 1993 .\" Modified Sat Jul 24 17:28:08 1993 by Rik Faith (faith@cs.unc.edu) -.TH intro 7 2022-10-30 "Linux man-pages 6.05.01" +.TH intro 7 2022-10-30 "Linux man-pages 6.7" .SH NAME intro \- introduction to overview and miscellany section .SH DESCRIPTION diff --git a/man7/ip.7 b/man7/ip.7 index d96afc7..34e2ff8 100644 --- a/man7/ip.7 +++ b/man7/ip.7 @@ -35,7 +35,7 @@ .\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71 .\" Author: Erich E. Hoover .\" -.TH ip 7 2023-07-15 "Linux man-pages 6.05.01" +.TH ip 7 2024-03-17 "Linux man-pages 6.7" .SH NAME ip \- Linux IPv4 protocol implementation .SH SYNOPSIS @@ -45,7 +45,7 @@ ip \- Linux IPv4 protocol implementation .\" .B #include -- never include .B #include .B #include \fR/* superset of previous */ -.PP +.P .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");" @@ -56,20 +56,20 @@ described in RFC\ 791 and RFC\ 1122. .B ip contains a level 2 multicasting implementation conforming to RFC\ 1112. It also contains an IP router including a packet filter. -.PP +.P The programming interface is BSD-sockets compatible. For more information on sockets, see .BR socket (7). -.PP +.P An IP socket is created using .BR socket (2): -.PP +.P .in +4n .EX socket(AF_INET, socket_type, protocol); .EE .in -.PP +.P Valid socket types include .B SOCK_STREAM to open a stream socket, @@ -79,7 +79,7 @@ to open a datagram socket, and to open a .BR raw (7) socket to access the IP protocol directly. -.PP +.P .I protocol is the IP protocol in the IP header to be received or sent. Valid values for @@ -107,12 +107,12 @@ stream sockets; and for .BR udplite (7) datagram sockets. -.PP +.P For .B SOCK_RAW you may specify a valid IANA IP protocol defined in RFC\ 1700 assigned numbers. -.PP +.P When a process wants to receive new incoming packets or connections, it should bind a socket to a local interface address using .BR bind (2). @@ -134,7 +134,7 @@ is called on an unbound socket, the socket is automatically bound to a random free port or to a usable shared port with the local address set to .BR INADDR_ANY . -.PP +.P A TCP local socket address that has been bound is unavailable for some time after closing, unless the .B SO_REUSEADDR @@ -151,7 +151,7 @@ and On raw sockets .I sin_port is set to the IP protocol. -.PP +.P .in +4n .EX struct sockaddr_in { @@ -166,7 +166,7 @@ struct in_addr { }; .EE .in -.PP +.P .I sin_family is always set to .BR AF_INET . @@ -190,7 +190,7 @@ port, they are implemented only by higher protocols like .BR tcp (7) and .BR udp (7). -.PP +.P .I sin_addr is the IP host address. The @@ -212,7 +212,7 @@ or set using the .BR inet_makeaddr (3) library functions or directly with the name resolver (see .BR gethostbyname (3)). -.PP +.P IPv4 addresses are divided into unicast, broadcast, and multicast addresses. Unicast addresses specify a single interface of a host, @@ -224,7 +224,7 @@ socket flag is set. In the current implementation, connection-oriented sockets are allowed to use only unicast addresses. .\" Leave a loophole for XTP @) -.PP +.P Note that the address and the port are always stored in network byte order. In particular, this means that you need to call @@ -275,7 +275,7 @@ Since Linux 5.14, .\" commit 58fee5fc83658aaacf60246aeab738946a9ba516 it is treated as an ordinary unicast address and can be assigned to an interface. -.PP +.P Internet standards have traditionally also reserved various addresses for particular uses, though Linux no longer treats some of these specially. @@ -314,7 +314,7 @@ The socket option level for IP is .BR IPPROTO_IP . .\" or SOL_IP on Linux A boolean integer flag is zero when it is false, otherwise true. -.PP +.P When an invalid socket option is specified, .BR getsockopt (2) and @@ -607,7 +607,7 @@ IP_PMTUDISC_DONT:Never do Path MTU Discovery. IP_PMTUDISC_DO:Always do Path MTU Discovery. IP_PMTUDISC_PROBE:Set DF but ignore Path MTU. .TE -.sp 1 +.IP When PMTU discovery is enabled, the kernel automatically keeps track of the path MTU per destination host. When it is connected to a specific peer with @@ -828,6 +828,10 @@ is not zero, the primary local address of the interface specified by the index overwrites .I ipi_spec_dst for the routing table lookup. +.IP +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVERR " (since Linux 2.2)" .\" Precisely: since Linux 2.1.15 @@ -989,6 +993,9 @@ in which the kernel returns the original destination address of the datagram being received. The ancillary message contains a .IR "struct sockaddr_in" . +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVTOS " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -998,6 +1005,9 @@ ancillary message is passed with incoming packets. It contains a byte which specifies the Type of Service/Precedence field of the packet header. Expects a boolean integer flag. +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_RECVTTL " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -1015,6 +1025,9 @@ Identical to .BR IP_RECVOPTS , but returns raw unprocessed options with timestamp and route record options not filled in for this hop. +Not supported for +.B SOCK_STREAM +sockets. .TP .BR IP_ROUTER_ALERT " (since Linux 2.2)" .\" Precisely: since Linux 2.1.68 @@ -1287,7 +1300,9 @@ Time in seconds to keep an IPv6 fragment in memory. Regeneration interval (in seconds) of the hash secret (or lifetime for the hash secret) for IPv6 fragments. .TP -.IR ipfrag_high_thresh " (integer), " ipfrag_low_thresh " (integer)" +.IR ipfrag_high_thresh " (integer)" +.TQ +.IR ipfrag_low_thresh " (integer)" If the amount of queued IP fragments reaches .IR ipfrag_high_thresh , the queue is pruned down to @@ -1305,7 +1320,7 @@ All ioctls described in .BR socket (7) apply to .BR ip . -.PP +.P Ioctls to configure generic device parameters are described in .BR netdevice (7). .\" FIXME Add a discussion of multicasting @@ -1365,7 +1380,9 @@ was called on an already connected socket. .B EMSGSIZE Datagram is bigger than an MTU on the path and it cannot be fragmented. .TP -.BR ENOBUFS ", " ENOMEM +.B ENOBUFS +.TQ +.B ENOMEM Not enough free memory. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory, but this is not 100% consistent. @@ -1393,7 +1410,7 @@ The connection was unexpectedly closed or shut down by the other end. .TP .B ESOCKTNOSUPPORT The socket is not configured or an unknown socket type was requested. -.PP +.P Other errors may be generated by the overlaying protocols; see .BR tcp (7), .BR raw (7), @@ -1415,7 +1432,7 @@ and are Linux-specific. .\" IP_XFRM_POLICY is Linux-specific .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs -.PP +.P Be very careful with the .B SO_BROADCAST option \- it is not privileged in Linux. @@ -1428,7 +1445,7 @@ See RFC 6762 for an example of a protocol (mDNS) using the more modern multicast approach to communicating with an open-ended group of hosts on the local network. -.PP +.P Some other BSD sockets implementations provide .B IP_RCVDSTADDR and @@ -1438,7 +1455,7 @@ received datagrams. Linux has the more general .B IP_PKTINFO for the same task. -.PP +.P Some BSD sockets implementations also provide an .B IP_RECVTTL option, but an ancillary message with type @@ -1447,13 +1464,13 @@ is passed with the incoming packet. This is different from the .B IP_TTL option used in Linux. -.PP +.P Using the .B SOL_IP socket options level isn't portable; BSD-based stacks use the .B IPPROTO_IP level. -.PP +.P .B INADDR_ANY (0.0.0.0) and .B INADDR_BROADCAST @@ -1476,7 +1493,7 @@ address structure for generic link layer information instead of the old .BR sockaddr_pkt . .SH BUGS There are too many inconsistent error values. -.PP +.P The error used to diagnose exhaustion of the ephemeral port range differs across the various system calls .RB ( connect (2), @@ -1484,14 +1501,14 @@ across the various system calls .BR listen (2), .BR sendto (2)) that can assign ephemeral ports. -.PP +.P The ioctls to configure IP-specific interface options and ARP tables are not described. -.\" .PP +.\" .P .\" Some versions of glibc forget to declare .\" .IR in_pktinfo . .\" Workaround currently is to copy it into your program from this man page. -.PP +.P Receiving the original destination address with .B MSG_ERRQUEUE in @@ -1515,10 +1532,10 @@ does not work in some Linux 2.2 kernels. .BR tcp (7), .BR udp (7), .BR ip (8) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 791 for the original IP specification. RFC\ 1122 for the IPv4 host requirements. RFC\ 1812 for the IPv4 router requirements. diff --git a/man7/ipc_namespaces.7 b/man7/ipc_namespaces.7 index 0b13f07..fe17ae1 100644 --- a/man7/ipc_namespaces.7 +++ b/man7/ipc_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH ipc_namespaces 7 2023-02-05 "Linux man-pages 6.05.01" +.TH ipc_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME ipc_namespaces \- overview of Linux IPC namespaces .SH DESCRIPTION @@ -18,13 +18,13 @@ POSIX message queues (see The common characteristic of these IPC mechanisms is that IPC objects are identified by mechanisms other than filesystem pathnames. -.PP +.P Each IPC namespace has its own set of System V IPC identifiers and its own POSIX message queue filesystem. Objects created in an IPC namespace are visible to all other processes that are members of that namespace, but are not visible to processes in other IPC namespaces. -.PP +.P The following .I /proc interfaces are distinct in each IPC namespace: @@ -47,11 +47,11 @@ and .IP \[bu] The System V IPC interfaces in .IR /proc/sysvipc . -.PP +.P When an IPC namespace is destroyed (i.e., when the last process that is a member of the namespace terminates), all IPC objects in the namespace are automatically destroyed. -.PP +.P Use of IPC namespaces requires a kernel that is configured with the .B CONFIG_IPC_NS option. diff --git a/man7/ipv6.7 b/man7/ipv6.7 index e6f9d54..18acdc9 100644 --- a/man7/ipv6.7 +++ b/man7/ipv6.7 @@ -78,14 +78,14 @@ .\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f .\" Author: Erich E. Hoover .\" -.TH ipv6 7 2023-07-30 "Linux man-pages 6.05.01" +.TH ipv6 7 2023-10-31 "Linux man-pages 6.7" .SH NAME ipv6 \- Linux IPv6 protocol implementation .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" .IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" .IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" @@ -97,12 +97,12 @@ implemented by the Linux kernel and glibc 2.1. The interface is based on the BSD sockets interface; see .BR socket (7). -.PP +.P The IPv6 API aims to be mostly compatible with the IPv4 API (see .BR ip (7)). Only differences are described in this man page. -.PP +.P To bind an .B AF_INET6 socket to any process, the local address should be copied from the @@ -114,21 +114,21 @@ In static initializations, .B IN6ADDR_ANY_INIT may also be used, which expands to a constant expression. Both of them are in network byte order. -.PP +.P The IPv6 loopback address (::1) is available in the global .I in6addr_loopback variable. For initializations, .B IN6ADDR_LOOPBACK_INIT should be used. -.PP +.P IPv4 connections can be handled with the v6 API by using the v4-mapped-on-v6 address type; thus a program needs to support only this API type to support both protocols. This is handled transparently by the address handling functions in the C library. -.PP +.P IPv4 and IPv6 share the local port space. When you get an IPv4 connection or packet to an IPv6 socket, @@ -149,7 +149,7 @@ struct in6_addr { }; .EE .in -.PP +.P .I sin6_family is always set to .BR AF_INET6 ; @@ -169,19 +169,19 @@ Linux supports it only for link-local addresses, in that case .I sin6_scope_id contains the interface index (see .BR netdevice (7)) -.PP +.P IPv6 supports several address types: unicast to address a single host, multicast to address a group of hosts, anycast to address the nearest member of a group of hosts (not implemented in Linux), IPv4-on-IPv6 to address an IPv4 host, and other reserved address types. -.PP +.P The address notation for IPv6 is a group of 8 4-digit hexadecimal numbers, separated with a \[aq]:\[aq]. \&"::" stands for a string of 0 bits. Special addresses are ::1 for loopback and ::FFFF: for IPv4-mapped-on-IPv6. -.PP +.P The port space of IPv6 is shared with IPv4. .SS Socket options IPv6 supports some protocol-specific socket options that can be set with @@ -368,7 +368,7 @@ or into other structures may not be. This is not a problem for 32-bit hosts like i386. -.PP +.P The .I sin6_flowinfo field is new in Linux 2.4. @@ -386,7 +386,7 @@ Programs that assume that all address types can be stored safely in a need to be changed to use .I struct sockaddr_storage for that instead. -.PP +.P .BR SOL_IP , .BR SOL_IPV6 , .BR SOL_ICMPV6 , @@ -401,16 +401,16 @@ The IPv6 extended API as in RFC\ 2292 is currently only partly implemented; although the 2.2 kernel has near complete support for receiving options, the macros for generating IPv6 options are missing in glibc 2.1. -.PP +.P IPSec support for EH and AH headers is missing. -.PP +.P Flow label management is not complete and not documented here. -.PP +.P This man page is not complete. .SH SEE ALSO .BR cmsg (3), .BR ip (7) -.PP +.P RFC\ 2553: IPv6 BASIC API; Linux tries to be compliant to this. RFC\ 2460: IPv6 specification. diff --git a/man7/iso_8859-1.7 b/man7/iso_8859-1.7 index 7534a85..18e1bdc 100644 --- a/man7/iso_8859-1.7 +++ b/man7/iso_8859-1.7 @@ -5,37 +5,37 @@ .\" .\" Slightly rearranged, aeb, 950713 .\" Updated, dpo, 990531 -.TH ISO_8859-1 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-1 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-1 \- ISO 8859-1 character set encoded in octal, decimal, +iso_8859-1 \- ISO/IEC\~8859-1 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-1 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-1 encodes the characters used in many West European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-1 characters -The following table displays the characters in ISO 8859-1 that +.SS ISO/IEC\~8859-1 characters +The following table displays the characters in ISO/IEC\~8859-1 that are printable and unlisted in the .BR ascii (7) manual page. @@ -141,7 +141,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-1 is also known as Latin-1. +ISO/IEC\~8859-1 is also known as Latin-1. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-10.7 b/man7/iso_8859-10.7 index d43a00a..79ee5f3 100644 --- a/man7/iso_8859-10.7 +++ b/man7/iso_8859-10.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-10 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-10 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-10 \- ISO 8859-10 character set encoded in octal, decimal, +iso_8859-10 \- ISO/IEC\~8859-10 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-10 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-10 encodes the characters used in Nordic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-10 characters -The following table displays the characters in ISO 8859-10 that +.SS ISO/IEC\~8859-10 characters +The following table displays the characters in ISO/IEC\~8859-10 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ĸ LATIN SMALL LETTER KRA .TE .SH NOTES -ISO 8859-10 is also known as Latin-6. +ISO/IEC\~8859-10 is also known as Latin-6. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-11.7 b/man7/iso_8859-11.7 index e488606..f7dc9b4 100644 --- a/man7/iso_8859-11.7 +++ b/man7/iso_8859-11.7 @@ -5,37 +5,37 @@ .\" .\"Thanomsub Noppaburana made valuable suggestions. .\" -.TH ISO_8859-11 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-11 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-11 \- ISO 8859-11 character set encoded in octal, decimal, +iso_8859-11 \- ISO/IEC\~8859-11 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-11 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-11 encodes the characters used in the Thai language. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-11 characters -The following table displays the characters in ISO 8859-11 that +.SS ISO/IEC\~8859-11 characters +The following table displays the characters in ISO/IEC\~8859-11 that are printable and unlisted in the .BR ascii (7) manual page. @@ -133,9 +133,9 @@ _ 373 251 FB ๛ THAI CHARACTER KHOMUT .TE .SH NOTES -ISO 8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, +ISO/IEC\~8859-11 is the same as TIS (Thai Industrial Standard) 620-2253, commonly known as TIS-620, except for the character in position A0: -ISO 8859-11 defines this as NO-BREAK SPACE, +ISO/IEC\~8859-11 defines this as NO-BREAK SPACE, while TIS-620 leaves it undefined. .SH SEE ALSO .BR ascii (7), diff --git a/man7/iso_8859-13.7 b/man7/iso_8859-13.7 index 1158347..62561bf 100644 --- a/man7/iso_8859-13.7 +++ b/man7/iso_8859-13.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-13 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-13 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-13 \- ISO 8859-13 character set encoded in octal, decimal, +iso_8859-13 \- ISO/IEC\~8859-13 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-13 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-13 encodes the characters used in Baltic Rim languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-13 characters -The following table displays the characters in ISO 8859-13 that +.SS ISO/IEC\~8859-13 characters +The following table displays the characters in ISO/IEC\~8859-13 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ’ RIGHT SINGLE QUOTATION MARK .TE .SH NOTES -ISO 8859-13 is also known as Latin-7. +ISO/IEC\~8859-13 is also known as Latin-7. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-14.7 b/man7/iso_8859-14.7 index eedac82..6c1f6ee 100644 --- a/man7/iso_8859-14.7 +++ b/man7/iso_8859-14.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-14 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-14 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-14 \- ISO 8859-14 character set encoded in octal, decimal, +iso_8859-14 \- ISO/IEC\~8859-14 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-14 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-14 encodes the characters used in Celtic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-14 characters -The following table displays the characters in ISO 8859-14 that +.SS ISO/IEC\~8859-14 characters +The following table displays the characters in ISO/IEC\~8859-14 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-14 is also known as Latin-8. +ISO/IEC\~8859-14 is also known as Latin-8. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-15.7 b/man7/iso_8859-15.7 index 908bb9b..fb6d681 100644 --- a/man7/iso_8859-15.7 +++ b/man7/iso_8859-15.7 @@ -4,37 +4,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-15 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-15 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-15 \- ISO 8859-15 character set encoded in octal, decimal, +iso_8859-15 \- ISO/IEC\~8859-15 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-15 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-15 encodes the characters used in many West European languages and adds the Euro sign. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-15 characters -The following table displays the characters in ISO 8859-15 that +.SS ISO/IEC\~8859-15 characters +The following table displays the characters in ISO/IEC\~8859-15 that are printable and unlisted in the .BR ascii (7) manual page. @@ -140,7 +140,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-15 is also known as Latin-9 (or sometimes as Latin-0). +ISO/IEC\~8859-15 is also known as Latin-9 (or sometimes as Latin-0). .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-16.7 b/man7/iso_8859-16.7 index 697a3f9..9e3fdd3 100644 --- a/man7/iso_8859-16.7 +++ b/man7/iso_8859-16.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-16 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-16 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-16 \- ISO 8859-16 character set encoded in octal, decimal, +iso_8859-16 \- ISO/IEC\~8859-16 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-16 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-16 encodes the Latin characters used in Southeast European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-16 characters -The following table displays the characters in ISO 8859-16 that +.SS ISO/IEC\~8859-16 characters +The following table displays the characters in ISO/IEC\~8859-16 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-16 is also known as Latin-10. +ISO/IEC\~8859-16 is also known as Latin-10. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-2.7 b/man7/iso_8859-2.7 index 403e85e..225fbaa 100644 --- a/man7/iso_8859-2.7 +++ b/man7/iso_8859-2.7 @@ -6,37 +6,37 @@ .\" .\" Slightly rearranged, aeb, 950713 .\" Updated, dpo, 990531 -.TH ISO_8859-2 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-2 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-2 \- ISO 8859-2 character set encoded in octal, decimal, +iso_8859-2 \- ISO/IEC\~8859-2 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-2 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-2 encodes the Latin characters used in many Central and East European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-2 characters -The following table displays the characters in ISO 8859-2 that +.SS ISO/IEC\~8859-2 characters +The following table displays the characters in ISO/IEC\~8859-2 that are printable and unlisted in the .BR ascii (7) manual page. @@ -142,7 +142,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-2 is also known as Latin-2. +ISO/IEC\~8859-2 is also known as Latin-2. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-3.7 b/man7/iso_8859-3.7 index 8eb9a24..29c9e59 100644 --- a/man7/iso_8859-3.7 +++ b/man7/iso_8859-3.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-3 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-3 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-3 \- ISO 8859-3 character set encoded in octal, decimal, +iso_8859-3 \- ISO/IEC\~8859-3 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-3 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-3 encodes the characters used in certain Southeast European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-3 characters -The following table displays the characters in ISO 8859-3 that +.SS ISO/IEC\~8859-3 characters +The following table displays the characters in ISO/IEC\~8859-3 that are printable and unlisted in the .BR ascii (7) manual page. @@ -132,7 +132,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-3 is also known as Latin-3. +ISO/IEC\~8859-3 is also known as Latin-3. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-4.7 b/man7/iso_8859-4.7 index b209bf1..d772f62 100644 --- a/man7/iso_8859-4.7 +++ b/man7/iso_8859-4.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-4 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-4 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-4 \- ISO 8859-4 character set encoded in octal, decimal, +iso_8859-4 \- ISO/IEC\~8859-4 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-4 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-4 encodes the characters used in Scandinavian and Baltic languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-4 characters -The following table displays the characters in ISO 8859-4 that +.SS ISO/IEC\~8859-4 characters +The following table displays the characters in ISO/IEC\~8859-4 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ˙ DOT ABOVE .TE .SH NOTES -ISO 8859-4 is also known as Latin-4. +ISO/IEC\~8859-4 is also known as Latin-4. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-5.7 b/man7/iso_8859-5.7 index 1fbb266..6100a1d 100644 --- a/man7/iso_8859-5.7 +++ b/man7/iso_8859-5.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-5 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-5 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-5 \- ISO 8859-5 character set encoded in octal, decimal, +iso_8859-5 \- ISO/IEC\~8859-5 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-5 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-5 encodes the Cyrillic characters used in many East European languages. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-5 characters -The following table displays the characters in ISO 8859-5 that +.SS ISO/IEC\~8859-5 characters +The following table displays the characters in ISO/IEC\~8859-5 that are printable and unlisted in the .BR ascii (7) manual page. diff --git a/man7/iso_8859-6.7 b/man7/iso_8859-6.7 index b73e846..f1b4b5c 100644 --- a/man7/iso_8859-6.7 +++ b/man7/iso_8859-6.7 @@ -3,37 +3,39 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-6 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-6 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-6 \- ISO 8859-6 character set encoded in octal, decimal, +iso_8859-6 +\- +ISO/IEC\~8859-6 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-6 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-6 encodes the characters used in the Arabic language. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-6 characters -The following table displays the characters in ISO 8859-6 that +.SS ISO/IEC\~8859-6 characters +The following table displays the characters in ISO/IEC\~8859-6 that are printable and unlisted in the .BR ascii (7) manual page. @@ -94,7 +96,7 @@ _ 362 242 F2 ْ ARABIC SUKUN .TE .SH NOTES -ISO 8859-6 lacks the glyphs required for many related languages, +ISO/IEC\~8859-6 lacks the glyphs required for many related languages, such as Urdu and Persian (Farsi). .SH SEE ALSO .BR ascii (7), diff --git a/man7/iso_8859-7.7 b/man7/iso_8859-7.7 index a66a28e..242359c 100644 --- a/man7/iso_8859-7.7 +++ b/man7/iso_8859-7.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-7 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-7 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-7 \- ISO 8859-7 character set encoded in octal, decimal, +iso_8859-7 \- ISO/IEC\~8859-7 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-7 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-7 encodes the characters used in modern monotonic Greek. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-7 characters -The following table displays the characters in ISO 8859-7 that +.SS ISO/IEC\~8859-7 characters +The following table displays the characters in ISO/IEC\~8859-7 that are printable and unlisted in the .BR ascii (7) manual page. @@ -143,7 +143,7 @@ T} 376 254 FE ώ GREEK SMALL LETTER OMEGA WITH TONOS .TE .SH NOTES -ISO 8859-7 was formerly known as ELOT-928 or ECMA-118:1986. +ISO/IEC\~8859-7 was formerly known as ELOT-928 or ECMA-118:1986. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/iso_8859-8.7 b/man7/iso_8859-8.7 index d854116..9fcc066 100644 --- a/man7/iso_8859-8.7 +++ b/man7/iso_8859-8.7 @@ -5,37 +5,37 @@ .\" .\" Eli Zaretskii made valuable suggestions .\" -.TH ISO_8859-8 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-8 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-8 \- ISO 8859-8 character set encoded in octal, decimal, +iso_8859-8 \- ISO/IEC\~8859-8 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-8 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-8 encodes the characters used in Modern Hebrew. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-8 characters -The following table displays the characters in ISO 8859-8 that +.SS ISO/IEC\~8859-8 characters +The following table displays the characters in ISO/IEC\~8859-8 that are printable and unlisted in the .BR ascii (7) manual page. @@ -105,8 +105,8 @@ _ 376 254 FE †RIGHT-TO-LEFT MARK .TE .SH NOTES -ISO 8859-8 was also known as ISO-IR-138. -ISO 8859-8 includes neither short vowels nor diacritical marks, +ISO/IEC\~8859-8 was also known as ISO-IR-138. +ISO/IEC\~8859-8 includes neither short vowels nor diacritical marks, and Yiddish is not provided for. .SH SEE ALSO .BR ascii (7), diff --git a/man7/iso_8859-9.7 b/man7/iso_8859-9.7 index 6386144..4e630d7 100644 --- a/man7/iso_8859-9.7 +++ b/man7/iso_8859-9.7 @@ -3,37 +3,37 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH ISO_8859-9 7 2022-12-15 "Linux man-pages 6.05.01" +.TH ISO_8859-9 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -iso_8859-9 \- ISO 8859-9 character set encoded in octal, decimal, +iso_8859-9 \- ISO/IEC\~8859-9 character set encoded in octal, decimal, and hexadecimal .SH DESCRIPTION -The ISO 8859 standard includes several 8-bit extensions to the ASCII -character set (also known as ISO 646-IRV). -ISO 8859-9 encodes the +The ISO/IEC\~8859 standard includes several 8-bit extensions to the ASCII +character set (also known as ISO/IEC\~646-IRV). +ISO/IEC\~8859-9 encodes the characters used in Turkish. -.SS ISO 8859 alphabets -The full set of ISO 8859 alphabets includes: +.SS ISO/IEC\~8859 alphabets +The full set of ISO/IEC\~8859 alphabets includes: .TS l l. -ISO 8859-1 West European languages (Latin-1) -ISO 8859-2 Central and East European languages (Latin-2) -ISO 8859-3 Southeast European and miscellaneous languages (Latin-3) -ISO 8859-4 Scandinavian/Baltic languages (Latin-4) -ISO 8859-5 Latin/Cyrillic -ISO 8859-6 Latin/Arabic -ISO 8859-7 Latin/Greek -ISO 8859-8 Latin/Hebrew -ISO 8859-9 Latin-1 modification for Turkish (Latin-5) -ISO 8859-10 Lappish/Nordic/Eskimo languages (Latin-6) -ISO 8859-11 Latin/Thai -ISO 8859-13 Baltic Rim languages (Latin-7) -ISO 8859-14 Celtic (Latin-8) -ISO 8859-15 West European languages (Latin-9) -ISO 8859-16 Romanian (Latin-10) +ISO/IEC\~8859-1 West European languages (Latin-1) +ISO/IEC\~8859-2 Central and East European languages (Latin-2) +ISO/IEC\~8859-3 Southeast European and miscellaneous languages (Latin-3) +ISO/IEC\~8859-4 Scandinavian/Baltic languages (Latin-4) +ISO/IEC\~8859-5 Latin/Cyrillic +ISO/IEC\~8859-6 Latin/Arabic +ISO/IEC\~8859-7 Latin/Greek +ISO/IEC\~8859-8 Latin/Hebrew +ISO/IEC\~8859-9 Latin-1 modification for Turkish (Latin-5) +ISO/IEC\~8859-10 Lappish/Nordic/Eskimo languages (Latin-6) +ISO/IEC\~8859-11 Latin/Thai +ISO/IEC\~8859-13 Baltic Rim languages (Latin-7) +ISO/IEC\~8859-14 Celtic (Latin-8) +ISO/IEC\~8859-15 West European languages (Latin-9) +ISO/IEC\~8859-16 Romanian (Latin-10) .TE -.SS ISO 8859-9 characters -The following table displays the characters in ISO 8859-9 that +.SS ISO/IEC\~8859-9 characters +The following table displays the characters in ISO/IEC\~8859-9 that are printable and unlisted in the .BR ascii (7) manual page. @@ -139,7 +139,7 @@ _ 377 255 FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS .TE .SH NOTES -ISO 8859-9 is also known as Latin-5. +ISO/IEC\~8859-9 is also known as Latin-5. .SH SEE ALSO .BR ascii (7), .BR charsets (7), diff --git a/man7/kernel_lockdown.7 b/man7/kernel_lockdown.7 index aac19aa..cb8aa7c 100644 --- a/man7/kernel_lockdown.7 +++ b/man7/kernel_lockdown.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH kernel_lockdown 7 2023-02-05 "Linux man-pages 6.05.01" +.TH kernel_lockdown 7 2023-10-31 "Linux man-pages 6.7" .SH NAME kernel_lockdown \- kernel image access prevention feature .SH DESCRIPTION @@ -13,18 +13,18 @@ access to a running kernel image, attempting to protect against unauthorized modification of the kernel image and to prevent access to security and cryptographic data located in kernel memory, whilst still permitting driver modules to be loaded. -.PP +.P If a prohibited or restricted feature is accessed or used, the kernel will emit a message that looks like: -.PP +.P .in +4n .EX Lockdown: X: Y is restricted, see man kernel_lockdown.7 .EE .in -.PP +.P where X indicates the process name and Y indicates what is restricted. -.PP +.P On an EFI-enabled x86 or arm64 machine, lockdown will be automatically enabled if the system boots in EFI Secure Boot mode. .\" @@ -33,7 +33,7 @@ When lockdown is in effect, a number of features are disabled or have their use restricted. This includes special device files and kernel services that allow direct access of the kernel image: -.PP +.P .RS /dev/mem .br @@ -47,7 +47,7 @@ BPF .br kprobes .RE -.PP +.P and the ability to directly configure and control devices, so as to prevent the use of a device to access or modify a kernel image: .IP \[bu] 3 @@ -73,7 +73,7 @@ The use of ACPI error injection. The specification of the ACPI RDSP address. .IP \[bu] The use of ACPI custom methods. -.PP +.P Certain facilities are restricted: .IP \[bu] 3 Only validly signed modules may be loaded (waived if the module file being diff --git a/man7/keyrings.7 b/man7/keyrings.7 index 1ebd25f..879d1aa 100644 --- a/man7/keyrings.7 +++ b/man7/keyrings.7 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH keyrings 7 2023-02-05 "Linux man-pages 6.05.01" +.TH keyrings 7 2024-02-25 "Linux man-pages 6.7" .SH NAME keyrings \- in-kernel key management and retention facility .SH DESCRIPTION @@ -12,14 +12,14 @@ The Linux key-management facility is primarily a way for various kernel components to retain or cache security data, authentication keys, encryption keys, and other data in the kernel. -.PP +.P System call interfaces are provided so that user-space programs can manage those objects and also use the facility for their own purposes; see .BR add_key (2), .BR request_key (2), and .BR keyctl (2). -.PP +.P A library and some user-space utilities are provided to allow access to the facility. See @@ -98,7 +98,7 @@ the key is scheduled for garbage collection. .SS Key types The kernel provides several basic types of key: .TP -.I """keyring""" +.I \[dq]keyring\[dq] .\" Note that keyrings use different fields in struct key in order to store .\" their data - index_key instead of type/description and name_link/keys .\" instead of payload. @@ -111,7 +111,7 @@ being garbage collected because nothing refers to them. Keyrings with descriptions (names) that begin with a period (\[aq].\[aq]) are reserved to the implementation. .TP -.I """user""" +.I \[dq]user\[dq] This is a general-purpose key type. The key is kept entirely within kernel memory. The payload may be read and updated by user-space applications. @@ -123,12 +123,12 @@ The description may be any valid string, though it is preferred that it start with a colon-delimited prefix representing the service to which the key is of interest (for instance -.IR """afs:mykey""" ). +.IR \[dq]afs:mykey\[dq] ). .TP -.IR """logon""" " (since Linux 3.3)" +.IR \[dq]logon\[dq] " (since Linux 3.3)" .\" commit 9f6ed2ca257fa8650b876377833e6f14e272848b This key type is essentially the same as -.IR """user""" , +.IR \[dq]user\[dq] , but it does not provide reading (i.e., the .BR keyctl (2) .B KEYCTL_READ @@ -138,19 +138,19 @@ This is suitable for storing username-password pairs that should not be readable from user space. .IP The description of a -.I """logon""" +.I \[dq]logon\[dq] key .I must start with a non-empty colon-delimited prefix whose purpose is to identify the service to which the key belongs. (Note that this differs from keys of the -.I """user""" +.I \[dq]user\[dq] type, where the inclusion of a prefix is recommended but is not enforced.) .TP -.IR """big_key""" " (since Linux 3.13)" +.IR \[dq]big_key\[dq] " (since Linux 3.13)" .\" commit ab3c3587f8cda9083209a61dbe3a4407d3cada10 This key type is similar to the -.I """user""" +.I \[dq]user\[dq] key type, but it may hold a payload of up to 1\ MiB in size. This key type is useful for purposes such as holding Kerberos ticket caches. .IP @@ -165,11 +165,11 @@ Since Linux 4.8, .\" commit 13100a72f40f5748a04017e0ab3df4cf27c809ef the payload data is encrypted when stored in tmpfs, thereby preventing it from being written unencrypted into swap space. -.PP +.P There are more specialized key types available also, but they aren't discussed here because they aren't intended for normal user-space use. -.PP +.P Key type names that begin with a period (\[aq].\[aq]) are reserved to the implementation. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -179,7 +179,7 @@ links to other keys (which may include other keyrings). Keys may be linked to by multiple keyrings. Keyrings may be considered as analogous to UNIX directories where each directory contains a set of hard links to files. -.PP +.P Various operations (system calls) may be applied only to keyrings: .TP Adding @@ -204,7 +204,7 @@ A keyring may be considered the root of a tree or subtree in which keyrings form the branches and non-keyrings the leaves. This tree may be searched for a key matching a particular type and description. -.PP +.P See .BR keyctl_clear (3), .BR keyctl_link (3), @@ -217,13 +217,13 @@ for more information. To prevent a key from being garbage collected, it must be anchored to keep its reference count elevated when it is not in active use by the kernel. -.PP +.P Keyrings are used to anchor other keys: each link is a reference on a key. Note that keyrings themselves are just keys and are also subject to the same anchoring requirement to prevent them being garbage collected. -.PP +.P The kernel makes available a number of anchor keyrings. Note that some of these keyrings will be created only when first accessed. .TP @@ -302,7 +302,7 @@ encryption keys for module signature verification. .IP These special keyrings are usually closed to direct alteration by user space. -.PP +.P An originally planned "group keyring", for storing keys associated with each GID known to the kernel, is not so far implemented, is unlikely to be implemented. @@ -335,16 +335,16 @@ If a process is upcalled from the kernel to instantiate a key (see .BR request_key (2)), then it also possesses the requester's keyrings as in rule (1) as if it were the requester. -.PP +.P Note that possession is not a fundamental property of a key, but must rather be calculated each time the key is needed. -.PP +.P Possession is designed to allow set-user-ID programs run from, say a user's shell to access the user's keys. Granting permissions to the key possessor while denying them to the key owner and group allows the prevention of access to keys on the basis of UID and GID matches. -.PP +.P When it creates the session keyring, .BR pam_keyinit (8) adds a link to the @@ -361,7 +361,7 @@ The ID of a group that is permitted to access the key A security label .IP \[bu] A permissions mask -.PP +.P The permissions mask contains four sets of rights. The first three sets are mutually exclusive. One and only one will be in force for a particular access check. @@ -379,17 +379,17 @@ filesystem GID or one of the caller's supplementary group IDs. .I other The set specifies the rights granted if neither the key's user ID nor group ID matched. -.PP +.P The fourth set of rights is: .TP .I possessor The set specifies the rights granted if a key is determined to be possessed by the caller. -.PP +.P The complete set of rights for a key is the union of whichever of the first three sets is applicable plus the fourth set if the key is possessed. -.PP +.P The set of rights that may be granted in each of the four masks is as follows: .TP @@ -421,14 +421,14 @@ doesn't require this permission. .I setattr The ownership details and security label of the key may be changed, the key's expiration time may be set, and the key may be revoked. -.PP +.P In addition to access rights, any active Linux Security Module (LSM) may prevent access to a key if its policy so dictates. A key may be given a security label or other attribute by the LSM; this label is retrievable via .BR keyctl_get_security (3). -.PP +.P See .BR keyctl_chown (3), .BR keyctl_describe (3), @@ -447,7 +447,7 @@ system call is the primary point of access for user-space applications to find a key. (Internally, the kernel has something similar available for use by internal components that make use of keys.) -.PP +.P The search algorithm works as follows: .IP (1) 5 The process keyrings are searched in the following order: the @@ -480,10 +480,10 @@ If no valid matching key is found, then the first noted error state is returned; otherwise, an .B ENOKEY error is returned. -.PP +.P It is also possible to search a specific keyring, in which case only steps (3) to (6) apply. -.PP +.P See .BR request_key (2) and @@ -498,18 +498,18 @@ will, if given a argument, create a new key and then upcall to user space to instantiate the key. This allows keys to be created on an as-needed basis. -.PP +.P Typically, this will involve the kernel creating a new process that executes the .BR request\-key (8) program, which will then execute the appropriate handler based on its configuration. -.PP +.P The handler is passed a special authorization key that allows it and only it to instantiate the new key. This is also used to permit searches performed by the handler program to also search the requester's keyrings. -.PP +.P See .BR request_key (2), .BR keyctl_assume_authority (3), @@ -685,16 +685,16 @@ field provides some further information about the key. The information that appears here depends on the key type, as follows: .RS .TP -.IR """user""" " and " """logon""" +.IR \[dq]user\[dq] " and " \[dq]logon\[dq] The size in bytes of the key payload (expressed in decimal). .TP -.I """keyring""" +.I \[dq]keyring\[dq] The number of keys linked to the keyring, or the string .I empty if there are no keys linked to the keyring. .TP -.I """big_key""" +.I \[dq]big_key\[dq] The payload size in bytes, followed either by the string .IR [file] , if the key payload exceeds the threshold that means that the @@ -707,7 +707,7 @@ indicating that the key is small enough to reside in kernel memory. .RE .IP For the -.I """.request_key_auth""" +.I \[dq].request_key_auth\[dq] key type (authorization key; see .BR request_key (2)), @@ -796,7 +796,7 @@ or the operation.) .IP The default value in this file is 259200 (i.e., 3 days). -.PP +.P The following files (which are writable by privileged processes) are used to enforce quotas on the number of keys and number of bytes of data that can be stored in key payloads: @@ -833,14 +833,14 @@ may own. .IP .\"738c5d190f6540539a04baf36ce21d46b5da04bd The default value in this file is 1,000,000 (200 before Linux 3.17). -.PP +.P With respect to keyrings, note that each link in a keyring consumes 4 bytes of the keyring payload. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SS Users The Linux key-management facility has a number of users and usages, but is not limited to those that already exist. -.PP +.P In-kernel users of this facility include: .TP Network filesystems - DNS @@ -863,7 +863,7 @@ The CIFS filesystem uses keys to store passwords for accessing remote shares. Module verification The kernel build process can be made to cryptographically sign modules. That signature is then checked when a module is loaded. -.PP +.P User-space users of this facility include: .TP Kerberos key storage @@ -892,7 +892,7 @@ scripts can use them. .BR user\-session\-keyring (7), .BR pam_keyinit (8), .BR request\-key (8) -.PP +.P The kernel source files .I Documentation/crypto/asymmetric\-keys.txt and under diff --git a/man7/koi8-r.7 b/man7/koi8-r.7 index 65fc642..5239cb5 100644 --- a/man7/koi8-r.7 +++ b/man7/koi8-r.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH KOI8-R 7 2022-12-15 "Linux man-pages 6.05.01" +.TH KOI8-R 7 2022-12-15 "Linux man-pages 6.7" .SH NAME koi8-r \- Russian character set encoded in octal, decimal, and hexadecimal diff --git a/man7/koi8-u.7 b/man7/koi8-u.7 index c515c2a..00dec19 100644 --- a/man7/koi8-u.7 +++ b/man7/koi8-u.7 @@ -5,7 +5,7 @@ .\" .\" 2009-01-15, mtk, Some edits .\" -.TH KOI8-U 7 2022-12-15 "Linux man-pages 6.05.01" +.TH KOI8-U 7 2022-12-15 "Linux man-pages 6.7" .SH NAME koi8-u \- Ukrainian character set encoded in octal, decimal, and hexadecimal diff --git a/man7/landlock.7 b/man7/landlock.7 index 96f8217..3df7d7b 100644 --- a/man7/landlock.7 +++ b/man7/landlock.7 @@ -5,7 +5,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH Landlock 7 2023-05-03 "Linux man-pages 6.05.01" +.TH Landlock 7 2023-10-31 "Linux man-pages 6.7" .SH NAME Landlock \- unprivileged access-control .SH DESCRIPTION @@ -18,7 +18,7 @@ the existing system-wide access-controls. This kind of sandbox is expected to help mitigate the security impact of bugs, and unexpected or malicious behaviors in applications. -.PP +.P A Landlock security policy is a set of access rights (e.g., open a file in read-only, make a directory, etc.) tied to a file hierarchy. @@ -33,7 +33,7 @@ adds a new rule to a ruleset; .IP \[bu] .BR landlock_restrict_self (2) enforces a ruleset on the calling thread. -.PP +.P To be able to use these system calls, the running kernel must support Landlock and it must be enabled at boot time. @@ -57,7 +57,7 @@ See and .BR landlock_create_ruleset (2) for more context. -.PP +.P A file can only receive these access rights: .TP .B LANDLOCK_ACCESS_FS_EXECUTE @@ -98,14 +98,14 @@ using and .BR LANDLOCK_ACCESS_FS_WRITE_FILE . This access right is available since the third version of the Landlock ABI. -.PP +.P A directory can receive access rights related to files or directories. The following access right is applied to the directory itself, and the directories beneath it: .TP .B LANDLOCK_ACCESS_FS_READ_DIR Open a directory or list its content. -.PP +.P However, the following access rights only apply to the content of a directory, not the directory itself: @@ -194,7 +194,7 @@ Indeed, this complementary policy is composed with the potentially other rulesets already restricting this thread. A sandboxed thread can then safely add more constraints to itself with a new enforced ruleset. -.PP +.P One policy layer grants access to a file path if at least one of its rules encountered on the path grants the access. A sandboxed thread can only access a file path @@ -208,7 +208,7 @@ which means that these access rights can be propagated with bind mounts (cf. .BR mount_namespaces (7)) but not with OverlayFS. -.PP +.P A bind mount mirrors a source file hierarchy to a destination. The destination hierarchy is then composed of the exact same files, on which Landlock rules can be tied, @@ -217,7 +217,7 @@ These rules restrict access when they are encountered on a path, which means that they can restrict access to multiple file hierarchies at the same time, whether these hierarchies are the result of bind mounts or not. -.PP +.P An OverlayFS mount point consists of upper and lower layers. These layers are combined in a merge directory, result of the mount point. This merge hierarchy may include files from the upper and lower layers, @@ -244,7 +244,7 @@ For instance, one process's thread may apply Landlock rules to itself, but they will not be automatically applied to other sibling threads (unlike POSIX thread credential changes, cf. .BR nptl (7)). -.PP +.P When a thread sandboxes itself, we have the guarantee that the related security policy will stay enforced on all this thread's descendants. @@ -271,14 +271,14 @@ and both change the contents of a file and sometimes overlap in non-intuitive ways. It is recommended to always specify both of these together. -.PP +.P A particularly surprising example is .BR creat (2). The name suggests that this system call requires the rights to create and write files. However, it also requires the truncate right if an existing file under the same name is already present. -.PP +.P It should also be noted that truncating files does not require the .B LANDLOCK_ACCESS_FS_WRITE_FILE right. @@ -288,7 +288,7 @@ system call, this can also be done through .BR open (2) with the flags .IR "O_RDONLY\ |\ O_TRUNC" . -.PP +.P When opening a file, the availability of the .B LANDLOCK_ACCESS_FS_TRUNCATE right is associated with the newly created file descriptor @@ -302,7 +302,7 @@ but not during the subsequent and .BR write (2) calls. -.PP +.P As a consequence, it is possible to have multiple open file descriptors for the same file, where one grants the right to truncate the file and the other does not. @@ -311,7 +311,7 @@ keeping their Landlock properties, even when these processes do not have an enforced Landlock ruleset. .SH VERSIONS Landlock was introduced in Linux 5.13. -.PP +.P To determine which Landlock features are available, users should query the Landlock ABI version: .TS @@ -338,20 +338,19 @@ _ _ _ _ _ _ 3 6.2 LANDLOCK_ACCESS_FS_TRUNCATE .TE -.sp 1 -.PP +.P Users should use the Landlock ABI version rather than the kernel version to determine which features are available. The mainline kernel versions listed here are only included for orientation. Kernels from other sources may contain backported features, and their version numbers may not match. -.PP +.P To query the running kernel's Landlock ABI version, programs may pass the .B LANDLOCK_CREATE_RULESET_VERSION flag to .BR landlock_create_ruleset (2). -.PP +.P When building fallback mechanisms for compatibility with older kernels, users are advised to consider the special semantics of the .B LANDLOCK_ACCESS_FS_REFER @@ -394,7 +393,7 @@ accessible through these system call families: Future Landlock evolutions will enable to restrict them. .SH EXAMPLES We first need to create the ruleset that will contain our rules. -.PP +.P For this example, the ruleset will contain rules that only allow read actions, but write actions will be denied. @@ -402,7 +401,7 @@ The ruleset then needs to handle both of these kinds of actions. See the .B DESCRIPTION section for the description of filesystem actions. -.PP +.P .in +4n .EX struct landlock_ruleset_attr attr = {0}; @@ -426,11 +425,11 @@ attr.handled_access_fs = LANDLOCK_ACCESS_FS_TRUNCATE; .EE .in -.PP +.P To be compatible with older Linux versions, we detect the available Landlock ABI version, and only use the available subset of access rights: -.PP +.P .in +4n .EX /* @@ -459,11 +458,11 @@ abi = MIN(abi, 3); attr.handled_access_fs &= landlock_fs_access_rights[abi \- 1]; .EE .in -.PP +.P The available access rights for each ABI version are listed in the .B VERSIONS section. -.PP +.P If our program needed to create hard links or rename files between different directories .RB ( LANDLOCK_ACCESS_FS_REFER ), @@ -474,13 +473,13 @@ Therefore, if the program needed to do file reparenting, and if only Landlock ABI version 1 was available, we could not restrict the process. -.PP +.P Now that the ruleset attributes are determined, we create the Landlock ruleset and acquire a file descriptor as a handle to it, using .BR landlock_create_ruleset (2): -.PP +.P .in +4n .EX ruleset_fd = landlock_create_ruleset(&attr, sizeof(attr), 0); @@ -490,13 +489,13 @@ if (ruleset_fd == \-1) { } .EE .in -.PP +.P We can now add a new rule to the ruleset through the ruleset's file descriptor. The requested access rights must be a subset of the access rights which were specified in .I attr.handled_access_fs at ruleset creation time. -.PP +.P In this example, the rule will only allow reading the file hierarchy .IR /usr . Without another rule, write actions would then be denied by the ruleset. @@ -507,7 +506,7 @@ to the ruleset, we open it with the flag and fill the .I struct landlock_path_beneath_attr with this file descriptor. -.PP +.P .in +4n .EX struct landlock_path_beneath_attr path_beneath = {0}; @@ -534,14 +533,14 @@ if (err) { } .EE .in -.PP +.P We now have a ruleset with one rule allowing read access to .I /usr while denying all other handled accesses for the filesystem. The next step is to restrict the current thread from gaining more privileges (e.g., thanks to a set-user-ID binary). -.PP +.P .in +4n .EX if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { @@ -551,9 +550,9 @@ if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { } .EE .in -.PP +.P The current thread is now ready to sandbox itself with the ruleset. -.PP +.P .in +4n .EX if (landlock_restrict_self(ruleset_fd, 0)) { @@ -564,7 +563,7 @@ if (landlock_restrict_self(ruleset_fd, 0)) { close(ruleset_fd); .EE .in -.PP +.P If the .BR landlock_restrict_self (2) system call succeeds, the current thread is now restricted and @@ -573,7 +572,7 @@ Once a thread is landlocked, there is no way to remove its security policy; only adding more restrictions is allowed. These threads are now in a new Landlock domain, merge of their parent one (if any) with the new ruleset. -.PP +.P Full working code can be found in .UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c .UE @@ -581,6 +580,6 @@ Full working code can be found in .BR landlock_create_ruleset (2), .BR landlock_add_rule (2), .BR landlock_restrict_self (2) -.PP +.P .UR https://landlock.io/ .UE diff --git a/man7/libc.7 b/man7/libc.7 index 7a62251..5e906d1 100644 --- a/man7/libc.7 +++ b/man7/libc.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH libc 7 2023-02-05 "Linux man-pages 6.05.01" +.TH libc 7 2023-10-31 "Linux man-pages 6.7" .SH NAME libc \- overview of standard C libraries on Linux .SH DESCRIPTION @@ -36,7 +36,7 @@ Release 1.0 of glibc was made in September 1992. (There were earlier 0.x releases.) The next major release of glibc was 2.0, at the beginning of 1997. -.PP +.P The pathname .I /lib/libc.so.6 (or something similar) @@ -61,7 +61,7 @@ this version used the shared library soname .IR libc.so.5 . For a while, Linux libc was the standard C library in many Linux distributions. -.PP +.P However, notwithstanding the original motivations of the Linux libc effort, by the time glibc 2.0 was released @@ -72,7 +72,7 @@ soon switched back to glibc. To avoid any confusion with Linux libc versions, glibc 2.0 and later used the shared library soname .IR libc.so.6 . -.PP +.P Since the switch from Linux libc to glibc 2.0 occurred long ago, .I man-pages no longer takes care to document Linux libc details. diff --git a/man7/locale.7 b/man7/locale.7 index 49aa367..862a1d5 100644 --- a/man7/locale.7 +++ b/man7/locale.7 @@ -8,7 +8,7 @@ .\" .\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible .\" -.TH locale 7 2023-05-03 "Linux man-pages 6.05.01" +.TH locale 7 2024-02-25 "Linux man-pages 6.7" .SH NAME locale \- description of multilanguage support .SH SYNOPSIS @@ -22,18 +22,18 @@ such as language for messages, different character sets, lexicographic conventions, and so on. A program needs to be able to determine its locale and act accordingly to be portable to different cultures. -.PP +.P The header .I declares data types, functions, and macros which are useful in this task. -.PP +.P The functions it declares are .BR setlocale (3) to set the current locale, and .BR localeconv (3) to get information about number formatting. -.PP +.P There are different categories for locale information a program might need; they are declared as macros. Using them as the first argument @@ -131,7 +131,7 @@ functions also obey the environment variable .B LANGUAGE (containing a colon-separated list of locales) if the category is set to a valid locale other than -.BR """C""" . +.BR \[dq]C\[dq] . This category also affects the behavior of .BR catopen (3). .TP @@ -213,7 +213,7 @@ and .TP .B LC_ALL All of the above. -.PP +.P If the second argument to .BR setlocale (3) is an empty string, @@ -234,13 +234,13 @@ If there is a non-null environment variable the value of .B LANG is used. -.PP +.P Values about local numeric formatting is made available in a .I struct lconv returned by the .BR localeconv (3) function, which has the following declaration: -.PP +.P .in +4n .EX struct lconv { @@ -299,7 +299,7 @@ based on implementations that first appeared in glibc 2.3. These extensions are designed to address the problem that the traditional locale APIs do not mix well with multithreaded applications and with applications that must deal with multiple locales. -.PP +.P The extensions take the form of new functions for creating and manipulating locale objects .RB ( newlocale (3), diff --git a/man7/mailaddr.7 b/man7/mailaddr.7 index 8218daa..f2da7da 100644 --- a/man7/mailaddr.7 +++ b/man7/mailaddr.7 @@ -24,7 +24,7 @@ .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" %%%LICENSE_END .\" -.TH mailaddr 7 2023-02-05 "Linux man-pages 6.05.01" +.TH mailaddr 7 2023-10-31 "Linux man-pages 6.7" .UC 5 .SH NAME mailaddr \- mail addressing description @@ -33,16 +33,16 @@ mailaddr \- mail addressing description This manual page gives a brief introduction to SMTP mail addresses, as used on the Internet. These addresses are in the general format -.PP +.P .in +4n .EX user@domain .EE .in -.PP +.P where a domain is a hierarchical dot-separated list of subdomains. These examples are valid forms of the same address: -.PP +.P .in +4n .EX john.doe@monet.example.com @@ -50,11 +50,11 @@ John Doe john.doe@monet.example.com (John Doe) .EE .in -.PP +.P The domain part ("monet.example.com") is a mail-accepting domain. It can be a host and in the past it usually was, but it doesn't have to be. The domain part is not case sensitive. -.PP +.P The local part ("john.doe") is often a username, but its meaning is defined by the local software. Sometimes it is case sensitive, @@ -62,7 +62,7 @@ although that is unusual. If you see a local-part that looks like garbage, it is usually because of a gateway between an internal e-mail system and the net, here are some examples: -.PP +.P .in +4n .EX "surname/admd=telemail/c=us/o=hp/prmd=hp"@some.where @@ -71,17 +71,17 @@ machine!machine!name@some.where I2461572@some.where .EE .in -.PP +.P (These are, respectively, an X.400 gateway, a gateway to an arbitrary internal mail system that lacks proper internet support, an UUCP gateway, and the last one is just boring username policy.) -.PP +.P The real-name part ("John Doe") can either be placed before <>, or in () at the end. (Strictly speaking the two aren't the same, but the difference is beyond the scope of this page.) The name may have to be quoted using "", for example, if it contains ".": -.PP +.P .in +4n .EX "John Q. Doe" @@ -99,17 +99,17 @@ In the past, sometimes one had to route a message through several hosts to get it to its final destination. Addresses which show these relays are termed "route-addrs". These use the syntax: -.PP +.P .in +4n .EX <@hosta,@hostb:user@hostc> .EE .in -.PP +.P This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. Many hosts disregard route-addrs and send directly to hostc. -.PP +.P Route-addrs are very unusual now. They occur sometimes in old mail archives. It is generally possible to ignore all but the "user@hostc" @@ -128,7 +128,7 @@ The "postmaster" address is not case sensitive. .BR aliases (5), .BR forward (5), .BR sendmail (8) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc5322.txt IETF RFC\ 5322 .UE diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 6d8b0ea..c7eeb0a 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -8,7 +8,7 @@ .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" -.TH man-pages 7 2023-03-30 "Linux man-pages 6.05.01" +.TH man-pages 7 2023-10-31 "Linux man-pages 6.7" .SH NAME man-pages \- conventions for writing Linux man pages .SH SYNOPSIS @@ -86,12 +86,12 @@ submitted inline. The first command in a man page should be a .B TH command: -.PP +.P .RS .B \&.TH .I "title section date source manual-section" .RE -.PP +.P The arguments of the command are as follows: .TP .I title @@ -126,7 +126,7 @@ Most manual pages should include at least the sections. Arrange a new manual page so that sections are placed in the order shown in the list. -.PP +.P .RS .TS l l. @@ -163,7 +163,7 @@ COPYRIGHT [Not used in man-pages] \fBSEE ALSO\fP .TE .RE -.PP +.P .IR "Where a traditional heading would apply" ", " "please use it" ; this kind of consistency can make the information easier to understand. If you must, you can create your own @@ -172,7 +172,7 @@ be especially useful for pages in Sections 4 and 5). However, before doing this, consider whether you could use the traditional headings, with some subsections (\fI.SS\fP) within those sections. -.PP +.P The following list elaborates on the contents of each of the above sections. .TP @@ -386,7 +386,7 @@ The .BR syscalls (2) manual page also provides information about kernel versions in which various system calls first appeared. -.PP +.P Old versions of standards should be mentioned here, rather than in STANDARDS, for example, @@ -479,13 +479,13 @@ project. Wrap the function prototype(s) in a .IR .nf / .fi pair to prevent filling. -.PP +.P In general, where more than one function prototype is shown in the SYNOPSIS, the prototypes should .I not be separated by blank lines. However, blank lines (achieved using -.IR .PP ) +.IR .P ) may be added in the following cases: .IP \[bu] 3 to separate long lists of function prototypes into related groups @@ -493,7 +493,7 @@ to separate long lists of function prototypes into related groups .BR list (3)); .IP \[bu] in other cases that may improve readability. -.PP +.P In the SYNOPSIS, a long function prototype may need to be continued over to the next line. The continuation line is indented according to the following rules: @@ -565,7 +565,7 @@ Make free use of macro pairs to allow table cells to be broken over multiple lines (also bearing in mind that pages may sometimes be rendered to a width of less than 80 columns). -.PP +.P For examples of all of the above, see the source code of various pages. .SH STYLE GUIDE The following subsections describe the preferred style for the @@ -584,7 +584,7 @@ pronoun is acceptable. For manual pages that describe a command (typically in Sections 1 and 8), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" . -.PP +.P The name of the command, and its options, should always be formatted in bold. .\" @@ -593,11 +593,11 @@ For manual pages that describe functions (typically in Sections 2 and 3), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" , where the rest of the function is specified in bold: -.PP +.P .BI " int myfunction(int " argc ", char **" argv ); -.PP +.P Variable names should, like argument names, be specified in italics. -.PP +.P Any reference to the subject of the current manual page should be written with the name in bold followed by a pair of parentheses in Roman (normal) font. @@ -606,11 +606,11 @@ For example, in the man page, references to the subject of the page would be written as: .BR fcntl (). The preferred way to write this in the source file is: -.PP +.P .EX .BR fcntl () .EE -.PP +.P (Using this format, rather than the use of "\efB...\efP()" makes it easier to write tools that parse man page source files.) .\" @@ -676,7 +676,7 @@ usually covered by this type of list. Numbered notes Not really a list, but the syntax is identical to "positional lists". -.PP +.P There should always be exactly 2 spaces between the list symbol and the elements. This doesn't apply to "tagged paragraphs", @@ -684,14 +684,14 @@ which use the default indentation rules. .\" .SS Formatting conventions (general) Paragraphs should be separated by suitable markers (usually either -.I .PP +.I .P or .IR .IP ). Do .I not separate paragraphs using blank lines, as this results in poor rendering in some output formats (such as PostScript and PDF). -.PP +.P Filenames (whether pathnames, or references to header files) are always in italics (e.g., .IR ), @@ -701,26 +701,26 @@ When referring to a standard header file include, specify the header file surrounded by angle brackets, in the usual C way (e.g., .IR ). -.PP +.P Special macros, which are usually in uppercase, are in bold (e.g., .BR MAXINT ). Exception: don't boldface NULL. -.PP +.P When enumerating a list of error codes, the codes are in bold (this list usually uses the .B \&.TP macro). -.PP +.P Complete commands should, if long, be written as an indented line on their own, with a blank line before and after the command, for example -.PP +.P .in +4n .EX man 7 man\-pages .EE .in -.PP +.P If the command is short, then it can be included inline in the text, in italic format, for example, .IR "man 7 man-pages" . @@ -728,23 +728,23 @@ In this case, it may be worth using nonbreaking spaces (\e[ti]) at suitable places in the command. Command options should be written in italics (e.g., .IR \-l ). -.PP +.P Expressions, if not written on a separate indented line, should be specified in italics. Again, the use of nonbreaking spaces may be appropriate if the expression is inlined with normal text. -.PP +.P When showing example shell sessions, user input should be formatted in bold, for example -.PP +.P .in +4n .EX $ \fBdate\fP Thu Jul 7 13:01:27 CEST 2016 .EE .in -.PP +.P Any reference to another man page should be written with the name in bold, .I always @@ -753,15 +753,15 @@ formatted in Roman (normal) font, without any separating spaces (e.g., .BR intro (2)). The preferred way to write this in the source file is: -.PP +.P .EX .BR intro (2) .EE -.PP +.P (Including the section number in cross references lets tools like .BR man2html (1) create properly hyperlinked pages.) -.PP +.P Control characters should be written in bold face, with no quotes; for example, .BR \[ha]X . @@ -771,7 +771,7 @@ Starting with release 2.59, follows American spelling conventions (previously, there was a random mix of British and American spellings); please write all new pages and patches according to these conventions. -.PP +.P Aside from the well-known spelling differences, there are a few other subtleties to watch for: .IP \[bu] 3 @@ -797,7 +797,7 @@ capitalize the first word in the heading, but otherwise use lowercase, except where English usage (e.g., proper nouns) or programming language requirements (e.g., identifier names) dictate otherwise. For example: -.PP +.P .in +4n .EX \&.SS Unicode under Linux @@ -815,14 +815,14 @@ format them using the and .I .EE macros, and surround them with suitable paragraph markers (either -.I .PP +.I .P or .IR .IP ). For example: -.PP +.P .in +4n .EX -\&.PP +\&.P \&.in +4n \&.EX int @@ -832,7 +832,7 @@ main(int argc, char *argv[]) } \&.EE \&.in -\&.PP +\&.P .EE .in .SS Preferred terms @@ -897,7 +897,7 @@ Except if referring to result of "uname\ \-m" or similar T} zeros zeroes .TE -.PP +.P See also the discussion .I Hyphenation of attributive compounds below. @@ -958,10 +958,10 @@ is the .IR "null byte" , a byte with the value 0, represented in C via the character constant .IR \[aq]\e0\[aq] . -.PP +.P The preferred term for the pointer is "null pointer" or simply "NULL"; avoid writing "NULL pointer". -.PP +.P The preferred term for the byte is "null byte". Avoid writing "NUL", since it is too easily confused with "NULL". Avoid also the terms "zero byte" and "null character". @@ -977,7 +977,7 @@ macro pair .BR groff_man (7)). This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say: -.PP +.P .in +4n .EX BROWSER=firefox man -H pagename @@ -988,11 +988,11 @@ In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "cf.", and "a.k.a." should be avoided, in favor of suitable full wordings ("for example", "that is", "and so on", "compare to", "also known as"). -.PP +.P The only place where such abbreviations may be acceptable is in .I short parenthetical asides (e.g., like this one). -.PP +.P Always include periods in such abbreviations, as shown here. In addition, "e.g." and "i.e." should always be followed by a comma. .SS Em-dashes @@ -1046,7 +1046,7 @@ subcomponent subdirectory subsystem .TE -.PP +.P Hyphens should be retained when the prefixes are used in nonstandard English words, with trademarks, proper nouns, acronyms, or compound terms. Some examples: @@ -1058,7 +1058,7 @@ non-English non-NULL non-real-time .TE -.PP +.P Finally, note that "re-create" and "recreate" are two different verbs, and the former is probably what you want. .\" @@ -1069,15 +1069,15 @@ for man page cross references such as or when writing options that have a leading dash, such as in .IR "ls\ \-l"), use the following form in the man page source: -.PP +.P .in +4n .EX \e\- .EE .in -.PP +.P This guideline applies also to code examples. -.PP +.P The use of real minus signs serves the following purposes: .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ .IP \[bu] 3 @@ -1087,26 +1087,26 @@ notably in PDF and on Unicode/UTF\-8-capable terminals. .IP \[bu] To generate glyphs that when copied from rendered pages will produce real minus signs when pasted into a terminal. -.PP +.P To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, use "\e[aq]" ("apostrophe quote"); for example -.PP +.P .in +4n .EX \e[aq]C\e[aq] .EE .in -.PP +.P where .I C is the quoted character. This guideline applies also to character constants used in code examples. -.PP +.P Where a proper caret (\[ha]) that renders well in both a terminal and PDF is required, use "\\[ha]". This is especially necessary in code samples, to get a nicely rendered caret when rendering to PDF. -.PP +.P Using a naked "\[ti]" character results in a poor rendering in PDF. Instead use "\\[ti]". This is especially necessary in code samples, @@ -1195,7 +1195,7 @@ as in: .in .IP Always do this if the explanatory text includes a shell session log. -.PP +.P If you include a shell session log demonstrating the use of a program or other system feature: .IP \[bu] 3 @@ -1205,7 +1205,7 @@ Indent the session log by four spaces. .IP \[bu] Boldface the user input text, to distinguish it from output produced by the system. -.PP +.P For some examples of what example programs should look like, see .BR wait (2) and diff --git a/man7/man.7 b/man7/man.7 index b0788f3..f460f4a 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -1,507 +1 @@ -.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler -.\" (faith@cs.unc.edu and dwheeler@ida.org) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu) -.\" Modified Sat Jun 8 00:39:52 1996 by aeb -.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org) -.\" Modified Thu Jul 15 12:43:28 1999 by aeb -.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze -.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson -.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7. -.\" -.TH man 7 2023-07-29 "Linux man-pages 6.05.01" -.SH NAME -man \- macros to format man pages -.SH SYNOPSIS -.B groff \-Tascii \-man -.I file -\&... -.br -.B groff \-Tps \-man -.I file -\&... -.PP -.B man -.RI [ section ] -.I title -.SH DESCRIPTION -This manual page explains the -.B "groff an.tmac" -macro package (often called the -.B man -macro package). -This macro package should be used by developers when -writing or porting man pages for Linux. -It is fairly compatible with other -versions of this macro package, so porting man pages should not be a major -problem (exceptions include the NET-2 BSD release, which uses a totally -different macro package called mdoc; see -.BR mdoc (7)). -.PP -Note that NET-2 BSD mdoc man pages can be used with -.B groff -simply by specifying the -.B \-mdoc -option instead of the -.B \-man -option. -Using the -.B \-mandoc -option is, however, recommended, since this will automatically detect which -macro package is in use. -.PP -For conventions that should be employed when writing man pages -for the Linux \fIman-pages\fP package, see -.BR man\-pages (7). -.SS Title line -The first command in a man page (after comment lines, -that is, lines that start with \fB.\e"\fP) should be -.PP -.RS -.B .TH -.I "title section date source manual" -.RE -.PP -For details of the arguments that should be supplied to the -.B TH -command, see -.BR man\-pages (7). -.PP -Note that BSD mdoc-formatted pages begin with the -.B Dd -command, not the -.B TH -command. -.SS Sections -Sections are started with -.B .SH -followed by the heading name. -.\" The following doesn't seem to be required (see Debian bug 411303), -.\" If the name contains spaces and appears -.\" on the same line as -.\" .BR .SH , -.\" then place the heading in double quotes. -.PP -The only mandatory heading is NAME, which should be the first section and -be followed on the next line by a one-line description of the program: -.PP -.RS -\&.SH NAME -.br -item \e- description -.RE -.PP -It is extremely important that this format is followed, and that there is a -backslash before the single dash which follows the item name. -This syntax is used by the -.BR mandb (8) -program to create a database of short descriptions for the -.BR whatis (1) -and -.BR apropos (1) -commands. -(See -.BR lexgrog (1) -for further details on the syntax of the NAME section.) -.PP -For a list of other sections that might appear in a manual page, see -.BR man\-pages (7). -.SS Fonts -The commands to select the type face are: -.TP 4 -.B .B -Bold -.TP -.B .BI -Bold alternating with italics -(especially useful for function specifications) -.TP -.B .BR -Bold alternating with Roman -(especially useful for referring to other -manual pages) -.TP -.B .I -Italics -.TP -.B .IB -Italics alternating with bold -.TP -.B .IR -Italics alternating with Roman -.TP -.B .RB -Roman alternating with bold -.TP -.B .RI -Roman alternating with italics -.TP -.B .SB -Small alternating with bold -.TP -.B .SM -Small (useful for acronyms) -.PP -Traditionally, each command can have up to six arguments, but the GNU -implementation removes this limitation (you might still want to limit -yourself to 6 arguments for portability's sake). -Arguments are delimited by spaces. -Double quotes can be used to specify an argument which contains spaces. -For the macros that produce alternating type faces, -the arguments will be printed next to each other without -intervening spaces, so that the -.B .BR -command can be used to specify a word in bold followed by a mark of -punctuation in Roman. -If no arguments are given, the command is applied to the following line -of text. -.SS Other macros and strings -Below are other relevant macros and predefined strings. -Unless noted otherwise, all macros -cause a break (end the current line of text). -Many of these macros set or use the "prevailing indent". -The "prevailing indent" value is set by any macro with the parameter -.I i -below; -macros may omit -.I i -in which case the current prevailing indent will be used. -As a result, successive indented paragraphs can use the same indent without -respecifying the indent value. -A normal (nonindented) paragraph resets the prevailing indent value -to its default value (0.5 inches). -By default, a given indent is measured in ens; -try to use ens or ems as units for -indents, since these will automatically adjust to font size changes. -The other key macro definitions are: -.SS Normal paragraphs -.TP 9m -.B .LP -Same as -.B .PP -(begin a new paragraph). -.TP -.B .P -Same as -.B .PP -(begin a new paragraph). -.TP -.B .PP -Begin a new paragraph and reset prevailing indent. -.SS Relative margin indent -.TP 9m -.BI .RS " i" -Start relative margin indent: moves the left margin -.I i -to the right (if -.I i -is omitted, the prevailing indent value is used). -A new prevailing indent is set to 0.5 inches. -As a result, all following paragraph(s) will be -indented until the corresponding -.BR .RE . -.TP -.B .RE -End relative margin indent and -restores the previous value of the prevailing indent. -.SS Indented paragraph macros -.TP 9m -.BI .HP " i" -Begin paragraph with a hanging indent -(the first line of the paragraph is at the left margin of -normal paragraphs, and the rest of the paragraph's lines are indented). -.TP -.BI .IP " x i" -Indented paragraph with optional hanging tag. -If the tag -.I x -is omitted, the entire following paragraph is indented by -.IR i . -If the tag -.I x -is provided, it is hung at the left margin -before the following indented paragraph -(this is just like -.B .TP -except the tag is included with the command instead of being on the -following line). -If the tag is too long, the text after the tag will be moved down to the -next line (text will not be lost or garbled). -For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash) -as the tag, and for numbered lists, use the number or letter followed by -a period as the tag; -this simplifies translation to other formats. -.TP -.BI .TP " i" -Begin paragraph with hanging tag. -The tag is given on the next line, but -its results are like those of the -.B .IP -command. -.SS Hypertext link macros -.TP -.BI .UR " url" -Insert a hypertext link to the URI (URL) -.IR url , -with all text up to the following -.B .UE -macro as the link text. -.TP -.BR .UE \~\c -.RI [ trailer ] -Terminate the link text of the preceding -.B .UR -macro, with the optional -.I trailer -(if present, usually a closing parenthesis and/or end-of-sentence -punctuation) immediately following. -For non-HTML output devices (e.g., -.BR "man \-Tutf8" ), -the link text is followed by the URL in angle brackets; if there is no -link text, the URL is printed as its own link text, surrounded by angle -brackets. -(Angle brackets may not be available on all output devices.) -For the HTML output device, the link text is hyperlinked to the URL; if -there is no link text, the URL is printed as its own link text. -.PP -These macros have been supported since GNU Troff 1.20 (2009-01-05) and -Heirloom Doctools Troff since 160217 (2016-02-17). -.SS Miscellaneous macros -.TP 9m -.B .DT -Reset tabs to default tab values (every 0.5 inches); -does not cause a break. -.TP -.BI .PD " d" -Set inter-paragraph vertical distance to d -(if omitted, d=0.4v); -does not cause a break. -.TP -.BI .SS " t" -Subheading -.I t -(like -.BR .SH , -but used for a subsection inside a section). -.SS Predefined strings -The -.B man -package has the following predefined strings: -.TP -\e*R -Registration Symbol: \*R -.TP -\e*S -Change to default font size -.TP -\e*(Tm -Trademark Symbol: \*(Tm -.TP -\e*(lq -Left angled double quote: \*(lq -.TP -\e*(rq -Right angled double quote: \*(rq -.SS Safe subset -Although technically -.B man -is a troff macro package, in reality a large number of other tools -process man page files that don't implement all of troff's abilities. -Thus, it's best to avoid some of troff's more exotic abilities -where possible to permit these other tools to work correctly. -Avoid using the various troff preprocessors -(if you must, go ahead and use -.BR tbl (1), -but try to use the -.B IP -and -.B TP -commands instead for two-column tables). -Avoid using computations; most other tools can't process them. -Use simple commands that are easy to translate to other formats. -The following troff macros are believed to be safe (though in many cases -they will be ignored by translators): -.BR \e" , -.BR . , -.BR ad , -.BR bp , -.BR br , -.BR ce , -.BR de , -.BR ds , -.BR el , -.BR ie , -.BR if , -.BR fi , -.BR ft , -.BR hy , -.BR ig , -.BR in , -.BR na , -.BR ne , -.BR nf , -.BR nh , -.BR ps , -.BR so , -.BR sp , -.BR ti , -.BR tr . -.PP -You may also use many troff escape sequences (those sequences beginning -with \e). -When you need to include the backslash character as normal text, -use \ee. -Other sequences you may use, where x or xx are any characters and N -is any digit, include: -.BR \e\[aq] , -.BR \e\[ga] , -.BR \e- , -.BR \e. , -.BR \e" , -.BR \e% , -.BR \e*x , -.BR \e*(xx , -.BR \e(xx , -.BR \e$N , -.BR \enx , -.BR \en(xx , -.BR \efx , -and -.BR \ef(xx . -Avoid using the escape sequences for drawing graphics. -.PP -Do not use the optional parameter for -.B bp -(break page). -Use only positive values for -.B sp -(vertical space). -Don't define a macro -.RB ( de ) -with the same name as a macro in this or the -mdoc macro package with a different meaning; it's likely that -such redefinitions will be ignored. -Every positive indent -.RB ( in ) -should be paired with a matching negative indent -(although you should be using the -.B RS -and -.B RE -macros instead). -The condition test -.RB ( if,ie ) -should only have \[aq]t\[aq] or \[aq]n\[aq] as the condition. -Only translations -.RB ( tr ) -that can be ignored should be used. -Font changes -.RB ( ft -and the \fB\ef\fP escape sequence) -should only have the values 1, 2, 3, 4, R, I, B, P, or CW -(the ft command may also have no parameters). -.PP -If you use capabilities beyond these, check the -results carefully on several tools. -Once you've confirmed that the additional capability is safe, -let the maintainer of this -document know about the safe command or sequence -that should be added to this list. -.SH FILES -.IR /usr/share/groff/ [*/] tmac/an.tmac -.br -.I /usr/man/whatis -.SH NOTES -By all means include full URLs (or URIs) in the text itself; -some tools such as -.BR man2html (1) -can automatically turn them into hypertext links. -You can also use the -.B UR -and -.B UE -macros to identify links to related information. -If you include URLs, use the full URL -(e.g., -.UR http://www.kernel.org -.UE ) -to ensure that tools can automatically find the URLs. -.PP -Tools processing these files should open the file and examine the first -nonwhitespace character. -A period (.) or single quote (\[aq]) at the beginning -of a line indicates a troff-based file (such as man or mdoc). -A left angle bracket (<) indicates an SGML/XML-based -file (such as HTML or Docbook). -Anything else suggests simple ASCII -text (e.g., a "catman" result). -.PP -Many man pages begin with \fB\[aq]\e"\fP followed by a -space and a list of characters, -indicating how the page is to be preprocessed. -For portability's sake to non-troff translators we recommend -that you avoid using anything other than -.BR tbl (1), -and Linux can detect that automatically. -However, you might want to include this information so your man page -can be handled by other (less capable) systems. -Here are the definitions of the preprocessors invoked by these characters: -.TP 3 -.B e -eqn(1) -.TP -.B g -grap(1) -.TP -.B p -pic(1) -.TP -.B r -refer(1) -.TP -.B t -tbl(1) -.TP -.B v -vgrind(1) -.SH BUGS -Most of the macros describe formatting (e.g., font type and spacing) instead -of marking semantic content (e.g., this text is a reference to another page), -compared to formats like mdoc and DocBook (even HTML has more semantic -markings). -This situation makes it harder to vary the -.B man -format for different media, -to make the formatting consistent for a given media, and to automatically -insert cross-references. -By sticking to the safe subset described above, it should be easier to -automate transitioning to a different reference page format in the future. -.PP -The Sun macro -.B TX -is not implemented. -.\" .SH AUTHORS -.\" .IP \[em] 3m -.\" James Clark (jjc@jclark.com) wrote the implementation of the macro package. -.\" .IP \[em] -.\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of -.\" this manual page. -.\" .IP \[em] -.\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO -.\" (which influenced this manual page). -.\" .IP \[em] -.\" David A. Wheeler (dwheeler@ida.org) heavily modified this -.\" manual page, such as adding detailed information on sections and macros. -.SH SEE ALSO -.BR apropos (1), -.BR groff (1), -.BR lexgrog (1), -.BR man (1), -.BR man2html (1), -.BR whatis (1), -.BR groff_man (7), -.BR groff_www (7), -.BR man\-pages (7), -.BR mdoc (7) +.so man7/groff_man.7 diff --git a/man7/math_error.7 b/man7/math_error.7 index d3b3c1a..6fdff9a 100644 --- a/man7/math_error.7 +++ b/man7/math_error.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH math_error 7 2023-05-03 "Linux man-pages 6.05.01" +.TH math_error 7 2023-10-31 "Linux man-pages 6.7" .SH NAME math_error \- detecting errors from mathematical functions .SH SYNOPSIS @@ -30,33 +30,33 @@ and as outlined below) described in .BR fenv (3). -.PP +.P A portable program that needs to check for an error from a mathematical function should set .I errno to zero, and make the following call -.PP +.P .in +4n .EX feclearexcept(FE_ALL_EXCEPT); .EE .in -.PP +.P before calling a mathematical function. -.PP +.P Upon return from the mathematical function, if .I errno is nonzero, or the following call (see .BR fenv (3)) returns nonzero -.PP +.P .in +4n .EX fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW); .EE .in -.PP +.P .\" enum .\" { .\" FE_INVALID = 0x01, @@ -67,7 +67,7 @@ fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | .\" FE_INEXACT = 0x20 .\" }; then an error occurred in the mathematical function. -.PP +.P The error conditions that can occur for mathematical functions are described below. .SS Domain error @@ -117,7 +117,7 @@ occurs when the magnitude of the function result means that it cannot be represented in the result type of the function. The return value of the function depends on whether the range error was an overflow or an underflow. -.PP +.P A floating result .I overflows if the result is finite, @@ -139,7 +139,7 @@ is set to and an "overflow" .RB ( FE_OVERFLOW ) floating-point exception is raised. -.PP +.P A floating result .I underflows if the result is too small to be represented in the result type. @@ -154,7 +154,7 @@ may be set to and an "underflow" .RB ( FE_UNDERFLOW ) floating-point exception may be raised. -.PP +.P Some functions deliver a range error if the supplied argument value, or the correct function result, would be .IR subnormal . @@ -186,7 +186,7 @@ A few functions set but don't raise an exception. A very few functions do neither. See the individual manual pages for details. -.PP +.P To avoid the complexities of using .I errno and @@ -199,7 +199,7 @@ For example, the following code ensures that .BR log (3)'s argument is not a NaN and is not zero (a pole error) or less than zero (a domain error): -.PP +.P .in +4n .EX double x, r; @@ -211,13 +211,13 @@ if (isnan(x) || islessequal(x, 0)) { r = log(x); .EE .in -.PP +.P The discussion on this page does not apply to the complex mathematical functions (i.e., those declared by .IR ), which in general are not required to return errors by C99 and POSIX.1. -.PP +.P The .BR gcc (1) .I "\-fno\-math\-errno" @@ -242,5 +242,5 @@ An error can still be tested for using .BR isgreater (3), .BR matherr (3), .BR nan (3) -.PP +.P .I "info libc" diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7 index 0ce2fee..475b44d 100644 --- a/man7/mount_namespaces.7 +++ b/man7/mount_namespaces.7 @@ -4,18 +4,18 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH mount_namespaces 7 2023-05-03 "Linux man-pages 6.05.01" +.TH mount_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME mount_namespaces \- overview of Linux mount namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P Mount namespaces provide isolation of the list of mounts seen by the processes in each namespace instance. Thus, the processes in each of the mount namespace instances will see distinct single-directory hierarchies. -.PP +.P The views provided by the .IR /proc/ pid /mounts , .IR /proc/ pid /mountinfo , @@ -28,7 +28,7 @@ correspond to the mount namespace in which the process with the PID resides. (All of the processes that reside in the same mount namespace will see the same view in these files.) -.PP +.P A new mount namespace is created using either .BR clone (2) or @@ -48,7 +48,7 @@ If the namespace is created using .BR unshare (2), the mount list of the new namespace is a copy of the mount list in the caller's previous mount namespace. -.PP +.P Subsequent modifications to the mount list .RB ( mount (2) and @@ -75,7 +75,7 @@ between namespaces (or, more precisely, between the mounts that are members of a .I peer group that are propagating events to one another). -.PP +.P Each mount is marked (via .BR mount (2)) as having one of the following @@ -148,16 +148,16 @@ flags) is performed on a directory subtree, any bind mounts within the subtree are automatically pruned (i.e., not replicated) when replicating that subtree to produce the target subtree. -.PP +.P For a discussion of the propagation type assigned to a new mount, see NOTES. -.PP +.P The propagation type is a per-mount-point setting; some mounts may be marked as shared (with each shared mount being a member of a distinct peer group), while others are private (or slaved or unbindable). -.PP +.P Note that a mount's propagation type determines whether .BR mount (2) and @@ -171,7 +171,7 @@ What happens if the mount itself is unmounted is determined by the propagation type that is in effect for the .I parent of the mount. -.PP +.P Members are added to a .I peer group when a mount is marked as shared and either: @@ -179,21 +179,21 @@ when a mount is marked as shared and either: the mount is replicated during the creation of a new mount namespace; or .IP (b) a new bind mount is created from the mount. -.PP +.P In both of these cases, the new mount joins the peer group of which the existing mount is a member. -.PP +.P A new peer group is also created when a child mount is created under an existing mount that is marked as shared. In this case, the new child mount is also marked as shared and the resulting peer group consists of all the mounts that are replicated under the peers of parent mounts. -.PP +.P A mount ceases to be a member of a peer group when either the mount is explicitly unmounted, or when the mount is implicitly unmounted because a mount namespace is removed (because it has no more member processes). -.PP +.P The propagation type of the mounts in a mount namespace can be discovered via the "optional fields" exposed in .IR /proc/ pid /mountinfo . @@ -239,14 +239,14 @@ For further details, see below. .TP .I unbindable This is an unbindable mount. -.PP +.P If none of the above tags is present, then this is a private mount. .SS MS_SHARED and MS_PRIVATE example Suppose that on a terminal in the initial mount namespace, we mark one mount as shared and another as private, and then view the mounts in .IR /proc/self/mountinfo : -.PP +.P .in +4n .EX sh1# \fBmount \-\-make\-shared /mntS\fP @@ -256,7 +256,7 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 83 61 8:15 / /mntP rw,relatime .EE .in -.PP +.P From the .I /proc/self/mountinfo output, we see that @@ -273,18 +273,18 @@ and is the root directory, .IR / , which is mounted as private: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]\fP 61 0 8:2 / / rw,relatime .EE .in -.PP +.P On a second terminal, we create a new mount namespace where we run a second shell and inspect the mounts: -.PP +.P .in +4n .EX $ \fBPS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh\fP @@ -293,7 +293,7 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 225 145 8:15 / /mntP rw,relatime .EE .in -.PP +.P The new mount namespace received a copy of the initial mount namespace's mounts. These new mounts maintain the same propagation types, @@ -305,13 +305,13 @@ option prevents from marking all mounts as private when creating a new mount namespace, .\" Since util-linux 2.27 which it does by default.) -.PP +.P In the second terminal, we then create submounts under each of .I /mntS and .I /mntP and inspect the set-up: -.PP +.P .in +4n .EX sh2# \fBmkdir /mntS/a\fP @@ -325,13 +325,13 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 230 225 8:23 / /mntP/b rw,relatime .EE .in -.PP +.P From the above, it can be seen that .I /mntS/a was created as shared (inheriting this setting from its parent mount) and .I /mntP/b was created as a private mount. -.PP +.P Returning to the first terminal and inspecting the set-up, we see that the new mount created under the shared mount .I /mntS @@ -339,7 +339,7 @@ propagated to its peer mount (in the initial mount namespace), but the new mount created under the private mount .I /mntP did not propagate: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -365,10 +365,10 @@ and .BR umount (2) events under the slave mount from having side effects in other namespaces. -.PP +.P We can demonstrate the effect of slaving by first marking two mounts as shared in the initial mount namespace: -.PP +.P .in +4n .EX sh1# \fBmount \-\-make\-shared /mntX\fP @@ -378,10 +378,10 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 133 83 8:22 / /mntY rw,relatime shared:2 .EE .in -.PP +.P On a second terminal, we create a new mount namespace and inspect the mounts: -.PP +.P .in +4n .EX sh2# \fBunshare \-m \-\-propagation unchanged sh\fP @@ -390,9 +390,9 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 169 167 8:22 / /mntY rw,relatime shared:2 .EE .in -.PP +.P In the new mount namespace, we then mark one of the mounts as a slave: -.PP +.P .in +4n .EX sh2# \fBmount \-\-make\-slave /mntY\fP @@ -401,17 +401,17 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 169 167 8:22 / /mntY rw,relatime master:2 .EE .in -.PP +.P From the above output, we see that .I /mntY is now a slave mount that is receiving propagation events from the shared peer group with the ID 2. -.PP +.P Continuing in the new namespace, we create submounts under each of .I /mntX and .IR /mntY : -.PP +.P .in +4n .EX sh2# \fBmkdir /mntX/a\fP @@ -420,7 +420,7 @@ sh2# \fBmkdir /mntY/b\fP sh2# \fBmount /dev/sda5 /mntY/b\fP .EE .in -.PP +.P When we inspect the state of the mounts in the new mount namespace, we see that .I /mntX/a @@ -428,7 +428,7 @@ was created as a new shared mount (inheriting the "shared" setting from its parent mount) and .I /mntY/b was created as a private mount: -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -438,7 +438,7 @@ sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 175 169 8:5 / /mntY/b rw,relatime .EE .in -.PP +.P Returning to the first terminal (in the initial mount namespace), we see that the mount .I /mntX/a @@ -447,7 +447,7 @@ propagated to the peer (the shared but the mount .I /mntY/b was not propagated: -.PP +.P .in +4n .EX sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -456,11 +456,11 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 174 132 8:3 / /mntX/a rw,relatime shared:3 .EE .in -.PP +.P Now we create a new mount under .I /mntY in the first shell: -.PP +.P .in +4n .EX sh1# \fBmkdir /mntY/c\fP @@ -472,12 +472,12 @@ sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq 178 133 8:1 / /mntY/c rw,relatime shared:4 .EE .in -.PP +.P When we examine the mounts in the second mount namespace, we see that in this case the new mount has been propagated to the slave mount, and that the new mount is itself a slave mount (to peer group 4): -.PP +.P .in +4n .EX sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP @@ -494,9 +494,9 @@ One of the primary purposes of unbindable mounts is to avoid the "mount explosion" problem when repeatedly performing bind mounts of a higher-level subtree at a lower-level mount. The problem is illustrated by the following shell session. -.PP +.P Suppose we have a system with the following mounts: -.PP +.P .in +4n .EX # \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP @@ -505,11 +505,11 @@ Suppose we have a system with the following mounts: /dev/sdb7 on /mntY .EE .in -.PP +.P Suppose furthermore that we wish to recursively bind mount the root directory under several users' home directories. We do this for the first user, and inspect the mounts: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/cecilia/\fP @@ -522,10 +522,10 @@ We do this for the first user, and inspect the mounts: /dev/sdb7 on /home/cecilia/mntY .EE .in -.PP +.P When we repeat this operation for the second user, we start to see the explosion problem: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/henry\fP @@ -544,7 +544,7 @@ we start to see the explosion problem: /dev/sdb7 on /home/henry/home/cecilia/mntY .EE .in -.PP +.P Under .IR /home/henry , we have not only recursively added the @@ -556,7 +556,7 @@ mounts, but also the recursive mounts of those directories under that were created in the previous step. Upon repeating the step for a third user, it becomes obvious that the explosion is exponential in nature: -.PP +.P .in +4n .EX # \fBmount \-\-rbind / /home/otto\fP @@ -587,21 +587,21 @@ it becomes obvious that the explosion is exponential in nature: /dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY .EE .in -.PP +.P The mount explosion problem in the above scenario can be avoided by making each of the new mounts unbindable. The effect of doing this is that recursive mounts of the root directory will not replicate the unbindable mounts. We make such a mount for the first user: -.PP +.P .in +4n .EX # \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP .EE .in -.PP +.P Before going further, we show that unbindable mounts are indeed unbindable: -.PP +.P .in +4n .EX # \fBmkdir /mntZ\fP @@ -613,21 +613,21 @@ mount: wrong fs type, bad option, bad superblock on /home/cecilia, dmesg | tail or so. .EE .in -.PP +.P Now we create unbindable recursive bind mounts for the other two users: -.PP +.P .in +4n .EX # \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP # \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP .EE .in -.PP +.P Upon examining the list of mounts, we see there has been no explosion of mounts, because the unbindable mounts were not replicated under each user's directory: -.PP +.P .in +4n .EX # \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP @@ -666,9 +666,9 @@ slave+shared slave+shared slave priv unbind private shared priv [2] priv unbind unbindable shared unbind [2] priv unbind .TE -.sp 1 +.P Note the following details to the table: -.IP [1] 4 +.IP [1] 5 If a shared mount is the only mount in its peer group, making it a slave automatically makes it private. .IP [2] @@ -676,13 +676,13 @@ Slaving a nonshared mount has no effect on the mount. .\" .SS Bind (MS_BIND) semantics Suppose that the following command is performed: -.PP +.P .in +4n .EX mount \-\-bind A/a B/b .EE .in -.PP +.P Here, .I A is the source mount, @@ -702,7 +702,7 @@ depends on the propagation types of the mounts and .IR B , and is summarized in the following table. -.PP +.P .TS lb2 lb1 lb2 lb2 lb2 lb0 lb2 lb1 lb2 lb2 lb2 lb0 @@ -713,24 +713,24 @@ _ dest(B) shared shared shared slave+shared invalid nonshared shared private slave invalid .TE -.sp 1 +.P Note that a recursive bind of a subtree follows the same semantics as for a bind operation on each mount in the subtree. (Unbindable mounts are automatically pruned at the target mount point.) -.PP +.P For further details, see .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. .\" .SS Move (MS_MOVE) semantics Suppose that the following command is performed: -.PP +.P .in +4n .EX mount \-\-move A B/b .EE .in -.PP +.P Here, .I A is the source mount, @@ -746,7 +746,7 @@ depends on the propagation types of the mounts and .IR B , and is summarized in the following table. -.PP +.P .TS lb2 lb1 lb2 lb2 lb2 lb0 lb2 lb1 lb2 lb2 lb2 lb0 @@ -757,22 +757,22 @@ _ dest(B) shared shared shared slave+shared invalid nonshared shared private slave unbindable .TE -.sp 1 +.P Note: moving a mount that resides under a shared mount is invalid. -.PP +.P For further details, see .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. .\" .SS Mount semantics Suppose that we use the following command to create a mount: -.PP +.P .in +4n .EX mount device B/b .EE .in -.PP +.P Here, .I B is the destination mount, and @@ -787,13 +787,13 @@ is considered always to be private. .\" .SS Unmount semantics Suppose that we use the following command to tear down a mount: -.PP +.P .in +4n .EX umount A .EE .in -.PP +.P Here, .I A is a mount on @@ -822,7 +822,7 @@ record in cases where a process can't see a slave's immediate master the filesystem root directory) and so cannot determine the chain of propagation between the mounts it can see. -.PP +.P In the following example, we first create a two-link master-slave chain between the mounts .IR /mnt , @@ -837,7 +837,7 @@ mount point unreachable from the root directory, creating a situation where the master of .I /mnt/tmp/etc is not reachable from the (new) root directory of the process. -.PP +.P First, we bind mount the root directory onto .I /mnt and then bind mount @@ -850,7 +850,7 @@ the .BR proc (5) filesystem remains visible at the correct location in the chroot-ed environment. -.PP +.P .in +4n .EX # \fBmkdir \-p /mnt/proc\fP @@ -858,11 +858,11 @@ in the chroot-ed environment. # \fBmount \-\-bind /proc /mnt/proc\fP .EE .in -.PP +.P Next, we ensure that the .I /mnt mount is a shared mount in a new peer group (with no peers): -.PP +.P .in +4n .EX # \fBmount \-\-make\-private /mnt\fP # Isolate from any previous peer group @@ -872,12 +872,12 @@ mount is a shared mount in a new peer group (with no peers): 248 239 0:4 / /mnt/proc ... shared:5 .EE .in -.PP +.P Next, we bind mount .I /mnt/etc onto .IR /tmp/etc : -.PP +.P .in +4n .EX # \fBmkdir \-p /tmp/etc\fP @@ -888,7 +888,7 @@ onto 267 40 8:2 /etc /tmp/etc ... shared:102 .EE .in -.PP +.P Initially, these two mounts are in the same peer group, but we then make the .I /tmp/etc @@ -898,7 +898,7 @@ and then make .I /tmp/etc shared as well, so that it can propagate events to the next slave in the chain: -.PP +.P .in +4n .EX # \fBmount \-\-make\-slave /tmp/etc\fP @@ -909,7 +909,7 @@ so that it can propagate events to the next slave in the chain: 267 40 8:2 /etc /tmp/etc ... shared:105 master:102 .EE .in -.PP +.P Then we bind mount .I /tmp/etc onto @@ -919,7 +919,7 @@ but we then make .I /mnt/tmp/etc a slave of .IR /tmp/etc : -.PP +.P .in +4n .EX # \fBmkdir \-p /mnt/tmp/etc\fP @@ -932,30 +932,30 @@ a slave of 273 239 8:2 /etc /mnt/tmp/etc ... master:105 .EE .in -.PP +.P From the above, we see that .I /mnt is the master of the slave .IR /tmp/etc , which in turn is the master of the slave .IR /mnt/tmp/etc . -.PP +.P We then .BR chroot (1) to the .I /mnt directory, which renders the mount with ID 267 unreachable from the (new) root directory: -.PP +.P .in +4n .EX # \fBchroot /mnt\fP .EE .in -.PP +.P When we examine the state of the mounts inside the chroot-ed environment, we see the following: -.PP +.P .in +4n .EX # \fBcat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP @@ -964,7 +964,7 @@ we see the following: 273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102 .EE .in -.PP +.P Above, we see that the mount with ID 273 is a slave whose master is the peer group 105. The mount point for that master is unreachable, and so a @@ -992,7 +992,7 @@ then the propagation type of the new mount is also .BR MS_SHARED . Otherwise, the propagation type of the new mount is .BR MS_PRIVATE . -.PP +.P Notwithstanding the fact that the default propagation type for new mount is in many cases .BR MS_PRIVATE , @@ -1005,7 +1005,7 @@ automatically remounts all mounts as on system startup. Thus, on most modern systems, the default propagation type is in practice .BR MS_SHARED . -.PP +.P Since, when one uses .BR unshare (1) to create a mount namespace, @@ -1020,18 +1020,18 @@ by making all mounts private in the new namespace. That is, .BR unshare (1) performs the equivalent of the following in the new mount namespace: -.PP +.P .in +4n .EX mount \-\-make\-rprivate / .EE .in -.PP +.P To prevent this, one can use the .I \-\-propagation\~unchanged option to .BR unshare (1). -.PP +.P An application that creates a new mount namespace directly using .BR clone (2) or @@ -1045,13 +1045,13 @@ mounts in the new namespace to either or .BR MS_PRIVATE , using a call such as the following: -.PP +.P .in +4n .EX mount(NULL, "/", MS_SLAVE | MS_REC, NULL); .EE .in -.PP +.P For a discussion of propagation types when moving mounts .RB ( MS_MOVE ) and creating bind mounts @@ -1063,7 +1063,7 @@ see .\" .SS Restrictions on mount namespaces Note the following points with respect to mount namespaces: -.IP [1] 4 +.IP [1] 5 Each mount namespace has an owner user namespace. As explained above, when a new mount namespace is created, its mount list is initialized as a copy of the mount list @@ -1366,6 +1366,6 @@ See .BR pam_namespace (8), .BR pivot_root (8), .BR umount (8) -.PP +.P .I Documentation/filesystems/sharedsubtree.rst in the kernel source tree. diff --git a/man7/mq_overview.7 b/man7/mq_overview.7 index b022ea0..223f238 100644 --- a/man7/mq_overview.7 +++ b/man7/mq_overview.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH mq_overview 7 2023-02-05 "Linux man-pages 6.05.01" +.TH mq_overview 7 2023-10-31 "Linux man-pages 6.7" .SH NAME mq_overview \- overview of POSIX message queues .SH DESCRIPTION @@ -14,7 +14,7 @@ This API is distinct from that provided by System V message queues .BR msgsnd (2), .BR msgrcv (2), etc.), but provides similar functionality. -.PP +.P Message queues are created and opened using .BR mq_open (3); this function returns a @@ -29,7 +29,7 @@ that is, a null-terminated string of up to followed by one or more characters, none of which are slashes. Two processes can operate on the same queue by passing the same name to .BR mq_open (3). -.PP +.P Messages are transferred to and from a queue using .BR mq_send (3) and @@ -45,7 +45,7 @@ and A process can request asynchronous notification of the arrival of a message on a previously empty queue using .BR mq_notify (3). -.PP +.P A message queue descriptor is a reference to an .I "open message queue description" (see @@ -58,7 +58,7 @@ as the corresponding message queue descriptors in the parent. Corresponding message queue descriptors in the two processes share the flags .RI ( mq_flags ) that are associated with the open message queue description. -.PP +.P Each message has an associated .IR priority , and messages are always delivered to the receiving process @@ -71,7 +71,7 @@ On Linux, returns 32768, but POSIX.1 requires only that an implementation support at least priorities in the range 0 to 31; some implementations provide only this range. -.PP +.P The remainder of this section describes some specific details of the Linux implementation of POSIX message queues. .SS Library interfaces and system calls @@ -265,33 +265,33 @@ On Linux, message queues are created in a virtual filesystem. but the details are likely to differ.) This filesystem can be mounted (by the superuser) using the following commands: -.PP +.P .in +4n .EX .RB "#" " mkdir /dev/mqueue" .RB "#" " mount \-t mqueue none /dev/mqueue" .EE .in -.PP +.P The sticky bit is automatically enabled on the mount directory. -.PP +.P After the filesystem has been mounted, the message queues on the system can be viewed and manipulated using the commands usually used for files (e.g., .BR ls (1) and .BR rm (1)). -.PP +.P The contents of each file in the directory consist of a single line containing information about the queue: -.PP +.P .in +4n .EX .RB "$" " cat /dev/mqueue/mymq" QSIZE:129 NOTIFY:2 SIGNO:0 NOTIFY_PID:8260 .EE .in -.PP +.P These fields are as follows: .TP .B QSIZE @@ -325,7 +325,7 @@ This means that a message queue descriptor can be monitored using or .BR epoll (7). This is not portable. -.PP +.P The close-on-exec flag (see .BR open (2)) is automatically set on the file descriptor returned by @@ -344,7 +344,7 @@ POSIX message queues provide a better designed interface than System V message queues; on the other hand POSIX message queues are less widely available (especially on older systems) than System V message queues. -.PP +.P Linux does not currently (Linux 2.6.26) support the use of access control lists (ACLs) for POSIX message queues. .SH BUGS @@ -356,7 +356,7 @@ limit could be raised, and the ceiling was enforced even for privileged processes. This ceiling value was removed in Linux 3.14, and patches to stable Linux 3.5.x to Linux 3.13.x also removed the ceiling. -.PP +.P As originally implemented (and documented), the QSIZE field displayed the total number of (user-supplied) bytes in all messages in the message queue. diff --git a/man7/namespaces.7 b/man7/namespaces.7 index 6ff11af..5fdca2e 100644 --- a/man7/namespaces.7 +++ b/man7/namespaces.7 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH namespaces 7 2023-07-20 "Linux man-pages 6.05.01" +.TH namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME namespaces \- overview of Linux namespaces .SH DESCRIPTION @@ -15,7 +15,7 @@ have their own isolated instance of the global resource. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. One use of namespaces is to implement containers. -.PP +.P This page provides pointers to information on the various namespace types, describes the associated .I /proc @@ -108,7 +108,7 @@ Various operations can be used to discover information about namespaces. These operations are described in .BR ioctl_ns (2). -.PP +.P Creation of new namespaces using .BR clone (2) and @@ -131,7 +131,7 @@ Each process has a subdirectory containing one entry for each namespace that supports being manipulated by .BR setns (2): -.PP +.P .in +4n .EX $ \fBls \-l /proc/$$/ns | awk \[aq]{print $1, $9, $10, $11}\[aq]\fP @@ -148,7 +148,7 @@ lrwxrwxrwx. user \-> user:[4026531837] lrwxrwxrwx. uts \-> uts:[4026531838] .EE .in -.PP +.P Bind mounting (see .BR mount (2)) one of the files in this directory @@ -156,7 +156,7 @@ to somewhere else in the filesystem keeps the corresponding namespace of the process specified by .I pid alive even if all processes currently in the namespace terminate. -.PP +.P Opening one of the files in this directory (or a file that is bind mounted to one of these files) returns a file handle for @@ -167,7 +167,7 @@ the namespace will remain alive, even if all processes in the namespace terminate. The file descriptor can be passed to .BR setns (2). -.PP +.P In Linux 3.7 and earlier, these files were visible as hard links. Since Linux 3.8, .\" commit bf056bfa80596a5d14b26b17276a56a0dcb080e5 @@ -188,14 +188,14 @@ fields returned by .BR stat (2). The content of this symbolic link is a string containing the namespace type and inode number as in the following example: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/uts\fP uts:[4026531838] .EE .in -.PP +.P The symbolic links in this subdirectory are as follows: .TP .IR /proc/ pid /ns/cgroup " (since Linux 4.6)" @@ -256,7 +256,7 @@ This file is a handle for the user namespace of the process. .TP .IR /proc/ pid /ns/uts " (since Linux 3.0)" This file is a handle for the UTS namespace of the process. -.PP +.P Permission to dereference or read .RB ( readlink (2)) these symbolic links is governed by a ptrace access mode @@ -305,7 +305,7 @@ user namespaces that may be created in the user namespace. .I max_uts_namespaces The value in this file defines a per-user limit on the number of uts namespaces that may be created in the user namespace. -.PP +.P Note the following details about these files: .IP \[bu] 3 The values in these files are modifiable by privileged processes. diff --git a/man7/netdevice.7 b/man7/netdevice.7 index a0f0049..9f9f002 100644 --- a/man7/netdevice.7 +++ b/man7/netdevice.7 @@ -10,7 +10,7 @@ .\" Modified, 2011-11-02, , added many basic .\" but missing ioctls, such as SIOCGIFADDR. .\" -.TH netdevice 7 2023-07-15 "Linux man-pages 6.05.01" +.TH netdevice 7 2023-10-31 "Linux man-pages 6.7" .SH NAME netdevice \- low-level access to Linux network devices .SH SYNOPSIS @@ -21,14 +21,14 @@ netdevice \- low-level access to Linux network devices .SH DESCRIPTION This man page describes the sockets interface which is used to configure network devices. -.PP +.P Linux supports some standard ioctls to configure network devices. They can be used on any socket's file descriptor regardless of the family or type. Most of them pass an .I ifreq structure: -.PP +.P .in +4n .EX struct ifreq { @@ -51,13 +51,13 @@ struct ifreq { }; .EE .in -.PP +.P .B AF_INET6 is an exception. It passes an .I in6_ifreq structure: -.PP +.P .in +4n .EX struct in6_ifreq { @@ -67,7 +67,7 @@ struct in6_ifreq { }; .EE .in -.PP +.P Normally, the user specifies which device to affect by setting .I ifr_name to the name of the interface or @@ -96,7 +96,9 @@ This is the only ioctl which returns its result in Retrieve the interface index of the interface into .IR ifr_ifindex . .TP -.BR SIOCGIFFLAGS ", " SIOCSIFFLAGS +.B SIOCGIFFLAGS +.TQ +.B SIOCSIFFLAGS Get or set the active flag word of the device. .I ifr_flags contains a bit mask of the following values: @@ -132,11 +134,13 @@ IFF_DORMANT:Driver signals dormant (since Linux 2.6.17) IFF_ECHO:Echo sent packets (since Linux 2.6.25) .TE .ad -.PP +.P Setting the active flag word is a privileged operation, but any process may read it. .TP -.BR SIOCGIFPFLAGS ", " SIOCSIFPFLAGS +.B SIOCGIFPFLAGS +.TQ +.B SIOCSIFPFLAGS Get or set extended (private) flags for the device. .I ifr_flags contains a bit mask of the following values: @@ -154,10 +158,14 @@ IFF_BONDING:Interface is a bonding master or slave. IFF_SLAVE_NEEDARP:Interface needs ARPs for validation. IFF_ISATAP:Interface is RFC4214 ISATAP interface. .TE -.PP +.P Setting the extended (private) interface flags is a privileged operation. .TP -.BR SIOCGIFADDR ", " SIOCSIFADDR ", " SIOCDIFADDR +.B SIOCGIFADDR +.TQ +.B SIOCSIFADDR +.TQ +.B SIOCDIFADDR Get, set, or delete the address of the device using .IR ifr_addr , or @@ -185,7 +193,9 @@ A address can be deleted by setting it to zero via .BR SIOCSIFADDR . .TP -.BR SIOCGIFDSTADDR ", " SIOCSIFDSTADDR +.B SIOCGIFDSTADDR +.TQ +.B SIOCSIFDSTADDR Get or set the destination address of a point-to-point device using .IR ifr_dstaddr . For compatibility, only @@ -193,7 +203,9 @@ For compatibility, only addresses are accepted or returned. Setting the destination address is a privileged operation. .TP -.BR SIOCGIFBRDADDR ", " SIOCSIFBRDADDR +.B SIOCGIFBRDADDR +.TQ +.B SIOCSIFBRDADDR Get or set the broadcast address for a device using .IR ifr_brdaddr . For compatibility, only @@ -201,7 +213,9 @@ For compatibility, only addresses are accepted or returned. Setting the broadcast address is a privileged operation. .TP -.BR SIOCGIFNETMASK ", " SIOCSIFNETMASK +.B SIOCGIFNETMASK +.TQ +.B SIOCSIFNETMASK Get or set the network mask for a device using .IR ifr_netmask . For compatibility, only @@ -209,7 +223,9 @@ For compatibility, only addresses are accepted or returned. Setting the network mask is a privileged operation. .TP -.BR SIOCGIFMETRIC ", " SIOCSIFMETRIC +.B SIOCGIFMETRIC +.TQ +.B SIOCSIFMETRIC Get or set the metric of the device using .IR ifr_metric . This is currently not implemented; it sets @@ -218,14 +234,18 @@ to 0 if you attempt to read it and returns .B EOPNOTSUPP if you attempt to set it. .TP -.BR SIOCGIFMTU ", " SIOCSIFMTU +.B SIOCGIFMTU +.TQ +.B SIOCSIFMTU Get or set the MTU (Maximum Transfer Unit) of a device using .IR ifr_mtu . Setting the MTU is a privileged operation. Setting the MTU to too small values may cause kernel crashes. .TP -.BR SIOCGIFHWADDR ", " SIOCSIFHWADDR +.B SIOCGIFHWADDR +.TQ +.B SIOCSIFHWADDR Get or set the hardware address of a device using .IR ifr_hwaddr . The hardware address is specified in a struct @@ -241,7 +261,9 @@ Set the hardware broadcast address of a device from .IR ifr_hwaddr . This is a privileged operation. .TP -.BR SIOCGIFMAP ", " SIOCSIFMAP +.B SIOCGIFMAP +.TQ +.B SIOCSIFMAP Get or set the interface's hardware parameters using .IR ifr_map . Setting the parameters is a privileged operation. @@ -262,7 +284,9 @@ struct ifmap { The interpretation of the ifmap structure depends on the device driver and the architecture. .TP -.BR SIOCADDMULTI ", " SIOCDELMULTI +.B SIOCADDMULTI +.TQ +.B SIOCDELMULTI Add an address to or delete an address from the device's link layer multicast filters using .IR ifr_hwaddr . @@ -271,7 +295,9 @@ See also .BR packet (7) for an alternative. .TP -.BR SIOCGIFTXQLEN ", " SIOCSIFTXQLEN +.B SIOCGIFTXQLEN +.TQ +.B SIOCSIFTXQLEN Get or set the transmit queue length of a device using .IR ifr_qlen . Setting the transmit queue length is a privileged operation. @@ -357,19 +383,21 @@ will be returned. .\" Slaving isn't supported in Linux 2.2 .\" . .\" .TP -.\" .BR SIOCGIFSLAVE ", " SIOCSIFSLAVE +.\" .B SIOCGIFSLAVE +.\" .TQ +.\" .B SIOCSIFSLAVE .\" Get or set the slave device using .\" .IR ifr_slave . .\" Setting the slave device is a privileged operation. -.\" .PP +.\" .P .\" FIXME . add amateur radio stuff. -.PP +.P Most protocols support their own ioctls to configure protocol-specific interface options. See the protocol man pages for a description. For configuring IP addresses, see .BR ip (7). -.PP +.P In addition, some devices support private ioctls. These are not described here. .SH NOTES @@ -379,12 +407,12 @@ and the other ioctls that accept or return only socket addresses are IP-specific and perhaps should rather be documented in .BR ip (7). -.PP +.P The names of interfaces with no addresses or that don't have the .B IFF_RUNNING flag set can be found via .IR /proc/net/dev . -.PP +.P .B AF_INET6 IPv6 addresses can be read from .I /proc/net/if_inet6 @@ -406,7 +434,7 @@ glibc 2.1 is missing the macro in .IR . Add the following to your program as a workaround: -.PP +.P .in +4n .EX #ifndef ifr_newname diff --git a/man7/netlink.7 b/man7/netlink.7 index 4d6cdbc..e0e14f4 100644 --- a/man7/netlink.7 +++ b/man7/netlink.7 @@ -6,7 +6,7 @@ .\" Based on the original comments from Alexey Kuznetsov .\" Modified 2005-12-27 by Hasso Tepper .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ -.TH netlink 7 2023-07-30 "Linux man-pages 6.05.01" +.TH netlink 7 2023-10-31 "Linux man-pages 6.7" .SH NAME netlink \- communication between kernel and user space (AF_NETLINK) .SH SYNOPSIS @@ -14,7 +14,7 @@ netlink \- communication between kernel and user space (AF_NETLINK) .B #include .B #include .B #include -.PP +.P .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); .fi .SH DESCRIPTION @@ -26,7 +26,7 @@ The internal kernel interface is not documented in this manual page. There is also an obsolete netlink interface via netlink character devices; this interface is not documented here and is provided only for backward compatibility. -.PP +.P Netlink is a datagram-oriented service. Both .B SOCK_RAW @@ -36,7 +36,7 @@ are valid values for .IR socket_type . However, the netlink protocol does not distinguish between datagram and raw sockets. -.PP +.P .I netlink_family selects the kernel module or netlink group to communicate with. The currently assigned netlink families are: @@ -144,7 +144,7 @@ Generic netlink family for simplified netlink usage. Netlink interface to request information about ciphers registered with the kernel crypto API as well as allow configuration of the kernel crypto API. -.PP +.P Netlink messages consist of a byte stream with one or multiple .I nlmsghdr headers and associated payload. @@ -154,7 +154,7 @@ macros. See .BR netlink (3) for further information. -.PP +.P In multipart messages (multiple .I nlmsghdr headers with associated payload in one byte stream) the first and all @@ -162,11 +162,11 @@ following headers have the .B NLM_F_MULTI flag set, except for the last header which has the type .BR NLMSG_DONE . -.PP +.P After each .I nlmsghdr the payload follows. -.PP +.P .in +4n .EX struct nlmsghdr { @@ -178,7 +178,7 @@ struct nlmsghdr { }; .EE .in -.PP +.P .I nlmsg_type can be one of the standard message types: .B NLMSG_NOOP @@ -192,7 +192,7 @@ message terminates a multipart message. Error messages get the original request appended, unless the user requests to cap the error message, and get extra error data if requested. -.PP +.P .in +4n .EX struct nlmsgerr { @@ -212,7 +212,7 @@ struct nlmsgerr { }; .EE .in -.PP +.P A netlink family usually specifies more message types, see the appropriate manual pages for that, for example, .BR rtnetlink (7) @@ -261,7 +261,7 @@ Convenience macro; equivalent to T} .TE .\" FIXME NLM_F_ATOMIC is not used anymore? -.PP +.P Note that .B NLM_F_ATOMIC requires the @@ -286,7 +286,7 @@ NLM_F_APPEND:T{ Add to the end of the object list. T} .TE -.PP +.P .I nlmsg_seq and .I nlmsg_pid @@ -300,14 +300,14 @@ socket. See the .B ADDRESS FORMATS section for further information. -.PP +.P Both .I nlmsg_seq and .I nlmsg_pid .\" FIXME Explain more about nlmsg_seq and nlmsg_pid. are opaque to netlink core. -.PP +.P Netlink is not a reliable protocol. It tries its best to deliver a message to its destination(s), but may drop messages when an out-of-memory condition or @@ -325,7 +325,7 @@ The kernel tries to send an .B NLMSG_ERROR message for every failed packet. A user process should follow this convention too. -.PP +.P However, reliable transmissions from kernel to user are impossible in any case. The kernel can't send a netlink message if the socket buffer is full: @@ -346,7 +346,7 @@ can be either unicast (only sent to one peer) or sent to netlink multicast groups .RI ( nl_groups not equal 0). -.PP +.P .in +4n .EX struct sockaddr_nl { @@ -357,7 +357,7 @@ struct sockaddr_nl { }; .EE .in -.PP +.P .I nl_pid is the unicast address of netlink socket. It's always 0 if the destination is in the kernel. @@ -386,7 +386,7 @@ The kernel assigns the process ID to the first netlink socket the process opens and assigns a unique .I nl_pid to every netlink socket that the process subsequently creates. -.PP +.P .I nl_groups is a bit mask with every bit representing a netlink group number. Each netlink family has a set of 32 multicast groups. @@ -443,7 +443,9 @@ Enable control messages for received packets to get the extended destination group number. .TP -.BR NETLINK_ADD_MEMBERSHIP ,\ NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" +.B NETLINK_ADD_MEMBERSHIP +.TQ +.BR NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)" .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99 .\" Author: Patrick McHardy Join/leave a group specified by @@ -502,7 +504,7 @@ The netlink message header is still included, so the user can guess from the sequence number which message triggered the acknowledgement. .SH VERSIONS The socket interface to netlink first appeared Linux 2.2. -.PP +.P Linux 2.0 supported a more primitive device-based netlink interface (which is still available as a compatibility option). This obsolete interface is not described here. @@ -522,7 +524,7 @@ netlink socket which will listen to the (network interface create/delete/up/down events) and .B RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) multicast groups. -.PP +.P .in +4n .EX struct sockaddr_nl sa; @@ -535,12 +537,12 @@ fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); bind(fd, (struct sockaddr *) &sa, sizeof(sa)); .EE .in -.PP +.P The next example demonstrates how to send a netlink message to the kernel (pid 0). Note that the application must take care of message sequence numbers in order to reliably track acknowledgements. -.PP +.P .in +4n .EX struct nlmsghdr *nh; /* The nlmsghdr with payload to send */ @@ -559,9 +561,9 @@ nh\->nlmsg_flags |= NLM_F_ACK; sendmsg(fd, &msg, 0); .EE .in -.PP +.P And the last example is about reading netlink message. -.PP +.P .in +4n .EX int len; @@ -597,13 +599,13 @@ for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); .BR capabilities (7), .BR rtnetlink (7), .BR sock_diag (7) -.PP +.P .UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2* information about libnetlink .UE -.PP +.P .UR http://www.infradead.org\:/\[ti]tgr\:/libnl/ information about libnl .UE -.PP +.P RFC 3549 "Linux Netlink as an IP Services Protocol" diff --git a/man7/network_namespaces.7 b/man7/network_namespaces.7 index a9e6306..06d323f 100644 --- a/man7/network_namespaces.7 +++ b/man7/network_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH network_namespaces 7 2023-03-12 "Linux man-pages 6.05.01" +.TH network_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME network_namespaces \- overview of Linux network namespaces .SH DESCRIPTION @@ -21,7 +21,7 @@ port numbers (sockets), and so on. In addition, network namespaces isolate the UNIX domain abstract socket namespace (see .BR unix (7)). -.PP +.P A physical network device can live in exactly one network namespace. When a network namespace is freed @@ -29,7 +29,7 @@ When a network namespace is freed its physical network devices are moved back to the initial network namespace (not to the namespace of the parent of the process). -.PP +.P A virtual network .RB ( veth (4)) device pair provides a pipe-like abstraction @@ -39,7 +39,7 @@ in another namespace. When a namespace is freed, the .BR veth (4) devices that it contains are destroyed. -.PP +.P Use of network namespaces requires a kernel that is configured with the .B CONFIG_NET_NS option. diff --git a/man7/nptl.7 b/man7/nptl.7 index a00c845..421ad5f 100644 --- a/man7/nptl.7 +++ b/man7/nptl.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH nptl 7 2023-02-05 "Linux man-pages 6.05.01" +.TH nptl 7 2023-10-31 "Linux man-pages 6.7" .SH NAME nptl \- Native POSIX Threads Library .SH DESCRIPTION @@ -20,7 +20,7 @@ One of these signals is used to support thread cancelation and POSIX timers the other is used as part of a mechanism that ensures all threads in a process always have the same UIDs and GIDs, as required by POSIX. These signals cannot be used in applications. -.PP +.P To prevent accidental use of these signals in applications, which might interfere with the operation of the NPTL implementation, various glibc library functions and system call wrapper functions @@ -66,7 +66,7 @@ the NPTL implementation wraps all of the system calls that change process credentials with functions that, in addition to invoking the underlying system call, arrange for all other threads in the process to also change their credentials. -.PP +.P The implementation of each of these system calls involves the use of a real-time signal that is sent (using .BR tgkill (2)) @@ -76,7 +76,7 @@ saves the new credential(s) and records the system call being employed in a global buffer. A signal handler in the receiving thread(s) fetches this information and then uses the same system call to change its credentials. -.PP +.P Wrapper functions employing this technique are provided for .BR setgid (2), .BR setuid (2), diff --git a/man7/numa.7 b/man7/numa.7 index 9ac5097..0365469 100644 --- a/man7/numa.7 +++ b/man7/numa.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH numa 7 2023-04-03 "Linux man-pages 6.05.01" +.TH numa 7 2023-10-31 "Linux man-pages 6.7" .SH NAME numa \- overview of Non-Uniform Memory Architecture .SH DESCRIPTION @@ -35,11 +35,11 @@ see "Library Support" below. .\" See also Changelog-2.6.14 This file displays information about a process's NUMA memory policy and allocation. -.PP +.P Each line contains information about a memory range used by the process, displaying\[em]among other information\[em]the effective memory policy for that memory range and on which nodes the pages have been allocated. -.PP +.P .I numa_maps is a read-only file. When @@ -47,14 +47,14 @@ When is read, the kernel will scan the virtual address space of the process and report how memory is used. One line is displayed for each unique memory range of the process. -.PP +.P The first field of each line shows the starting address of the memory range. This field allows a correlation with the contents of the .IR /proc/ pid /maps file, which contains the end address of the range and other information, such as the access permissions and sharing. -.PP +.P The second field shows the memory policy currently in effect for the memory range. Note that the effective policy is not necessarily the policy @@ -62,7 +62,7 @@ installed by the process for that memory range. Specifically, if the process installed a "default" policy for that range, the effective policy for that range will be the process policy, which may or may not be "default". -.PP +.P The rest of the line contains information about the pages allocated in the memory range, as follows: .TP @@ -143,7 +143,7 @@ and the required header are available in the .I numactl package. -.PP +.P However, applications should not use these system calls directly. Instead, the higher level interface provided by the .BR numa (3) diff --git a/man7/operator.7 b/man7/operator.7 index ec4652f..047041e 100644 --- a/man7/operator.7 +++ b/man7/operator.7 @@ -14,12 +14,12 @@ .\" .\" 2007-12-08, mtk, Converted from mdoc to man macros .\" -.TH operator 7 2023-02-05 "Linux man-pages 6.05.01" +.TH operator 7 2023-10-31 "Linux man-pages 6.7" .SH NAME operator \- C operator precedence and order of evaluation .SH DESCRIPTION This manual page lists C operators and their precedence in evaluation. -.PP +.P .TS lb lb lb l l l. @@ -41,11 +41,11 @@ Operator Associativity Notes = *= /= %= += \-= <<= >>= &= \[ha]= |= right to left , left to right .TE -.PP +.P The following notes provide further information to the above table: -.PP +.P .PD 0 -.IP [1] 4 +.IP [1] 5 The ++ and \-\- operators at this precedence level are the postfix flavors of the operators. .IP [2] diff --git a/man7/packet.7 b/man7/packet.7 index b2a264c..5d9d0cf 100644 --- a/man7/packet.7 +++ b/man7/packet.7 @@ -4,7 +4,7 @@ .\" .\" $Id: packet.7,v 1.13 2000/08/14 08:03:45 ak Exp $ .\" -.TH packet 7 2023-07-15 "Linux man-pages 6.05.01" +.TH packet 7 2023-10-31 "Linux man-pages 6.7" .SH NAME packet \- packet interface on device level .SH SYNOPSIS @@ -12,7 +12,7 @@ packet \- packet interface on device level .B #include .B #include .B #include /* the L2 protocols */ -.PP +.P .BI "packet_socket = socket(AF_PACKET, int " socket_type ", int "protocol ); .fi .SH DESCRIPTION @@ -20,7 +20,7 @@ Packet sockets are used to receive or send raw packets at the device driver (OSI Layer 2) level. They allow the user to implement protocol modules in user space on top of the physical layer. -.PP +.P The .I socket_type is either @@ -50,11 +50,11 @@ no packets are received. can optionally be called with a nonzero .I sll_protocol to start receiving packets for the protocols specified. -.PP +.P In order to create a packet socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. -.PP +.P .B SOCK_RAW packets are passed to and from the device driver without any changes in the packet data. @@ -72,7 +72,7 @@ Some device drivers always add other headers. is similar to but not compatible with the obsolete .B AF_INET/SOCK_PACKET of Linux 2.0. -.PP +.P .B SOCK_DGRAM operates on a slightly higher level. The physical header is removed before the packet is passed to the user. @@ -82,7 +82,7 @@ packet socket get a suitable physical-layer header based on the information in the .I sockaddr_ll destination address before they are queued. -.PP +.P By default, all packets of the specified protocol type are passed to a packet socket. To get packets only from a specific interface use @@ -97,11 +97,11 @@ Fields used for binding are .IR sll_protocol , and .IR sll_ifindex . -.PP +.P The .BR connect (2) operation is not supported on packet sockets. -.PP +.P When the .B MSG_TRUNC flag is passed to @@ -115,7 +115,7 @@ even when it is longer than the buffer. The .I sockaddr_ll structure is a device-independent physical-layer address. -.PP +.P .in +4n .EX struct sockaddr_ll { @@ -129,7 +129,7 @@ struct sockaddr_ll { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sll_protocol @@ -171,7 +171,7 @@ These types make sense only for receiving. .I sll_halen contain the physical-layer (e.g., IEEE 802.3) address and its length. The exact interpretation depends on the device. -.PP +.P When you send packets, it is enough to specify .IR sll_family , .IR sll_addr , @@ -502,7 +502,7 @@ Argument is a .I struct timeval variable. .\" FIXME Document SIOCGSTAMPNS -.PP +.P In addition, all standard ioctls defined in .BR netdevice (7) and @@ -546,7 +546,7 @@ Interface address contained an invalid interface index. .TP .B EPERM User has insufficient privileges to carry out this operation. -.PP +.P In addition, other errors may be generated by the low-level driver. .SH VERSIONS .B AF_PACKET @@ -561,7 +561,7 @@ via although this covers only a subset of the .B AF_PACKET features. -.PP +.P The .B SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC @@ -582,17 +582,17 @@ bind to instead and do the protocol multiplex yourself. The default for sending is the standard Ethernet DIX encapsulation with the protocol filled in. -.PP +.P Packet sockets are not subject to the input or output firewall chains. .SS Compatibility In Linux 2.0, the only way to get a packet socket was with the call: -.PP +.P .in +4n .EX socket(AF_INET, SOCK_PACKET, protocol) .EE .in -.PP +.P This is still supported, but deprecated and strongly discouraged. The main difference between the two methods is that .B SOCK_PACKET @@ -600,7 +600,7 @@ uses the old .I struct sockaddr_pkt to specify an interface, which doesn't provide physical-layer independence. -.PP +.P .in +4n .EX struct sockaddr_pkt { @@ -610,7 +610,7 @@ struct sockaddr_pkt { }; .EE .in -.PP +.P .I spkt_family contains the device type, @@ -620,7 +620,7 @@ is the IEEE 802.3 protocol type as defined in and .I spkt_device is the device name as a null-terminated string, for example, eth0. -.PP +.P This structure is obsolete and should not be used in new code. .SH BUGS .SS LLC header handling @@ -648,12 +648,12 @@ This means the names of network devices longer than 14 bytes will be truncated to fit into .IR spkt_device . All these lengths include the terminating null byte (\[aq]\e0\[aq])). -.PP +.P Issues from this with old code typically show up with very long interface names used by the .B Predictable Network Interface Names feature enabled by default in many modern Linux distributions. -.PP +.P The preferred solution is to rewrite code to avoid .BR SOCK_PACKET . Possible user solutions are to disable @@ -676,14 +676,14 @@ Socket filters are not documented. .BR raw (7), .BR socket (7), .BR ip (8), -.PP +.P RFC\ 894 for the standard IP Ethernet encapsulation. RFC\ 1700 for the IEEE 802.3 IP encapsulation. -.PP +.P The .I include file for physical-layer protocols. -.PP +.P The Linux kernel source tree. .I Documentation/networking/filter.rst describes how to apply Berkeley Packet Filters to packet sockets. diff --git a/man7/path_resolution.7 b/man7/path_resolution.7 index 1704603..ac814ed 100644 --- a/man7/path_resolution.7 +++ b/man7/path_resolution.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH path_resolution 7 2023-02-05 "Linux man-pages 6.05.01" +.TH path_resolution 7 2024-02-18 "Linux man-pages 6.7" .SH NAME path_resolution \- how a pathname is resolved to a file .SH DESCRIPTION @@ -20,7 +20,7 @@ system call, or may temporarily use a different root directory by using with the .B RESOLVE_IN_ROOT flag set. -.PP +.P A process may get an entirely private mount namespace in case it\[em]or one of its ancestors\[em]was started by an invocation of the .BR clone (2) @@ -28,7 +28,7 @@ system call that had the .B CLONE_NEWNS flag set. This handles the \[aq]/\[aq] part of the pathname. -.PP +.P If the pathname does not start with the \[aq]/\[aq] character, the starting lookup directory of the resolution process is the current working directory of the process \[em] or in the case of @@ -44,7 +44,7 @@ The current working directory is inherited from the parent, and can be changed by use of the .BR chdir (2) system call. -.PP +.P Pathnames starting with a \[aq]/\[aq] character are called absolute pathnames. Pathnames not starting with a \[aq]/\[aq] are called relative pathnames. .SS Step 2: walk along the path @@ -52,27 +52,27 @@ Set the current lookup directory to the starting lookup directory. Now, for each nonfinal component of the pathname, where a component is a substring delimited by \[aq]/\[aq] characters, this component is looked up in the current lookup directory. -.PP +.P If the process does not have search permission on the current lookup directory, an .B EACCES error is returned ("Permission denied"). -.PP +.P If the component is not found, an .B ENOENT error is returned ("No such file or directory"). -.PP +.P If the component is found, but is neither a directory nor a symbolic link, an .B ENOTDIR error is returned ("Not a directory"). -.PP +.P If the component is found and is a directory, we set the current lookup directory to that directory, and go to the next component. -.PP +.P If the component is found and is a symbolic link, we first resolve this symbolic link (with the current lookup directory @@ -96,7 +96,7 @@ An .B ELOOP error is returned when the maximum is exceeded ("Too many levels of symbolic links"). -.PP +.P .\" .\" presently: max recursion depth during symlink resolution: 5 .\" max total number of symbolic links followed: 40 @@ -114,7 +114,7 @@ the kernel's pathname-resolution code was reworked to eliminate the use of recursion, so that the only limit that remains is the maximum of 40 resolutions for the entire pathname. -.PP +.P The resolution of symbolic links during this stage can be blocked by using .BR openat2 (2), with the @@ -132,15 +132,15 @@ we are just creating it. The details on the treatment of the final entry are described in the manual pages of the specific system calls. -.SS . and .. +.SS "\&. and .." By convention, every directory has the entries "." and "..", which refer to the directory itself and to its parent directory, respectively. -.PP +.P The path resolution process will assume that these entries have their conventional meanings, regardless of whether they are actually present in the physical filesystem. -.PP +.P One cannot walk up past the root: "/.." is the same as "/". .SS Mount points After a @@ -148,11 +148,11 @@ After a command, the pathname "path" refers to the root of the filesystem hierarchy on the device "dev", and no longer to whatever it referred to earlier. -.PP +.P One can walk out of a mounted filesystem: "path/.." refers to the parent directory of "path", outside of the filesystem hierarchy on "dev". -.PP +.P Traversal of mount points can be blocked by using .BR openat2 (2), with the @@ -202,16 +202,16 @@ effective group ID of the calling process, or is one of the supplementary group IDs of the calling process (as set by .BR setgroups (2)). When neither holds, the third group is used. -.PP +.P Of the three bits used, the first bit determines read permission, the second write permission, and the last execute permission in case of ordinary files, or search permission in case of directories. -.PP +.P Linux uses the fsuid instead of the effective user ID in permission checks. Ordinarily the fsuid will equal the effective user ID, but the fsuid can be changed by the system call .BR setfsuid (2). -.PP +.P (Here "fsuid" stands for something like "filesystem user ID". The concept was required for the implementation of a user space NFS server at a time when processes could send a signal to a process @@ -219,7 +219,7 @@ with the same effective user ID. It is obsolete now. Nobody should use .BR setfsuid (2).) -.PP +.P Similarly, Linux uses the fsgid ("filesystem group ID") instead of the effective group ID. See @@ -236,7 +236,7 @@ when accessing files. .\" on some implementations (e.g., Solaris, FreeBSD), .\" access(X_OK) by superuser will report success, regardless .\" of the file's execute permission bits. -- MTK (Oct 05) -.PP +.P On Linux, superuser privileges are divided into capabilities (see .BR capabilities (7)). Two capabilities are relevant for file permissions checks: @@ -244,13 +244,13 @@ Two capabilities are relevant for file permissions checks: and .BR CAP_DAC_READ_SEARCH . (A process has these capabilities if its fsuid is 0.) -.PP +.P The .B CAP_DAC_OVERRIDE capability overrides all permission checking, but grants execute permission only when at least one of the file's three execute permission bits is set. -.PP +.P The .B CAP_DAC_READ_SEARCH capability grants read and search permission diff --git a/man7/persistent-keyring.7 b/man7/persistent-keyring.7 index 472782a..0db4940 100644 --- a/man7/persistent-keyring.7 +++ b/man7/persistent-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH persistent-keyring 7 2023-02-08 "Linux man-pages 6.05.01" +.TH persistent-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME persistent-keyring \- per-user persistent keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The persistent keyring has a name (description) of the form where .I is the user ID of the corresponding user. -.PP +.P The persistent keyring may not be accessed directly, even by processes with the appropriate UID. .\" FIXME The meaning of the preceding sentence isn't clear. What is meant? @@ -25,34 +25,34 @@ by virtue of its possessor permits. This linking is done with the .BR keyctl_get_persistent (3) function. -.PP +.P If a persistent keyring does not exist when it is accessed by the .BR keyctl_get_persistent (3) operation, it will be automatically created. -.PP +.P Each time the .BR keyctl_get_persistent (3) operation is performed, the persistent keyring's expiration timer is reset to the value in: -.PP +.P .in +4n .EX /proc/sys/kernel/keys/persistent_keyring_expiry .EE .in -.PP +.P Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected. The keyring will then be re-created on a subsequent call to .BR keyctl_get_persistent (3). -.PP +.P The persistent keyring is not directly searched by .BR request_key (2); it is searched only if it is linked into one of the keyrings that is searched by .BR request_key (2). -.PP +.P The persistent keyring is independent of .BR clone (2), .BR fork (2), @@ -72,7 +72,7 @@ The persistent keyring can thus be used to hold authentication tokens for processes that run without user interaction, such as programs started by .BR cron (8). -.PP +.P The persistent keyring is used to store UID-specific objects that themselves have limited lifetimes (e.g., kerberos tokens). If those tokens cease to be used diff --git a/man7/pid_namespaces.7 b/man7/pid_namespaces.7 index b154fb4..90d062b 100644 --- a/man7/pid_namespaces.7 +++ b/man7/pid_namespaces.7 @@ -4,20 +4,20 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH pid_namespaces 7 2023-03-30 "Linux man-pages 6.05.01" +.TH pid_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pid_namespaces \- overview of Linux PID namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P PID namespaces isolate the process ID number space, meaning that processes in different PID namespaces can have the same PID. PID namespaces allow containers to provide functionality such as suspending/resuming the set of processes in the container and migrating the container to a new host while the processes inside the container maintain the same PIDs. -.PP +.P PIDs in a new PID namespace start at 1, somewhat like a standalone system, and calls to .BR fork (2), @@ -25,7 +25,7 @@ somewhat like a standalone system, and calls to or .BR clone (2) will produce processes with PIDs that are unique within the namespace. -.PP +.P Use of PID namespaces requires a kernel that is configured with the .B CONFIG_PID_NS option. @@ -47,7 +47,7 @@ flag) has the PID 1, and is the "init" process for the namespace (see This process becomes the parent of any child processes that are orphaned because a process that resides in this PID namespace terminated (see below for further details). -.PP +.P If the "init" process of a PID namespace terminates, the kernel terminates all of the processes in the namespace via a .B SIGKILL @@ -74,13 +74,13 @@ terminates, then subsequent calls to .BR fork (2) fail with .BR ENOMEM . -.PP +.P Only signals for which the "init" process has established a signal handler can be sent to the "init" process by other members of the PID namespace. This restriction applies even to privileged processes, and prevents other members of the PID namespace from accidentally killing the "init" process. -.PP +.P Likewise, a process in an ancestor namespace can\[em]subject to the usual permission checks described in .BR kill (2)\[em]send @@ -100,7 +100,7 @@ these signals are forcibly delivered when sent from an ancestor PID namespace. Neither of these signals can be caught by the "init" process, and so will result in the usual actions associated with those signals (respectively, terminating and stopping the process). -.PP +.P Starting with Linux 3.4, the .BR reboot (2) system call causes a signal to be sent to the namespace "init" process. @@ -125,7 +125,7 @@ Since Linux 3.7, .\" commit f2302505775fd13ba93f034206f1e2a587017929 .\" The kernel constant MAX_PID_NS_LEVEL the kernel limits the maximum nesting depth for PID namespaces to 32. -.PP +.P A process is visible to other processes in its PID namespace, and to the processes in each direct ancestor PID namespace going back to the root PID namespace. @@ -140,7 +140,7 @@ set nice values with .BR setpriority (2), etc.) only processes contained in its own PID namespace and in descendants of that namespace. -.PP +.P A process has one process ID in each of the layers of the PID namespace hierarchy in which is visible, and walking back though each direct ancestor namespace @@ -152,7 +152,7 @@ A call to .BR getpid (2) always returns the PID associated with the namespace in which the process was created. -.PP +.P Some processes in a PID namespace may have parents that are outside of the namespace. For example, the parent of the initial process in the namespace @@ -167,7 +167,7 @@ PID namespace from the caller of Calls to .BR getppid (2) for such processes return 0. -.PP +.P While processes may freely descend into child PID namespaces (e.g., using .BR setns (2) @@ -176,7 +176,7 @@ they may not move in the other direction. That is to say, processes may not enter any ancestor namespaces (parent, grandparent, etc.). Changing PID namespaces is a one-way operation. -.PP +.P The .B NS_GET_PARENT .BR ioctl (2) @@ -206,7 +206,7 @@ because doing so would change the caller's idea of its own PID (as reported by .BR getpid ()), which would break many applications and libraries. -.PP +.P To put things another way: a process's PID namespace membership is determined when the process is created and cannot be changed thereafter. @@ -214,7 +214,7 @@ Among other things, this means that the parental relationship between processes mirrors the parental relationship between PID namespaces: the parent of a process is either in the same namespace or resides in the immediate parent PID namespace. -.PP +.P A process may call .BR unshare (2) with the @@ -268,7 +268,7 @@ type in Since this is computed when a signal is enqueued, a signal queue shared by processes in multiple PID namespaces would defeat that. -.PP +.P .\" Note these restrictions were all introduced in .\" 8382fcac1b813ad0a4e68a838fc7ae93fa39eda0 .\" when CLONE_NEWPID|CLONE_VM was disallowed @@ -297,7 +297,7 @@ directories) only processes visible in the PID namespace of the process that performed the mount, even if the .I /proc filesystem is viewed from processes in other namespaces. -.PP +.P After creating a new PID namespace, it is useful for the child to change its root directory and mount a new procfs instance at @@ -316,17 +316,17 @@ or then it isn't necessary to change the root directory: a new procfs instance can be mounted directly over .IR /proc . -.PP +.P From a shell, the command to mount .I /proc is: -.PP +.P .in +4n .EX $ mount \-t proc proc /proc .EE .in -.PP +.P Calling .BR readlink (2) on the path diff --git a/man7/pipe.7 b/man7/pipe.7 index baf05bc..bebb856 100644 --- a/man7/pipe.7 +++ b/man7/pipe.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pipe 7 2023-07-16 "Linux man-pages 6.05.01" +.TH pipe 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pipe \- overview of pipes and FIFOs .SH DESCRIPTION @@ -14,7 +14,7 @@ and a .IR "write end" . Data written to the write end of a pipe can be read from the read end of the pipe. -.PP +.P A pipe is created using .BR pipe (2), which creates a new pipe and returns two file descriptors, @@ -24,7 +24,7 @@ Pipes can be used to create a communication channel between related processes; see .BR pipe (2) for an example. -.PP +.P A FIFO (short for First In First Out) has a name within the filesystem (created using .BR mkfifo (3)), @@ -48,7 +48,7 @@ The only difference between pipes and FIFOs is the manner in which they are created and opened. Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same semantics. -.PP +.P If a process attempts to read from an empty pipe, then .BR read (2) will block until data is available. @@ -56,7 +56,7 @@ If a process attempts to write to a full pipe (see below), then .BR write (2) blocks until sufficient data has been read from the pipe to allow the write to complete. -.PP +.P Nonblocking I/O is possible by using the .BR fcntl (2) .B F_SETFL @@ -69,11 +69,11 @@ with If any process has the pipe open for writing, reads fail with .BR EAGAIN ; otherwise\[em]with no potential writers\[em]reads succeed and return empty. -.PP +.P The communication channel provided by a pipe is a .IR "byte stream" : there is no concept of message boundaries. -.PP +.P If all file descriptors referring to the write end of a pipe have been closed, then an attempt to .BR read (2) @@ -100,7 +100,7 @@ calls to close unnecessary duplicate file descriptors; this ensures that end-of-file and .BR SIGPIPE / EPIPE are delivered when appropriate. -.PP +.P It is not possible to apply .BR lseek (2) to a pipe. @@ -116,7 +116,7 @@ Applications should not rely on a particular capacity: an application should be designed so that a reading process consumes data as soon as it is available, so that a writing process does not remain blocked. -.PP +.P Before Linux 2.6.11, the capacity of a pipe was the same as the system page size (e.g., 4096 bytes on i386). Since Linux 2.6.11, the pipe capacity is 16 pages @@ -131,7 +131,7 @@ operations. See .BR fcntl (2) for more information. -.PP +.P The following .BR ioctl (2) operation, which can be applied to a file descriptor @@ -139,13 +139,13 @@ that refers to either end of a pipe, places a count of the number of unread bytes in the pipe in the .I int buffer pointed to by the final argument of the call: -.PP +.P .in +4n .EX ioctl(fd, FIONREAD, &nbytes); .EE .in -.PP +.P The .B FIONREAD operation is not specified in any standard, @@ -227,7 +227,7 @@ and attempts to increase a pipe's capacity will be denied. When the value of this limit is zero, no soft limit is applied. The default value for this file is 16384, which permits creating up to 1024 pipes with the default capacity. -.PP +.P Before Linux 4.9, some bugs affected the handling of the .I pipe\-user\-pages\-soft and @@ -310,7 +310,7 @@ a pipe or FIFO are .B O_NONBLOCK and .BR O_ASYNC . -.PP +.P Setting the .B O_ASYNC flag for the read end of a pipe causes a signal @@ -383,7 +383,7 @@ allocation could be pushed over the limit. Starting with Linux 4.9, the accounting step is performed before doing the allocation, and the operation fails if the limit would be exceeded. -.PP +.P Before Linux 4.9, bugs similar to points (a) and (c) could also occur when the kernel allocated memory for a new pipe buffer; that is, when calling diff --git a/man7/pkeys.7 b/man7/pkeys.7 index 4f96f1e..660805c 100644 --- a/man7/pkeys.7 +++ b/man7/pkeys.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pkeys 7 2023-05-03 "Linux man-pages 6.05.01" +.TH pkeys 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pkeys \- overview of Memory Protection Keys .SH DESCRIPTION @@ -14,13 +14,13 @@ when changing permissions. Memory Protection Keys provide a mechanism for changing protections without requiring modification of the page tables on every permission change. -.PP +.P To use pkeys, software must first "tag" a page in the page tables with a pkey. After this tag is in place, an application only has to change the contents of a register in order to remove write access, or all access to a tagged page. -.PP +.P Protection keys work in conjunction with the existing .BR PROT_READ , .BR PROT_WRITE , @@ -32,7 +32,7 @@ and .BR mmap (2), but always act to further restrict these traditional permission mechanisms. -.PP +.P If a process performs an access that violates pkey restrictions, it receives a .B SIGSEGV @@ -40,7 +40,7 @@ signal. See .BR sigaction (2) for details of the information available with that signal. -.PP +.P To use the pkeys feature, the processor must support it, and the kernel must contain support for the feature on a given processor. As of early 2016 only future Intel x86 processors are supported, @@ -50,7 +50,7 @@ are available for actual application use. The default key is assigned to any memory region for which a pkey has not been explicitly assigned via .BR pkey_mprotect (2). -.PP +.P Protection keys have the potential to add a layer of security and reliability to applications. But they have not been primarily designed as @@ -58,7 +58,7 @@ a security feature. For instance, WRPKRU is a completely unprivileged instruction, so pkeys are useless in any case that an attacker controls the PKRU register or can execute arbitrary instructions. -.PP +.P Applications should be very careful to ensure that they do not "leak" protection keys. For instance, before calling @@ -77,7 +77,7 @@ Applications may implement these checks by searching the file for memory regions with the pkey assigned. Further details can be found in .BR proc (5). -.PP +.P Any application wanting to use protection keys needs to be able to function without them. They might be unavailable because the hardware that the @@ -91,7 +91,7 @@ keys should simply call and test whether the call succeeds, instead of attempting to detect support for the feature in any other way. -.PP +.P Although unnecessary, hardware support for protection keys may be enumerated with the .I cpuid @@ -104,7 +104,7 @@ under the "flags" field. The string "pku" in this field indicates hardware support for protection keys and the string "ospke" indicates that the kernel contains and has enabled protection keys support. -.PP +.P Applications using threads and protection keys should be especially careful. Threads inherit the protection key rights of the parent at the time @@ -126,7 +126,7 @@ key rights upon entering a signal handler if the desired rights differ from the defaults. The rights of any interrupted context are restored when the signal handler returns. -.PP +.P This signal behavior is unusual and is due to the fact that the x86 PKRU register (which stores protection key access rights) is managed with the same hardware mechanism (XSAVE) that manages floating-point registers. @@ -138,7 +138,7 @@ The Linux kernel implements the following pkey-related system calls: .BR pkey_alloc (2), and .BR pkey_free (2). -.PP +.P The Linux pkey system calls are available only if the kernel was configured and built with the .B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS @@ -151,7 +151,7 @@ After that, it attempts to allocate a protection key and disallows access to the page by using the WRPKRU instruction. It then tries to access the page, which we now expect to cause a fatal signal to the application. -.PP +.P .in +4n .EX .RB "$" " ./a.out" diff --git a/man7/posixoptions.7 b/man7/posixoptions.7 index b0dea3d..2b3e3bc 100644 --- a/man7/posixoptions.7 +++ b/man7/posixoptions.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH posixoptions 7 2022-10-30 "Linux man-pages 6.05.01" +.TH posixoptions 7 2023-11-01 "Linux man-pages 6.7" .SH NAME posixoptions \- optional parts of the POSIX standard .SH DESCRIPTION @@ -19,7 +19,7 @@ From shell scripts one can use .BR getconf (1). For more detail, see .BR sysconf (3). -.PP +.P We give the name of the POSIX abbreviation, the option, the name of the .BR sysconf (3) parameter used to inquire about the option, and possibly @@ -28,7 +28,7 @@ Much more precise detail can be found in the POSIX standard itself, versions of which can nowadays be accessed freely on the web. .SS ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO The following advisory functions are present: -.PP +.P .nf .in +4n .IR posix_fadvise () @@ -42,7 +42,7 @@ The header .I is present. The following functions are present: -.PP +.P .nf .in +4n .IR aio_cancel () @@ -62,7 +62,7 @@ and .B _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_barrier_destroy () @@ -80,8 +80,8 @@ The following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then only root may change the owner of a file, and nonroot can set the group of a file only to one of the groups it belongs to. -This affects the following functions -.PP +This affects the following functions: +.P .nf .in +4n .IR chown () @@ -94,7 +94,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_condattr_getclock () @@ -102,7 +102,7 @@ The following functions are present: .IR clock_nanosleep () .in .fi -.PP +.P If .B CLOCK_REALTIME is changed by the function @@ -136,7 +136,7 @@ Internet Protocol Version 6 is supported. If this option is in effect (as it always is under POSIX.1-2001), then the system implements POSIX-style job control, and the following functions are present: -.PP +.P .nf .in +4n .IR setpgid () @@ -154,7 +154,7 @@ The include file .I is present. The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -165,7 +165,7 @@ The following functions are present: .SS ML - _POSIX_MEMLOCK - _SC_MEMLOCK Shared memory can be locked into core. The following functions are present: -.PP +.P .nf .in +4n .IR mlockall () @@ -175,7 +175,7 @@ The following functions are present: .SS MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE More precisely, ranges can be locked into core. The following functions are present: -.PP +.P .nf .in +4n .IR mlock () @@ -191,7 +191,7 @@ The include file .I is present. The following functions are present: -.PP +.P .nf .in +4n .IR mq_close () @@ -211,7 +211,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are affected: -.PP +.P .nf .in +4n .IR aio_suspend () @@ -236,7 +236,7 @@ This property may be dependent on the path prefix of the component. .SS PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO This option says that one can specify priorities for asynchronous I/O. This affects the functions -.PP +.P .nf .in +4n .IR aio_read () @@ -248,7 +248,7 @@ The include file .I is present. The following functions are present: -.PP +.P .nf .in +4n .IR sched_get_priority_max () @@ -261,11 +261,11 @@ The following functions are present: .IR sched_yield () .in .fi -.PP +.P If also .B _POSIX_SPAWN is in effect, then the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawnattr_getschedparam () @@ -277,7 +277,7 @@ is in effect, then the following functions are present: .SS RS - _POSIX_RAW_SOCKETS Raw sockets are supported. The following functions are affected: -.PP +.P .nf .in +4n .IR getsockopt () @@ -292,9 +292,9 @@ Conversely, under POSIX.1-2001 the .B _POSIX_THREADS option implies this option. -.PP +.P The following functions are present: -.PP +.P .in +4n .nf .IR pthread_rwlock_destroy () @@ -311,7 +311,7 @@ The following functions are present: .SS RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS Realtime signals are supported. The following functions are present: -.PP +.P .nf .in +4n .IR sigqueue () @@ -323,7 +323,7 @@ The following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then POSIX regular expressions are supported and the following functions are present: -.PP +.P .nf .in +4n .IR regcomp () @@ -336,7 +336,7 @@ and the following functions are present: If this option is in effect (as it always is under POSIX.1-2001), then a process has a saved set-user-ID and a saved set-group-ID. The following functions are affected: -.PP +.P .nf .in +4n .IR exec () @@ -354,7 +354,7 @@ The include file .I is present. The following functions are present: -.PP +.P .nf .in +4n .IR sem_close () @@ -370,7 +370,7 @@ The following functions are present: .fi .SS SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -389,13 +389,13 @@ This option describes support for process creation in a context where it is difficult or impossible to use .IR fork (), for example, because no MMU is present. -.PP +.P If .B _POSIX_SPAWN is in effect, then the include file .I and the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawn () @@ -417,12 +417,12 @@ and the following functions are present: .IR posix_spawnp () .in .fi -.PP +.P If also .B _POSIX_PRIORITY_SCHEDULING is in effect, then the following functions are present: -.PP +.P .nf .in +4n .IR posix_spawnattr_getschedparam () @@ -438,7 +438,7 @@ and .B _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_spin_destroy () @@ -456,7 +456,7 @@ This option implies the .B _POSIX_PRIORITY_SCHEDULING option. The following functions are affected: -.PP +.P .nf .in +4n .IR sched_setparam () @@ -465,7 +465,7 @@ The following functions are affected: .fi .SS SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO The following functions are affected: -.PP +.P .nf .in +4n .IR open () @@ -476,7 +476,7 @@ The following functions are affected: .fi .SS TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getstack () @@ -487,7 +487,7 @@ The following functions are affected: .fi .SS TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getstack () @@ -502,7 +502,7 @@ This option implies the .B _POSIX_TIMERS option. The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_getcpuclockid () @@ -514,7 +514,7 @@ The following functions are affected: .fi .SS TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_mutexattr_getprotocol () @@ -523,7 +523,7 @@ The following functions are affected: .fi .SS TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_mutex_getprioceiling () @@ -538,7 +538,7 @@ The following functions are affected: If this option is in effect, the different threads inside a process can run with different priorities and/or different schedulers. The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_attr_getinheritsched () @@ -554,7 +554,7 @@ The following functions are affected: .fi .SS TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED The following functions are affected: -.PP +.P .nf .in +4n .IR pthread_barrierattr_getpshared () @@ -569,7 +569,7 @@ The following functions are affected: .fi .SS TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS The following functions are affected: -.PP +.P .nf .in +4n .IR readdir_r () @@ -598,7 +598,7 @@ This option implies the .B _POSIX_THREAD_PRIORITY_SCHEDULING option. The following functions are affected: -.PP +.P .nf .in +4n .IR sched_getparam () @@ -609,7 +609,7 @@ The following functions are affected: .SS THR - _POSIX_THREADS - _SC_THREADS Basic support for POSIX threads is available. The following functions are present: -.PP +.P .nf .in +4n .IR pthread_atfork () @@ -664,7 +664,7 @@ The following functions are present: .fi .SS TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS The following functions are present: -.PP +.P .nf .in +4n .IR mq_timedreceive () @@ -678,7 +678,7 @@ The following functions are present: .fi .SS TMR - _POSIX_TIMERS - _SC_TIMERS The following functions are present: -.PP +.P .nf .in +4n .IR clock_getres () @@ -695,7 +695,7 @@ The following functions are present: .SS TRC - _POSIX_TRACE - _SC_TRACE POSIX tracing is available. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_destroy () @@ -736,7 +736,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_eventset_add () @@ -755,7 +755,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_getinherited () @@ -767,7 +767,7 @@ This option implies the .B _POSIX_TRACE option. The following functions are present: -.PP +.P .nf .in +4n .IR posix_trace_attr_getlogfullpolicy () @@ -782,7 +782,7 @@ The following functions are present: .fi .SS TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT The following functions are present: -.PP +.P .nf .in +4n .IR posix_mem_offset () @@ -797,7 +797,7 @@ character to indicate that it is disabled. .SH X/OPEN SYSTEM INTERFACE EXTENSIONS .SS XSI - _XOPEN_CRYPT - _SC_XOPEN_CRYPT The following functions are present: -.PP +.P .nf .in +4n .IR crypt () @@ -806,7 +806,7 @@ The following functions are present: .fi .SS XSI - _XOPEN_REALTIME - _SC_XOPEN_REALTIME This option implies the following options: -.PP +.P .PD 0 .TP .BR _POSIX_ASYNCHRONOUS_IO == 200112L @@ -841,7 +841,7 @@ This option implies the following options: .SS ADV - --- - --- The Advanced Realtime option group implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_ADVISORY_INFO @@ -872,7 +872,7 @@ are all defined to 200112L: .SS XSI - _XOPEN_REALTIME_THREADS - _SC_XOPEN_REALTIME_THREADS This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_THREAD_PRIO_INHERIT @@ -884,7 +884,7 @@ are all defined to 200112L: .SS ADVANCED REALTIME THREADS - --- - --- This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_BARRIERS @@ -909,7 +909,7 @@ are all defined to 200112L: .SS TRACING - --- - --- This option implies that the following options are all defined to 200112L: -.PP +.P .PD 0 .TP .B _POSIX_TRACE @@ -922,7 +922,7 @@ are all defined to 200112L: .PD .SS STREAMS - _XOPEN_STREAMS - _SC_XOPEN_STREAMS The following functions are present: -.PP +.P .nf .in +4n .IR fattach () @@ -939,7 +939,7 @@ The following functions are present: Functions included in the legacy option group were previously mandatory, but are now optional in this version. The following functions are present: -.PP +.P .nf .in +4n .IR bcmp () @@ -959,7 +959,7 @@ The following functions are present: .fi .SS XSI - _XOPEN_UNIX - _SC_XOPEN_UNIX The following functions are present: -.PP +.P .nf .in +4n .IR mmap () @@ -967,9 +967,9 @@ The following functions are present: .IR msync () .in .fi -.PP +.P This option implies the following options: -.PP +.P .PD 0 .TP .B _POSIX_FSYNC @@ -988,9 +988,9 @@ This option implies the following options: .TP .B _POSIX_THREADS .PD -.PP +.P This option may imply the following options from the XSI option groups: -.PP +.P .PD 0 .TP .RB "Encryption (" _XOPEN_CRYPT ) diff --git a/man7/process-keyring.7 b/man7/process-keyring.7 index 53557a0..23a7722 100644 --- a/man7/process-keyring.7 +++ b/man7/process-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH process-keyring 7 2022-10-30 "Linux man-pages 6.05.01" +.TH process-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME process-keyring \- per-process shared keyring .SH DESCRIPTION @@ -11,19 +11,19 @@ The process keyring is a keyring used to anchor keys on behalf of a process. It is created only when a process requests it. The process keyring has the name (description) .IR _pid . -.PP +.P A special serial number value, .BR KEY_SPEC_PROCESS_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's process keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@p\fP' can be used instead of a numeric key ID in much the same way, but since .BR keyctl (1) is a program run after forking, this is of no utility. -.PP +.P A thread created using the .BR clone (2) .B CLONE_THREAD @@ -36,7 +36,7 @@ A process's process keyring is cleared on .BR execve (2). The process keyring is destroyed when the last thread that refers to it terminates. -.PP +.P If a process doesn't have a process keyring when it is accessed, then the process keyring will be created if the keyring is to be modified; otherwise, the error diff --git a/man7/pthreads.7 b/man7/pthreads.7 index 2c00798..6d4a5e3 100644 --- a/man7/pthreads.7 +++ b/man7/pthreads.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pthreads 7 2023-03-18 "Linux man-pages 6.05.01" +.TH pthreads 7 2023-10-31 "Linux man-pages 6.7" .SH NAME pthreads \- POSIX threads .SH DESCRIPTION @@ -12,7 +12,7 @@ A single process can contain multiple threads, all of which are executing the same program. These threads share the same global memory (data and heap segments), but each thread has its own stack (automatic variables). -.PP +.P POSIX.1 also requires that threads share a range of other attributes (i.e., these attributes are process-wide rather than per-thread): .IP \[bu] 3 @@ -57,7 +57,7 @@ measurements of the consumption of CPU time .RB ( times (2)) and resources .RB ( getrusage (2)) -.PP +.P As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including: .IP \[bu] 3 @@ -77,7 +77,7 @@ alternate signal stack .IP \[bu] real-time scheduling policy and priority .RB ( sched (7)) -.PP +.P The following Linux-specific features are also per-thread: .IP \[bu] 3 capabilities (see @@ -104,12 +104,12 @@ This identifier is returned to the caller of .BR pthread_create (3), and a thread can obtain its own thread identifier using .BR pthread_self (3). -.PP +.P Thread IDs are guaranteed to be unique only within a process. (In all pthreads functions that accept a thread ID as an argument, that ID by definition refers to a thread in the same process as the caller.) -.PP +.P The system may reuse a thread ID after a terminated thread has been joined, or a detached thread has terminated. POSIX says: "If an application attempts to use a thread ID whose @@ -118,11 +118,11 @@ lifetime has ended, the behavior is undefined." A thread-safe function is one that can be safely (i.e., it will deliver the same results regardless of whether it is) called from multiple threads at the same time. -.PP +.P POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the standard shall be thread-safe, except for the following functions: -.PP +.P .in +4n .EX asctime() @@ -224,10 +224,10 @@ wctomb() An async-cancel-safe function is one that can be safely called in an application where asynchronous cancelability is enabled (see .BR pthread_setcancelstate (3)). -.PP +.P Only the following functions are required to be async-cancel-safe by POSIX.1-2001 and POSIX.1-2008: -.PP +.P .in +4n .EX pthread_cancel() @@ -242,10 +242,10 @@ If a thread is cancelable, its cancelability type is deferred, and a cancelation request is pending for the thread, then the thread is canceled when it calls a function that is a cancelation point. -.PP +.P The following functions are required to be cancelation points by POSIX.1-2001 and/or POSIX.1-2008: -.PP +.P .\" FIXME .\" Document the list of all functions that are cancelation points in glibc .in +4n @@ -310,10 +310,10 @@ write() writev() .EE .in -.PP +.P The following functions may be cancelation points according to POSIX.1-2001 and/or POSIX.1-2008: -.PP +.P .in +4n .EX access() @@ -545,13 +545,13 @@ wprintf() wscanf() .EE .in -.PP +.P An implementation may also mark other functions not specified in the standard as cancelation points. In particular, an implementation is likely to mark any nonstandard function that may block as a cancelation point. (This includes most functions that can touch files.) -.PP +.P It should be noted that even if an application is not using asynchronous cancelation, that calling a function from the above list from an asynchronous signal handler may cause the equivalent of @@ -669,7 +669,7 @@ the requirements of the POSIX.1 specification and better performance when creating large numbers of threads. NPTL is available since glibc 2.3.2, and requires features that are present in the Linux 2.6 kernel. -.PP +.P Both of these are so-called 1:1 implementations, meaning that each thread maps to a kernel scheduling entity. Both threading implementations employ the Linux @@ -707,7 +707,7 @@ more information than usual, but which do not share a common process ID.) LinuxThreads threads (including the manager thread) are visible as separate processes using .BR ps (1). -.PP +.P The LinuxThreads implementation deviates from the POSIX.1 specification in a number of ways, including the following: .IP \[bu] 3 @@ -789,13 +789,13 @@ With NPTL, all of the threads in a process are placed in the same thread group; all members of a thread group share the same PID. NPTL does not employ a manager thread. -.PP +.P NPTL makes internal use of the first two real-time signals; these signals cannot be used in applications. See .BR nptl (7) for further details. -.PP +.P NPTL still has at least one nonconformance with POSIX.1: .IP \[bu] 3 Threads do not share a common nice value. @@ -804,7 +804,7 @@ Threads do not share a common nice value. .\" Sep 08: there is a patch by Denys Vlasenko to address this .\" "make setpriority POSIX compliant; introduce PRIO_THREAD extension" .\" Monitor this to see if it makes it into mainline. -.PP +.P Some NPTL nonconformances occur only with older kernels: .IP \[bu] 3 The information returned by @@ -831,7 +831,7 @@ However, a new thread's alternate signal stack settings are copied from the thread that created it, so that the threads initially share an alternate signal stack (fixed in Linux 2.6.16). -.PP +.P Note the following further points about the NPTL implementation: .IP \[bu] 3 If the stack size soft resource limit (see the description of @@ -852,17 +852,17 @@ Since glibc 2.3.2, the .BR getconf (1) command can be used to determine the system's threading implementation, for example: -.PP +.P .in +4n .EX bash$ getconf GNU_LIBPTHREAD_VERSION NPTL 2.3.4 .EE .in -.PP +.P With older glibc versions, a command such as the following should be sufficient to determine the default threading implementation: -.PP +.P .in +4n .EX bash$ $( ldd /bin/ls | grep libc.so | awk \[aq]{print $3}\[aq] ) | \e @@ -885,7 +885,7 @@ of LinuxThreads. (broken) application that depends on some nonconformant behavior in LinuxThreads.) For example: -.PP +.P .in +4n .EX bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e @@ -904,9 +904,9 @@ bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \e .BR attributes (7), .BR futex (7), .BR nptl (7), -.BR sigevent (7), +.BR sigevent (3type), .BR signal (7) -.PP +.P Various Pthreads manual pages, for example: .BR pthread_atfork (3), .BR pthread_attr_init (3), diff --git a/man7/pty.7 b/man7/pty.7 index 5d9b429..45cdb5f 100644 --- a/man7/pty.7 +++ b/man7/pty.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH pty 7 2022-12-04 "Linux man-pages 6.05.01" +.TH pty 7 2023-11-19 "Linux man-pages 6.7" .SH NAME pty \- pseudoterminal interfaces .SH DESCRIPTION @@ -13,7 +13,7 @@ One end of the channel is called the .IR master ; the other end is called the .IR slave . -.PP +.P The slave end of the pseudoterminal provides an interface that behaves exactly like a classical terminal. A process that expects to be connected to a terminal, @@ -29,24 +29,24 @@ that is connected to the slave. Conversely, anything that is written to the slave end of the pseudoterminal can be read by the process that is connected to the master end. -.PP +.P Data flow between master and slave is handled asynchronously, much like data flow with a physical terminal. Data written to the slave will be available at the master promptly, but may not be available immediately. Similarly, there may be a small processing delay between a write to the master, and the effect being visible at the slave. -.PP +.P Historically, two pseudoterminal APIs have evolved: BSD and System V. SUSv1 standardized a pseudoterminal API based on the System V API, and this API should be employed in all new programs that use pseudoterminals. -.PP +.P Linux provides both BSD-style and (standardized) System V-style pseudoterminals. System V-style terminals are commonly called UNIX 98 pseudoterminals on Linux systems. -.PP +.P Since Linux 2.6.4, BSD-style pseudoterminals are considered deprecated: support can be disabled when building the kernel by disabling the .B CONFIG_LEGACY_PTYS @@ -71,7 +71,7 @@ the name returned by .BR ptsname (3) in a call to .BR open (2). -.PP +.P The Linux kernel imposes a limit on the number of available UNIX 98 pseudoterminals. Up to and including Linux 2.6.3, this limit is configured @@ -122,7 +122,10 @@ BSD master devices BSD slave devices .SH NOTES Pseudoterminals are used by applications such as network login services -.RB ( ssh "(1), " rlogin "(1), " telnet (1)), +(\c +.BR ssh (1), +.BR rlogin (1), +.BR telnet (1)), terminal emulators such as .BR xterm (1), .BR script (1), @@ -131,13 +134,13 @@ terminal emulators such as .BR unbuffer (1), and .BR expect (1). -.PP +.P A description of the .B TIOCPKT .BR ioctl (2), which controls packet mode operation, can be found in .BR ioctl_tty (2). -.PP +.P The BSD .BR ioctl (2) operations diff --git a/man7/queue.7 b/man7/queue.7 index 6f2d5ab..469974f 100644 --- a/man7/queue.7 +++ b/man7/queue.7 @@ -5,7 +5,7 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" .\" -.TH queue 7 2023-03-30 "Linux man-pages 6.05.01" +.TH queue 7 2023-10-31 "Linux man-pages 6.7" .SH NAME queue \- implementations of linked lists and queues .SH DESCRIPTION @@ -28,7 +28,7 @@ doubly linked tail queues .TP CIRCLEQ doubly linked circular queues -.PP +.P All structures support the following functionality: .IP \[bu] 3 Insertion of a new entry at the head of the list. @@ -38,9 +38,9 @@ Insertion of a new entry after any element in the list. O(1) removal of an entry from the head of the list. .IP \[bu] Forward traversal through the list. -.\".IP * +.\".IP \[bu] .\" Swapping the contents of two lists. -.PP +.P Code size and execution time depend on the complexity of the data structure being used, so programmers should take care to choose the appropriate one. @@ -61,13 +61,13 @@ Entries can be added at the end of a list. O(n) removal of any entry in the list. .IP \[bu] They may be concatenated. -.PP +.P However: .IP \[bu] 3 All list insertions must specify the head of the list. .IP \[bu] Each head entry requires two pointers rather than one. -.PP +.P Singly linked tail queues are ideal for applications with large datasets and few or no removals, or for implementing a FIFO queue. @@ -78,7 +78,7 @@ additionally allow: Insertion of a new entry before any element in the list. .IP \[bu] O(1) removal of any entry in the list. -.PP +.P However: .IP \[bu] 3 Each element requires two pointers rather than one. @@ -87,7 +87,7 @@ Linked lists are the simplest of the doubly linked data structures. They add the following functionality over the above: .IP \[bu] 3 They may be traversed backwards. -.PP +.P However: .IP \[bu] 3 To traverse backwards, an entry to begin the traversal and the list in @@ -100,7 +100,7 @@ Entries can be added at the end of a list. They may be traversed backwards, from tail to head. .IP \[bu] They may be concatenated. -.PP +.P However: .IP \[bu] 3 All list insertions and removals must specify the head of the list. @@ -110,7 +110,7 @@ Each head entry requires two pointers rather than one. Circular queues add the following functionality over the above: .IP \[bu] 3 The first and last entries are connected. -.PP +.P However: .IP \[bu] 3 The termination condition for traversal is more complex. diff --git a/man7/random.7 b/man7/random.7 index bca67ce..5ba6d33 100644 --- a/man7/random.7 +++ b/man7/random.7 @@ -9,7 +9,7 @@ .\" The following web page is quite informative: .\" http://www.2uo.de/myths-about-urandom/ .\" -.TH random 7 2023-02-10 "Linux man-pages 6.05.01" +.TH random 7 2023-10-31 "Linux man-pages 6.7" .SH NAME random \- overview of interfaces for obtaining randomness .SH DESCRIPTION @@ -17,7 +17,7 @@ The kernel random-number generator relies on entropy gathered from device drivers and other sources of environmental noise to seed a cryptographically secure pseudorandom number generator (CSPRNG). It is designed for security, rather than speed. -.PP +.P The following interfaces provide access to output from the kernel CSPRNG: .IP \[bu] 3 The @@ -77,7 +77,7 @@ flag. The cryptographic algorithms used for the .I urandom source are quite conservative, and so should be sufficient for all purposes. -.PP +.P The disadvantage of .B GRND_RANDOM and reads from @@ -194,7 +194,7 @@ or Diffie-Hellman private key has an effective key size of 128 bits (it requires about 2\[ha]128 operations to break) so a key generator needs only 128 bits (16 bytes) of seed material from .IR /dev/random . -.PP +.P While some safety margin above that minimum is reasonable, as a guard against flaws in the CSPRNG algorithm, no cryptographic primitive available today can hope to promise more than 256 bits of security, diff --git a/man7/raw.7 b/man7/raw.7 index ab43dd4..65cdbe0 100644 --- a/man7/raw.7 +++ b/man7/raw.7 @@ -5,7 +5,7 @@ .\" .\" $Id: raw.7,v 1.6 1999/06/05 10:32:08 freitag Exp $ .\" -.TH raw 7 2023-07-15 "Linux man-pages 6.05.01" +.TH raw 7 2023-10-31 "Linux man-pages 6.7" .SH NAME raw \- Linux IPv4 raw sockets .SH SYNOPSIS @@ -18,17 +18,17 @@ raw \- Linux IPv4 raw sockets Raw sockets allow new IPv4 protocols to be implemented in user space. A raw socket receives or sends the raw datagram not including link level headers. -.PP +.P The IPv4 layer generates an IP header when sending a packet unless the .B IP_HDRINCL socket option is enabled on the socket. When it is enabled, the packet must contain an IP header. For receiving, the IP header is always included in the packet. -.PP +.P In order to create a raw socket, a process must have the .B CAP_NET_RAW capability in the user namespace that governs its network namespace. -.PP +.P All packets or errors matching the .I protocol number specified @@ -39,7 +39,7 @@ see the IANA list of assigned protocol numbers at .UE and .BR getprotobyname (3). -.PP +.P A protocol of .B IPPROTO_RAW implies enabled @@ -61,7 +61,7 @@ Packet ID:Filled in when zero Total Length:Always filled in .TE .RE -.PP +.P If .B IP_HDRINCL is specified and the IP header has a nonzero destination address, then @@ -71,7 +71,7 @@ When is specified, the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes are ignored. -.PP +.P If .B IP_HDRINCL isn't set, then IP header options can be set on raw sockets with @@ -79,12 +79,12 @@ isn't set, then IP header options can be set on raw sockets with see .BR ip (7) for more information. -.PP +.P Starting with Linux 2.2, all IP header fields and options can be set using IP socket options. This means raw sockets are usually needed only for new protocols or protocols with no user interface (like ICMP). -.PP +.P When a packet is received, it is passed to any raw sockets which have been bound to its protocol before it is passed to other protocol handlers (e.g., kernel protocol modules). @@ -123,7 +123,7 @@ protocol. The value has a bit set for each ICMP message type which should be filtered out. The default is to filter no ICMP messages. -.PP +.P In addition, all .BR ip (7) .B IPPROTO_IP @@ -178,7 +178,7 @@ and .B ICMP_FILTER are new in Linux 2.2. They are Linux extensions and should not be used in portable programs. -.PP +.P Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket code when the .B SO_BSDCOMPAT @@ -202,7 +202,7 @@ When turned off, raw sockets will fragment outgoing packets that exceed the interface MTU. However, disabling it is not recommended for performance and reliability reasons. -.PP +.P A raw socket can be bound to a specific local address using the .BR bind (2) call. @@ -211,7 +211,7 @@ In addition, a raw socket can be bound to a specific network device using .BR SO_BINDTODEVICE ; see .BR socket (7). -.PP +.P An .B IPPROTO_RAW socket is send only. @@ -222,28 +222,28 @@ socket with the protocol. Note that packet sockets don't reassemble IP fragments, unlike raw sockets. -.PP +.P If you want to receive all ICMP packets for a datagram socket, it is often better to use .B IP_RECVERR on that particular socket; see .BR ip (7). -.PP +.P Raw sockets may tap all IP protocols in Linux, even protocols like ICMP or TCP which have a protocol module in the kernel. In this case, the packets are passed to both the kernel module and the raw socket(s). This should not be relied upon in portable programs, many other BSD socket implementation have limitations here. -.PP +.P Linux never changes headers passed from the user (except for filling in some zeroed fields as described for .BR IP_HDRINCL ). This differs from many other implementations of raw sockets. -.PP +.P Raw sockets are generally rather unportable and should be avoided in programs intended to be portable. -.PP +.P Sending on raw sockets should take the IP protocol from .IR sin_port ; this ability was lost in Linux 2.2. @@ -251,12 +251,12 @@ The workaround is to use .BR IP_HDRINCL . .SH BUGS Transparent proxy extensions are not described. -.PP +.P When the .B IP_HDRINCL option is set, datagrams will not be fragmented and are limited to the interface MTU. -.PP +.P Setting the IP protocol for sending in .I sin_port got lost in Linux 2.2. @@ -272,7 +272,7 @@ call is always used. .BR capabilities (7), .BR ip (7), .BR socket (7) -.PP +.P .B RFC\ 1191 for path MTU discovery. .B RFC\ 791 diff --git a/man7/regex.7 b/man7/regex.7 index 7a5b2d8..ad63573 100644 --- a/man7/regex.7 +++ b/man7/regex.7 @@ -35,14 +35,14 @@ .\" .ie t .ds dg \(dg .el .ds dg (!) -.TH regex 7 2023-03-08 "Linux man-pages 6.05.01" +.TH regex 7 2023-11-01 "Linux man-pages 6.7" .SH NAME regex \- POSIX.2 regular expressions .SH DESCRIPTION Regular expressions ("RE"s), as defined in POSIX.2, come in two forms: modern REs (roughly those of -.IR egrep ; +.BR egrep (1); POSIX.2 calls these "extended" REs) and obsolete REs (roughly those of .BR ed (1); @@ -52,15 +52,15 @@ they will be discussed at the end. POSIX.2 leaves some aspects of RE syntax and semantics open; "\*(dg" marks decisions on these aspects that may not be fully portable to other POSIX.2 implementations. -.PP +.P A (modern) RE is one\*(dg or more nonempty\*(dg \fIbranches\fR, separated by \[aq]|\[aq]. It matches anything that matches one of the branches. -.PP +.P A branch is one\*(dg or more \fIpieces\fR, concatenated. It matches a match for the first, followed by a match for the second, and so on. -.PP +.P A piece is an \fIatom\fR possibly followed by a single\*(dg \[aq]*\[aq], \[aq]+\[aq], \[aq]?\[aq], or \fIbound\fR. An atom followed by \[aq]*\[aq] @@ -69,7 +69,7 @@ An atom followed by \[aq]+\[aq] matches a sequence of 1 or more matches of the atom. An atom followed by \[aq]?\[aq] matches a sequence of 0 or 1 matches of the atom. -.PP +.P A \fIbound\fR is \[aq]{\[aq] followed by an unsigned decimal integer, possibly followed by \[aq],\[aq] possibly followed by another unsigned decimal integer, @@ -87,7 +87,7 @@ a sequence of \fIi\fR or more matches of the atom. An atom followed by a bound containing two integers \fIi\fR and \fIj\fR matches a sequence of \fIi\fR through \fIj\fR (inclusive) matches of the atom. -.PP +.P An atom is a regular expression enclosed in "\fI()\fP" (matching a match for the regular expression), an empty set of "\fI()\fP" (matching the null string)\*(dg, @@ -105,7 +105,7 @@ A \[aq]{\[aq] followed by a character other than a digit is an ordinary character, not the beginning of a bound\*(dg. It is illegal to end an RE with \[aq]\e\[aq]. -.PP +.P A \fIbracket expression\fR is a list of characters enclosed in "\fI[]\fP". It normally matches any single character from the list (but see below). If the list begins with \[aq]\[ha]\[aq], @@ -119,7 +119,7 @@ It is illegal\*(dg for two ranges to share an endpoint, for example, "\fIa\-c\-e\fP". Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them. -.PP +.P To include a literal \[aq]]\[aq] in the list, make it the first character (following a possible \[aq]\[ha]\[aq]). To include a literal \[aq]\-\[aq], make it the first or last character, @@ -130,7 +130,7 @@ to make it a collating element (see below). With the exception of these and some combinations using \[aq][\[aq] (see next paragraphs), all other special characters, including \[aq]\e\[aq], lose their special significance within a bracket expression. -.PP +.P Within a bracket expression, a collating element (a character, a multicharacter sequence that collates as if it were a single character, or a collating-sequence name for either) @@ -142,7 +142,7 @@ can thus match more than one character, for example, if the collating sequence includes a "ch" collating element, then the RE "\fI[[.ch.]]*c\fP" matches the first five characters of "chchcc". -.PP +.P Within a bracket expression, a collating element enclosed in "\fI[=\fP" and "\fI=]\fP" is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. @@ -154,13 +154,13 @@ then "\fI[[=o=]]\fP", "\fI[[=\(^o=]]\fP", and "\fI[o\(^o]\fP" are all synonymous. An equivalence class may not\*(dg be an endpoint of a range. -.PP +.P Within a bracket expression, the name of a \fIcharacter class\fR enclosed in "\fI[:\fP" and "\fI:]\fP" stands for the list of all characters belonging to that class. Standard character class names are: -.PP +.P .RS .TS l l l. @@ -170,14 +170,14 @@ blank lower upper cntrl print xdigit .TE .RE -.PP +.P These stand for the character classes defined in .BR wctype (3). A locale may provide others. A character class may not be used as an endpoint of a range. .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 .\" The following does not seem to apply in the glibc implementation -.\" .PP +.\" .P .\" There are two special cases\*(dg of bracket expressions: .\" the bracket expressions "\fI[[:<:]]\fP" and "\fI[[:>:]]\fP" match .\" the null string at the beginning and end of a word respectively. @@ -194,7 +194,7 @@ A character class may not be used as an endpoint of a range. .\" compatible with but not specified by POSIX.2, .\" and should be used with .\" caution in software intended to be portable to other systems. -.PP +.P In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. @@ -206,7 +206,7 @@ with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions. -.PP +.P Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, @@ -218,7 +218,7 @@ matches all three characters, and when "\fI(a*)*\fP" is matched against "bc" both the whole RE and the parenthesized subexpression match the null string. -.PP +.P If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. @@ -229,13 +229,13 @@ for example, \[aq]x\[aq] becomes "\fI[xX]\fP". When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that, for example, "\fI[x]\fP" becomes "\fI[xX]\fP" and "\fI[\[ha]x]\fP" becomes "\fI[\[ha]xX]\fP". -.PP +.P No particular limit is imposed on the length of REs\*(dg. Programs intended to be portable should not employ REs longer than 256 bytes, as an implementation can refuse to accept such REs and remain POSIX-compliant. -.PP +.P Obsolete ("basic") regular expressions differ in several respects. \[aq]|\[aq], \[aq]+\[aq], and \[aq]?\[aq] are ordinary characters and there is no equivalent @@ -251,7 +251,7 @@ RE or\*(dg the end of a parenthesized subexpression, and \[aq]*\[aq] is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading \[aq]\[ha]\[aq]). -.PP +.P Finally, there is one new type of atom, a \fIback reference\fR: \[aq]\e\[aq] followed by a nonzero decimal digit \fId\fR matches the same sequence of characters @@ -261,26 +261,26 @@ left to right), so that, for example, "\fI\e([bc]\e)\e1\fP" matches "bb" or "cc" but not "bc". .SH BUGS Having two kinds of REs is a botch. -.PP +.P The current POSIX.2 spec says that \[aq])\[aq] is an ordinary character in the absence of an unmatched \[aq](\[aq]; this was an unintentional result of a wording error, and change is likely. Avoid relying on it. -.PP +.P Back references are a dreadful botch, posing major problems for efficient implementations. They are also somewhat vaguely defined (does "\fIa\e(\e(b\e)*\e2\e)*d\fP" match "abbbd"?). Avoid using them. -.PP +.P POSIX.2's specification of case-independent matching is vague. The "one case implies all cases" definition given above is current consensus among implementors as to the right interpretation. .\" As per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=295666 .\" The following does not seem to apply in the glibc implementation -.\" .PP +.\" .P .\" The syntax for word boundaries is incredibly ugly. .SH AUTHOR .\" Sigh... The page license means we must have the author's name @@ -289,5 +289,5 @@ This page was taken from Henry Spencer's regex package. .SH SEE ALSO .BR grep (1), .BR regex (3) -.PP +.P POSIX.2, section 2.8 (Regular Expression Notation). diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7 index df04a8c..67678b4 100644 --- a/man7/rtld-audit.7 +++ b/man7/rtld-audit.7 @@ -5,7 +5,7 @@ .\" .\" 2009-01-12, mtk, Created .\" -.TH RTLD-AUDIT 7 2023-05-03 "Linux man-pages 6.05.01" +.TH RTLD-AUDIT 7 2023-10-31 "Linux man-pages 6.7" .SH NAME rtld\-audit \- auditing API for the dynamic linker .SH SYNOPSIS @@ -21,14 +21,14 @@ This API is very similar to the auditing interface provided by the Solaris run-time linker. The necessary constants and prototypes are defined by including .IR . -.PP +.P To use this interface, the programmer creates a shared library that implements a standard set of function names. Not all of the functions need to be implemented: in most cases, if the programmer is not interested in a particular class of auditing event, then no implementation needs to be provided for the corresponding auditing function. -.PP +.P To employ the auditing interface, the environment variable .B LD_AUDIT must be defined to contain a colon-separated list of shared libraries, @@ -41,7 +41,7 @@ in the order that the libraries are listed. .nf .BI "unsigned int la_version(unsigned int " version ); .fi -.PP +.P This is the only function that .I must be defined by an auditing library: @@ -50,7 +50,7 @@ the auditing library. When invoking this function, the dynamic linker passes, in .IR version , the highest version of the auditing interface that the linker supports. -.PP +.P A typical implementation of this function simply returns the constant .BR LAV_CURRENT , which indicates the version of @@ -61,7 +61,7 @@ not support this version of the audit interface, it will refuse to activate this audit module. If the function returns zero, the dynamic linker also does not activate this audit module. -.PP +.P In order to enable backwards compatibility with older dynamic linkers, an audit module can examine the .I version @@ -83,7 +83,7 @@ definitions used to build the audit module. .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , .BI " unsigned int " flag ); .fi -.PP +.P The dynamic linker invokes this function to inform the auditing library that it is about to search for a shared object. The @@ -130,7 +130,7 @@ was found via a search of one of the default directories. .B LA_SER_SECURE .I name is specific to a secure object (unused on Linux). -.PP +.P As its function result, .BR la_objsearch () returns the pathname that the dynamic linker should use @@ -144,7 +144,7 @@ should be returned. .nf .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); .fi -.PP +.P The dynamic linker calls this function to inform the auditing library that link-map activity is occurring. .I cookie @@ -167,7 +167,7 @@ Link-map activity has been completed: the map is once again consistent. .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , .BI " uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker calls this function when a new shared object is loaded. The .I map @@ -182,7 +182,7 @@ Link map is part of the initial namespace. .B LM_ID_NEWLM Link map is part of a new namespace requested via .BR dlmopen (3). -.PP +.P .I cookie is a pointer to an identifier for this object. The identifier is provided to later calls to functions @@ -190,7 +190,7 @@ in the auditing library in order to identify this object. This identifier is initialized to point to object's link map, but the audit library can change the identifier to some other value that it may prefer to use to identify the object. -.PP +.P As its return value, .BR la_objopen () returns a bit mask created by ORing zero or more of the @@ -203,7 +203,7 @@ Audit symbol bindings to this object. .TP .B LA_FLG_BINDFROM Audit symbol bindings from this object. -.PP +.P A return value of 0 from .BR la_objopen () indicates that no symbol bindings should be audited for this object. @@ -212,7 +212,7 @@ indicates that no symbol bindings should be audited for this object. .nf .BI "unsigned int la_objclose(uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker invokes this function after any finalization code for the object has been executed, before the object is unloaded. @@ -220,7 +220,7 @@ The .I cookie argument is the identifier obtained from a previous invocation of .BR la_objopen (). -.PP +.P In the current implementation, the value returned by .BR la_objclose () is ignored. @@ -229,7 +229,7 @@ is ignored. .nf .BI "void la_preinit(uintptr_t *" cookie ); .fi -.PP +.P The dynamic linker invokes this function after all shared objects have been loaded, before control is passed to the application (i.e., before calling @@ -248,7 +248,7 @@ may still later dynamically load objects using .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " unsigned int *" flags ", const char *" symname ); .fi -.PP +.P The dynamic linker invokes one of these functions when a symbol binding occurs between two shared objects that have been marked for auditing notification by @@ -259,7 +259,7 @@ function is employed on 32-bit platforms; the .BR la_symbind64 () function is employed on 64-bit platforms. -.PP +.P The .I sym argument is a pointer to a structure @@ -269,12 +269,12 @@ The structure definition is shown in Among the fields of this structure, .I st_value indicates the address to which the symbol is bound. -.PP +.P The .I ndx argument gives the index of the symbol in the symbol table of the bound shared object. -.PP +.P The .I refcook argument identifies the shared object that is making the symbol reference; @@ -289,11 +289,11 @@ this is the same identifier that is provided to the .BR la_objopen () function that returned .BR LA_FLG_BINDTO . -.PP +.P The .I symname argument points a string containing the name of the symbol. -.PP +.P The .I flags argument is a bit mask that both provides information about the symbol @@ -310,7 +310,7 @@ The binding resulted from a call to A previous .BR la_symbind* () call returned an alternate value for this symbol. -.PP +.P By default, if the auditing library implements .BR la_pltenter () and @@ -334,7 +334,7 @@ for this symbol. Don't call .BR la_pltexit () for this symbol. -.PP +.P The return value of .BR la_symbind32 () and @@ -351,17 +351,17 @@ depend on the hardware platform. (The appropriate definition is supplied by .IR .) Here is the definition for x86-32: -.PP +.P .nf .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " La_i86_regs *" regs ", unsigned int *" flags , .BI " const char *" symname ", long *" framesizep ); .fi -.PP +.P This function is invoked just before a PLT entry is called, between two shared objects that have been marked for binding notification. -.PP +.P The .IR sym , .IR ndx , @@ -371,20 +371,20 @@ and .I symname are as for .BR la_symbind* (). -.PP +.P The .I regs argument points to a structure (defined in .IR ) containing the values of registers to be used for the call to this PLT entry. -.PP +.P The .I flags argument points to a bit mask that conveys information about, and can be used to modify subsequent auditing of, this PLT entry, as for .BR la_symbind* (). -.PP +.P .\" FIXME . Is the following correct? The .I framesizep @@ -400,7 +400,7 @@ The .BR la_pltexit () function is called only if this buffer is explicitly set to a suitable value. -.PP +.P The return value of .BR la_pltenter () is as for @@ -411,20 +411,20 @@ depend on the hardware platform. (The appropriate definition is supplied by .IR .) Here is the definition for x86-32: -.PP +.P .nf .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx , .BI " uintptr_t *" refcook ", uintptr_t *" defcook , .BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs , .BI " const char *" symname ); .fi -.PP +.P This function is called when a PLT entry, made between two shared objects that have been marked for binding notification, returns. The function is called just before control returns to the caller of the PLT entry. -.PP +.P The .IR sym , .IR ndx , @@ -434,7 +434,7 @@ and .I symname are as for .BR la_symbind* (). -.PP +.P The .I inregs argument points to a structure (defined in @@ -447,7 +447,7 @@ argument points to a structure (defined in containing return values for the call to this PLT entry. These values can be modified by the caller, and the changes will be visible to the caller of the PLT entry. -.PP +.P In the current GNU implementation, the return value of .BR la_pltexit () is ignored. diff --git a/man7/rtnetlink.7 b/man7/rtnetlink.7 index 3b6465f..1ab355f 100644 --- a/man7/rtnetlink.7 +++ b/man7/rtnetlink.7 @@ -7,7 +7,7 @@ .\" help from Matthew Wilcox. .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ .\" -.TH rtnetlink 7 2023-07-15 "Linux man-pages 6.05.01" +.TH rtnetlink 7 2023-10-31 "Linux man-pages 6.7" .SH NAME rtnetlink \- Linux routing socket .SH SYNOPSIS @@ -16,7 +16,7 @@ rtnetlink \- Linux routing socket .B #include .B #include .B #include -.PP +.P .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);" .fi .SH DESCRIPTION @@ -35,7 +35,7 @@ for more information. .\" FIXME . ? all these macros could be moved to rtnetlink(3) .SS Routing attributes Some rtnetlink messages have optional attributes after the initial header: -.PP +.P .in +4n .EX struct rtattr { @@ -45,7 +45,7 @@ struct rtattr { }; .EE .in -.PP +.P These attributes should be manipulated using only the RTA_* macros or libnetlink, see .BR rtnetlink (3). @@ -53,7 +53,11 @@ or libnetlink, see Rtnetlink consists of these message types (in addition to standard netlink messages): .TP -.BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK +.B RTM_NEWLINK +.TQ +.B RTM_DELLINK +.TQ +.B RTM_GETLINK Create, remove, or get information about a specific network interface. These messages contain an .I ifinfomsg @@ -112,7 +116,11 @@ is .RI ( "struct net_device_stats" in Linux 2.4 and earlier). .TP -.BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR +.B RTM_NEWADDR +.TQ +.B RTM_DELADDR +.TQ +.B RTM_GETADDR Add, remove, or receive information about an IP address associated with an interface. In Linux 2.2, an interface can carry multiple IP addresses, @@ -170,7 +178,11 @@ IFA_CACHEINFO:struct ifa_cacheinfo:Address information .TE .\" FIXME Document struct ifa_cacheinfo .TP -.BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE +.B RTM_NEWROUTE +.TQ +.B RTM_DELROUTE +.TQ +.B RTM_GETROUTE Create, remove, or receive information about a network route. These messages contain an .I rtmsg @@ -242,7 +254,7 @@ RTPROT_KERNEL:by the kernel RTPROT_BOOT:during boot RTPROT_STATIC:by the administrator .TE -.sp 1 +.IP Values larger than .B RTPROT_STATIC are not interpreted by the kernel, they are just for user information. @@ -265,7 +277,7 @@ RT_SCOPE_LINK:route on this link RT_SCOPE_HOST:route on the local host RT_SCOPE_NOWHERE:destination doesn't exist .TE -.sp 1 +.IP The values between .B RT_SCOPE_UNIVERSE and @@ -284,7 +296,7 @@ T} RTM_F_CLONED:route is cloned from another route RTM_F_EQUALIZE:a multipath equalizer (not yet implemented) .TE -.sp 1 +.IP .I rtm_table specifies the routing table .TS @@ -295,7 +307,7 @@ RT_TABLE_DEFAULT:the default table RT_TABLE_MAIN:the main table RT_TABLE_LOCAL:the local table .TE -.sp 1 +.IP The user may assign arbitrary values between .B RT_TABLE_UNSPEC and @@ -423,7 +435,11 @@ defined in .IP .B Fill these values in! .TP -.BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH +.B RTM_NEWNEIGH +.TQ +.B RTM_DELNEIGH +.TQ +.B RTM_GETNEIGH Add, remove, or receive information about a neighbor table entry (e.g., an ARP entry). The message contains an @@ -461,7 +477,7 @@ NUD_FAILED:an invalid cache entry NUD_NOARP:a device with no destination cache NUD_PERMANENT:a static entry .TE -.sp 1 +.IP Valid .I ndm_flags are: @@ -471,7 +487,7 @@ lb l. NTF_PROXY:a proxy arp entry NTF_ROUTER:an IPv6 router .TE -.sp 1 +.IP .\" FIXME . .\" document the members of the struct better The @@ -487,7 +503,7 @@ NDA_DST:a neighbor cache n/w layer destination address NDA_LLADDR:a neighbor cache link layer address NDA_CACHEINFO:cache statistics .TE -.sp 1 +.IP If the .I rta_type field is @@ -496,12 +512,20 @@ then a .I struct nda_cacheinfo header follows. .TP -.BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE +.B RTM_NEWRULE +.TQ +.B RTM_DELRULE +.TQ +.B RTM_GETRULE Add, delete, or retrieve a routing rule. Carries a .I struct rtmsg .TP -.BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC +.B RTM_NEWQDISC +.TQ +.B RTM_DELQDISC +.TQ +.B RTM_GETQDISC Add, remove, or get a queueing discipline. The message contains a .I struct tcmsg @@ -531,17 +555,25 @@ TCA_STATS:struct tc_stats:Qdisc statistics TCA_XSTATS:qdisc-specific:Module-specific statistics TCA_RATE:struct tc_estimator:Rate limit .TE -.sp 1 +.IP In addition, various other qdisc-module-specific attributes are allowed. For more information see the appropriate include files. .TP -.BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS +.B RTM_NEWTCLASS +.TQ +.B RTM_DELTCLASS +.TQ +.B RTM_GETTCLASS Add, remove, or get a traffic class. These messages contain a .I struct tcmsg as described above. .TP -.BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER +.B RTM_NEWTFILTER +.TQ +.B RTM_DELTFILTER +.TQ +.B RTM_GETTFILTER Add, remove, or receive information about a traffic filter. These messages contain a .I struct tcmsg diff --git a/man7/sched.7 b/man7/sched.7 index 7854505..7e1212f 100644 --- a/man7/sched.7 +++ b/man7/sched.7 @@ -10,7 +10,7 @@ .\" .\" Worth looking at: http://rt.wiki.kernel.org/index.php .\" -.TH sched 7 2023-02-10 "Linux man-pages 6.05.01" +.TH sched 7 2024-02-18 "Linux man-pages 6.7" .SH NAME sched \- overview of CPU scheduling .SH DESCRIPTION @@ -91,12 +91,12 @@ scheduling priority, .IR sched_priority . The scheduler makes its decisions based on knowledge of the scheduling policy and static priority of all threads on the system. -.PP +.P For threads scheduled under one of the normal scheduling policies (\fBSCHED_OTHER\fP, \fBSCHED_IDLE\fP, \fBSCHED_BATCH\fP), \fIsched_priority\fP is not used in scheduling decisions (it must be specified as 0). -.PP +.P Processes scheduled under one of the real-time policies (\fBSCHED_FIFO\fP, \fBSCHED_RR\fP) have a \fIsched_priority\fP value in the range 1 (low) to 99 (high). @@ -110,17 +110,17 @@ Portable programs should use and .BR sched_get_priority_max (2) to find the range of priorities supported for a particular policy. -.PP +.P Conceptually, the scheduler maintains a list of runnable threads for each possible \fIsched_priority\fP value. In order to determine which thread runs next, the scheduler looks for the nonempty list with the highest static priority and selects the thread at the head of this list. -.PP +.P A thread's scheduling policy determines where it will be inserted into the list of threads with equal static priority and how it will move inside this list. -.PP +.P All scheduling is preemptive: if a thread with a higher static priority becomes ready to run, the currently running thread will be preempted and @@ -158,7 +158,7 @@ changes the priority of the running or runnable thread identified by .I pid the effect on the thread's position in the list depends on -the direction of the change to threads priority: +the direction of the change to the thread's priority: .RS .IP (a) 5 If the thread's priority is raised, @@ -184,11 +184,11 @@ the list for its priority. A thread calling .BR sched_yield (2) will be put at the end of the list. -.PP +.P No other events will move a thread scheduled under the \fBSCHED_FIFO\fP policy in the wait list of runnable threads with equal static priority. -.PP +.P A \fBSCHED_FIFO\fP thread runs until either it is blocked by an I/O request, it is preempted by a higher priority thread, or it calls @@ -224,7 +224,7 @@ one must use the Linux-specific and .BR sched_getattr (2) system calls. -.PP +.P A sporadic task is one that has a sequence of jobs, where each job is activated at most once per period. Each job also has a @@ -242,9 +242,9 @@ is the time at which a task starts its execution. The .I absolute deadline is thus obtained by adding the relative deadline to the arrival time. -.PP +.P The following diagram clarifies these terms: -.PP +.P .in +4n .EX arrival/wakeup absolute deadline @@ -257,7 +257,7 @@ arrival/wakeup absolute deadline |<-------------- period ------------------->| .EE .in -.PP +.P When setting a .B SCHED_DEADLINE policy for a thread using @@ -274,7 +274,7 @@ Deadline to the relative deadline, and Period to the period of the task. Thus, for .B SCHED_DEADLINE scheduling, we have: -.PP +.P .in +4n .EX arrival/wakeup absolute deadline @@ -287,7 +287,7 @@ arrival/wakeup absolute deadline |<-------------- Period ------------------->| .EE .in -.PP +.P The three deadline-scheduling parameters correspond to the .IR sched_runtime , .IR sched_deadline , @@ -305,15 +305,15 @@ If .I sched_period is specified as 0, then it is made the same as .IR sched_deadline . -.PP +.P The kernel requires that: -.PP +.P .in +4n .EX sched_runtime <= sched_deadline <= sched_period .EE .in -.PP +.P .\" See __checkparam_dl in kernel/sched/core.c In addition, under the current implementation, all of the parameter values must be at least 1024 @@ -323,10 +323,10 @@ If any of these checks fails, .BR sched_setattr (2) fails with the error .BR EINVAL . -.PP +.P The CBS guarantees non-interference between tasks, by throttling threads that attempt to over-run their specified Runtime. -.PP +.P To ensure deadline scheduling guarantees, the kernel must prevent situations where the set of .B SCHED_DEADLINE @@ -339,13 +339,13 @@ if it is not, .BR sched_setattr (2) fails with the error .BR EBUSY . -.PP +.P For example, it is required (but not necessarily sufficient) for the total utilization to be less than or equal to the total number of CPUs available, where, since each thread can maximally run for Runtime per Period, that thread's utilization is its Runtime divided by its Period. -.PP +.P In order to fulfill the guarantees that are made when a thread is admitted to the .B SCHED_DEADLINE @@ -356,7 +356,7 @@ system; if any .B SCHED_DEADLINE thread is runnable, it will preempt any thread scheduled under one of the other policies. -.PP +.P A call to .BR fork (2) by a thread scheduled under the @@ -364,7 +364,7 @@ by a thread scheduled under the policy fails with the error .BR EAGAIN , unless the thread has its reset-on-fork flag set (see below). -.PP +.P A .B SCHED_DEADLINE thread that calls @@ -383,7 +383,7 @@ processes). \fBSCHED_OTHER\fP is the standard Linux time-sharing scheduler that is intended for all threads that do not require the special real-time mechanisms. -.PP +.P The thread to run is chosen from the static priority 0 list based on a \fIdynamic\fP priority that is determined only inside this list. @@ -391,7 +391,7 @@ The dynamic priority is based on the nice value (see below) and is increased for each time quantum the thread is ready to run, but denied to run by the scheduler. This ensures fair progress among all \fBSCHED_OTHER\fP threads. -.PP +.P In the Linux kernel source code, the .B SCHED_OTHER policy is actually named @@ -411,12 +411,12 @@ The nice value can be modified using .BR setpriority (2), or .BR sched_setattr (2). -.PP +.P According to POSIX.1, the nice value is a per-process attribute; that is, the threads in a process should share a nice value. However, on Linux, the nice value is a per-thread attribute: different threads in the same process may have different nice values. -.PP +.P The range of the nice value varies across UNIX systems. On modern Linux, the range is \-20 (high priority) to +19 (low priority). @@ -424,12 +424,12 @@ On some other systems, the range is \-20..20. Very early Linux kernels (before Linux 2.0) had the range \-infinity..15. .\" Linux before 1.3.36 had \-infinity..15. .\" Since Linux 1.3.43, Linux has the range \-20..19. -.PP +.P The degree to which the nice value affects the relative scheduling of .B SCHED_OTHER processes likewise varies across UNIX systems and across Linux kernel versions. -.PP +.P With the advent of the CFS scheduler in Linux 2.6.23, Linux adopted an algorithm that causes relative differences in nice values to have a much stronger effect. @@ -441,14 +441,14 @@ to a process whenever there is any other higher priority load on the system, and makes high nice values (\-20) deliver most of the CPU to applications that require it (e.g., some audio applications). -.PP +.P On Linux, the .B RLIMIT_NICE resource limit can be used to define a limit to which an unprivileged process's nice value can be raised; see .BR setrlimit (2) for details. -.PP +.P For further details on the nice value, see the subsections on the autogroup feature and group scheduling, below. .\" @@ -464,7 +464,7 @@ that the thread is CPU-intensive. Consequently, the scheduler will apply a small scheduling penalty with respect to wakeup behavior, so that this thread is mildly disfavored in scheduling decisions. -.PP +.P .\" The following paragraph is drawn largely from the text that .\" accompanied Ingo Molnar's patch for the implementation of .\" SCHED_BATCH. @@ -478,7 +478,7 @@ interactivity causing extra preemptions (between the workload's tasks). (Since Linux 2.6.23.) \fBSCHED_IDLE\fP can be used only at static priority 0; the process nice value has no influence for this policy. -.PP +.P This policy is intended for running jobs at extremely low priority (lower even than a +19 nice value with the .B SCHED_OTHER @@ -508,20 +508,20 @@ flag in .I attr.sched_flags when calling .BR sched_setattr (2). -.PP +.P Note that the constants used with these two APIs have different names. The state of the reset-on-fork flag can analogously be retrieved using .BR sched_getscheduler (2) and .BR sched_getattr (2). -.PP +.P The reset-on-fork feature is intended for media-playback applications, and can be used to prevent applications evading the .B RLIMIT_RTTIME resource limit (see .BR getrlimit (2)) by creating multiple child processes. -.PP +.P More precisely, if the reset-on-fork flag is set, the following rules apply for subsequently created children: .IP \[bu] 3 @@ -535,7 +535,7 @@ in child processes. .IP \[bu] If the calling process has a negative nice value, the nice value is reset to zero in child processes. -.PP +.P After the reset-on-fork flag has been enabled, it can be reset only if the thread has the .B CAP_SYS_NICE @@ -555,13 +555,13 @@ matches the real or effective user ID of the target thread (i.e., the thread specified by .IR pid ) whose policy is being changed. -.PP +.P A thread must be privileged .RB ( CAP_SYS_NICE ) in order to set or modify a .B SCHED_DEADLINE policy. -.PP +.P Since Linux 2.6.12, the .B RLIMIT_RTPRIO resource limit defines a ceiling on an unprivileged thread's @@ -608,7 +608,7 @@ policy so long as its nice value falls within the range permitted by its .B RLIMIT_NICE resource limit (see .BR getrlimit (2)). -.PP +.P Privileged .RB ( CAP_SYS_NICE ) threads ignore the @@ -632,7 +632,7 @@ process from freezing the system was to run (at the console) a shell scheduled under a higher static priority than the tested application. This allows an emergency kill of tested real-time applications that do not block or terminate as expected. -.PP +.P Since Linux 2.6.25, there are other techniques for dealing with runaway real-time and deadline processes. One of these is to use the @@ -642,7 +642,7 @@ a real-time process may consume. See .BR getrlimit (2) for details. -.PP +.P Since Linux 2.6.25, Linux also provides two .I /proc files that can be used to reserve a certain amount of CPU time @@ -684,7 +684,7 @@ Child processes inherit the scheduling policy and parameters across a .BR fork (2). The scheduling policy and parameters are preserved across .BR execve (2). -.PP +.P Memory locking is usually needed for real-time processes to avoid paging delays; this can be done with .BR mlock (2) @@ -701,7 +701,7 @@ parallel build processes (i.e., the .BR make (1) .B \-j flag). -.PP +.P This feature operates in conjunction with the CFS scheduler and requires a kernel that is configured with .BR CONFIG_SCHED_AUTOGROUP . @@ -711,7 +711,7 @@ a value of 0 disables the feature, while a value of 1 enables it. The default value in this file is 1, unless the kernel was booted with the .I noautogroup parameter. -.PP +.P A new autogroup is created when a new session is created via .BR setsid (2); this happens, for example, when a new terminal window is started. @@ -721,14 +721,14 @@ inherits its parent's autogroup membership. Thus, all of the processes in a session are members of the same autogroup. An autogroup is automatically destroyed when the last process in the group terminates. -.PP +.P When autogrouping is enabled, all of the members of an autogroup are placed in the same kernel scheduler "task group". The CFS scheduler employs an algorithm that equalizes the distribution of CPU cycles across task groups. The benefits of this for interactive desktop performance can be described via the following example. -.PP +.P Suppose that there are two autogroups competing for the same CPU (i.e., presume either a single CPU system or the use of .BR taskset (1) @@ -759,17 +759,17 @@ the scheduler distributes CPU cycles across task groups such that an autogroup that contains a large number of CPU-bound processes does not end up hogging CPU cycles at the expense of the other jobs on the system. -.PP +.P A process's autogroup (task group) membership can be viewed via the file .IR /proc/ pid /autogroup : -.PP +.P .in +4n .EX $ \fBcat /proc/1/autogroup\fP /autogroup\-1 nice 0 .EE .in -.PP +.P This file can also be used to modify the CPU bandwidth allocated to an autogroup. This is done by writing a number in the "nice" range to the file @@ -791,7 +791,7 @@ to fail with the error .\" A patch was posted on 23 Nov 2016 .\" ("sched/autogroup: Fix 64bit kernel nice adjustment"; .\" check later to see in which kernel version it lands. -.PP +.P The autogroup nice setting has the same meaning as the process nice value, but applies to distribution of CPU cycles to the autogroup as a whole, based on the relative nice values of other autogroups. @@ -800,12 +800,12 @@ will be a product of the autogroup's nice value (compared to other autogroups) and the process's nice value (compared to other processes in the same autogroup. -.PP +.P The use of the .BR cgroups (7) CPU controller to place processes in cgroups other than the root CPU cgroup overrides the effect of autogrouping. -.PP +.P The autogroup feature groups only processes scheduled under non-real-time policies .RB ( SCHED_OTHER , @@ -826,7 +826,7 @@ policies), the CFS scheduler employs a technique known as "group scheduling", if the kernel was configured with the .B CONFIG_FAIR_GROUP_SCHED option (which is typical). -.PP +.P Under group scheduling, threads are scheduled in "task groups". Task groups have a hierarchical relationship, rooted under the initial task group on the system, @@ -856,7 +856,7 @@ If group scheduling was disabled (i.e., the kernel was configured without .BR CONFIG_FAIR_GROUP_SCHED ), then all of the processes on the system are notionally placed in a single task group. -.PP +.P Under group scheduling, a thread's nice value has an effect for scheduling decisions .IR "only relative to other threads in the same task group" . @@ -870,7 +870,7 @@ or on a process has an effect only for scheduling relative to other processes executed in the same session (typically: the same terminal window). -.PP +.P Conversely, for two processes that are (for example) the sole CPU-bound processes in different sessions (e.g., different terminal windows, @@ -886,7 +886,7 @@ A possibly useful workaround here is to use a command such as the following to modify the autogroup nice value for .I all of the processes in a terminal session: -.PP +.P .in +4n .EX $ \fBecho 10 > /proc/self/autogroup\fP @@ -904,17 +904,17 @@ Until the patches have been completely merged into the mainline kernel, they must be installed to achieve the best real-time performance. These patches are named: -.PP +.P .in +4n .EX patch\-\fIkernelversion\fP\-rt\fIpatchversion\fP .EE .in -.PP +.P and can be downloaded from .UR http://www.kernel.org\:/pub\:/linux\:/kernel\:/projects\:/rt/ .UE . -.PP +.P Without the patches and prior to their full inclusion into the mainline kernel, the kernel configuration offers only the three preemption classes .BR CONFIG_PREEMPT_NONE , @@ -923,7 +923,7 @@ and .B CONFIG_PREEMPT_DESKTOP which respectively provide no, some, and considerable reduction of the worst-case scheduling latency. -.PP +.P With the patches applied or after their full inclusion into the mainline kernel, the additional configuration item .B CONFIG_PREEMPT_RT @@ -937,7 +937,7 @@ The .BR cgroups (7) CPU controller can be used to limit the CPU consumption of groups of processes. -.PP +.P Originally, Standard Linux was intended as a general-purpose operating system being able to handle background processes, interactive applications, and less demanding real-time applications (applications that @@ -980,10 +980,10 @@ was not possible up to Linux 2.6.17. .BR capabilities (7), .BR cpuset (7) .ad -.PP +.P .I Programming for the real world \- POSIX.4 by Bill O.\& Gallmeister, O'Reilly & Associates, Inc., ISBN 1-56592-074-0. -.PP +.P The Linux kernel source files .IR \%Documentation/\:scheduler/\:sched\-deadline\:.txt , .IR \%Documentation/\:scheduler/\:sched\-rt\-group\:.txt , diff --git a/man7/sem_overview.7 b/man7/sem_overview.7 index c452a1c..67f2e41 100644 --- a/man7/sem_overview.7 +++ b/man7/sem_overview.7 @@ -2,12 +2,12 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sem_overview 7 2022-12-04 "Linux man-pages 6.05.01" +.TH sem_overview 7 2023-10-31 "Linux man-pages 6.7" .SH NAME sem_overview \- overview of POSIX semaphores .SH DESCRIPTION POSIX semaphores allow processes and threads to synchronize their actions. -.PP +.P A semaphore is an integer whose value is never allowed to fall below zero. Two operations can be performed on semaphores: increment the semaphore value by one @@ -17,7 +17,7 @@ and decrement the semaphore value by one If the value of a semaphore is currently zero, then a .BR sem_wait (3) operation will block until the value becomes greater than zero. -.PP +.P POSIX semaphores come in two forms: named semaphores and unnamed semaphores. .TP @@ -81,7 +81,7 @@ When the semaphore is no longer required, and before the memory in which it is located is deallocated, the semaphore should be destroyed using .BR sem_destroy (3). -.PP +.P The remainder of this section describes some specific details of the Linux implementation of POSIX semaphores. .SS Versions @@ -111,7 +111,7 @@ with names of the form rather than .B NAME_MAX characters.) -.PP +.P Since Linux 2.6.19, ACLs can be placed on files under this directory, to control object permissions on a per-user and per-group basis. .SH NOTES diff --git a/man7/session-keyring.7 b/man7/session-keyring.7 index d8a950f..d67de25 100644 --- a/man7/session-keyring.7 +++ b/man7/session-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH session-keyring 7 2023-03-12 "Linux man-pages 6.05.01" +.TH session-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME session-keyring \- session shared process keyring .SH DESCRIPTION @@ -18,17 +18,17 @@ may revoke the session keyring on logout. (In typical configurations, PAM does do this revocation.) The session keyring has the name (description) .IR _ses . -.PP +.P A special serial number value, .BR KEY_SPEC_SESSION_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's session keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@s\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P A process's session keyring is inherited across .BR clone (2), .BR fork (2), @@ -40,7 +40,7 @@ is preserved across even when the executable is set-user-ID or set-group-ID or has capabilities. The session keyring is destroyed when the last process that refers to it exits. -.PP +.P If a process doesn't have a session keyring when it is accessed, then, under certain circumstances, the .BR user\-session\-keyring (7) @@ -76,11 +76,11 @@ identical security attributes and must be single threaded. .BR keyctl (2) .B KEYCTL_SESSION_TO_PARENT operation.) -.PP +.P These operations are also exposed through the .BR keyctl (1) utility as: -.PP +.P .in +4n .EX keyctl session @@ -88,9 +88,9 @@ keyctl session \- [ ...] keyctl session [ ...] .EE .in -.PP +.P and: -.PP +.P .in +4n .EX keyctl new_session diff --git a/man7/shm_overview.7 b/man7/shm_overview.7 index 9a33ea0..a049e4c 100644 --- a/man7/shm_overview.7 +++ b/man7/shm_overview.7 @@ -3,13 +3,13 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH shm_overview 7 2022-12-04 "Linux man-pages 6.05.01" +.TH shm_overview 7 2023-10-31 "Linux man-pages 6.7" .SH NAME shm_overview \- overview of POSIX shared memory .SH DESCRIPTION The POSIX shared memory API allows processes to communicate information by sharing a region of memory. -.PP +.P The interfaces employed in the API are: .TP 15 .BR shm_open (3) @@ -80,7 +80,7 @@ to control the permissions of objects in the virtual filesystem. .SH NOTES Typically, processes must synchronize their access to a shared memory object, using, for example, POSIX semaphores. -.PP +.P System V shared memory .RB ( shmget (2), .BR shmop (2), diff --git a/man7/sigevent.7 b/man7/sigevent.7 index 1ae860f..b43f1bb 100644 --- a/man7/sigevent.7 +++ b/man7/sigevent.7 @@ -1,120 +1 @@ -.\" Copyright (C) 2006, 2010 Michael Kerrisk -.\" Copyright (C) 2009 Petr Baudis -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH sigevent 7 2022-10-30 "Linux man-pages 6.05.01" -.SH NAME -sigevent \- structure for notification from asynchronous routines -.SH SYNOPSIS -.nf -#include -.PP -union sigval { /* Data passed with notification */ - int sival_int; /* Integer value */ - void *sival_ptr; /* Pointer value */ -}; -.PP -struct sigevent { - int sigev_notify; /* Notification method */ - int sigev_signo; /* Notification signal */ - union sigval sigev_value; - /* Data passed with notification */ - void (*sigev_notify_function)(union sigval); - /* Function used for thread - notification (SIGEV_THREAD) */ - void *sigev_notify_attributes; - /* Attributes for notification thread - (SIGEV_THREAD) */ - pid_t sigev_notify_thread_id; - /* ID of thread to signal - (SIGEV_THREAD_ID); Linux-specific */ -}; -.fi -.SH DESCRIPTION -The -.I sigevent -structure is used by various APIs -to describe the way a process is to be notified about an event -(e.g., completion of an asynchronous request, expiration of a timer, -or the arrival of a message). -.PP -The definition shown in the SYNOPSIS is approximate: -some of the fields in the -.I sigevent -structure may be defined as part of a union. -Programs should employ only those fields relevant -to the value specified in -.IR sigev_notify . -.PP -The -.I sigev_notify -field specifies how notification is to be performed. -This field can have one of the following values: -.TP -.B SIGEV_NONE -A "null" notification: don't do anything when the event occurs. -.TP -.B SIGEV_SIGNAL -Notify the process by sending the signal specified in -.IR sigev_signo . -.IP -If the signal is caught with a signal handler that was registered using the -.BR sigaction (2) -.B SA_SIGINFO -flag, then the following fields are set in the -.I siginfo_t -structure that is passed as the second argument of the handler: -.RS -.TP 10 -.I si_code -This field is set to a value that depends on the API -delivering the notification. -.TP -.I si_signo -This field is set to the signal number (i.e., the same value as in -.IR sigev_signo ). -.TP -.I si_value -This field is set to the value specified in -.IR sigev_value . -.RE -.IP -Depending on the API, other fields may also be set in the -.I siginfo_t -structure. -.IP -The same information is also available if the signal is accepted using -.BR sigwaitinfo (2). -.TP -.B SIGEV_THREAD -Notify the process by invoking -.I sigev_notify_function -"as if" it were the start function of a new thread. -(Among the implementation possibilities here are that -each timer notification could result in the creation of a new thread, -or that a single thread is created to receive all notifications.) -The function is invoked with -.I sigev_value -as its sole argument. -If -.I sigev_notify_attributes -is not NULL, it should point to a -.I pthread_attr_t -structure that defines attributes for the new thread (see -.BR pthread_attr_init (3)). -.TP -.BR SIGEV_THREAD_ID " (Linux-specific)" -.\" | SIGEV_SIGNAL vs not? -Currently used only by POSIX timers; see -.BR timer_create (2). -.SH SEE ALSO -.BR timer_create (2), -.BR aio_fsync (3), -.BR aio_read (3), -.BR aio_write (3), -.BR getaddrinfo_a (3), -.BR lio_listio (3), -.BR mq_notify (3), -.BR aio (7), -.BR pthreads (7) +.so man3type/sigevent.3type diff --git a/man7/signal-safety.7 b/man7/signal-safety.7 index 4bcb478..d307dda 100644 --- a/man7/signal-safety.7 +++ b/man7/signal-safety.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH signal-safety 7 2023-02-05 "Linux man-pages 6.05.01" +.TH signal-safety 7 2023-10-31 "Linux man-pages 6.7" .SH NAME signal-safety \- async-signal-safe functions .SH DESCRIPTION @@ -15,13 +15,13 @@ Many functions are async-signal-safe. In particular, nonreentrant functions are generally unsafe to call from a signal handler. -.PP +.P The kinds of issues that render a function unsafe can be quickly understood when one considers the implementation of the .I stdio library, all of whose functions are not async-signal-safe. -.PP +.P When performing buffered I/O on a file, the .I stdio functions must maintain a statically allocated data buffer @@ -38,7 +38,7 @@ the program is interrupted by a signal handler that also calls then the second call to .BR printf (3) will operate on inconsistent data, with unpredictable results. -.PP +.P To avoid problems with unsafe functions, there are two possible choices: .IP (a) 5 Ensure that @@ -50,26 +50,26 @@ with respect to global variables in the main program. Block signal delivery in the main program when calling functions that are unsafe or operating on global data that is also accessed by the signal handler. -.PP +.P Generally, the second choice is difficult in programs of any complexity, so the first choice is taken. -.PP +.P POSIX.1 specifies a set of functions that an implementation must make async-signal-safe. (An implementation may provide safe implementations of additional functions, but this is not required by the standard and other implementations may not provide the same guarantees.) -.PP +.P In general, a function is async-signal-safe either because it is reentrant or because it is atomic with respect to signals (i.e., its execution can't be interrupted by a signal handler). -.PP +.P The set of functions required to be async-signal-safe by POSIX.1 is shown in the following table. The functions not otherwise noted were required to be async-signal-safe in POSIX.1-2001; the table details changes in the subsequent standards. -.PP +.P .TS lb lb l l. @@ -272,7 +272,7 @@ T} \fBwmemset\fP(3) Added in POSIX.1-2008 TC2 \fBwrite\fP(2) .TE -.PP +.P Notes: .IP \[bu] 3 POSIX.1-2001 and POSIX.1-2001 TC2 required the functions diff --git a/man7/signal.7 b/man7/signal.7 index 6f6f9c9..39281e5 100644 --- a/man7/signal.7 +++ b/man7/signal.7 @@ -23,7 +23,7 @@ .\" Added section on stop/cont signals interrupting syscalls. .\" 2008-10-05, mtk: various additions .\" -.TH signal 7 2023-04-03 "Linux man-pages 6.05.01" +.TH signal 7 2023-10-31 "Linux man-pages 6.7" .SH NAME signal \- overview of signals .SH DESCRIPTION @@ -34,7 +34,7 @@ Each signal has a current .IR disposition , which determines how the process behaves when it is delivered the signal. -.PP +.P The entries in the "Action" column of the table below specify the default disposition for each signal, as follows: .TP @@ -53,7 +53,7 @@ Default action is to stop the process. .TP Cont Default action is to continue the process if it is currently stopped. -.PP +.P A process can change the disposition of a signal using .BR sigaction (2) or @@ -69,18 +69,18 @@ or catch the signal with a .IR "signal handler" , a programmer-defined function that is automatically invoked when the signal is delivered. -.PP +.P By default, a signal handler is invoked on the normal process stack. It is possible to arrange that the signal handler uses an alternate stack; see .BR sigaltstack (2) for a discussion of how to do this and when it might be useful. -.PP +.P The signal disposition is a per-process attribute: in a multithreaded application, the disposition of a particular signal is the same for all threads. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal dispositions. @@ -164,7 +164,7 @@ which means that it will not be delivered until it is later unblocked. Between the time when it is generated and when it is delivered a signal is said to be .IR pending . -.PP +.P Each thread in a process has an independent .IR "signal mask" , which indicates the set of signals that the thread is currently blocking. @@ -173,13 +173,13 @@ A thread can manipulate its signal mask using In a traditional single-threaded application, .BR sigprocmask (2) can be used to manipulate the signal mask. -.PP +.P A child created via .BR fork (2) inherits a copy of its parent's signal mask; the signal mask is preserved across .BR execve (2). -.PP +.P A signal may be process-directed or thread-directed. A process-directed signal is one that is targeted at (and thus pending for) the process as a whole. @@ -202,7 +202,7 @@ interfaces such as .BR tgkill (2) or .BR pthread_kill (3). -.PP +.P A process-directed signal may be delivered to any one of the threads that does not currently have the signal blocked. .\" Joseph C. Sible notes: @@ -225,14 +225,14 @@ threads that does not currently have the signal blocked. .\" If more than one of the threads has the signal unblocked, then the kernel chooses an arbitrary thread to which to deliver the signal. -.PP +.P A thread can obtain the set of signals that it currently has pending using .BR sigpending (2). This set will consist of the union of the set of pending process-directed signals and the set of signals pending for the calling thread. -.PP +.P A child created via .BR fork (2) initially has an empty pending signal set; @@ -320,7 +320,7 @@ Upon completion of the call to the kernel transfers control back to user space, and the thread recommences execution at the point where it was interrupted by the signal handler. -.PP +.P Note that if the signal handler does not return (e.g., control is transferred out of the handler using .BR siglongjmp (3), @@ -338,7 +338,7 @@ may or may not restore the signal mask, depending on the .I savesigs value that was specified in the corresponding call to .BR sigsetjmp (3).) -.PP +.P From the kernel's point of view, execution of the signal handler code is exactly the same as the execution of any other user-space code. @@ -405,13 +405,13 @@ SIGXFSZ P2001 Core File size limit exceeded (4.2BSD); see \fBsetrlimit\fP(2) SIGWINCH \- Ign Window resize signal (4.3BSD, Sun) .TE -.PP +.P The signals .B SIGKILL and .B SIGSTOP cannot be caught, blocked, or ignored. -.PP +.P Up to and including Linux 2.2, the default behavior for .BR SIGSYS ", " SIGXCPU ", " SIGXFSZ , and (on architectures other than SPARC and MIPS) @@ -422,17 +422,17 @@ was to terminate the process (without a core dump). is to terminate the process without a core dump.) Linux 2.4 conforms to the POSIX.1-2001 requirements for these signals, terminating the process with a core dump. -.PP +.P .B SIGEMT is not specified in POSIX.1-2001, but nevertheless appears on most other UNIX systems, where its default action is typically to terminate the process with a core dump. -.PP +.P .B SIGPWR (which is not specified in POSIX.1-2001) is typically ignored by default on those other UNIX systems where it appears. -.PP +.P .B SIGIO (which is not specified in POSIX.1-2001) is ignored by default on several other UNIX systems. @@ -440,7 +440,7 @@ on several other UNIX systems. .SS Queueing and delivery semantics for standard signals If multiple standard signals are pending for a process, the order in which the signals are delivered is unspecified. -.PP +.P Standard signals do not queue. If multiple instances of a standard signal are generated while that signal is blocked, @@ -510,7 +510,7 @@ SIGLOST \- \-/29 \- \- SIGSYS 31 12 12 31 SIGUNUSED 31 \- \- 31 .TE -.PP +.P Note the following: .IP \[bu] 3 Where defined, @@ -538,7 +538,7 @@ and POSIX.1-2001 requires that an implementation support at least .B _POSIX_RTSIG_MAX (8) real-time signals. -.PP +.P The Linux kernel supports a range of 33 different real-time signals, numbered 32 to 64. However, the glibc POSIX threads implementation internally uses @@ -560,14 +560,14 @@ and include suitable (run-time) checks that .BR SIGRTMIN +n does not exceed .BR SIGRTMAX . -.PP +.P Unlike standard signals, real-time signals have no predefined meanings: the entire set of real-time signals can be used for application-defined purposes. -.PP +.P The default action for an unhandled real-time signal is to terminate the receiving process. -.PP +.P Real-time signals are distinguished by the following: .IP \[bu] 3 Multiple instances of real-time signals can be queued. @@ -602,12 +602,12 @@ starting with the lowest-numbered signal. (I.e., low-numbered signals have highest priority.) By contrast, if multiple standard signals are pending for a process, the order in which they are delivered is unspecified. -.PP +.P If both standard and real-time signals are pending for a process, POSIX leaves it unspecified which is delivered first. Linux, like many other implementations, gives priority to standard signals in this case. -.PP +.P According to POSIX, an implementation should permit at least .B _POSIX_SIGQUEUE_MAX (32) real-time signals to be queued to @@ -630,7 +630,7 @@ resource limit, which specifies a per-user limit for queued signals; see .BR setrlimit (2) for further details. -.PP +.P The addition of real-time signals required the widening of the signal set structure .RI ( sigset_t ) @@ -658,7 +658,7 @@ the call is automatically restarted after the signal handler returns; or .IP \[bu] the call fails with the error .BR EINTR . -.PP +.P Which of these two behaviors occurs depends on the interface and whether or not the signal handler was established using the .B SA_RESTART @@ -666,7 +666,7 @@ flag (see .BR sigaction (2)). The details vary across UNIX systems; below, the details for Linux. -.PP +.P If a blocked call to one of the following interfaces is interrupted by a signal handler, then the call is automatically restarted after the signal handler returns if the @@ -771,7 +771,7 @@ file descriptor .\" commit 1ca39ab9d21ac93f94b9e3eb364ea9a5cf2aba06 beforehand, always failed with .BR EINTR ). -.PP +.P The following interfaces are never restarted after being interrupted by a signal handler, regardless of the use of @@ -838,12 +838,12 @@ and .BR usleep (3). .IP \[bu] .BR io_getevents (2). -.PP +.P The .BR sleep (3) function is also never restarted if interrupted by a handler, but gives a success return: the number of seconds remaining to sleep. -.PP +.P In certain circumstances, the .BR seccomp (2) user-space notification feature can lead to restarting of system calls @@ -861,7 +861,7 @@ and then resumed via .BR SIGCONT . This behavior is not sanctioned by POSIX.1, and doesn't occur on other systems. -.PP +.P The Linux interfaces that display this behavior are: .IP \[bu] 3 "Input" socket interfaces, when a timeout @@ -925,7 +925,7 @@ POSIX.1, except as noted. .SH NOTES For a discussion of async-signal-safe functions, see .BR signal\-safety (7). -.PP +.P The .IR /proc/ pid /task/ tid /status file contains various fields that show the signals @@ -961,13 +961,13 @@ and Which of these signals is delivered, for any given hardware exception, is not documented and does not always make sense. -.PP +.P For example, an invalid memory access that causes delivery of .B SIGSEGV on one CPU architecture may cause delivery of .B SIGBUS on another architecture, or vice versa. -.PP +.P For another example, using the x86 .I int instruction with a forbidden argument @@ -1016,4 +1016,4 @@ because of how the CPU reports the forbidden operation to the kernel. .BR proc (5), .BR nptl (7), .BR pthreads (7), -.BR sigevent (7) +.BR sigevent (3type) diff --git a/man7/sock_diag.7 b/man7/sock_diag.7 index adf47b7..3da3b4a 100644 --- a/man7/sock_diag.7 +++ b/man7/sock_diag.7 @@ -2,7 +2,7 @@ .\" Copyright (c) 2016 Dmitry V. Levin .\" .\" SPDX-License-Identifier: GPL-2.0-or-later -.TH sock_diag 7 2023-05-03 "Linux man-pages 6.05.01" +.TH sock_diag 7 2023-10-31 "Linux man-pages 6.7" .SH NAME sock_diag \- obtaining information about sockets .SH SYNOPSIS @@ -11,7 +11,7 @@ sock_diag \- obtaining information about sockets .B #include .BR "#include " " /* for UNIX domain sockets */" .BR "#include " " /* for IPv4 and IPv6 sockets */" -.PP +.P .BI "diag_socket = socket(AF_NETLINK, " socket_type ", NETLINK_SOCK_DIAG);" .fi .SH DESCRIPTION @@ -19,16 +19,16 @@ The sock_diag netlink subsystem provides a mechanism for obtaining information about sockets of various address families from the kernel. This subsystem can be used to obtain information about individual sockets or request a list of sockets. -.PP +.P In the request, the caller can specify additional information it would like to obtain about the socket, for example, memory information or information specific to the address family. -.PP +.P When requesting a list of sockets, the caller can specify filters that would be applied by the kernel to select a subset of sockets to report. For now, there is only the ability to filter sockets by state (connected, listening, and so on.) -.PP +.P Note that sock_diag reports only those sockets that have a name; that is, either sockets bound explicitly with .BR bind (2) @@ -51,7 +51,7 @@ field set to .BR SOCK_DIAG_BY_FAMILY . It is followed by a header specific to the address family that starts with a common part shared by all address families: -.PP +.P .in +4n .EX struct sock_diag_req { @@ -60,7 +60,7 @@ struct sock_diag_req { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sdiag_family @@ -79,7 +79,7 @@ constant for and .BR AF_INET6 , and to 0 otherwise. -.PP +.P If the .I nlmsg_flags field of the @@ -98,7 +98,7 @@ The array is to be accessed with the standard macros from the .BR netlink (3) API. -.PP +.P Each object is the NLA (netlink attributes) list that is to be accessed with the .B RTA_* @@ -108,7 +108,7 @@ API. .\" .SS UNIX domain sockets For UNIX domain sockets the request is represented in the following structure: -.PP +.P .in +4n .EX struct unix_diag_req { @@ -122,13 +122,13 @@ struct unix_diag_req { }; .EE .in -.PP +.P The fields of this structure are as follows: .TP .I sdiag_family The address family; it should be set to .BR AF_UNIX . -.PP +.P .I sdiag_protocol .PD 0 .TP @@ -141,11 +141,11 @@ This is a bit mask that defines a filter of sockets states. Only those sockets whose states are in this mask will be reported. Ignored when querying for an individual socket. Supported values are: -.PP +.P .RS 12 1 << .B TCP_ESTABLISHED -.PP +.P 1 << .B TCP_LISTEN .RE @@ -253,7 +253,7 @@ The attribute reported in answer to this request is .BR UNIX_DIAG_MEMINFO . The payload associated with this attribute is an array of __u32 values described below in the subsection "Socket memory information". -.PP +.P The following attributes are reported back without any specific request: .TP .B UNIX_DIAG_SHUTDOWN @@ -269,9 +269,9 @@ This is an array of opaque identifiers that could be used along with to specify an individual socket. It is ignored when querying for a list of sockets, as well as when all its elements are set to \-1. -.PP +.P The response to a query for UNIX domain sockets is represented as an array of -.PP +.P .in +4n .EX struct unix_diag_msg { @@ -284,9 +284,9 @@ struct unix_diag_msg { }; .EE .in -.PP +.P followed by netlink attributes. -.PP +.P The fields of this structure are as follows: .TP .I udiag_family @@ -319,7 +319,7 @@ queries. .SS IPv4 and IPv6 sockets For IPv4 and IPv6 sockets, the request is represented in the following structure: -.PP +.P .in +4n .EX struct inet_diag_req_v2 { @@ -332,11 +332,11 @@ struct inet_diag_req_v2 { }; .EE .in -.PP +.P where .I "struct inet_diag_sockid" is defined as follows: -.PP +.P .in +4n .EX struct inet_diag_sockid { @@ -349,7 +349,7 @@ struct inet_diag_sockid { }; .EE .in -.PP +.P The fields of .I "struct inet_diag_req_v2" are as follows: @@ -447,7 +447,7 @@ about individual sockets, and is reported back in each response. Unlike UNIX domain sockets, IPv4 and IPv6 sockets are identified using addresses and ports. All values are in network byte order. -.PP +.P The fields of .I "struct inet_diag_sockid" are as follows: @@ -472,9 +472,9 @@ This is an array of opaque identifiers that could be used along with other fields of this structure to specify an individual socket. It is ignored when querying for a list of sockets, as well as when all its elements are set to \-1. -.PP +.P The response to a query for IPv4 or IPv6 sockets is represented as an array of -.PP +.P .in +4n .EX struct inet_diag_msg { @@ -493,9 +493,9 @@ struct inet_diag_msg { }; .EE .in -.PP +.P followed by netlink attributes. -.PP +.P The fields of this structure are as follows: .TP .I idiag_family @@ -611,7 +611,7 @@ In Linux 3.3, it was renamed to and extended to support .B AF_UNIX sockets. -.PP +.P .B UNIX_DIAG_MEMINFO and .B INET_DIAG_SKMEMINFO @@ -621,7 +621,7 @@ Linux. .SH EXAMPLES The following example program prints inode number, peer's inode number, and name of all UNIX domain sockets in the current namespace. -.PP +.P .EX #include #include diff --git a/man7/socket.7 b/man7/socket.7 index 2cc24d9..619139e 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -47,13 +47,13 @@ .\" commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e .\" Author: Michal Sekletar .\" -.TH socket 7 2023-07-15 "Linux man-pages 6.05.01" +.TH socket 7 2024-01-16 "Linux man-pages 6.7" .SH NAME socket \- Linux socket interface .SH SYNOPSIS .nf .B #include -.PP +.P .IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol ); .fi .SH DESCRIPTION @@ -79,7 +79,7 @@ for more information on families and types. These functions are used by the user process to send or receive packets and to do other socket operations. For more information, see their respective manual pages. -.PP +.P .BR socket (2) creates a socket, .BR connect (2) @@ -95,7 +95,7 @@ is used to get a new socket with a new incoming connection. returns two connected anonymous sockets (implemented only for a few local families like .BR AF_UNIX ) -.PP +.P .BR send (2), .BR sendto (2), and @@ -117,7 +117,7 @@ In addition, the standard I/O operations like and .BR readv (2) can be used to read and write data. -.PP +.P .BR getsockname (2) returns the local socket address and .BR getpeername (2) @@ -128,18 +128,18 @@ and are used to set or get socket layer or protocol options. .BR ioctl (2) can be used to set or read some other options. -.PP +.P .BR close (2) is used to close a socket. .BR shutdown (2) closes parts of a full-duplex socket connection. -.PP +.P Seeking, or calling .BR pread (2) or .BR pwrite (2) with a nonzero position is not supported on sockets. -.PP +.P It is possible to do nonblocking I/O on sockets by setting the .B O_NONBLOCK flag on a socket file descriptor using @@ -208,7 +208,7 @@ T} .\" or .\" .BR close (2). .TE -.PP +.P An alternative to .BR poll (2) and @@ -244,7 +244,7 @@ the various system calls (e.g., .BR getpeername (2)), which are generic to all socket domains, to determine the domain of a particular socket address. -.PP +.P To allow any type of socket address to be passed to interfaces in the sockets API, the type @@ -254,7 +254,7 @@ The purpose of this type is purely to allow casting of domain-specific socket address types to a "generic" type, so as to avoid compiler warnings about type mismatches in calls to the sockets API. -.PP +.P In addition, the sockets API provides the data type .IR "struct sockaddr_storage". This type @@ -264,13 +264,13 @@ address structures; it is large enough and is aligned properly. IPv6 socket addresses.) The structure includes the following field, which can be used to identify the type of socket address actually stored in the structure: -.PP +.P .in +4n .EX sa_family_t ss_family; .EE .in -.PP +.P The .I sockaddr_storage structure is useful in programs that must handle socket addresses @@ -303,7 +303,9 @@ The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. This socket option is read-only. .TP -.BR SO_ATTACH_FILTER " (since Linux 2.2), " SO_ATTACH_BPF " (since Linux 3.19)" +.BR SO_ATTACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_ATTACH_BPF " (since Linux 3.19)" Attach a classic BPF .RB ( SO_ATTACH_FILTER ) or an extended BPF @@ -348,7 +350,9 @@ never has more than one filter defined. Both classic and extended BPF are explained in the kernel source file .I Documentation/networking/filter.txt .TP -.BR SO_ATTACH_REUSEPORT_CBPF ", " SO_ATTACH_REUSEPORT_EBPF +.B SO_ATTACH_REUSEPORT_CBPF +.TQ +.B SO_ATTACH_REUSEPORT_EBPF For use with the .B SO_REUSEPORT option, these options allow the user to set a classic BPF @@ -451,7 +455,9 @@ Allowed only for processes with the .B CAP_NET_ADMIN capability or an effective user ID of 0. .TP -.BR SO_DETACH_FILTER " (since Linux 2.2), " SO_DETACH_BPF " (since Linux 3.19)" +.BR SO_DETACH_FILTER " (since Linux 2.2)" +.TQ +.BR SO_DETACH_BPF " (since Linux 3.19)" These two options, which are synonyms, may be used to remove the classic or extended BPF program attached to a socket with either @@ -608,7 +614,9 @@ Changing the mark can be used for mark-based routing without netfilter or for packet filtering. Setting this option requires the .B CAP_NET_ADMIN -capability. +or +.B CAP_NET_RAW +(since Linux 5.17) capability. .TP .B SO_OOBINLINE If this option is enabled, @@ -1054,7 +1062,7 @@ The signal is not sent when the write call specified the .B MSG_NOSIGNAL flag. -.PP +.P When requested with the .B FIOSETOWN .BR fcntl (2) @@ -1079,7 +1087,7 @@ field of its See .BR fcntl (2) for more information. -.PP +.P Under some circumstances (e.g., multiple processes accessing a single socket), the condition that caused the .B SIGIO @@ -1124,7 +1132,7 @@ per socket. .SS Ioctls These operations can be accessed using .BR ioctl (2): -.PP +.P .in +4n .EX .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" @@ -1198,7 +1206,7 @@ or signals, or 0 when none is set. -.PP +.P Valid .BR fcntl (2) operations: @@ -1231,7 +1239,7 @@ Linux assumes that half of the send/receive buffer is used for internal kernel structures; thus the values in the corresponding .I /proc files are twice what can be observed on the wire. -.PP +.P Linux will allow port reuse only with the .B SO_REUSEADDR option diff --git a/man7/spufs.7 b/man7/spufs.7 index fc3b424..3e8c2ed 100644 --- a/man7/spufs.7 +++ b/man7/spufs.7 @@ -10,14 +10,14 @@ .\" 2007-07-10, quite a lot of polishing by mtk .\" 2007-09-28, updates for newer kernels by Jeremy Kerr .\" -.TH spufs 7 2023-02-05 "Linux man-pages 6.05.01" +.TH spufs 7 2023-10-31 "Linux man-pages 6.7" .SH NAME spufs \- SPU filesystem .SH DESCRIPTION The SPU filesystem is used on PowerPC machines that implement the Cell Broadband Engine Architecture in order to access Synergistic Processor Units (SPUs). -.PP +.P The filesystem provides a name space similar to POSIX shared memory or message queues. Users that have write permissions @@ -26,7 +26,7 @@ on the filesystem can use to establish SPU contexts under the .B spufs root directory. -.PP +.P Every SPU context is represented by a directory containing a predefined set of files. These files can be @@ -58,7 +58,7 @@ supported on regular filesystems. This list details the supported operations and the deviations from the standard behavior described in the respective man pages. -.PP +.P All files that support the .BR read (2) operation also support @@ -80,7 +80,7 @@ structure that contain reliable information are .IR st_uid , and .IR st_gid . -.PP +.P All files support the .BR chmod (2)/\c .BR fchmod (2) @@ -91,7 +91,7 @@ operations, but will not be able to grant permissions that contradict the possible operations (e.g., read access on the .I wbox file). -.PP +.P The current set of files is: .TP .I /capabilities @@ -105,7 +105,7 @@ This context may be scheduled. .TP .B step This context can be run in single-step mode, for debugging. -.PP +.P New capabilities flags may be added in the future. .RE .TP @@ -119,7 +119,15 @@ The possible operations on an open file are: .RS .TP -.BR read "(2), " pread "(2), " write "(2), " pwrite "(2), " lseek (2) +.BR read (2) +.TQ +.BR pread (2) +.TQ +.BR write (2) +.TQ +.BR pwrite (2) +.TQ +.BR lseek (2) These operate as usual, with the exception that .BR lseek (2), .BR write (2), @@ -289,7 +297,11 @@ file returns whenever space is available for writing. .RE .TP -.IR /mbox_stat ", " /ibox_stat ", " /wbox_stat +.I /mbox_stat +.TQ +.I /ibox_stat +.TQ +.I /wbox_stat These are read-only files that contain the length of the current queue of each mailbox\[em]that is, how many words can be read from .IR mbox " or " ibox @@ -324,8 +336,21 @@ the respective mailbox without blocking or returning an error. .RE .TP -.IR /npc ", " /decr ", " /decr_status ", " /spu_tag_mask ", " \ -/event_mask ", " /event_status ", " /srr0 ", " /lslr +.I /npc +.TQ +.I /decr +.TQ +.I /decr_status +.TQ +.I /spu_tag_mask +.TQ +.I /event_mask +.TQ +.I /event_status +.TQ +.I /srr0 +.TQ +.I /lslr Internal registers of the SPU. These files contain an ASCII string representing the hex value of the specified register. @@ -433,7 +458,9 @@ updating the value of the register. .RE .TP -.IR /signal1 ", " /signal2 +.I /signal1 +.TQ +.I /signal2 The files provide access to the two signal notification channels of an SPU. These are read-write files that operate on four-byte words. @@ -484,7 +511,9 @@ or files respectively. .RE .TP -.IR /signal1_type ", " /signal2_type +.I /signal1_type +.TQ +.I /signal2_type These two files change the behavior of the .I signal1 and @@ -524,7 +553,15 @@ Subsequent writes to the same file descriptor overwrite the previous setting. .RE .TP -.IR /mbox_info ", " /ibox_info ", " /wbox_info ", " /dma_into ", " /proxydma_info +.I /mbox_info +.TQ +.I /ibox_info +.TQ +.I /wbox_info +.TQ +.I /dma_into +.TQ +.I /proxydma_info Read-only files that contain the saved state of the SPU mailboxes and DMA queues. This allows the SPU status to be inspected, mainly for debugging. @@ -763,5 +800,5 @@ none /spu spufs gid=spu 0 0 .BR spu_create (2), .BR spu_run (2), .BR capabilities (7) -.PP +.P .I The Cell Broadband Engine Architecture (CBEA) specification diff --git a/man7/standards.7 b/man7/standards.7 index c1df6f8..a058b92 100644 --- a/man7/standards.7 +++ b/man7/standards.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH standards 7 2023-03-13 "Linux man-pages 6.05.01" +.TH standards 7 2023-10-31 "Linux man-pages 6.7" .SH NAME standards \- C and UNIX Standards .SH DESCRIPTION @@ -183,7 +183,9 @@ See also .UR http://www.unix.org\:/version2/ .UE .) .TP -.B POSIX.1-2001, SUSv3 +.B POSIX.1-2001 +.TQ +.B SUSv3 This was a 2001 revision and consolidation of the POSIX.1, POSIX.2, and SUS standards into a single document, conducted under the auspices of the Austin Group @@ -233,7 +235,9 @@ of the original 2001 standard have occurred: TC1 in 2003 and TC2 in 2004. .TP -.B POSIX.1-2008, SUSv4 +.B POSIX.1-2008 +.TQ +.B SUSv4 Work on the next revision of POSIX.1/SUS was completed and ratified in 2008. The standard is available online at @@ -286,7 +290,7 @@ Technical Corrigenda 1 and 2 applied. .B SUSv4 2018 edition This is equivalent to POSIX.1-2017, with the addition of the XCurses specification. -.PP +.P The interfaces documented in POSIX.1/SUS are available as manual pages under sections 0p (header files), 1p (commands), and 3p (functions); diff --git a/man7/string_copying.7 b/man7/string_copying.7 index 814eabd..43bc00d 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -2,18 +2,17 @@ .\" .\" SPDX-License-Identifier: BSD-3-Clause .\" -.TH string_copying 7 2023-07-29 "Linux man-pages 6.05.01" +.TH string_copying 7 2023-12-17 "Linux man-pages 6.7" .\" ----- NAME :: -----------------------------------------------------/ .SH NAME stpcpy, strcpy, strcat, stpecpy, +strtcpy, strlcpy, strlcat, stpncpy, strncpy, -zustr2ustp, zustr2stp, -strncat, -ustpcpy, ustr2stp +strncat \- copying strings and character sequences .\" ----- SYNOPSIS :: -------------------------------------------------/ .SH SYNOPSIS @@ -22,63 +21,57 @@ ustpcpy, ustr2stp .nf // Chain-copy a string. .BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); -.PP +.P // Copy/catenate a string. .BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); .BI "char *strcat(char *restrict " dst ", const char *restrict " src ); -.PP +.P // Chain-copy a string with truncation. .BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); -.PP +.P // Copy/catenate a string with truncation. -.BI "size_t strlcpy(char " dst "[restrict ." sz "], \ +.BI "ssize_t strtcpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.BI "size_t strlcat(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "size_t strlcpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); +.BI " size_t " dsize ); +.BI "size_t strlcat(char " dst "[restrict ." dsize "], \ +const char *restrict " src , +.BI " size_t " dsize ); .fi .\" ----- SYNOPSIS :: Null-padded character sequences --------/ .SS Null-padded character sequences .nf -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *stpncpy(char " dst "[restrict ." sz "], \ +// Fill a fixed-size buffer with characters from a string +// and pad with null bytes. +.BI "char *strncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.PP -// Zero a fixed-width buffer, and -// copy a string into a character sequence with truncation. -.BI "char *strncpy(char " dst "[restrict ." sz "], \ +.BI " size_t " dsize ); +.BI "char *stpncpy(char " dst "[restrict ." dsize "], \ const char *restrict " src , -.BI " size_t " sz ); -.PP +.BI " size_t " dsize ); +.P // Chain-copy a null-padded character sequence into a character sequence. -.BI "char *zustr2ustp(char *restrict " dst ", \ -const char " src "[restrict ." sz ], -.BI " size_t " sz ); -.PP +.I mempcpy(dst, src, strnlen(src, NITEMS(src))); +.P // Chain-copy a null-padded character sequence into a string. -.BI "char *zustr2stp(char *restrict " dst ", \ -const char " src "[restrict ." sz ], -.BI " size_t " sz ); -.PP +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]); +.P // Catenate a null-padded character sequence into a string. -.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ], -.BI " size_t " sz ); +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ], +.BI " size_t " ssize ); .fi -.\" ----- SYNOPSIS :: Measured character sequences --------------------/ -.SS Measured character sequences +.\" ----- SYNOPSIS :: Known-length character sequences --------------------/ +.SS Known-length character sequences .nf -// Chain-copy a measured character sequence. -.BI "char *ustpcpy(char *restrict " dst ", \ -const char " src "[restrict ." len ], -.BI " size_t " len ); -.PP -// Chain-copy a measured character sequence into a string. -.BI "char *ustr2stp(char *restrict " dst ", \ -const char " src "[restrict ." len ], +// Chain-copy a known-length character sequence. +.BI "void *mempcpy(void " dst "[restrict ." len "], \ +const void " src "[restrict ." len ], .BI " size_t " len ); +.P +// Chain-copy a known-length character sequence into a string. +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]); .fi .SH DESCRIPTION .\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/ @@ -86,7 +79,7 @@ const char " src "[restrict ." len ], .\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/ .TP .IR "string " ( str ) -is a sequence of zero or more non-null characters followed by a null byte. +is a sequence of zero or more non-null characters followed by a null character. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq .TP .I character sequence @@ -96,15 +89,18 @@ However, with appropriate care, a string can be used in the place of a character sequence. .RS .TP -.IR "null-padded character sequence " ( zustr ) -Character sequences can be contained in fixed-width buffers, +.I null-padded character sequence +Character sequences can be contained in fixed-size buffers, which contain padding null bytes after the character sequence, to fill the rest of the buffer without affecting the character sequence; however, those padding null bytes are not part of the character sequence. -.\" ----- DESCRIPTION :: Terms (and abbreviations) :: measured character sequence +Don't confuse null-padded with null-terminated: +null-padded means 0 or more padding null bytes, +while null-terminated means exactly 1 terminating null character. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: known-length character sequence .TP -.IR "measured character sequence " ( ustr ) +.I known-length character sequence Character sequence delimited by its length. It may be a slice of a larger character sequence, or even of a string. @@ -116,10 +112,10 @@ is the number of non-null characters in a string or character sequence. It is the return value of .I strlen(str) and of -.IR "strnlen(ustr, sz)" . -.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size (sz) -------/ +.IR "strnlen(buf, size)" . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size ------------/ .TP -.IR "size " ( sz ) +.I size refers to the entire buffer where the string or character sequence is contained. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/ @@ -127,7 +123,7 @@ where the string or character sequence is contained. .I end is the name of a pointer to one past the last element of a buffer. It is equivalent to -.IR &str[sz] . +.IR &str[size] . It is used as a sentinel value, to be able to truncate strings or character sequences instead of overrunning the containing buffer. @@ -141,7 +137,7 @@ the writing starts at the first element pointed to by .TP .I catenate This term is used when -a function first finds the terminating null byte in +a function first finds the terminating null character in .IR dst , and then starts writing at that position. .\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ @@ -149,12 +145,12 @@ and then starts writing at that position. .I chain This term is used when it's the programmer who provides -a pointer to the terminating null byte in the string +a pointer to the terminating null character in the string .I dst (or one after the last character in a character sequence), and the function starts writing at that location. The function returns -a pointer to the new location of the terminating null byte +a pointer to the new location of the terminating null character (or one after the last character in a character sequence) after the call, so that the programmer can use it to chain such calls. @@ -166,11 +162,11 @@ However, newer functions that copy while allowing chaining cover both use cases with a single API. They are also algorithmically faster, since they don't need to search for -the terminating null byte of the existing string. +the terminating null character of the existing string. However, functions that catenate have a much simpler use, so if performance is not important, it can make sense to use them for improving readability. -.PP +.P The pointer returned by functions that allow chaining is a byproduct of the copy operation, so it has no performance costs. @@ -180,7 +176,7 @@ have names of the form .RB * stp *(), since it's common to name the pointer just .IR p . -.PP +.P Chain-copying functions that truncate should accept a pointer to the end of the destination buffer, and have names of the form @@ -191,14 +187,14 @@ This allows not having to recalculate the remaining size after each call. The first thing to note is that programmers should be careful with buffers, so they always have the correct size, and truncation is not necessary. -.PP +.P In most cases, truncation is not desired, and it is simpler to just do the copy. Simpler code is safer code. Programming against programming mistakes by adding more code just adds more points where mistakes can be made. -.PP +.P Nowadays, compilers can detect most programmer errors with features like compiler warnings, @@ -208,22 +204,25 @@ static analyzers, and .BR ftm (7)). Keeping the code simple helps these overflow-detection features be more precise. -.PP +.P When validating user input, +code should normally not truncate, +but instead fail and prevent the copy at all. +.P +In some cases, however, it makes sense to truncate. -Remember to check the return value of such function calls. -.PP +.P Functions that truncate: .IP \[bu] 3 -.BR stpecpy (3) -is the most efficient string copy function that performs truncation. -It only requires to check for truncation once after all chained calls. +.BR stpecpy () +.IP \[bu] +.BR strtcpy () .IP \[bu] .BR strlcpy (3bsd) and .BR strlcat (3bsd) -are similar, but less efficient when chained. +are similar, but have important performance problems; see BUGS. .IP \[bu] .BR stpncpy (3) and @@ -233,30 +232,29 @@ but rather null-padded character sequences. .\" ----- DESCRIPTION :: Null-padded character sequences --------------/ .SS Null-padded character sequences For historic reasons, -some standard APIs, +some standard APIs and file formats, such as -.BR utmpx (5), -use null-padded character sequences in fixed-width buffers. +.BR utmpx (5) +and +.BR tar (1), +use null-padded character sequences in fixed-size buffers. To interface with them, specialized functions need to be used. -.PP -To copy strings into them, use -.BR stpncpy (3). -.PP -To copy from an unterminated string within a fixed-width buffer into a string, -ignoring any trailing null bytes in the source fixed-width buffer, -you should use -.BR zustr2stp (3) +.P +To copy bytes from strings into these buffers, use +.BR strncpy (3) or -.BR strncat (3). -.PP -To copy from an unterminated string within a fixed-width buffer -into a character sequence, -ignoring any trailing null bytes in the source fixed-width buffer, -you should use -.BR zustr2ustp (3). -.\" ----- DESCRIPTION :: Measured character sequences -----------------/ -.SS Measured character sequences +.BR stpncpy (3). +.P +To read a null-padded character sequence, +use +.IR "strnlen(src,\ NITEMS(src))" , +and then you can treat it as a known-length character sequence; +or use +.BR strncat (3) +directly. +.\" ----- DESCRIPTION :: Known-length character sequences -----------------/ +.SS Known-length character sequences The simplest character sequence copying function is .BR mempcpy (3). It requires always knowing the length of your character sequences, @@ -266,39 +264,34 @@ since you always know the length of your character sequences, and can do the minimal copies and length measurements. .BR mempcpy (3) copies character sequences, -so you need to explicitly set the terminating null byte if you need a string. -.PP -However, -for keeping type safety, -it's good to add a wrapper that uses -.I char\~* -instead of -.IR void\~* : -.BR ustpcpy (3). -.PP +so you need to explicitly set the terminating null character +if you need a string. +.P In programs that make considerable use of strings or character sequences, and need the best performance, using overlapping character sequences can make a big difference. It allows holding subsequences of a larger character sequence, while not duplicating memory nor using time to do a copy. -.PP +.P However, this is delicate, since it requires using character sequences. C library APIs use strings, so programs that use character sequences will have to take care of differentiating strings from character sequences. -.PP -To copy a measured character sequence, use -.BR ustpcpy (3). -.PP -To copy a measured character sequence into a string, use -.BR ustr2stp (3). -.PP -Because these functions ask for the length, -and a string is by nature composed of a character sequence of the same length -plus a terminating null byte, -a string is also accepted as input. +.P +To copy a known-length character sequence, use +.BR mempcpy (3). +.P +To copy a known-length character sequence into a string, use +.IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" . +.P +A string is also accepted as input, +because +.BR mempcpy (3) +asks for the length, +and a string is composed of a character sequence of the same length +plus a terminating null character. .\" ----- DESCRIPTION :: String vs character sequence -----------------/ .SS String vs character sequence Some functions only operate on strings. @@ -319,12 +312,14 @@ List of functions: .BR strcpy (3), .BR strcat (3) .IP \[bu] -.BR stpecpy (3) +.BR stpecpy () +.IP \[bu] +.BR strtcpy () .IP \[bu] .BR strlcpy (3bsd), .BR strlcat (3bsd) .PD -.PP +.P Other functions require an input string, but create a character sequence as output. These functions have confusing names, @@ -336,7 +331,7 @@ List of functions: .IP \[bu] .BR strncpy (3) .PD -.PP +.P Other functions operate on an input character sequence, and create an output string. Functions that catenate @@ -347,29 +342,19 @@ holds a string before the call. has an even more misleading name than the functions above. List of functions: .IP \[bu] 3 -.PD 0 -.BR zustr2stp (3) -.IP \[bu] .BR strncat (3) -.IP \[bu] -.BR ustr2stp (3) -.PD -.PP +.P Other functions operate on an input character sequence to create an output character sequence. List of functions: .IP \[bu] 3 -.PD 0 -.BR ustpcpy (3) -.IP \[bu] -.BR zustr2stp (3) -.PD +.BR mempcpy (3) .\" ----- DESCRIPTION :: Functions :: ---------------------------------/ .SS Functions .\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ .TP .BR stpcpy (3) -This function copies the input string into a destination string. +Copy the input string into a destination string. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. .\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ @@ -377,16 +362,16 @@ It returns a pointer suitable for chaining. .BR strcpy (3) .TQ .BR strcat (3) -These functions copy and catenate the input string into a destination string. +Copy and catenate the input string into a destination string. The programmer is responsible for allocating a buffer large enough. The return value is useless. .IP .BR stpcpy (3) is a faster alternative to these functions. -.\" ----- DESCRIPTION :: Functions :: stpecpy(3) ----------------------/ +.\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/ .TP -.BR stpecpy (3) -This function copies the input string into a destination string. +.BR stpecpy () +Chain-copy the input string into a destination string. If the destination buffer, limited by a pointer to its end, isn't large enough to hold the copy, @@ -397,12 +382,24 @@ Truncation needs to be detected only once after the last chained call. .IP This function is not provided by any library; see EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strtcpy() -----------------------/ +.TP +.BR strtcpy () +Copy the input string into a destination string. +If the destination buffer isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +It returns the length of the string, +or \-1 if it truncated. +.IP +This function is not provided by any library; +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ .TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) -These functions copy and catenate the input string into a destination string. +Copy and catenate the input string into a destination string. If the destination buffer, limited by its size, isn't large enough to hold the copy, @@ -410,19 +407,23 @@ the resulting string is truncated (but it is guaranteed to be null-terminated). They return the length of the total string they tried to create. .IP -.BR stpecpy (3) -is a simpler alternative to these functions. +Check BUGS before using these functions. +.IP +.BR strtcpy () +and +.BR stpecpy () +are better alternatives to these functions. .\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ .TP .BR stpncpy (3) -This function copies the input string into -a destination null-padded character sequence in a fixed-width buffer. +Copy the input string into +a destination null-padded character sequence in a fixed-size buffer. If the destination buffer, limited by its size, isn't large enough to hold the copy, the resulting character sequence is truncated. Since it creates a character sequence, -it doesn't need to write a terminating null byte. +it doesn't need to write a terminating null character. It's impossible to distinguish truncation by the result of the call, from a character sequence that just fits the destination buffer; truncation should be detected by @@ -437,147 +438,105 @@ except for the useless return value. .IP .BR stpncpy (3) is a more useful alternative to this function. -.\" ----- DESCRIPTION :: Functions :: zustr2ustp(3) --------------------/ -.TP -.BR zustr2ustp (3) -This function copies the input character sequence, -contained in a null-padded fixed-width buffer, -into a destination character sequence. -The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.IP -A truncating version of this function doesn't exist, -since the size of the original character sequence is always known, -so it wouldn't be very useful. -.IP -This function is not provided by any library; -see EXAMPLES for a reference implementation. -.\" ----- DESCRIPTION :: Functions :: zustr2stp(3) --------------------/ +.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ .TP -.BR zustr2stp (3) -This function copies the input character sequence, -contained in a null-padded fixed-width buffer, +.BR strncat (3) +Catenate the input character sequence, +contained in a null-padded fixed-size buffer, into a destination string. The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. -.IP -A truncating version of this function doesn't exist, -since the size of the original character sequence is always known, -so it wouldn't be very useful. +The return value is useless. .IP -This function is not provided by any library; -see EXAMPLES for a reference implementation. -.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ -.TP -.BR strncat (3) Do not confuse this function with .BR strncpy (3); they are not related at all. .IP -This function catenates the input character sequence, -contained in a null-padded fixed-width buffer, -into a destination string. -The programmer is responsible for allocating a buffer large enough. -The return value is useless. -.IP -.BR zustr2stp (3) +.I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ NITEMS(src))),\ \[dq]\[dq]) is a faster alternative to this function. -.\" ----- DESCRIPTION :: Functions :: ustpcpy(3) ----------------------/ +.\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/ .TP -.BR ustpcpy (3) -This function copies the input character sequence, +.BR mempcpy (3) +Copy the input character sequence, limited by its length, into a destination character sequence. The programmer is responsible for allocating a buffer large enough. It returns a pointer suitable for chaining. -.\" ----- DESCRIPTION :: Functions :: ustr2stp(3) ---------------------/ -.TP -.BR ustr2stp (3) -This function copies the input character sequence, -limited by its length, -into a destination string. -The programmer is responsible for allocating a buffer large enough. -It returns a pointer suitable for chaining. .\" ----- RETURN VALUE :: ---------------------------------------------/ .SH RETURN VALUE -The following functions return -a pointer to the terminating null byte in the destination string. -.IP \[bu] 3 -.PD 0 +.TP .BR stpcpy (3) -.IP \[bu] -.BR ustr2stp (3) -.IP \[bu] -.BR zustr2stp (3) -.PD -.PP -The following function returns -a pointer to the terminating null byte in the destination string, -except when truncation occurs; -if truncation occurs, -it returns a pointer to the end of the destination buffer. -.IP \[bu] 3 -.BR stpecpy (3) -.PP -The following function returns -a pointer to one after the last character -in the destination character sequence; -if truncation occurs, -that pointer is equivalent to -a pointer to the end of the destination buffer. -.IP \[bu] 3 +A pointer to the terminating null character in the destination string. +.TP +.BR stpecpy () +A pointer to the terminating null character in the destination string, +on success. +On error, +NULL is returned, +and +.I errno +is set to indicate the error. +.TP +.BR mempcpy (3) +.TQ .BR stpncpy (3) -.PP -The following functions return -a pointer to one after the last character +A pointer to one after the last character in the destination character sequence. -.IP \[bu] 3 -.PD 0 -.BR zustr2ustp (3) -.IP \[bu] -.BR ustpcpy (3) -.PD -.PP -The following functions return -the length of the total string that they tried to create -(as if truncation didn't occur). -.IP \[bu] 3 -.BR strlcpy (3bsd), +.TP +.BR strtcpy () +The length of the string, +on success. +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.TP +.BR strlcpy (3bsd) +.TQ .BR strlcat (3bsd) -.PP -The following functions return the -.I dst -pointer, -which is useless. -.IP \[bu] 3 -.PD 0 -.BR strcpy (3), +The length of the total string that they tried to create +(as if truncation didn't occur). +.TP +.BR strcpy (3) +.TQ .BR strcat (3) -.IP \[bu] +.TQ .BR strncpy (3) -.IP \[bu] +.TQ .BR strncat (3) -.PD +The +.I dst +pointer, +which is useless. +.\" ----- ERRORS ------------------------------------------------------/ +.SH ERRORS +Most of these functions don't set +.IR errno . +.TP +.BR stpecpy () +.TQ +.BR strtcpy () +.RS +.TP +.B ENOBUFS +.I dsize +was +.BR 0 . +.TP +.B E2BIG +The string has been truncated. +.RE .\" ----- NOTES :: strscpy(9) -----------------------------------------/ .SH NOTES The Linux kernel has an internal function for copying strings, -which is similar to -.BR stpecpy (3), -except that it can't be chained: -.TP -.BR strscpy (9) -This function copies the input string into a destination string. -If the destination buffer, -limited by its size, -isn't large enough to hold the copy, -the resulting string is truncated -(but it is guaranteed to be null-terminated). -It returns the length of the destination string, or +.BR strscpy (9), +which is identical to +.BR strtcpy (), +except that it returns .B \-E2BIG -on truncation. -.IP -.BR stpecpy (3) -is a simpler and faster alternative to this function. +instead of \-1 +and it doesn't set +.IR errno . .\" ----- CAVEATS :: --------------------------------------------------/ .SH CAVEATS Don't mix chain calls to truncating and non-truncating functions. @@ -591,8 +550,28 @@ Calling a non-truncating function after a truncating one is necessarily wrong. .SH BUGS All catenation functions share the same performance problem: .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ -Shlemiel the painter +Shlemiel the painter .UE . +As a mitigation, +compilers are able to transform some calls to catenation functions +into normal copy functions, +since +.I strlen(dst) +is usually a byproduct of the previous copy. +.P +.BR strlcpy (3) +and +.BR strlcat (3) +need to read the entire +.I src +string, +even if the destination buffer is small. +This makes them vulnerable to Denial of Service (DoS) attacks +if an attacker can control the length of the +.I src +string. +And if not, +they're still unnecessarily slow. .\" ----- EXAMPLES :: -------------------------------------------------/ .SH EXAMPLES The following are examples of correct use of each of these functions. @@ -619,43 +598,43 @@ strcat(buf, "!"); len = strlen(buf); puts(buf); .EE -.\" ----- EXAMPLES :: stpecpy(3) --------------------------------------/ +.\" ----- EXAMPLES :: stpecpy() ---------------------------------------/ .TP -.BR stpecpy (3) +.BR stpecpy () .EX -end = buf + sizeof(buf); +end = buf + NITEMS(buf); p = buf; p = stpecpy(p, end, "Hello "); p = stpecpy(p, end, "world"); p = stpecpy(p, end, "!"); -if (p == end) { - p\-\-; +if (p == NULL) { + len = NITEMS(buf) \- 1; goto toolong; } len = p \- buf; puts(buf); .EE +.\" ----- EXAMPLES :: strtcpy() ---------------------------------------/ +.TP +.BR strtcpy () +.EX +len = strtcpy(buf, "Hello world!", NITEMS(buf)); +if (len == \-1) + goto toolong; +puts(buf); +.EE .\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ .TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) .EX -if (strlcpy(buf, "Hello ", sizeof(buf)) >= sizeof(buf)) +if (strlcpy(buf, "Hello ", NITEMS(buf)) >= NITEMS(buf)) goto toolong; -if (strlcat(buf, "world", sizeof(buf)) >= sizeof(buf)) +if (strlcat(buf, "world", NITEMS(buf)) >= NITEMS(buf)) goto toolong; -len = strlcat(buf, "!", sizeof(buf)); -if (len >= sizeof(buf)) - goto toolong; -puts(buf); -.EE -.\" ----- EXAMPLES :: strscpy(9) --------------------------------------/ -.TP -.BR strscpy (9) -.EX -len = strscpy(buf, "Hello world!", sizeof(buf)); -if (len == \-E2BIG) +len = strlcat(buf, "!", NITEMS(buf)); +if (len >= NITEMS(buf)) goto toolong; puts(buf); .EE @@ -663,43 +642,40 @@ puts(buf); .TP .BR stpncpy (3) .EX -p = stpncpy(buf, "Hello world!", sizeof(buf)); -if (sizeof(buf) < strlen("Hello world!")) +p = stpncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) goto toolong; -len = p \- buf; -for (size_t i = 0; i < sizeof(buf); i++) - putchar(buf[i]); +len = p \- u->ut_user; +fwrite(u->ut_user, 1, len, stdout); .EE .\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ .TP .BR strncpy (3) .EX -strncpy(buf, "Hello world!", sizeof(buf)); -if (sizeof(buf) < strlen("Hello world!")) +strncpy(u->ut_user, "alx", NITEMS(u->ut_user)); +if (NITEMS(u->ut_user) < strlen("alx")) goto toolong; -len = strnlen(buf, sizeof(buf)); -for (size_t i = 0; i < sizeof(buf); i++) - putchar(buf[i]); +len = strnlen(u->ut_user, NITEMS(u->ut_user)); +fwrite(u->ut_user, 1, len, stdout); .EE -.\" ----- EXAMPLES :: zustr2ustp(3) -----------------------------------/ +.\" ----- EXAMPLES :: mempcpy(dst, src, strnlen(src, NITEMS(src))) ----/ .TP -.BR zustr2ustp (3) +.I mempcpy(dst, src, strnlen(src, NITEMS(src))) .EX +char buf[NITEMS(u->ut_user)]; p = buf; -p = zustr2ustp(p, "Hello ", 6); -p = zustr2ustp(p, "world", 42); // Padding null bytes ignored. -p = zustr2ustp(p, "!", 1); +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); len = p \- buf; -printf("%.*s\en", (int) len, buf); +fwrite(buf, 1, len, stdout); .EE -.\" ----- EXAMPLES :: zustr2stp(3) ------------------------------------/ +.\" ----- EXAMPLES :: stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), "") .TP -.BR zustr2stp (3) +.I stpcpy(mempcpy(dst, src, strnlen(src, NITEMS(src))), \[dq]\[dq]) .EX +char buf[NITEMS(u->ut_user) + 1]; p = buf; -p = zustr2stp(p, "Hello ", 6); -p = zustr2stp(p, "world", 42); // Padding null bytes ignored. -p = zustr2stp(p, "!", 1); +p = mempcpy(p, u->ut_user, strnlen(u->ut_user, NITEMS(u->ut_user))); +p = stpcpy(p, ""); len = p \- buf; puts(buf); .EE @@ -707,102 +683,77 @@ puts(buf); .TP .BR strncat (3) .EX -buf[0] = \[aq]\e0\[aq]; // There's no 'cpy' function to this 'cat'. -strncat(buf, "Hello ", 6); -strncat(buf, "world", 42); // Padding null bytes ignored. -strncat(buf, "!", 1); +char buf[NITEMS(u->ut_user) + 1]; +strcpy(buf, ""); +strncat(buf, u->ut_user, NITEMS(u->ut_user)); len = strlen(buf); puts(buf); .EE -.\" ----- EXAMPLES :: ustpcpy(3) --------------------------------------/ +.\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/ .TP -.BR ustpcpy (3) +.BR mempcpy (3) .EX p = buf; -p = ustpcpy(p, "Hello ", 6); -p = ustpcpy(p, "world", 5); -p = ustpcpy(p, "!", 1); +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); len = p \- buf; -printf("%.*s\en", (int) len, buf); +fwrite(buf, 1, len, stdout); .EE -.\" ----- EXAMPLES :: ustr2stp(3) -------------------------------------/ +.\" ----- EXAMPLES :: stpcpy(mempcpy(), "") ---------------------------/ .TP -.BR ustr2stp (3) +.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]) .EX p = buf; -p = ustr2stp(p, "Hello ", 6); -p = ustr2stp(p, "world", 5); -p = ustr2stp(p, "!", 1); +p = mempcpy(p, "Hello ", 6); +p = mempcpy(p, "world", 5); +p = mempcpy(p, "!", 1); +p = stpcpy(p, ""); len = p \- buf; puts(buf); .EE .\" ----- EXAMPLES :: Implementations :: ------------------------------/ .SS Implementations Here are reference implementations for functions not provided by libc. -.PP +.P .in +4n .EX /* This code is in the public domain. */ \& -.\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ +.\" ----- EXAMPLES :: Implementations :: stpecpy() --------------------/ char * .IR stpecpy "(char *dst, char end[0], const char *restrict src)" { - char *p; + size_t dlen; \& if (dst == NULL) return NULL; - if (dst == end) - return end; -\& - p = memccpy(dst, src, \[aq]\e0\[aq], end \- dst); - if (p != NULL) - return p \- 1; \& - /* truncation detected */ - end[\-1] = \[aq]\e0\[aq]; - return end; + dlen = strtcpy(dst, src, end \- dst); + return (dlen == \-1) ? NULL : dst + dlen; } \& -.\" ----- EXAMPLES :: Implementations :: zustr2ustp(3) ----------------/ -char * -.IR zustr2ustp "(char *restrict dst, const char *restrict src, size_t sz)" +.\" ----- EXAMPLES :: Implementations :: strtcpy() --------------------/ +ssize_t +.IR strtcpy "(char *restrict dst, const char *restrict src, size_t dsize)" { - return ustpcpy(dst, src, strnlen(src, sz)); -} + bool trunc; + size_t dlen, slen; \& -.\" ----- EXAMPLES :: Implementations :: zustr2stp(3) -----------------/ -char * -.IR zustr2stp "(char *restrict dst, const char *restrict src, size_t sz)" -{ - char *p; + if (dsize == 0) { + errno = ENOBUFS; + return \-1; + } \& - p = zustr2ustp(dst, src, sz); - *p = \[aq]\e0\[aq]; + slen = strnlen(src, dsize); + trunc = (slen == dsize); + dlen = slen \- trunc; \& - return p; + stpcpy(mempcpy(dst, src, dlen), ""); + if (trunc) + errno = E2BIG; + return trunc ? \-1 : slen; } -\& -.\" ----- EXAMPLES :: Implementations :: ustpcpy(3) -------------------/ -char * -.IR ustpcpy "(char *restrict dst, const char *restrict src, size_t len)" -{ - return mempcpy(dst, src, len); -} -\& -.\" ----- EXAMPLES :: Implementations :: ustr2stp(3) ------------------/ -char * -.IR ustr2stp "(char *restrict dst, const char *restrict src, size_t len)" -{ - char *p; -\& - p = ustpcpy(dst, src, len); - *p = \[aq]\e0\[aq]; -\& - return p; -} -.EE -.in .\" ----- SEE ALSO :: -------------------------------------------------/ .SH SEE ALSO .BR bzero (3), diff --git a/man7/suffixes.7 b/man7/suffixes.7 index 5e970f4..3352a9c 100644 --- a/man7/suffixes.7 +++ b/man7/suffixes.7 @@ -14,7 +14,7 @@ .\" Modified Thu Nov 16 23:28:25 2000 by David A. Wheeler .\" .\" -.TH SUFFIXES 7 2023-03-17 "Linux man-pages 6.05.01" +.TH SUFFIXES 7 2023-10-31 "Linux man-pages 6.7" .SH NAME suffixes \- list of file suffixes .SH DESCRIPTION @@ -25,10 +25,10 @@ file they are dealing with. The .BR make (1) utility is driven by rules based on file suffix. -.PP +.P Following is a list of suffixes which are likely to be found on a Linux system. -.PP +.P .TS l | l _ | _ diff --git a/man7/symlink.7 b/man7/symlink.7 index 9c238b2..737bb1f 100644 --- a/man7/symlink.7 +++ b/man7/symlink.7 @@ -10,14 +10,14 @@ .\" 2008-06-11, mtk, Taken from FreeBSD 6.2 and heavily edited for .\" specific Linux details, improved readability, and man-pages style. .\" -.TH symlink 7 2023-04-03 "Linux man-pages 6.05.01" +.TH symlink 7 2023-10-31 "Linux man-pages 6.7" .SH NAME symlink \- symbolic link handling .SH DESCRIPTION Symbolic links are files that act as pointers to other files. To understand their behavior, you must first understand how hard links work. -.PP +.P A hard link to a file is indistinguishable from the original file because it is a reference to the object underlying the original filename. (To be precise: each of the hard links to a file is a reference to @@ -33,7 +33,7 @@ Hard links may not refer to directories which would confuse many programs) and may not refer to files on different filesystems (because inode numbers are not unique across filesystems). -.PP +.P A symbolic link is a special type of file whose contents are a string that is the pathname of another file, the file to which the link refers. (The contents of a symbolic link can be read using @@ -42,13 +42,13 @@ In other words, a symbolic link is a pointer to another name, and not to an underlying object. For this reason, symbolic links may refer to directories and may cross filesystem boundaries. -.PP +.P There is no requirement that the pathname referred to by a symbolic link should exist. A symbolic link that refers to a pathname that does not exist is said to be a .IR "dangling link" . -.PP +.P Because a symbolic link and its referenced object coexist in the filesystem name space, confusion can arise in distinguishing between the link itself and the referenced object. @@ -76,7 +76,7 @@ representation of a file handle. As such, these magic links allow users to access files which cannot be referenced with normal paths (such as unlinked files still referenced by a running program ). -.PP +.P Because they can bypass ordinary .BR mount_namespaces (7)-based restrictions, @@ -94,22 +94,22 @@ and when the .I fs.protected_symlinks sysctl is set (see .BR proc (5)). -.PP +.P The last access and last modification timestamps of a symbolic link can be changed using .BR utimensat (2) or .BR lutimes (3). -.PP +.P .\" Linux does not currently implement an lchmod(2). On Linux, the permissions of an ordinary symbolic link are not used in any operations; the permissions are always 0777 (read, write, and execute for all user categories), and can't be changed. -.PP +.P However, magic links do not follow this rule. They can have a non-0777 mode, though this mode is not currently used in any permission checks. -.\" .PP +.\" .P .\" The .\" 4.4BSD .\" system differs from historical @@ -140,7 +140,7 @@ and .BR readlinkat (2), in order to operate on the symbolic link itself (rather than the file to which it refers). -.PP +.P By default (i.e., if the .B AT_SYMLINK_FOLLOW @@ -171,7 +171,7 @@ or a loop is detected. (Loop detection is done by placing an upper limit on the number of links that may be followed, and an error results if this limit is exceeded.) -.PP +.P There are three separate areas that need to be discussed. They are as follows: .IP \[bu] 3 @@ -183,7 +183,7 @@ are not traversing a file tree. Symbolic links encountered by utilities that are traversing a file tree (either specified on the command line or encountered as part of the file hierarchy walk). -.PP +.P Before describing the treatment of symbolic links by system calls and commands, we require some terminology. Given a pathname of the form @@ -201,7 +201,7 @@ component. .SS Treatment of symbolic links in system calls The first area is symbolic links used as filename arguments for system calls. -.PP +.P The treatment of symbolic links within a pathname passed to a system call is as follows: .IP (1) 5 @@ -224,7 +224,7 @@ the system call .I "open(""slink"" ...\&)" would return a file descriptor referring to the file .IR afile . -.PP +.P Various system calls do not follow links in the basename component of a pathname, and operate on the symbolic link itself. @@ -240,7 +240,7 @@ They are: .BR rmdir (2), and .BR unlink (2). -.PP +.P Certain other system calls optionally follow symbolic links in the basename component of a pathname. They are: @@ -265,7 +265,7 @@ When .BR rmdir (2) is applied to a symbolic link, it fails with the error .BR ENOTDIR . -.PP +.P .BR link (2) warrants special discussion. POSIX.1-2001 specifies that @@ -282,7 +282,7 @@ either behavior in an implementation. .SS Commands not traversing a file tree The second area is symbolic links, specified as command-line filename arguments, to commands which are not traversing a file tree. -.PP +.P Except as noted below, commands follow symbolic links named as command-line arguments. For example, if there were a symbolic link @@ -293,7 +293,7 @@ the command .I "cat slink" would display the contents of the file .IR afile . -.PP +.P It is important to realize that this rule includes commands which may optionally traverse file trees; for example, the command .I "chown file" @@ -301,7 +301,7 @@ is included in this rule, while the command .IR "chown\ \-R file" , which performs a tree traversal, is not. (The latter is described in the third area, below.) -.PP +.P If it is explicitly intended that the command operate on the symbolic link instead of following the symbolic link\[em]for example, it is desired that .I "chown slink" @@ -319,7 +319,7 @@ while would change the ownership of .I slink itself. -.PP +.P There are some exceptions to this rule: .IP \[bu] 3 The @@ -392,16 +392,16 @@ The following commands either optionally or always traverse file trees: .BR rm (1), and .BR tar (1). -.PP +.P It is important to realize that the following rules apply equally to symbolic links encountered during the file tree traversal and symbolic links listed as command-line arguments. -.PP +.P The \fIfirst rule\fP applies to symbolic links that reference files other than directories. Operations that apply to symbolic links are performed on the links themselves, but otherwise the links are ignored. -.PP +.P The command .I "rm\ \-r slink directory" will remove @@ -413,12 +413,12 @@ In no case will .BR rm (1) affect the file referred to by .IR slink . -.PP +.P The \fIsecond rule\fP applies to symbolic links that refer to directories. Symbolic links that refer to directories are never followed by default. This is often referred to as a "physical" walk, as opposed to a "logical" walk (where symbolic links that refer to directories are followed). -.PP +.P Certain conventions are (should be) followed as consistently as possible by commands that perform file tree walks: .IP \[bu] 3 @@ -486,7 +486,7 @@ provide the default behavior by specifying the (for "physical") flag. This flag is intended to make the entire name space look like the physical name space. -.PP +.P For commands that do not by default do file tree traversals, the .IR \-H , .IR \-L , @@ -504,7 +504,7 @@ options more than once; the last one specified determines the command's behavior. This is intended to permit you to alias commands to behave one way or the other, and then override that behavior on the command line. -.PP +.P The .BR ls (1) and diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 index c4b3925..f79b65d 100644 --- a/man7/system_data_types.7 +++ b/man7/system_data_types.7 @@ -4,7 +4,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH system_data_types 7 2023-05-20 "Linux man-pages 6.05.01" +.TH system_data_types 7 2023-10-31 "Linux man-pages 6.7" .SH NAME system_data_types \- overview of system data types .SH DESCRIPTION @@ -62,53 +62,6 @@ system_data_types \- overview of system data types .\"------------------------------------- regmatch_t -------------------/ .\"------------------------------------- regoff_t ---------------------/ .\"------------------------------------- sigevent ---------------------/ -.TP -.I sigevent -.RS -.IR Include : -.IR . -Alternatively, -.IR , -.IR , -or -.IR . -.PP -.EX -struct sigevent { - int sigev_notify; /* Notification type */ - int sigev_signo; /* Signal number */ - union sigval sigev_value; /* Signal value */ - void (*sigev_notify_function)(union sigval); - /* Notification function */ - pthread_attr_t *sigev_notify_attributes; - /* Notification attributes */ -}; -.EE -.PP -For further details about this type, see -.BR sigevent (7). -.PP -.IR Versions : -.I -and -.I -define -.I sigevent -since POSIX.1-2008. -.PP -.IR "Conforming to" : -POSIX.1-2001 and later. -.PP -.IR "See also" : -.BR timer_create (2), -.BR getaddrinfo_a (3), -.BR lio_listio (3), -.BR mq_notify (3) -.PP -See also the -.I aiocb -structure in this page. -.RE .\"------------------------------------- siginfo_t --------------------/ .TP .I siginfo_t @@ -117,27 +70,27 @@ structure in this page. .IR . Alternatively, .IR . -.PP +.P .EX typedef struct { int si_signo; /* Signal number */ int si_code; /* Signal code */ pid_t si_pid; /* Sending process ID */ uid_t si_uid; /* Real user ID of sending process */ - void *si_addr; /* Address of faulting instruction */ + void *si_addr; /* Memory location which caused fault */ int si_status; /* Exit value or signal */ union sigval si_value; /* Signal value */ } siginfo_t; .EE -.PP +.P Information associated with a signal. For further details on this structure (including additional, Linux-specific fields), see .BR sigaction (2). -.PP +.P .IR "Conforming to" : POSIX.1-2001 and later. -.PP +.P .IR "See also" : .BR pidfd_send_signal (2), .BR rt_sigqueueinfo (2), @@ -155,13 +108,13 @@ Alternatively, .IR , or .IR . -.PP +.P This is a type that represents a set of signals. According to POSIX, this shall be an integer or structure type. -.PP +.P .IR "Conforming to" : POSIX.1-2001 and later. -.PP +.P .IR "See also" : .BR epoll_pwait (2), .BR ppoll (2), @@ -175,37 +128,6 @@ POSIX.1-2001 and later. .BR signal (7) .RE .\"------------------------------------- sigval -----------------------/ -.TP -.I sigval -.RS -.IR Include : -.IR . -.PP -.EX -union sigval { - int sival_int; /* Integer value */ - void *sival_ptr; /* Pointer value */ -}; -.EE -.PP -Data passed with a signal. -.PP -.IR "Conforming to" : -POSIX.1-2001 and later. -.PP -.IR "See also" : -.BR pthread_sigqueue (3), -.BR sigqueue (3), -.BR sigevent (7) -.PP -See also the -.I sigevent -structure -and the -.I siginfo_t -type -in this page. -.RE .\"------------------------------------- size_t -----------------------/ .\"------------------------------------- sockaddr ---------------------/ .\"------------------------------------- socklen_t --------------------/ @@ -227,7 +149,7 @@ in this page. .SH NOTES The structures described in this manual page shall contain, at least, the members shown in their definition, in no particular order. -.PP +.P Most of the integer types described in this page don't have a corresponding length modifier for the .BR printf (3) @@ -258,7 +180,7 @@ In "Conforming to" we only concern ourselves with C99 and later and POSIX.1-2001 and later. Some types may be specified in earlier versions of one of these standards, but in the interests of simplicity we omit details from earlier standards. -.PP +.P In "Include", we first note the "primary" header(s) that define the type according to either the C or POSIX.1 standards. Under "Alternatively", we note additional headers that @@ -270,7 +192,7 @@ The appropriate conversions from and to .IR intmax_t , and the appropriate range checks, are used as explained in the notes section above. -.PP +.P .EX #include #include diff --git a/man7/sysvipc.7 b/man7/sysvipc.7 index 307292c..11c08ab 100644 --- a/man7/sysvipc.7 +++ b/man7/sysvipc.7 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sysvipc 7 2022-10-30 "Linux man-pages 6.05.01" +.TH sysvipc 7 2023-10-31 "Linux man-pages 6.7" .SH NAME sysvipc \- System V interprocess communication mechanisms .SH DESCRIPTION @@ -16,7 +16,7 @@ Each message can have an associated priority. POSIX message queues provide an alternative API for achieving the same result; see .BR mq_overview (7). -.PP +.P The System V message queue API consists of the following system calls: .TP .BR msgget (2) @@ -39,7 +39,7 @@ each semaphore in a set is a counting semaphore. POSIX semaphores provide an alternative API for achieving the same result; see .BR sem_overview (7). -.PP +.P The System V semaphore API consists of the following system calls: .TP .BR semget (2) @@ -57,7 +57,7 @@ System V shared memory allows processes to share a region a memory (a "segment"). POSIX shared memory is an alternative API for achieving the same result; see .BR shm_overview (7). -.PP +.P The System V shared memory API consists of the following system calls: .TP .BR shmget (2) diff --git a/man7/tcp.7 b/man7/tcp.7 index aec6b78..2b1d333 100644 --- a/man7/tcp.7 +++ b/man7/tcp.7 @@ -88,7 +88,7 @@ .\" commit cd8ae85299d54155702a56811b2e035e63064d3d .\" Author: Eric Dumazet .\" -.TH tcp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH tcp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME tcp \- TCP protocol .SH SYNOPSIS @@ -96,7 +96,7 @@ tcp \- TCP protocol .B #include .B #include .B #include -.PP +.P .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);" .fi .SH DESCRIPTION @@ -112,7 +112,7 @@ retransmits lost packets. It generates and checks a per-packet checksum to catch transmission errors. TCP does not preserve record boundaries. -.PP +.P A newly created TCP socket has no remote or local address and is not fully specified. To create an outgoing TCP connection use @@ -131,7 +131,7 @@ or .BR connect (2) successfully called on it is fully specified and may transmit data. Data cannot be transmitted on listening or not yet connected sockets. -.PP +.P Linux supports RFC\ 1323 TCP high performance extensions. These include Protection Against Wrapped @@ -151,7 +151,7 @@ and socket options with the .BR setsockopt (2) call. -.PP +.P The maximum sizes for socket buffers declared via the .B SO_SNDBUF and @@ -182,7 +182,7 @@ calls in order to have it take effect. See .BR socket (7) for more information. -.PP +.P TCP supports urgent data. Urgent data is used to signal the receiver that some important message is part of the data @@ -214,7 +214,7 @@ flag is set for .BR recv (2) or .BR recvmsg (2). -.PP +.P When out-of-band data is present, .BR select (2) indicates the file descriptor as having an exceptional condition and @@ -222,7 +222,7 @@ indicates the file descriptor as having an exceptional condition and indicates a .B POLLPRI event. -.PP +.P Linux 2.4 introduced a number of changes for improved throughput and scaling, as well as enhanced functionality. Some of these features include support for zero-copy @@ -1068,7 +1068,7 @@ most socket options are valid on TCP sockets. For more information see .BR ip (7). -.PP +.P Following is a list of TCP-specific socket options. For details of some other socket options that are also applicable for TCP sockets, see @@ -1368,19 +1368,19 @@ the stream (even when .B SO_OOBINLINE is not set). This differs from BSD-based stacks. -.PP +.P Linux uses the BSD compatible interpretation of the urgent pointer field by default. This violates RFC\ 1122, but is required for interoperability with other stacks. It can be changed via .IR /proc/sys/net/ipv4/tcp_stdurg . -.PP +.P It is possible to peek at out-of-band data using the .BR recv (2) .B MSG_PEEK flag. -.PP +.P Since Linux 2.4, Linux supports the use of .B MSG_TRUNC in the @@ -1402,14 +1402,14 @@ The following calls return information in .IR value . The correct syntax is: -.PP +.P .RS .nf .BI int " value"; .IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");" .fi .RE -.PP +.P .I ioctl_type is one of the following: .TP @@ -1484,7 +1484,7 @@ When a network error occurs, TCP tries to resend the packet. If it doesn't succeed after some time, either .B ETIMEDOUT or the last received error on this connection is reported. -.PP +.P Some applications require a quicker error notification. This can be enabled with the .B IPPROTO_IP @@ -1509,7 +1509,7 @@ executed on a shut down socket. .TP .B ETIMEDOUT The other end didn't acknowledge retransmitted data after some time. -.PP +.P Any errors defined for .BR ip (7) or the generic socket layer may also be returned for TCP. @@ -1522,7 +1522,7 @@ Support for forward acknowledgement (FACK), TIME_WAIT recycling, and per-connection keepalive socket options were introduced in Linux 2.3. .SH BUGS Not all errors are documented. -.PP +.P IPv6 is not described. .\" Only a single Linux kernel version is described .\" Info for 2.2 was lost. Should be added again, @@ -1544,10 +1544,10 @@ IPv6 is not described. .BR socket (2), .BR ip (7), .BR socket (7) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 793 for the TCP specification. .br RFC\ 1122 for the TCP requirements and a description of the Nagle algorithm. diff --git a/man7/termio.7 b/man7/termio.7 index 08bba54..bff1d9f 100644 --- a/man7/termio.7 +++ b/man7/termio.7 @@ -4,7 +4,7 @@ .\" .\" 28 Dec 2006 - Initial Creation .\" -.TH termio 7 2022-10-30 "Linux man-pages 6.05.01" +.TH termio 7 2023-10-31 "Linux man-pages 6.7" .SH NAME termio \- System V terminal driver interface .SH DESCRIPTION @@ -15,7 +15,7 @@ This interface defined a structure used to store terminal settings, and a range of .BR ioctl (2) operations to get and set terminal attributes. -.PP +.P The .B termio interface is now obsolete: POSIX.1-1990 standardized a modified @@ -30,7 +30,7 @@ operations that existed in System V. .BR ioctl (2) was unstandardized, and its variadic third argument does not allow argument type checking.) -.PP +.P If you're looking for a page called "termio", then you can probably find most of the information that you seek in either .BR termios (3) diff --git a/man7/thread-keyring.7 b/man7/thread-keyring.7 index 524bf22..703f083 100644 --- a/man7/thread-keyring.7 +++ b/man7/thread-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH thread-keyring 7 2022-10-30 "Linux man-pages 6.05.01" +.TH thread-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME thread-keyring \- per-thread keyring .SH DESCRIPTION @@ -11,19 +11,19 @@ The thread keyring is a keyring used to anchor keys on behalf of a process. It is created only when a thread requests it. The thread keyring has the name (description) .IR _tid . -.PP +.P A special serial number value, .BR KEY_SPEC_THREAD_KEYRING , is defined that can be used in lieu of the actual serial number of the calling thread's thread keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@t\fP' can be used instead of a numeric key ID in much the same way, but as .BR keyctl (1) is a program run after forking, this is of no utility. -.PP +.P Thread keyrings are not inherited across .BR clone (2) and @@ -31,7 +31,7 @@ and and are cleared by .BR execve (2). A thread keyring is destroyed when the thread that refers to it terminates. -.PP +.P Initially, a thread does not have a thread keyring. If a thread doesn't have a thread keyring when it is accessed, then it will be created if it is to be modified; diff --git a/man7/time.7 b/man7/time.7 index ee0db5d..7259feb 100644 --- a/man7/time.7 +++ b/man7/time.7 @@ -5,7 +5,7 @@ .\" 2008-06-24, mtk: added some details about where jiffies come into .\" play; added section on high-resolution timers. .\" -.TH time 7 2023-01-22 "Linux man-pages 6.05.01" +.TH time 7 2023-10-31 "Linux man-pages 6.7" .SH NAME time \- overview of time and timers .SH DESCRIPTION @@ -16,7 +16,7 @@ either from a standard point in the past (see the description of the Epoch and calendar time below), or from some point (e.g., the start) in the life of a process .RI ( "elapsed time" ). -.PP +.P .I "Process time" is defined as the amount of CPU time used by a process. This is sometimes divided into @@ -58,7 +58,7 @@ a clock maintained by the kernel which measures time in .IR jiffies . The size of a jiffy is determined by the value of the kernel constant .IR HZ . -.PP +.P The value of .I HZ varies across kernel versions and hardware platforms. @@ -75,7 +75,7 @@ yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. Since Linux 2.6.20, a further frequency is available: 300, a number that divides evenly for the common video frame rates (PAL, 25 Hz; NTSC, 30 Hz). -.PP +.P The .BR times (2) system call is a special case. @@ -99,7 +99,7 @@ The values of certain clocks are virtualized by time namespaces; see .SS High-resolution timers Before Linux 2.6.21, the accuracy of timer and sleep system calls (see below) was also limited by the size of the jiffy. -.PP +.P Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), optionally configurable via .BR CONFIG_HIGH_RES_TIMERS . @@ -112,14 +112,14 @@ checking the resolution returned by a call to .BR clock_getres (2) or looking at the "resolution" entries in .IR /proc/timer_list . -.PP +.P HRTs are not supported on all hardware architectures. (Support is provided on x86, ARM, and PowerPC, among others.) .SS The Epoch UNIX systems represent time in seconds since the .IR Epoch , 1970-01-01 00:00:00 +0000 (UTC). -.PP +.P A program can determine the .I "calendar time" via the @@ -159,7 +159,7 @@ Various system calls and functions allow a program to sleep .BR clock_nanosleep (2), and .BR sleep (3). -.PP +.P Various system calls allow a process to set a timer that expires at some point in the future, and optionally at repeated intervals; see diff --git a/man7/time_namespaces.7 b/man7/time_namespaces.7 index 6e29996..4c85001 100644 --- a/man7/time_namespaces.7 +++ b/man7/time_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH time_namespaces 7 2023-03-12 "Linux man-pages 6.05.01" +.TH time_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME time_namespaces \- overview of Linux time namespaces .SH DESCRIPTION @@ -23,7 +23,7 @@ described by POSIX\[em]"some unspecified point in the past". a nonsettable clock that is identical to .BR CLOCK_MONOTONIC , except that it also includes any time that the system is suspended. -.PP +.P Thus, the processes in a time namespace share per-namespace values for these clocks. This affects various APIs that measure against these clocks, including: @@ -34,7 +34,7 @@ This affects various APIs that measure against these clocks, including: .BR timerfd_settime (2), and .IR /proc/uptime . -.PP +.P Currently, the only way to create a time namespace is by calling .BR unshare (2) with the @@ -66,13 +66,13 @@ These offsets are exposed via the file Within this file, the offsets are expressed as lines consisting of three space-delimited fields: -.PP +.P .in +4n .EX .EE .in -.PP +.P The .I clock-id is a string that identifies the clock whose offsets are being shown. @@ -93,11 +93,11 @@ The value can be negative, subject to restrictions noted below; .I offset-nanosecs is an unsigned value. -.PP +.P In the initial time namespace, the contents of the .I timens_offsets file are as follows: -.PP +.P .in +4n .EX $ \fBcat /proc/self/timens_offsets\fP @@ -105,7 +105,7 @@ monotonic 0 0 boottime 0 0 .EE .in -.PP +.P In a new time namespace that has had no member processes, the clock offsets can be modified by writing newline-terminated records of the same form to the @@ -121,7 +121,7 @@ In order to write to the file, a process must have the .B CAP_SYS_TIME capability in the user namespace that owns the time namespace. -.PP +.P Writes to the .I timens_offsets file can fail with the following errors: @@ -158,7 +158,7 @@ inside the namespace would exceed half of the value of the kernel constant .B KTIME_SEC_MAX (this limits the clock value to a maximum of approximately 146 years). .RE -.PP +.P In a new time namespace created by .BR unshare (2), the contents of the @@ -168,13 +168,13 @@ file are inherited from the time namespace of the creating process. Use of time namespaces requires a kernel that is configured with the .B CONFIG_TIME_NS option. -.PP +.P Note that time namespaces do not virtualize the .B CLOCK_REALTIME clock. Virtualization of this clock was avoided for reasons of complexity and overhead within the kernel. -.PP +.P For compatibility with the initial implementation, when writing a .I clock-id to the @@ -185,7 +185,7 @@ instead of the symbolic names show above; i.e., 1 instead of and 7 instead of .IR boottime . For readability, the use of the symbolic names over the numbers is preferred. -.PP +.P The motivation for adding time namespaces was to allow the monotonic and boot-time clocks to maintain consistent values during container migration and checkpoint/restore. @@ -193,14 +193,14 @@ during container migration and checkpoint/restore. The following shell session demonstrates the operation of time namespaces. We begin by displaying the inode number of the time namespace of a shell in the initial time namespace: -.PP +.P .in +4n .EX $ \fBreadlink /proc/$$/ns/time\fP time:[4026531834] .EE .in -.PP +.P Continuing in the initial time namespace, we display the system uptime using .BR uptime (1) and use the @@ -208,7 +208,7 @@ and use the example program shown in .BR clock_getres (2) to display the values of various clocks: -.PP +.P .in +4n .EX $ \fBuptime \-\-pretty\fP @@ -220,7 +220,7 @@ CLOCK_MONOTONIC: 56338.247 (15h 38m 58s) CLOCK_BOOTTIME : 76633.544 (21h 17m 13s) .EE .in -.PP +.P We then use .BR unshare (1) to create a time namespace and execute a @@ -236,7 +236,7 @@ clock forward 2 days and the offset for the .B CLOCK_BOOTTIME clock forward 7 days: -.PP +.P .in +4n .EX $ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP @@ -244,7 +244,7 @@ ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP .EE .in -.PP +.P Above, we started the .BR bash (1) shell with the @@ -254,7 +254,7 @@ This ensures that no child processes are created from the shell before we have a chance to update the .I timens_offsets file. -.PP +.P We then use .BR cat (1) to display the contents of the @@ -266,7 +266,7 @@ creates the first process in the new time namespace, after which further attempts to update the .I timens_offsets file produce an error. -.PP +.P .in +4n .EX ns2# \fBcat /proc/$$/timens_offsets\fP @@ -276,13 +276,13 @@ ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP bash: echo: write error: Permission denied .EE .in -.PP +.P Continuing in the new namespace, we execute .BR uptime (1) and the .I clock_times example program: -.PP +.P .in +4n .EX ns2# \fBuptime \-\-pretty\fP @@ -294,17 +294,17 @@ CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s) CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s) .EE .in -.PP +.P From the above output, we can see that the monotonic and boot-time clocks have different values in the new time namespace. -.PP +.P Examining the .IR /proc/ pid /ns/time and .IR /proc/ pid /ns/time_for_children symbolic links, we see that the shell is a member of the initial time namespace, but its children are created in the new namespace. -.PP +.P .in +4n .EX ns2# \fBreadlink /proc/$$/ns/time\fP @@ -315,13 +315,13 @@ ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process time:[4026532900] .EE .in -.PP +.P Returning to the shell in the initial time namespace, we see that the monotonic and boot-time clocks are unaffected by the .I timens_offsets changes that were made in the other time namespace: -.PP +.P .in +4n .EX $ \fBuptime \-\-pretty\fP diff --git a/man7/udp.7 b/man7/udp.7 index 45c5cad..6b643a2 100644 --- a/man7/udp.7 +++ b/man7/udp.7 @@ -4,7 +4,7 @@ .\" .\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ .\" -.TH udp 7 2023-07-15 "Linux man-pages 6.05.01" +.TH udp 7 2023-10-31 "Linux man-pages 6.7" .SH NAME udp \- User Datagram Protocol for IPv4 .SH SYNOPSIS @@ -12,7 +12,7 @@ udp \- User Datagram Protocol for IPv4 .B #include .B #include .B #include -.PP +.P .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" .fi .SH DESCRIPTION @@ -21,7 +21,7 @@ described in RFC\ 768. It implements a connectionless, unreliable datagram packet service. Packets may be reordered or duplicated before they arrive. UDP generates and checks checksums to catch transmission errors. -.PP +.P When a UDP socket is created, its local and remote addresses are unspecified. Datagrams can be sent immediately using @@ -50,7 +50,7 @@ a free local port out of the range defined by .I /proc/sys/net/ipv4/ip_local_port_range and bind the socket to .BR INADDR_ANY . -.PP +.P All receive operations return only one packet. When the packet is smaller than the passed buffer, only that much data is returned; when it is bigger, the packet is truncated and the @@ -58,7 +58,7 @@ data is returned; when it is bigger, the packet is truncated and the flag is set. .B MSG_WAITALL is not supported. -.PP +.P IP options may be sent or received using the socket options described in .BR ip (7). They are processed by the kernel only when the appropriate @@ -67,12 +67,12 @@ parameter is enabled (but still passed to the user even when it is turned off). See .BR ip (7). -.PP +.P When the .B MSG_DONTROUTE flag is set on sending, the destination address must refer to a local interface address and the packet is sent only to that interface. -.PP +.P By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return @@ -106,7 +106,7 @@ This behavior differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. Linux's behavior is mandated by .BR RFC\ 1122 . -.PP +.P For compatibility with legacy code, in Linux 2.0 and 2.2 it was possible to set the .B SO_BSDCOMPAT @@ -120,7 +120,7 @@ Locally generated errors are always passed. Support for this socket option was removed in later kernels; see .BR socket (7) for further information. -.PP +.P When the .B IP_RECVERR option is enabled, all errors are stored in the socket error queue, @@ -181,7 +181,7 @@ Unless otherwise noted, .I optval is a pointer to an .IR int . -.PP +.P Following is a list of UDP-specific socket options. For details of some other socket options that are also applicable for UDP sockets, see @@ -246,7 +246,7 @@ This option should not be used in code intended to be portable. These ioctls can be accessed using .BR ioctl (2). The correct syntax is: -.PP +.P .RS .nf .BI int " value"; @@ -275,7 +275,7 @@ to distinguish these cases. .BR TIOCOUTQ " (" SIOCOUTQ ) Returns the number of data bytes in the local send queue. Supported only with Linux 2.4 and above. -.PP +.P In addition, all ioctls documented in .BR ip (7) and @@ -301,10 +301,10 @@ is a new feature in Linux 2.2. .BR raw (7), .BR socket (7), .BR udplite (7) -.PP +.P The kernel source file .IR Documentation/networking/ip\-sysctl.txt . -.PP +.P RFC\ 768 for the User Datagram Protocol. .br RFC\ 1122 for the host requirements. diff --git a/man7/udplite.7 b/man7/udplite.7 index 36a2db8..4ba4266 100644 --- a/man7/udplite.7 +++ b/man7/udplite.7 @@ -4,7 +4,7 @@ .\" .\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $ .\" -.TH udplite 7 2023-02-10 "Linux man-pages 6.05.01" +.TH udplite 7 2023-10-31 "Linux man-pages 6.7" .SH NAME udplite \- Lightweight User Datagram Protocol .SH SYNOPSIS @@ -13,25 +13,25 @@ udplite \- Lightweight User Datagram Protocol .\" FIXME . see #defines under `BUGS', .\" when glibc supports this, add .\" #include -.PP +.P .B sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE); .fi .SH DESCRIPTION This is an implementation of the Lightweight User Datagram Protocol (UDP-Lite), as described in RFC\ 3828. -.PP +.P UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length checksums. This has advantages for some types of multimedia transport that may be able to make use of slightly damaged datagrams, rather than having them discarded by lower-layer protocols. -.PP +.P The variable-length checksum coverage is set via a .BR setsockopt (2) option. If this option is not set, the only difference from UDP is in using a different IP protocol identifier (IANA number 136). -.PP +.P The UDP-Lite implementation is a full extension of .BR udp (7)\[em]that is, it shares the same API and API behavior, and in addition @@ -58,7 +58,7 @@ socket options are valid on a UDP-Lite socket. See .BR udp (7) for more information. -.PP +.P The following two options are specific to UDP-Lite. .TP .B UDPLITE_SEND_CSCOV @@ -93,7 +93,7 @@ exceeds the actual packet coverage, incoming packets are silently dropped, but may generate a warning message in the system log. .\" SO_NO_CHECK exists and is supported by UDPv4, but is .\" commented out in socket(7), hence also commented out here -.\".PP +.\".P .\"Since UDP-Lite mandates checksums, checksumming can not be disabled .\"via the .\".B SO_NO_CHECK @@ -116,7 +116,7 @@ UDP-Litev4/v6 first appeared in Linux 2.6.20. .SH BUGS .\" FIXME . remove this section once glibc supports UDP-Lite Where glibc support is missing, the following definitions are needed: -.PP +.P .in +4n .EX #define IPPROTO_UDPLITE 136 @@ -130,8 +130,8 @@ Where glibc support is missing, the following definitions are needed: .BR ipv6 (7), .BR socket (7), .BR udp (7) -.PP +.P RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite). -.PP +.P .I Documentation/networking/udplite.txt in the Linux kernel source tree diff --git a/man7/unicode.7 b/man7/unicode.7 index f65a9b2..fe38909 100644 --- a/man7/unicode.7 +++ b/man7/unicode.7 @@ -7,7 +7,7 @@ .\" 2001-05-11 Markus Kuhn .\" Update .\" -.TH unicode 7 2023-03-12 "Linux man-pages 6.05.01" +.TH unicode 7 2024-01-28 "Linux man-pages 6.7" .SH NAME unicode \- universal character set .SH DESCRIPTION @@ -18,7 +18,7 @@ It also guarantees "round-trip compatibility"; in other words, conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back. -.PP +.P UCS contains the characters required to represent practically all known languages. This includes not only the Latin, Greek, Cyrillic, @@ -40,7 +40,7 @@ graphical, typographical, mathematical, and scientific symbols, including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR fonts, as well as many word processing and publishing systems, and more are being added. -.PP +.P The UCS standard (ISO/IEC 10646) describes a 31-bit character set architecture consisting of 128 24-bit @@ -71,7 +71,7 @@ The supplemental planes added by ISO/IEC 10646-2 cover only more exotic characters for special scientific, dictionary printing, publishing industry, higher-level protocol and enthusiast needs. -.PP +.P The representation of each UCS character as a 2-byte word is referred to as the UCS-2 form (only for BMP characters), whereas UCS-4 is the representation of each character by a 4-byte word. @@ -79,12 +79,12 @@ In addition, there exist two encoding forms UTF-8 for backward compatibility with ASCII processing software and UTF-16 for the backward-compatible handling of non-BMP characters up to 0x10ffff by UCS-2 software. -.PP +.P The UCS characters 0x0000 to 0x007f are identical to those of the classic US-ASCII character set and the characters in the range 0x0000 to 0x00ff are identical to those in -ISO 8859-1 (Latin-1). +ISO/IEC\~8859-1 (Latin-1). .SS Combining characters Some code points in UCS have been assigned to @@ -101,7 +101,7 @@ character Umlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed UCS code 0x00c4, or alternatively as the combination of a normal "Latin capital letter A" followed by a "combining diaeresis": 0x0041 0x0308. -.PP +.P Combining characters are essential for instance for encoding the Thai script or for mathematical typesetting and users of the International Phonetic Alphabet. @@ -124,7 +124,7 @@ Arabic, Devanagari, Malayalam). .TP Level 3 All UCS characters are supported. -.PP +.P The Unicode 3.0 Standard published by the Unicode Consortium contains exactly the UCS Basic Multilingual Plane @@ -147,7 +147,7 @@ code values (in all locales), a convention that is signaled by the GNU C library to applications by defining the constant .B __STDC_ISO_10646__ as specified in the ISO C99 standard. -.PP +.P UCS/Unicode can be used just like ASCII in input/output streams, terminal communication, plaintext files, filenames, and environment variables in the ASCII compatible UTF-8 multibyte encoding. @@ -156,7 +156,7 @@ encoding to all applications, a suitable .I locale has to be selected via environment variables (e.g., "LANG=en_GB.UTF-8"). -.PP +.P The .B nl_langinfo(CODESET) function returns the name of the selected encoding. @@ -189,7 +189,7 @@ in the Linux kernel sources (or .I Documentation/unicode.txt before Linux 4.10). -.PP +.P Two other planes are reserved for private usage, plane 15 (Supplementary Private Use Area-A, range 0xf0000 to 0xffffd) and plane 16 (Supplementary Private Use Area-B, range diff --git a/man7/units.7 b/man7/units.7 index ca2bd2d..da0492f 100644 --- a/man7/units.7 +++ b/man7/units.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH units 7 2023-02-10 "Linux man-pages 6.05.01" +.TH units 7 2023-10-31 "Linux man-pages 6.7" .SH NAME units \- decimal and binary prefixes .SH DESCRIPTION @@ -41,7 +41,7 @@ R ronna 10\[ha]27 = 1000000000000000000000000000 Q quetta 10\[ha]30 = 1000000000000000000000000000000 .TE .RE -.PP +.P The symbol for micro is the Greek letter mu, often written u in an ASCII context where this Greek letter is not available. .SS Binary prefixes @@ -70,7 +70,7 @@ Before these binary prefixes were introduced, it was fairly common to use k=1000 and K=1024, just like b=bit, B=byte. Unfortunately, the M is capital already, and cannot be capitalized to indicate binary-ness. -.PP +.P At first that didn't matter too much, since memory modules and disks came in sizes that were powers of two, so everyone knew that in such contexts "kilobyte" and "megabyte" meant @@ -81,26 +81,26 @@ regarded as the "real true meaning" when computers were involved. But then disk technology changed, and disk sizes became arbitrary numbers. After a period of uncertainty all disk manufacturers settled on the standard, namely k=1000, M=1000\ k, G=1000\ M. -.PP +.P The situation was messy: in the 14k4 modems, k=1000; in the 1.44\ MB .\" also common: 14.4k modem diskettes, M=1024000; and so on. In 1998 the IEC approved the standard that defines the binary prefixes given above, enabling people to be precise and unambiguous. -.PP +.P Thus, today, MB = 1000000\ B and MiB = 1048576\ B. -.PP +.P In the free software world programs are slowly being changed to conform. When the Linux kernel boots and says -.PP +.P .in +4n .EX hda: 120064896 sectors (61473 MB) w/2048KiB Cache .EE .in -.PP +.P the MB are megabytes and the KiB are kibibytes. .SH SEE ALSO .UR https://www.bipm.org/\:documents/\:20126/\:41483022/\:SI\-Brochure\-9.pdf diff --git a/man7/unix.7 b/man7/unix.7 index cfa4188..426a430 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -12,14 +12,14 @@ .\" address that can appear in the sockaddr_un structure: pathname, .\" unnamed, and abstract. .\" -.TH UNIX 7 2023-07-15 "Linux man-pages 6.05.01" +.TH UNIX 7 2024-03-16 "Linux man-pages 6.7" .SH NAME unix \- sockets for local interprocess communication .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .IB unix_socket " = socket(AF_UNIX, type, 0);" .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" .fi @@ -34,7 +34,7 @@ Traditionally, UNIX domain sockets can be either unnamed, or bound to a filesystem pathname (marked as being of type socket). Linux also supports an abstract namespace which is independent of the filesystem. -.PP +.P Valid socket types in the UNIX domain are: .BR SOCK_STREAM , for a stream-oriented socket; @@ -47,12 +47,12 @@ and (since Linux 2.6.4) for a sequenced-packet socket that is connection-oriented, preserves message boundaries, and delivers messages in the order that they were sent. -.PP +.P UNIX domain sockets support passing file descriptors or process credentials to other processes using ancillary data. .SS Address format A UNIX domain socket address is represented in the following structure: -.PP +.P .in +4n .EX .\" #define UNIX_PATH_MAX 108 @@ -63,7 +63,7 @@ struct sockaddr_un { }; .EE .in -.PP +.P The .I sun_family field always contains @@ -71,8 +71,8 @@ field always contains On Linux, .I sun_path is 108 bytes in size; see also BUGS, below. -.PP -Various systems calls (for example, +.P +Various system calls (for example, .BR bind (2), .BR connect (2), and @@ -87,7 +87,7 @@ Some other system calls (for example, and .BR accept (2)) return an argument of this type. -.PP +.P Three types of address are distinguished in the .I sockaddr_un structure: @@ -186,7 +186,7 @@ or, more simply, .I addrlen can be specified as .IR "sizeof(struct sockaddr_un)" . -.PP +.P There is some variation in how implementations handle UNIX domain socket addresses that do not follow the above rules. For example, some (but not all) implementations @@ -194,7 +194,7 @@ For example, some (but not all) implementations .\" is 108 bytes append a null terminator if none is present in the supplied .IR sun_path . -.PP +.P When coding portable applications, keep in mind that some implementations .\" HP-UX @@ -203,7 +203,7 @@ have as short as 92 bytes. .\" Modern BSDs generally have 104, Tru64 and AIX have 104, .\" Solaris and Irix have 108 -.PP +.P Various system calls .RB ( accept (2), .BR recvfrom (2), @@ -227,7 +227,7 @@ In the Linux implementation, pathname sockets honor the permissions of the directory they are in. Creation of a new socket fails if the process does not have write and search (execute) permission on the directory in which the socket is created. -.PP +.P On Linux, connecting to a stream socket object requires write permission on that socket; sending a datagram to a datagram socket likewise @@ -237,13 +237,13 @@ on a socket file, and on some systems (e.g., older BSDs), the socket permissions are ignored. Portable programs should not rely on this feature for security. -.PP +.P When creating a new socket, the owner and group of the socket file are set according to the usual rules. The socket file has all permissions enabled, other than those that are turned off by the process .BR umask (2). -.PP +.P The owner, group, and permissions of a pathname socket can be changed (using .BR chown (2) and @@ -260,10 +260,10 @@ and changing the ownership and permissions of the object (via and .BR fchmod (2)) has no effect on the accessibility of the socket. -.PP +.P Abstract sockets automatically disappear when all open references to the socket are closed. -.PP +.P The abstract socket namespace is a nonportable Linux extension. .\" .SS Socket options @@ -331,7 +331,8 @@ This read-only socket option returns the credentials of the peer process connected to this socket. The returned credentials are those that were in effect at the time of the call to -.BR connect (2) +.BR connect (2), +.BR listen (2), or .BR socketpair (2). .IP @@ -418,7 +419,7 @@ The change to 5 bytes came in Linux 2.3.15.) .SS Sockets API The following paragraphs describe domain-specific details and unsupported features of the sockets API for UNIX domain sockets on Linux. -.PP +.P UNIX domain sockets do not support the transmission of out-of-band data (the .B MSG_OOB @@ -426,12 +427,12 @@ flag for .BR send (2) and .BR recv (2)). -.PP +.P The .BR send (2) .B MSG_MORE flag is not supported by UNIX domain sockets. -.PP +.P Before Linux 3.4, .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f the use of @@ -441,7 +442,7 @@ in the argument of .BR recv (2) was not supported by UNIX domain sockets. -.PP +.P The .B SO_SNDBUF socket option does have an effect for UNIX domain sockets, but the @@ -573,11 +574,11 @@ bytes in the data portion of the ancillary message for this data. To receive the security context, the .B SO_PASSSEC option must be enabled on the socket (see above). -.PP +.P When sending ancillary data with .BR sendmsg (2), only one item of each of the above types may be included in the sent message. -.PP +.P At least one byte of real data should be sent when sending ancillary data. On Linux, this is required to successfully send ancillary data over a UNIX domain stream socket. @@ -585,11 +586,11 @@ When sending ancillary data over a UNIX domain datagram socket, it is not necessary on Linux to send any accompanying real data. However, portable applications should also include at least one byte of real data when sending ancillary data over a datagram socket. -.PP +.P When receiving from a stream socket, ancillary data forms a kind of barrier for the received data. For example, suppose that the sender transmits as follows: -.PP +.P .RS .PD 0 .IP (1) 5 @@ -603,7 +604,7 @@ of one byte, with ancillary data. of four bytes, with no ancillary data. .PD .RE -.PP +.P Suppose that the receiver now performs .BR recvmsg (2) calls each with a buffer size of 20 bytes. @@ -612,7 +613,7 @@ along with the ancillary data sent by the second .BR sendmsg (2) call. The next call will receive the remaining four bytes of data. -.PP +.P If the space allocated for receiving incoming ancillary data is too small then the ancillary data is truncated to the number of headers that will fit in the supplied buffer (or, in the case of an @@ -639,14 +640,14 @@ The following calls return information in .IR value . The correct syntax is: -.PP +.P .RS .nf .BI int " value"; .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" .fi .RE -.PP +.P .I ioctl_type can be: .TP @@ -800,7 +801,7 @@ by sending each file descriptor with and then closing the file descriptor so that it was not accounted against the .B RLIMIT_NOFILE resource limit. -.PP +.P Other errors can be generated by the generic socket layer or by the filesystem while generating a filesystem socket object. See the appropriate manual pages for more information. @@ -818,7 +819,7 @@ longer needed (using The usual UNIX close-behind semantics apply; the socket can be unlinked at any time and will be finally removed from the filesystem when the last reference to it is closed. -.PP +.P To pass file descriptors or credentials over a .B SOCK_STREAM socket, you must @@ -827,12 +828,12 @@ send or receive at least one byte of nonancillary data in the same or .BR recvmsg (2) call. -.PP +.P UNIX domain stream sockets do not support the notion of out-of-band data. .\" .SH BUGS When binding a socket to an address, -Linux is one of the implementations that appends a null terminator +Linux is one of the implementations that append a null terminator if none is supplied in .IR sun_path . In most cases this is unproblematic: @@ -855,7 +856,7 @@ then the returned address structure .I won't have a null terminator in .IR sun_path . -.PP +.P In addition, some implementations .\" i.e., traditional BSD don't require a null terminator when binding a socket (the @@ -865,12 +866,12 @@ argument is used to determine the length of and when the socket address is retrieved on these implementations, there is no null terminator in .IR sun_path . -.PP +.P Applications that retrieve socket addresses can (portably) code to handle the possibility that there is no null terminator in .I sun_path by respecting the fact that the number of valid bytes in the pathname is: -.PP +.P .in +4n .EX strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) @@ -886,7 +887,7 @@ strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) .\" 2012-04-18 .\" .\" FIXME . Track http://austingroupbugs.net/view.php?id=561 -.PP +.P Alternatively, an application can retrieve the socket address by allocating a buffer of size .I "sizeof(struct sockaddr_un)+1" @@ -898,7 +899,7 @@ as and the extra zero byte ensures that there will be a null terminator for the string returned in .IR sun_path : -.PP +.P .in +4n .EX void *addrp; @@ -915,7 +916,7 @@ if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); .EE .in -.PP +.P This sort of messiness can be avoided if it is guaranteed that the applications that .I create @@ -933,7 +934,7 @@ The server sends back a message containing the sum of the client's integers. The client prints the sum and exits. The server waits for the next client to connect. To stop the server, the client is called with the command-line argument "DOWN". -.PP +.P The following output was recorded while running the server in the background and repeatedly executing the client. Execution of the server program ends when it receives the "DOWN" command. @@ -954,6 +955,7 @@ $ .in .SS Program source \& +.\" SRC BEGIN (connection.h) .EX /* * File connection.h @@ -961,7 +963,11 @@ $ \& #define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" #define BUFFER_SIZE 12 -\& +.EE +.\" SRC END +.P +.\" SRC BEGIN (server.c) +.EX /* * File server.c */ @@ -972,18 +978,20 @@ $ #include #include #include +\& #include "connection.h" \& int -main(int argc, char *argv[]) +main(void) { - struct sockaddr_un name; - int down_flag = 0; - int ret; - int connection_socket; - int data_socket; - int result; - char buffer[BUFFER_SIZE]; + int down_flag = 0; + int ret; + int connection_socket; + int data_socket; + int result; + ssize_t r, w; + struct sockaddr_un name; + char buffer[BUFFER_SIZE]; \& /* Create local socket. */ \& @@ -1042,8 +1050,8 @@ main(int argc, char *argv[]) \& /* Wait for next data packet. */ \& - ret = read(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { perror("read"); exit(EXIT_FAILURE); } @@ -1056,12 +1064,16 @@ main(int argc, char *argv[]) \& if (!strncmp(buffer, "DOWN", sizeof(buffer))) { down_flag = 1; - break; + continue; } \& if (!strncmp(buffer, "END", sizeof(buffer))) { break; } +\& + if (down_flag) { + continue; + } \& /* Add received summand. */ \& @@ -1071,8 +1083,8 @@ main(int argc, char *argv[]) /* Send result. */ \& sprintf(buffer, "%d", result); - ret = write(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + w = write(data_socket, buffer, sizeof(buffer)); + if (w == \-1) { perror("write"); exit(EXIT_FAILURE); } @@ -1096,27 +1108,32 @@ main(int argc, char *argv[]) \& exit(EXIT_SUCCESS); } -\& +.EE +.\" SRC END +.P +.\" SRC BEGIN (client.c) +.EX /* * File client.c */ \& -#include #include #include #include #include #include #include +\& #include "connection.h" \& int main(int argc, char *argv[]) { - struct sockaddr_un addr; - int ret; - int data_socket; - char buffer[BUFFER_SIZE]; + int ret; + int data_socket; + ssize_t r, w; + struct sockaddr_un addr; + char buffer[BUFFER_SIZE]; \& /* Create local socket. */ \& @@ -1148,9 +1165,9 @@ main(int argc, char *argv[]) \& /* Send arguments. */ \& - for (size_t i = 1; i < argc; ++i) { - ret = write(data_socket, argv[i], strlen(argv[i]) + 1); - if (ret == \-1) { + for (int i = 1; i < argc; ++i) { + w = write(data_socket, argv[i], strlen(argv[i]) + 1); + if (w == \-1) { perror("write"); break; } @@ -1159,16 +1176,16 @@ main(int argc, char *argv[]) /* Request result. */ \& strcpy(buffer, "END"); - ret = write(data_socket, buffer, strlen(buffer) + 1); - if (ret == \-1) { + w = write(data_socket, buffer, strlen(buffer) + 1); + if (w == \-1) { perror("write"); exit(EXIT_FAILURE); } \& /* Receive result. */ \& - ret = read(data_socket, buffer, sizeof(buffer)); - if (ret == \-1) { + r = read(data_socket, buffer, sizeof(buffer)); + if (r == \-1) { perror("read"); exit(EXIT_FAILURE); } @@ -1186,7 +1203,8 @@ main(int argc, char *argv[]) exit(EXIT_SUCCESS); } .EE -.PP +.\" SRC END +.P For examples of the use of .BR SCM_RIGHTS , see diff --git a/man7/uri.7 b/man7/uri.7 index a571aec..6823b45 100644 --- a/man7/uri.7 +++ b/man7/uri.7 @@ -25,7 +25,7 @@ .\" Modified Fri Aug 21 23:00:00 1999 by David A. Wheeler (dwheeler@dwheeler.com) .\" Modified Tue Mar 14 2000 by David A. Wheeler (dwheeler@dwheeler.com) .\" -.TH uri 7 2023-04-30 "Linux man-pages 6.05.01" +.TH uri 7 2023-10-31 "Linux man-pages 6.7" .SH NAME uri, url, urn \- uniform resource identifier (URI), including a URL or URN .SH SYNOPSIS @@ -36,7 +36,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] # \[dq]\~\c .IR fragment \~] .YS -.PP +.P .SY "\fIabsoluteURI\fP \fR=\fP" .I scheme\~\c .RB \[dq] : \[dq] @@ -44,7 +44,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN | .IR opaque_part \~) .YS -.PP +.P .SY "\fIrelativeURI\fP \fR=\fP" .RI (\~ net_path | @@ -54,7 +54,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fIscheme\fP \fR=\fP" .RB \[dq] http \[dq] | @@ -83,7 +83,7 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB \[dq] wais \[dq] | \&... .YS -.PP +.P .SY "\fIhierarchical_part\fP \fR=\fP" .RI (\~ net_path | @@ -91,18 +91,18 @@ uri, url, urn \- uniform resource identifier (URI), including a URL or URN .RB [\~\[dq] ? \[dq]\~\c .IR query \~] .YS -.PP +.P .SY "\fInet_path\fP \fR=\fP" .RB \[dq] // \[dq]\~\c .I authority .RI [\~ absolute_path \~] .YS -.PP +.P .SY "\fIabsolute_path\fP \fR=\fP" .RB \[dq] / \[dq]\~\c .I path_segments .YS -.PP +.P .SY "\fIrelative_path\fP \fR=\fP" .I relative_segment .RI [\~ absolute_path \~] @@ -117,14 +117,14 @@ by name or some other attribute of that resource. A Uniform Resource Name (URN) is a URI that must remain globally unique and persistent even when the resource ceases to exist or becomes unavailable. -.PP +.P URIs are the standard way to name hypertext link destinations for tools such as web browsers. The string "http://www.kernel.org" is a URL (and thus it is also a URI). Many people use the term URL loosely as a synonym for URI (though technically URLs are a subset of URIs). -.PP +.P URIs can be absolute or relative. An absolute identifier refers to a resource independent of context, while a relative @@ -140,7 +140,7 @@ character can't be used as the first segment of a relative URI path precede such segments with ./ (e.g., "./this:that"). Note that descendants of MS-DOS (e.g., Microsoft Windows) replace devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|". -.PP +.P A fragment identifier, if included, refers to a particular named portion (fragment) of a resource; @@ -155,9 +155,9 @@ For example, many URL schemes permit the authority to be the following format, called here an .I ip_server (square brackets show what's optional): -.PP +.P .IR "ip_server = " [ user " [ : " password " ] @ ] " host " [ : " port ] -.PP +.P This format allows you to optionally insert a username, a user plus password, and/or a port number. The @@ -173,18 +173,18 @@ security risks of having a password written down. If the URL supplies a username but no password, and the remote server requests a password, the program interpreting the URL should request one from the user. -.PP +.P Here are some of the most common schemes in use on UNIX-like systems that are understood by many tools. Note that many tools using URIs also have internal schemes or specialized schemes; see those tools' documentation for information on those schemes. -.PP +.P .B "http \- Web (HTTP) server" -.PP +.P .RI http:// ip_server / path .br .RI http:// ip_server / path ? query -.PP +.P This is a URL accessing a web (HTTP) server. The default port is 80. If the path refers to a directory, the web server will choose what @@ -192,7 +192,7 @@ to return; usually if there is a file named "index.html" or "index.htm" its content is returned, otherwise, a list of the files in the current directory (with appropriate links) is generated and returned. An example is . -.PP +.P A query can be given in the archaic "isindex" format, consisting of a word or phrase and not including an equal sign (=). A query can also be in the longer "GET" format, which has one or more @@ -215,11 +215,11 @@ See the Common Gateway Interface specification at .UR http://www.w3.org\:/CGI .UE for more information. -.PP +.P .B "ftp \- File Transfer Protocol (FTP)" -.PP +.P .RI ftp:// ip_server / path -.PP +.P This is a URL accessing a file through the file transfer protocol (FTP). The default port (for control) is 21. If no username is included, the username "anonymous" is supplied, and @@ -227,16 +227,16 @@ in that case many clients provide as the password the requestor's Internet email address. An example is . -.PP +.P .B "gopher \- Gopher server" -.PP +.P .RI gopher:// ip_server / "gophertype selector" .br .RI gopher:// ip_server / "gophertype selector" %09 search .br .RI gopher:// ip_server / "gophertype selector" %09 search %09 gopher+_string .br -.PP +.P The default gopher port is 70. .I gophertype is a single-character field to denote the @@ -245,18 +245,18 @@ which the URL refers. The entire path may also be empty, in which case the delimiting "/" is also optional and the gophertype defaults to "1". -.PP +.P .I selector is the Gopher selector string. In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR). -.PP +.P .B "mailto \- Email address" -.PP +.P .RI mailto: email-address -.PP +.P This is an email address, usually of the form .IR name @ hostname . See @@ -264,13 +264,13 @@ See for more information on the correct format of an email address. Note that any % character must be rewritten as %25. An example is . -.PP +.P .B "news \- Newsgroup or News message" -.PP +.P .RI news: newsgroup-name .br .RI news: message-id -.PP +.P A .I newsgroup-name is a period-delimited hierarchical name, such as @@ -278,7 +278,7 @@ is a period-delimited hierarchical name, such as If is "*" (as in ), it is used to refer to "all available news groups". An example is . -.PP +.P A .I message-id corresponds to the Message-ID of @@ -290,23 +290,23 @@ and ">"; it takes the form .IR unique @ full_domain_name . A message identifier may be distinguished from a news group name by the presence of the "@" character. -.PP +.P .B "telnet \- Telnet login" -.PP +.P .RI telnet:// ip_server / -.PP +.P The Telnet URL scheme is used to designate interactive text services that may be accessed by the Telnet protocol. The final "/" character may be omitted. The default port is 23. An example is . -.PP +.P .B "file \- Normal file" -.PP +.P .RI file:// ip_server / path_segments .br .RI file: path_segments -.PP +.P This represents a file or directory accessible locally. As a special case, .I ip_server @@ -323,7 +323,7 @@ the filename via filename globbing .BR glob (7) and .BR glob (3)). -.PP +.P The second format (e.g., ) is a correct format for referring to a local file. @@ -337,13 +337,13 @@ Note that if you really mean to say "start from the current location", don't specify the scheme at all; use a relative address like <../test.txt>, which has the side-effect of being scheme-independent. An example of this scheme is . -.PP +.P .B "man \- Man page documentation" -.PP +.P .RI man: command-name .br .RI man: command-name ( section ) -.PP +.P This refers to local online manual (man) reference pages. The command name can optionally be followed by a parenthesis and section number; see @@ -352,9 +352,9 @@ for more information on the meaning of the section numbers. This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. An example is . -.PP +.P .B "info \- Info page documentation" -.PP +.P .RI info: virtual-filename .br .RI info: virtual-filename # nodename @@ -362,7 +362,7 @@ An example is . .RI info:( virtual-filename ) .br .RI info:( virtual-filename ) nodename -.PP +.P This scheme refers to online info reference pages (generated from texinfo files), a documentation format used by programs such as the GNU tools. @@ -381,11 +381,11 @@ In both GNOME and KDE, if the form without the nodename is used the nodename is assumed to be "Top". Examples of the GNOME format are and . Examples of the KDE format are and . -.PP +.P .B "whatis \- Documentation search" -.PP +.P .RI whatis: string -.PP +.P This scheme searches the database of short (one-line) descriptions of commands and returns a list of descriptions containing that string. Only complete word matches are returned. @@ -393,16 +393,16 @@ See .BR whatis (1). This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. -.PP +.P .B "ghelp \- GNOME help documentation" -.PP +.P .RI ghelp: name-of-application -.PP +.P This loads GNOME help for the given application. Note that not much documentation currently exists in this format. -.PP +.P .B "ldap \- Lightweight Directory Access Protocol" -.PP +.P .RI ldap:// hostport .br .RI ldap:// hostport / @@ -416,7 +416,7 @@ Note that not much documentation currently exists in this format. .RI ldap:// hostport / dn ? attributes ? scope ? filter .br .RI ldap:// hostport / dn ? attributes ? scope ? filter ? extensions -.PP +.P This scheme supports queries to the Lightweight Directory Access Protocol (LDAP), a protocol for querying a set of servers for hierarchically organized information @@ -469,36 +469,36 @@ pairs, where the =value portion may be omitted for options not requiring it. An extension prefixed with a \[aq]!\[aq] is critical (must be supported to be valid), otherwise it is noncritical (optional). -.PP +.P LDAP queries are easiest to explain by example. Here's a query that asks ldap.itd.umich.edu for information about the University of Michigan in the U.S.: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US .fi -.PP +.P To just get its postal address attribute, request: -.PP +.P .nf ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress .fi -.PP +.P To ask a host.com at port 6666 for information about the person with common name (cn) "Babs Jensen" at University of Michigan, request: -.PP +.P .nf ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen) .fi -.PP +.P .B "wais \- Wide Area Information Servers" -.PP +.P .RI wais:// hostport / database .br .RI wais:// hostport / database ? search .br .RI wais:// hostport / database / wtype / wpath -.PP +.P This scheme designates a WAIS database, search, or document (see .UR http://www.ietf.org\:/rfc\:/rfc1625.txt @@ -507,7 +507,7 @@ IETF RFC\ 1625 for more information on WAIS). Hostport is the hostname, optionally followed by a colon and port number (the default port number is 210). -.PP +.P The first form designates a WAIS database for searching. The second form designates a particular search of the WAIS database .IR database . @@ -517,9 +517,9 @@ database to be retrieved. is the WAIS designation of the type of the object and .I wpath is the WAIS document-id. -.PP +.P .B "other schemes" -.PP +.P There are many other URI schemes. Most tools that accept URIs support a set of internal URIs (e.g., Mozilla has the about: scheme for internal information, @@ -536,7 +536,7 @@ Not all tools support all schemes. .SS Character encoding URIs use a limited number of characters so that they can be typed in and used in a variety of situations. -.PP +.P The following characters are reserved, that is, they may appear in a URI but their use is limited to their reserved purpose (conflicting data must be escaped before forming the URI): @@ -546,7 +546,7 @@ URI but their use is limited to their reserved purpose ; / ? : @ & = + $ , .EE .in -.PP +.P Unreserved characters may be included in a URI. Unreserved characters include uppercase and lowercase Latin letters, @@ -558,7 +558,7 @@ limited set of punctuation marks and symbols: \- _ . ! \[ti] * ' ( ) .EE .in -.PP +.P All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits @@ -573,13 +573,13 @@ in query text; this practice isn't uniformly defined in the relevant RFCs (which recommend %20 instead) but any tool accepting URIs with query text should be prepared for them. A URI is always shown in its "escaped" form. -.PP +.P Unreserved characters can be escaped without changing the semantics of the URI, but this should not be done unless the URI is being used in a context that does not allow the unescaped character to appear. For example, "%7e" is sometimes used instead of "\[ti]" in an HTTP URL path, but the two are equivalent for an HTTP URL. -.PP +.P For URIs which must handle characters outside the US ASCII character set, the HTML 4.01 specification (section B.2) and IETF RFC\~3986 (last paragraph of section 2.5) @@ -609,7 +609,7 @@ This latter system, called the 'new' or 'logical' quoting system by is preferred practice in Great Britain and in various European languages. Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. -.PP +.P The URI syntax was designed to be unambiguous. However, as URIs have become commonplace, traditional media (television, radio, newspapers, billboards, etc.) have increasingly @@ -644,9 +644,9 @@ be able to handle (directly or indirectly) all of the schemes described here, including the man: and info: schemes. Handling them by invoking some other program is fine and in fact encouraged. -.PP +.P Technically the fragment isn't part of the URI. -.PP +.P For information on how to embed URIs (including URLs) in a data format, see documentation on that format. HTML uses the format @@ -655,7 +655,7 @@ HTML uses the format Texinfo files use the format @uref{\fIuri\fP}. Man and mdoc have the recently added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI). -.PP +.P The GNOME and KDE desktop environments currently vary in the URIs they accept, in particular in their respective help browsers. To list man pages, GNOME uses while KDE uses , and @@ -685,7 +685,7 @@ guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can be obtained only from the person(s) controlling that namespace and the resource in question. -.PP +.P It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact @@ -700,11 +700,11 @@ interpreted according to this other protocol, cause an unexpected operation. An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server. -.PP +.P Caution should be used when using any URL that specifies a port number other than the default for the protocol, especially when it is a number within the reserved space. -.PP +.P Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet protocols) that these are not unescaped before transmission. @@ -712,7 +712,7 @@ This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed. -.PP +.P It is clearly unwise to use a URI that contains a password which is intended to be secret. In particular, the use of a password within @@ -739,10 +739,10 @@ without having to know the exact location of that documentation. Alternatively, a future version of the filesystem specification may specify file locations sufficiently so that the file: scheme will be able to locate documentation. -.PP +.P Many programs and file formats don't include a way to incorporate or implement links using URIs. -.PP +.P Many programs can't handle all of these different URI formats; there should be a standard mechanism to load an arbitrary URI that automatically detects the users' environment (e.g., text or graphics, @@ -755,7 +755,7 @@ tools) and invokes the right tool for any URI. .BR man2html (1), .BR mailaddr (7), .BR utf\-8 (7) -.PP +.P .UR http://www.ietf.org\:/rfc\:/rfc2255.txt IETF RFC\ 2255 .UE diff --git a/man7/user-keyring.7 b/man7/user-keyring.7 index 7468cc5..137c691 100644 --- a/man7/user-keyring.7 +++ b/man7/user-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH user-keyring 7 2023-02-05 "Linux man-pages 6.05.01" +.TH user-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME user-keyring \- per-user keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The user keyring has a name (description) of the form where .I is the user ID of the corresponding user. -.PP +.P The user keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the @@ -27,28 +27,28 @@ The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.) -.PP +.P Typically, the user keyring is created by .BR pam_keyinit (8) when a user logs in. -.PP +.P The user keyring is not searched by default by .BR request_key (2). When .BR pam_keyinit (8) creates a session keyring, it adds to it a link to the user keyring so that the user keyring will be searched when the session keyring is. -.PP +.P A special serial number value, .BR KEY_SPEC_USER_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's user keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@u\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P User keyrings are independent of .BR clone (2), .BR fork (2), @@ -58,14 +58,14 @@ and .BR _exit (2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits. -.PP +.P If it is necessary for a key associated with a user to exist beyond the UID record being garbage collected\[em]for example, for use by a .BR cron (8) script\[em]then the .BR persistent\-keyring (7) should be used instead. -.PP +.P If a user keyring does not exist when it is accessed, it will be created. .SH SEE ALSO .ad l diff --git a/man7/user-session-keyring.7 b/man7/user-session-keyring.7 index 3fc8795..7af56f0 100644 --- a/man7/user-session-keyring.7 +++ b/man7/user-session-keyring.7 @@ -3,7 +3,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH user-session-keyring 7 2023-02-05 "Linux man-pages 6.05.01" +.TH user-session-keyring 7 2023-10-31 "Linux man-pages 6.7" .SH NAME user-session-keyring \- per-user default session keyring .SH DESCRIPTION @@ -15,7 +15,7 @@ The user session keyring has a name (description) of the form where .I is the user ID of the corresponding user. -.PP +.P The user session keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the @@ -28,7 +28,7 @@ The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.) -.PP +.P The user session keyring is created on demand when a thread requests it or when a thread asks for its .BR session\-keyring (7) @@ -36,22 +36,22 @@ and that keyring doesn't exist. In the latter case, a user session keyring will be created and, if the session keyring wasn't to be created, the user session keyring will be set as the process's actual session keyring. -.PP +.P The user session keyring is searched by .BR request_key (2) if the actual session keyring does not exist and is ignored otherwise. -.PP +.P A special serial number value, .BR KEY_SPEC_USER_SESSION_KEYRING , is defined that can be used in lieu of the actual serial number of the calling process's user session keyring. -.PP +.P From the .BR keyctl (1) utility, '\fB@us\fP' can be used instead of a numeric key ID in much the same way. -.PP +.P User session keyrings are independent of .BR clone (2), .BR fork (2), @@ -61,10 +61,10 @@ and .BR _exit (2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits. -.PP +.P If a user session keyring does not exist when it is accessed, it will be created. -.PP +.P Rather than relying on the user session keyring, it is strongly recommended\[em]especially if the process is running as root\[em]that a diff --git a/man7/user_namespaces.7 b/man7/user_namespaces.7 index 0c29f93..94e0785 100644 --- a/man7/user_namespaces.7 +++ b/man7/user_namespaces.7 @@ -4,13 +4,13 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH user_namespaces 7 2023-05-03 "Linux man-pages 6.05.01" +.TH user_namespaces 7 2024-02-25 "Linux man-pages 6.7" .SH NAME user_namespaces \- overview of Linux user namespaces .SH DESCRIPTION For an overview of namespaces, see .BR namespaces (7). -.PP +.P User namespaces isolate security-related identifiers and attributes, in particular, user IDs and group IDs (see @@ -46,7 +46,7 @@ or with the .B CLONE_NEWUSER flag. -.PP +.P The kernel imposes (since Linux 3.11) a limit of 32 nested levels of .\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8 user namespaces. @@ -57,7 +57,7 @@ or .BR clone (2) that would cause this limit to be exceeded fail with the error .BR EUSERS . -.PP +.P Each process is a member of exactly one user namespace. A process created via .BR fork (2) @@ -72,7 +72,7 @@ if it has the .B CAP_SYS_ADMIN in that namespace; upon doing so, it gains a full set of capabilities in that namespace. -.PP +.P A call to .BR clone (2) or @@ -84,14 +84,14 @@ flag makes the new child process (for or the caller (for .BR unshare (2)) a member of the new user namespace created by the call. -.PP +.P The .B NS_GET_PARENT .BR ioctl (2) operation can be used to discover the parental relationship between user namespaces; see .BR ioctl_ns (2). -.PP +.P A task that changes one of its effective IDs will have its dumpability reset to the value in .IR /proc/sys/fs/suid_dumpable . @@ -134,7 +134,7 @@ and user namespace, even if the new namespace is created or joined by the root user (i.e., a process with user ID 0 in the root namespace). -.PP +.P Note that a call to .BR execve (2) will cause a process's capabilities to be recalculated in the usual way (see @@ -144,7 +144,7 @@ unless the process has a user ID of 0 within the namespace, or the executable file has a nonempty inheritable capabilities mask, the process will lose all capabilities. See the discussion of user and group ID mappings, below. -.PP +.P A call to .BR clone (2) or @@ -172,7 +172,7 @@ retaining its user namespace membership by using a pair of .BR setns (2) calls to move to another user namespace and then return to its original user namespace. -.PP +.P The rules for determining whether or not a process has a capability in a particular user namespace are as follows: .IP \[bu] 3 @@ -230,7 +230,7 @@ In other words, having a capability in a user namespace permits a process to perform privileged operations on resources that are governed by (nonuser) namespaces owned by (associated with) the user namespace (see the next subsection). -.PP +.P On the other hand, there are many privileged operations that affect resources that are not associated with any namespace type, for example, changing the system (i.e., calendar) time (governed by @@ -242,14 +242,14 @@ and creating a device (governed by Only a process with privileges in the .I initial user namespace can perform such operations. -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's mount namespace allows that process to create bind mounts and mount the following types of filesystems: .\" fs_flags = FS_USERNS_MOUNT in kernel sources -.PP +.P .RS 4 .PD 0 .IP \[bu] 3 @@ -281,7 +281,7 @@ and mount the following types of filesystems: (since Linux 5.11) .PD .RE -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's cgroup namespace @@ -289,9 +289,9 @@ allows (since Linux 4.6) that process to the mount the cgroup version 2 filesystem and cgroup version 1 named hierarchies (i.e., cgroup filesystems mounted with the -.I """none,name=""" +.I \[dq]none,name=\[dq] option). -.PP +.P Holding .B CAP_SYS_ADMIN within the user namespace that owns a process's PID namespace @@ -299,7 +299,7 @@ allows (since Linux 3.8) that process to mount .I /proc filesystems. -.PP +.P Note, however, that mounting block-based filesystems can be done only by a process that holds .B CAP_SYS_ADMIN @@ -312,14 +312,14 @@ Starting in Linux 3.8, unprivileged processes can create user namespaces, and the other types of namespaces can be created with just the .B CAP_SYS_ADMIN capability in the caller's user namespace. -.PP +.P When a nonuser namespace is created, it is owned by the user namespace in which the creating process was a member at the time of the creation of the namespace. Privileged operations on resources governed by the nonuser namespace require that the process has the necessary capabilities in the user namespace that owns the nonuser namespace. -.PP +.P If .B CLONE_NEWUSER is specified along with other @@ -336,7 +336,7 @@ or caller privileges over the remaining namespaces created by the call. Thus, it is possible for an unprivileged caller to specify this combination of flags. -.PP +.P When a new namespace (other than a user namespace) is created via .BR clone (2) or @@ -358,7 +358,7 @@ the process's UTS namespace, and check whether the process has the required capability .RB ( CAP_SYS_ADMIN ) in that user namespace. -.PP +.P The .B NS_GET_USERNS .BR ioctl (2) @@ -383,13 +383,13 @@ inside the user namespace for the process .IR pid . These files can be read to view the mappings in a user namespace and written to (once) to define the mappings. -.PP +.P The description in the following paragraphs explains the details for .IR uid_map ; .I gid_map is exactly the same, but each instance of "user ID" is replaced by "group ID". -.PP +.P The .I uid_map file exposes the mapping of user IDs from the user namespace @@ -403,7 +403,7 @@ will potentially see different values when reading from a particular .I uid_map file, depending on the user ID mappings for the user namespaces of the reading processes. -.PP +.P Each line in the .I uid_map file specifies a 1-to-1 mapping of a range of contiguous @@ -448,14 +448,14 @@ that created this user namespace. .IP (3) The length of the range of user IDs that is mapped between the two user namespaces. -.PP +.P System calls that return user IDs (group IDs)\[em]for example, .BR getuid (2), .BR getgid (2), and the credential fields in the structure returned by .BR stat (2)\[em]return the user ID (group ID) mapped into the caller's user namespace. -.PP +.P When a process accesses a file, its user and group IDs are mapped into the initial user namespace for the purpose of permission checking and assigning IDs when creating a file. @@ -463,7 +463,7 @@ When a process retrieves file user and group IDs via .BR stat (2), the IDs are mapped in the opposite direction, to produce values relative to the process user and group ID mappings. -.PP +.P The initial user namespace has no parent namespace, but, for consistency, the kernel provides dummy user and group ID mapping files for this namespace. @@ -472,14 +472,14 @@ Looking at the file .RI ( gid_map is the same) from a shell in the initial namespace shows: -.PP +.P .in +4n .EX $ \fBcat /proc/$$/uid_map\fP 0 0 4294967295 .EE .in -.PP +.P This mapping tells us that the range starting at user ID 0 in this namespace maps to a range starting at 0 in the (nonexistent) parent namespace, @@ -512,7 +512,7 @@ file in a user namespace fails with the error Similar rules apply for .I gid_map files. -.PP +.P The lines written to .I uid_map .RI ( gid_map ) @@ -552,10 +552,10 @@ Linux 3.9 and later fix this limitation, allowing any valid set of nonoverlapping maps. .IP \[bu] At least one line must be written to the file. -.PP +.P Writes that violate the above rules fail with the error .BR EINVAL . -.PP +.P In order for a process to write to the .IR /proc/ pid /uid_map .RI ( /proc/ pid /gid_map ) @@ -661,7 +661,7 @@ file (see below) before writing to .IR gid_map . .RE .RE -.PP +.P Writes that violate the above rules fail with the error .BR EPERM . .\" @@ -674,13 +674,13 @@ it is possible to create project ID mappings for a user namespace. .BR setquota (8) and .BR quotactl (2).) -.PP +.P Project ID mappings are defined by writing to the .IR /proc/ pid /projid_map file (present since .\" commit f76d207a66c3a53defea67e7d36c3eb1b7d6d61d Linux 3.7). -.PP +.P The validity rules for writing to the .IR /proc/ pid /projid_map file are as for writing to the @@ -689,7 +689,7 @@ file; violation of these rules causes .BR write (2) to fail with the error .BR EINVAL . -.PP +.P The permission rules for writing to the .IR /proc/ pid /projid_map file are as follows: @@ -701,7 +701,7 @@ or be in the parent user namespace of the process .IP \[bu] The mapped project IDs must in turn have a mapping in the parent user namespace. -.PP +.P Violation of these rules causes .BR write (2) to fail with the error @@ -722,7 +722,7 @@ and .I gid_map files have been written, only the mapped values may be used in system calls that change user and group IDs. -.PP +.P For user IDs, the relevant system calls include .BR setuid (2), .BR setfsuid (2), @@ -736,7 +736,7 @@ For group IDs, the relevant system calls include .BR setresgid (2), and .BR setgroups (2). -.PP +.P Writing .RI \[dq] deny \[dq] to the @@ -784,7 +784,7 @@ file (and regardless of the process's capabilities), calls to are also not permitted if .IR /proc/ pid /gid_map has not yet been set. -.PP +.P A privileged process (one with the .B CAP_SYS_ADMIN capability in the namespace) may write either of the strings @@ -800,7 +800,7 @@ Writing the string .RI \[dq] deny \[dq] prevents any process in the user namespace from employing .BR setgroups (2). -.PP +.P The essence of the restrictions described in the preceding paragraph is that it is permitted to write to .IR /proc/ pid /setgroups @@ -819,10 +819,10 @@ a process can transition only from being disallowed to .BR setgroups (2) being allowed. -.PP +.P The default value of this file in the initial user namespace is .RI \[dq] allow \[dq]. -.PP +.P Once .IR /proc/ pid /gid_map has been written to @@ -837,11 +837,11 @@ to .IR /proc/ pid /setgroups (the write fails with the error .BR EPERM ). -.PP +.P A child user namespace inherits the .IR /proc/ pid /setgroups setting from its parent. -.PP +.P If the .I setgroups file has the value @@ -855,7 +855,7 @@ to the file) in this user namespace. .BR EPERM .) This restriction also propagates down to all child user namespaces of this user namespace. -.PP +.P The .IR /proc/ pid /setgroups file was added in Linux 3.19, @@ -913,7 +913,7 @@ and .I /proc/sys/kernel/overflowgid in .BR proc (5). -.PP +.P The cases where unmapped IDs are mapped in this fashion include system calls that return user IDs .RB ( getuid (2), @@ -941,7 +941,7 @@ credentials written to the process accounting file (see .BR acct (5)), and credentials returned with POSIX message queue notifications (see .BR mq_notify (3)). -.PP +.P There is one notable case where unmapped user and group IDs are .I not .\" from_kuid(), from_kgid() @@ -978,7 +978,7 @@ These capabilities are: .BR CAP_FOWNER , and .BR CAP_FSETID . -.PP +.P Within a user namespace, these capabilities allow a process to bypass the rules if the process has the relevant capability over the file, @@ -988,7 +988,7 @@ the process has the relevant effective capability in its user namespace; and .IP \[bu] the file's user ID and group ID both have valid mappings in the user namespace. -.PP +.P The .B CAP_FOWNER capability is treated somewhat exceptionally: @@ -1057,7 +1057,7 @@ User namespaces require support in a range of subsystems across the kernel. When an unsupported subsystem is configured into the kernel, it is not possible to configure user namespaces support. -.PP +.P As at Linux 3.8, most relevant subsystems supported user namespaces, but a number of filesystems did not have the infrastructure needed to map user and group IDs between user namespaces. @@ -1077,9 +1077,9 @@ The comments and .IR usage () function inside the program provide a full explanation of the program. The following shell session demonstrates its use. -.PP +.P First, we look at the run-time environment: -.PP +.P .in +4n .EX $ \fBuname \-rs\fP # Need Linux 3.8 or later @@ -1090,7 +1090,7 @@ $ \fBid \-g\fP 1000 .EE .in -.PP +.P Now start a new shell in new user .RI ( \-U ), mount @@ -1102,29 +1102,29 @@ namespaces, with user ID and group ID .RI ( \-G ) 1000 mapped to 0 inside the user namespace: -.PP +.P .in +4n .EX $ \fB./userns_child_exec \-p \-m \-U \-M \[aq]0 1000 1\[aq] \-G \[aq]0 1000 1\[aq] bash\fP .EE .in -.PP +.P The shell has PID 1, because it is the first process in the new PID namespace: -.PP +.P .in +4n .EX bash$ \fBecho $$\fP 1 .EE .in -.PP +.P Mounting a new .I /proc filesystem and listing all of the processes visible in the new PID namespace shows that the shell can't see any processes outside the PID namespace: -.PP +.P .in +4n .EX bash$ \fBmount \-t proc proc /proc\fP @@ -1134,10 +1134,10 @@ bash$ \fBps ax\fP 22 pts/3 R+ 0:00 ps ax .EE .in -.PP +.P Inside the user namespace, the shell has user and group ID 0, and a full set of permitted and effective capabilities: -.PP +.P .in +4n .EX bash$ \fBcat /proc/$$/status | egrep \[aq]\[ha][UG]id\[aq]\fP @@ -1464,6 +1464,6 @@ main(int argc, char *argv[]) .BR credentials (7), .BR namespaces (7), .BR pid_namespaces (7) -.PP +.P The kernel source file .IR Documentation/admin\-guide/namespaces/resource\-control.rst . diff --git a/man7/utf-8.7 b/man7/utf-8.7 index 8a5f7ab..077fa42 100644 --- a/man7/utf-8.7 +++ b/man7/utf-8.7 @@ -7,7 +7,7 @@ .\" 2001-05-11 Markus Kuhn .\" Update .\" -.TH UTF-8 7 2023-03-12 "Linux man-pages 6.05.01" +.TH UTF-8 7 2024-03-14 "Linux man-pages 6.7" .SH NAME UTF-8 \- an ASCII compatible multibyte Unicode encoding .SH DESCRIPTION @@ -27,14 +27,13 @@ The ISO/IEC 10646 Universal Character Set (UCS), a superset of Unicode, occupies an even larger code space\[em]31\ bits\[em]and the obvious UCS-4 encoding for it (a sequence of 32-bit words) has the same problems. -.PP +.P The UTF-8 encoding of Unicode and UCS does not have these problems and is the common way in which Unicode is used on UNIX-style operating systems. .SS Properties The UTF-8 encoding has the following nice properties: -.TP 0.2i -* +.IP \[bu] 3 UCS characters 0x00000000 to 0x0000007f (the classic US-ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII @@ -43,24 +42,19 @@ This means that files and strings which contain only 7-bit ASCII characters have the same encoding under both ASCII and -UTF-8 . -.TP -* +UTF-8. +.IP \[bu] All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to 0xfd, so no ASCII byte can appear as part of another character and there are no problems with, for example, \[aq]\e0\[aq] or \[aq]/\[aq]. -.TP -* +.IP \[bu] The lexicographic sorting order of UCS-4 strings is preserved. -.TP -* +.IP \[bu] All possible 2\[ha]31 UCS codes can be encoded using UTF-8. -.TP -* +.IP \[bu] The bytes 0xc0, 0xc1, 0xfe, and 0xff are never used in the UTF-8 encoding. -.TP -* +.IP \[bu] The first byte of a multibyte sequence which represents a single non-ASCII UCS character is always in the range 0xc2 to 0xfd and indicates how long this multibyte sequence is. @@ -68,8 +62,7 @@ All further bytes in a multibyte sequence are in the range 0x80 to 0xbf. This allows easy resynchronization and makes the encoding stateless and robust against missing bytes. -.TP -* +.IP \[bu] UTF-8 encoded UCS characters may be up to six bytes long, however the Unicode standard specifies no characters above 0x10ffff, so Unicode characters can be only up to four bytes long in @@ -77,7 +70,7 @@ UTF-8. .SS Encoding The following byte sequences are used to represent a character. The sequence to be used depends on the UCS code number of the character: -.TP 0.4i +.TP 0x00000000 \- 0x0000007F: .RI 0 xxxxxxx .TP @@ -110,14 +103,14 @@ The sequence to be used depends on the UCS code number of the character: .RI 10 xxxxxx .RI 10 xxxxxx .RI 10 xxxxxx -.PP +.P The .I xxx bit positions are filled with the bits of the character code number in binary representation, most significant bit first (big-endian). Only the shortest possible multibyte sequence which can represent the code number of the character can be used. -.PP +.P The UCS code values 0xd800\[en]0xdfff (UTF-16 surrogates) as well as 0xfffe and 0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams. According to RFC 3629 no point above U+10FFFF should be used, @@ -125,45 +118,46 @@ which limits characters to four bytes. .SS Example The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded in UTF-8 as -.PP +.P .RS 11000010 10101001 = 0xc2 0xa9 .RE -.PP +.P and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is encoded as: -.PP +.P .RS 11100010 10001001 10100000 = 0xe2 0x89 0xa0 .RE .SS Application notes Users have to select a UTF-8 locale, for example with -.PP +.P .RS export LANG=en_GB.UTF-8 .RE -.PP +.P in order to activate the UTF-8 support in applications. -.PP +.P Application software that has to be aware of the used character encoding should always set the locale with for example -.PP +.P .RS setlocale(LC_CTYPE, "") .RE -.PP +.P and programmers can then test the expression -.PP +.P .RS strcmp(nl_langinfo(CODESET), "UTF-8") == 0 .RE -.PP +.P to determine whether a UTF-8 locale has been selected and whether therefore all plaintext standard input and output, terminal communication, plaintext file content, filenames, and environment variables are encoded in UTF-8. -.PP -Programmers accustomed to single-byte encodings such as US-ASCII or ISO 8859 +.P +Programmers accustomed to single-byte encodings +such as US-ASCII or ISO/IEC\~8859 have to be aware that two assumptions made so far are no longer valid in UTF-8 locales. Firstly, a single byte does not necessarily correspond any @@ -178,14 +172,14 @@ Library functions such as and .BR wcswidth (3) should be used today to count characters and cursor positions. -.PP -The official ESC sequence to switch from an ISO 2022 +.P +The official ESC sequence to switch from an ISO/IEC\~2022 encoding scheme (as used for instance by VT100 terminals) to UTF-8 is ESC % G ("\ex1b%G"). The corresponding return sequence from -UTF-8 to ISO 2022 is ESC % @ ("\ex1b%@"). -Other ISO 2022 sequences (such as +UTF-8 to ISO/IEC\~2022 is ESC % @ ("\ex1b%@"). +Other ISO/IEC\~2022 sequences (such as for switching the G0 and G1 sets) are not applicable in UTF-8 mode. .SS Security The Unicode and UCS standards require that producers of UTF-8 diff --git a/man7/uts_namespaces.7 b/man7/uts_namespaces.7 index 670d19e..0b2a9a0 100644 --- a/man7/uts_namespaces.7 +++ b/man7/uts_namespaces.7 @@ -3,7 +3,7 @@ .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .\" -.TH uts_namespaces 7 2022-12-04 "Linux man-pages 6.05.01" +.TH uts_namespaces 7 2023-10-31 "Linux man-pages 6.7" .SH NAME uts_namespaces \- overview of Linux UTS namespaces .SH DESCRIPTION @@ -21,7 +21,7 @@ and Changes made to these identifiers are visible to all other processes in the same UTS namespace, but are not visible to processes in other UTS namespaces. -.PP +.P When a process creates a new UTS namespace using .BR clone (2) or @@ -30,7 +30,7 @@ with the .B CLONE_NEWUTS flag, the hostname and domain name of the new UTS namespace are copied from the corresponding values in the caller's UTS namespace. -.PP +.P Use of UTS namespaces requires a kernel that is configured with the .B CONFIG_UTS_NS option. diff --git a/man7/vdso.7 b/man7/vdso.7 index 338ef72..d37360c 100644 --- a/man7/vdso.7 +++ b/man7/vdso.7 @@ -11,13 +11,13 @@ .\" http://www.linuxjournal.com/content/creating-vdso-colonels-other-chicken .\" http://www.trilithium.com/johan/2005/08/linux-gate/ .\" -.TH vDSO 7 2023-05-03 "Linux man-pages 6.05.01" +.TH vDSO 7 2024-02-18 "Linux man-pages 6.7" .SH NAME vdso \- overview of the virtual ELF dynamic shared object .SH SYNOPSIS .nf .B #include -.PP +.P .B void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR); .fi .SH DESCRIPTION @@ -29,7 +29,7 @@ as the vDSO is most commonly called by the C library. This way you can code in the normal way using standard functions and the C library will take care of using any functionality that is available via the vDSO. -.PP +.P Why does the vDSO exist at all? There are some system calls the kernel provides that user-space code ends up using frequently, @@ -37,7 +37,7 @@ to the point that such calls can dominate overall performance. This is due both to the frequency of the call as well as the context-switch overhead that results from exiting user space and entering the kernel. -.PP +.P The rest of this documentation is geared toward the curious and/or C library writers rather than general developers. If you're trying to call the vDSO in your own application rather than using @@ -56,14 +56,14 @@ Rather than require the C library to figure out if this functionality is available at run time, the C library can use functions provided by the kernel in the vDSO. -.PP +.P Note that the terminology can be confusing. On x86 systems, the vDSO function used to determine the preferred method of making a system call is named "__kernel_vsyscall", but on x86-64, the term "vsyscall" also refers to an obsolete way to ask the kernel what time it is or what CPU the caller is on. -.PP +.P One frequently used system call is .BR gettimeofday (2). This system call is called both directly by user-space applications @@ -86,7 +86,7 @@ each program in the initial auxiliary vector (see via the .B AT_SYSINFO_EHDR tag. -.PP +.P You must not assume the vDSO is mapped at any particular location in the user's memory map. The base address will usually be randomized at run time every time a new @@ -95,7 +95,7 @@ process image is created (at time). This is done for security reasons, to prevent "return-to-libc" attacks. -.PP +.P For some architectures, there is also an .B AT_SYSINFO tag. @@ -111,7 +111,7 @@ and allows the C library to detect available functionality at run time when running under different kernel versions. Oftentimes the C library will do detection with the first call and then cache the result for subsequent calls. -.PP +.P All symbols are also versioned (using the GNU version format). This allows the kernel to update the function signature without breaking backward compatibility. @@ -120,12 +120,12 @@ return value. Thus, when looking up a symbol in the vDSO, you must always include the version to match the ABI you expect. -.PP +.P Typically the vDSO follows the naming convention of prefixing all symbols with "__vdso_" or "__kernel_" so as to distinguish them from other standard symbols. For example, the "gettimeofday" function is named "__vdso_gettimeofday". -.PP +.P You use the standard C calling conventions when calling any of these functions. No need to worry about weird register or stack behavior. @@ -134,7 +134,7 @@ No need to worry about weird register or stack behavior. When you compile the kernel, it will automatically compile and link the vDSO code for you. You will frequently find it under the architecture-specific directory: -.PP +.P .in +4n .EX find arch/$ARCH/ \-name \[aq]*vdso*.so*\[aq] \-o \-name \[aq]*gate*.so*\[aq] @@ -173,7 +173,7 @@ x86/x32 linux\-vdso.so.1 .ft P \} .SS strace(1), seccomp(2), and the vDSO -When tracing systems calls with +When tracing system calls with .BR strace (1), symbols (system calls) that are exported by the vDSO will .I not @@ -184,7 +184,7 @@ filters. .SH ARCHITECTURE-SPECIFIC NOTES The subsections below provide architecture-specific notes on the vDSO. -.PP +.P Note that the vDSO that is used is based on the ABI of your user-space code and not the ABI of the kernel. Thus, for example, @@ -211,14 +211,14 @@ __vdso_clock_gettime LINUX_2.6 (exported since Linux 4.1) .in .ft P \} -.PP +.P .\" See linux/arch/arm/kernel/entry-armv.S .\" See linux/Documentation/arm/kernel_user_helpers.rst Additionally, the ARM port has a code page full of utility functions. Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. It does provide support for different versions though. -.PP +.P For information on this code page, it's best to refer to the kernel documentation as it's extremely detailed and covers everything you need to know: @@ -254,7 +254,7 @@ There is no provision for backward compatibility beyond sniffing raw opcodes, but as this is an embedded CPU, it can get away with things\[em]some of the object formats it runs aren't even ELF based (they're bFLT/FLAT). -.PP +.P For information on this code page, it's best to refer to the public documentation: .br @@ -295,7 +295,7 @@ __kernel_syscall_via_epc LINUX_2.5 .in .ft P \} -.PP +.P The Itanium port is somewhat tricky. In addition to the vDSO above, it also has "light-weight system calls" (also known as "fast syscalls" or "fsys"). @@ -337,12 +337,12 @@ the page to the process via the SR2 register. The permissions on the page are such that merely executing those addresses automatically executes with kernel privileges and not in user space. This is done to match the way HP-UX works. -.PP +.P Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. Simply call into the appropriate offset via the branch instruction, for example: -.PP +.P .in +4n .EX ble (%sr2, %r0) @@ -394,7 +394,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} -.PP +.P Before Linux 5.6, .\" commit 654abc69ef2e69712e6d4e8a6cb9292b97a4aa39 the @@ -434,7 +434,7 @@ __kernel_sync_dicache_p5 LINUX_2.6.15 .in .ft P \} -.PP +.P Before Linux 4.16, .\" commit 5c929885f1bb4b77f85b1769c49405a0e0f154a1 the @@ -598,15 +598,15 @@ to user space, so it was reconceived as a vDSO in the current format. .BR syscalls (2), .BR getauxval (3), .BR proc (5) -.PP +.P The documents, examples, and source code in the Linux source code tree: -.PP +.P .in +4n .EX Documentation/ABI/stable/vdso Documentation/ia64/fsys.rst Documentation/vDSO/* (includes examples of using the vDSO) -.PP +.P find arch/ \-iname \[aq]*vdso*\[aq] \-o \-iname \[aq]*gate*\[aq] .EE .in diff --git a/man7/vsock.7 b/man7/vsock.7 index f6c3711..3d679c0 100644 --- a/man7/vsock.7 +++ b/man7/vsock.7 @@ -2,14 +2,14 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH vsock 7 2022-10-30 "Linux man-pages 6.05.01" +.TH vsock 7 2024-02-25 "Linux man-pages 6.7" .SH NAME vsock \- Linux VSOCK address family .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);" .IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);" .fi @@ -19,7 +19,7 @@ the host they are running on. This address family is used by guest agents and hypervisor services that need a communications channel that is independent of virtual machine network configuration. -.PP +.P Valid socket types are .B SOCK_STREAM and @@ -31,26 +31,26 @@ provides a connectionless datagram packet service with best-effort delivery and best-effort ordering. Availability of these socket types is dependent on the underlying hypervisor. -.PP +.P A new socket is created with -.PP +.P .in +4n .EX socket(AF_VSOCK, socket_type, 0); .EE .in -.PP +.P When a process wants to establish a connection, it calls .BR connect (2) with a given destination socket address. The socket is automatically bound to a free port if unbound. -.PP +.P A process can listen for incoming connections by first binding to a socket address using .BR bind (2) and then calling .BR listen (2). -.PP +.P Data is transmitted using the .BR send (2) or @@ -67,7 +67,7 @@ The CID identifies the source or destination, which is either a virtual machine or the host. The port number differentiates between multiple services running on a single machine. -.PP +.P .in +4n .EX struct sockaddr_vm { @@ -83,7 +83,7 @@ struct sockaddr_vm { }; .EE .in -.PP +.P .I svm_family is always set to .BR AF_VSOCK . @@ -100,7 +100,7 @@ capability may to these port numbers. .I svm_zero must be zero-filled. -.PP +.P There are several special addresses: .B VMADDR_CID_ANY (\-1U) @@ -112,7 +112,7 @@ means any address for binding; .B VMADDR_CID_HOST (2) is the well-known address of the host. -.PP +.P The special constant .B VMADDR_PORT_ANY (\-1U) @@ -123,7 +123,7 @@ Connected .B SOCK_STREAM sockets become disconnected when the virtual machine migrates to a new host. Applications must reconnect when this happens. -.PP +.P The local CID may change across live migration if the old CID is not available on the new host. Bound sockets are automatically updated to the new CID. @@ -152,11 +152,11 @@ when binding instead of getting the local CID with (1) directs packets to the same host that generated them. This is useful for testing applications on a single host and for debugging. -.PP +.P The local CID obtained with .B IOCTL_VM_SOCKETS_GET_LOCAL_CID can be used for the same purpose, but it is preferable to use -.B VMADDR_CID_LOCAL . +.BR VMADDR_CID_LOCAL . .SH ERRORS .TP .B EACCES @@ -215,7 +215,7 @@ are valid. Support for VMware (VMCI) has been available since Linux 3.9. KVM (virtio) is supported since Linux 4.8. Hyper-V is supported since Linux 4.14. -.PP +.P .B VMADDR_CID_LOCAL is supported since Linux 5.6. .\" commit ef343b35d46667668a099655fca4a5b2e43a5dfe diff --git a/man7/x25.7 b/man7/x25.7 index 1dc498e..73ef2f3 100644 --- a/man7/x25.7 +++ b/man7/x25.7 @@ -4,14 +4,16 @@ .\" .\" $Id: x25.7,v 1.4 1999/05/18 10:35:12 freitag Exp $ .\" -.TH x25 7 2023-07-15 "Linux man-pages 6.05.01" +.TH x25 7 2024-01-28 "Linux man-pages 6.7" .SH NAME -x25 \- ITU-T X.25 / ISO-8208 protocol interface +x25 +\- +ITU-T X.25 / ISO/IEC\~8208 protocol interface .SH SYNOPSIS .nf .B #include .B #include -.PP +.P .IB x25_socket " = socket(AF_X25, SOCK_SEQPACKET, 0);" .fi .SH DESCRIPTION @@ -22,8 +24,8 @@ International Telecommunication Union's recommendation X.25 (X.25 DTE-DCE mode). X25 sockets can also be used for communication without an intermediate X.25 network (X.25 DTE-DTE mode) as described -in ISO-8208. -.PP +in ISO/IEC\~8208. +.P Message boundaries are preserved \[em] a .BR read (2) from a socket will @@ -47,7 +49,7 @@ socket address family uses the .I struct sockaddr_x25 for representing network addresses as defined in ITU-T recommendation X.121. -.PP +.P .in +4n .EX struct sockaddr_x25 { @@ -56,7 +58,7 @@ struct sockaddr_x25 { }; .EE .in -.PP +.P .I sx25_addr contains a char array .I x25_addr[] @@ -98,23 +100,23 @@ The AF_X25 protocol family is a new feature of Linux 2.2. .SH BUGS Plenty, as the X.25 PLP implementation is .BR CONFIG_EXPERIMENTAL . -.PP +.P This man page is incomplete. -.PP +.P There is no dedicated application programmer's header file yet; you need to include the kernel header file .IR . .B CONFIG_EXPERIMENTAL might also imply that future versions of the interface are not binary compatible. -.PP +.P X.25 N-Reset events are not propagated to the user process yet. Thus, if a reset occurred, data might be lost without notice. .SH SEE ALSO .BR socket (2), .BR socket (7) -.PP +.P Jonathan Simon Naylor: \[lq]The Re-Analysis and Re-Implementation of X.25.\[rq] The URL is diff --git a/man7/xattr.7 b/man7/xattr.7 index c2f12c9..c90aaf8 100644 --- a/man7/xattr.7 +++ b/man7/xattr.7 @@ -6,7 +6,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH xattr 7 2023-02-05 "Linux man-pages 6.05.01" +.TH xattr 7 2023-10-31 "Linux man-pages 6.7" .SH NAME xattr \- Extended attributes .SH DESCRIPTION @@ -15,7 +15,7 @@ files and directories, similar to the environment strings associated with a process. An attribute may be defined or undefined. If it is defined, its value may be empty or non-empty. -.PP +.P Extended attributes are extensions to the normal attributes which are associated with all inodes in the system (i.e., the .BR stat (2) @@ -23,11 +23,11 @@ data). They are often used to provide additional functionality to a filesystem\[em]for example, additional security features such as Access Control Lists (ACLs) may be implemented using extended attributes. -.PP +.P Users with search access to a file or directory may use .BR listxattr (2) to retrieve a list of attribute names defined for that file or directory. -.PP +.P Extended attributes are accessed as atomic objects. Reading .RB ( getxattr (2)) @@ -35,7 +35,7 @@ retrieves the whole value of an attribute and stores it in a buffer. Writing .RB ( setxattr (2)) replaces any previous value with the new value. -.PP +.P Space consumed for extended attributes may be counted towards the disk quotas of the file owner and file group. .SS Extended attribute namespaces @@ -48,14 +48,14 @@ form, for example, .IR system.posix_acl_access , or .IR security.selinux . -.PP +.P The namespace mechanism is used to define different classes of extended attributes. These different classes exist for several reasons; for example, the permissions and capabilities required for manipulating extended attributes of one namespace may differ to another. -.PP +.P Currently, the .IR security , .IR system , @@ -97,7 +97,7 @@ The access permissions for user attributes are defined by the file permission bits: read permission is required to retrieve the attribute value, and writer permission is required to change it. -.PP +.P The file permission bits of regular files and directories are interpreted differently from the file permission bits of special files and symbolic links. @@ -108,7 +108,7 @@ The file permissions of symbolic links are not used in access checks. These differences would allow users to consume filesystem resources in a way not controllable by disk quotas for group or world writable special files and directories. -.PP +.P For this reason, user extended attributes are allowed only for regular files and directories, and access to user extended attributes is restricted to the @@ -125,26 +125,26 @@ The list of attribute names that can be returned is also limited to 64\ kB (see BUGS in .BR listxattr (2)). -.PP +.P Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), require the filesystem to be mounted with the .B user_xattr mount option in order for user extended attributes to be used. -.PP +.P In the current ext2, ext3, and ext4 filesystem implementations, the total bytes used by the names and values of all of a file's extended attributes must fit in a single filesystem block (1024, 2048 or 4096 bytes, depending on the block size specified when the filesystem was created). -.PP +.P In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no practical limit on the number of extended attributes associated with a file, and the algorithms used to store extended attribute information on disk are scalable. -.PP +.P In the JFS, XFS, and Reiserfs filesystem implementations, the limit on bytes used in an EA value is the ceiling imposed by the VFS. -.PP +.P In the Btrfs filesystem implementation, the total bytes used for the name, value, and implementation overhead bytes is limited to the filesystem @@ -158,7 +158,7 @@ Since the filesystems on which extended attributes are stored might also be used on architectures with a different byte order and machine word size, care should be taken to store attribute values in an architecture-independent format. -.PP +.P This page was formerly named .BR attr (5). .\" .SH AUTHORS diff --git a/man8/iconvconfig.8 b/man8/iconvconfig.8 index f02eede..ab931d7 100644 --- a/man8/iconvconfig.8 +++ b/man8/iconvconfig.8 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" -.TH iconvconfig 8 2022-10-30 "Linux man-pages 6.05.01" +.TH iconvconfig 8 2023-10-31 "Linux man-pages 6.7" .SH NAME iconvconfig \- create iconv module configuration cache .SH SYNOPSIS @@ -21,12 +21,12 @@ Loading and parsing such a configuration file would slow down programs that use .BR iconv (3), so a caching mechanism is employed. -.PP +.P The .B iconvconfig program reads iconv module configuration files and writes a fast-loading gconv module configuration cache file. -.PP +.P In addition to the system provided gconv modules, the user can specify custom gconv module directories with the environment variable .BR GCONV_PATH . @@ -40,7 +40,9 @@ is not set. Do not search the system default gconv directory, only the directories provided on the command line. .TP -.BI \-o " outputfile" ", \-\-output=" outputfile +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile Use .I outputfile for output instead of the system default cache location. @@ -56,13 +58,17 @@ the gconv module configuration would be read from and the cache would be written to .IR foo/usr/lib/gconv/gconv\-modules.cache . .TP -.BR \-? ", " \-\-help +.B \-\-help +.TQ +.B \-? Print a usage summary and exit. .TP -.B "\-\-usage" +.B \-\-usage Print a short usage summary and exit. .TP -.BR \-V ", " \-\-version +.B \-\-version +.TQ +.B \-V Print the version number, license, and disclaimer of warranty for .BR iconv . .SH EXIT STATUS @@ -77,7 +83,7 @@ Usual system default gconv module configuration file. .TP .I /usr/lib/gconv/gconv\-modules.cache Usual system gconv module configuration cache. -.PP +.P Depending on the architecture, the above files may instead be located at directories with the path prefix .IR /usr/lib64 . diff --git a/man8/intro.8 b/man8/intro.8 index 23fbcbd..c1368eb 100644 --- a/man8/intro.8 +++ b/man8/intro.8 @@ -7,7 +7,7 @@ .\" Modified Sat Jul 24 17:35:48 1993 by Rik Faith (faith@cs.unc.edu) .\" 2007-10-23 mtk: minor rewrites, and added paragraph on exit status .\" -.TH intro 8 2022-10-30 "Linux man-pages 6.05.01" +.TH intro 8 2023-10-31 "Linux man-pages 6.7" .SH NAME intro \- introduction to administration and privileged commands .SH DESCRIPTION @@ -15,7 +15,7 @@ Section 8 of the manual describes commands which either can be or are used only by the superuser, like system-administration commands, daemons, and hardware-related commands. -.PP +.P As with the commands described in Section 1, the commands described in this section terminate with an exit status that indicates whether the command succeeded or failed. diff --git a/man8/ld.so.8 b/man8/ld.so.8 index afd29c5..8767b50 100644 --- a/man8/ld.so.8 +++ b/man8/ld.so.8 @@ -4,7 +4,7 @@ .\" Various parts: .\" Copyright (C) 2007-9, 2013, 2016 Michael Kerrisk .\" -.TH ld.so 8 2023-07-18 "Linux man-pages 6.05.01" +.TH ld.so 8 2024-02-12 "Linux man-pages 6.7" .SH NAME ld.so, ld\-linux.so \- dynamic linker/loader .SH SYNOPSIS @@ -15,7 +15,7 @@ to the dynamic linker can be passed and, in the ELF case, the dynamic linker which is stored in the .B .interp section of the program is executed) or directly by running: -.PP +.P .I /lib/ld\-linux.so.* [OPTIONS] [PROGRAM [ARGUMENTS]] .SH DESCRIPTION @@ -25,14 +25,14 @@ and .B ld\-linux.so* find and load the shared objects (shared libraries) needed by a program, prepare the program to run, and then run it. -.PP +.P Linux binaries require dynamic linking (linking at run time) unless the .B \-static option was given to .BR ld (1) during compilation. -.PP +.P The program .B ld.so handles a.out binaries, a binary format used long ago. @@ -46,7 +46,7 @@ support files and programs .BR ldconfig (8), and .IR /etc/ld.so.conf ). -.PP +.P When resolving shared object dependencies, the dynamic linker first inspects each dependency string to see if it contains a slash (this can occur if @@ -54,7 +54,7 @@ a shared object pathname containing slashes was specified at link time). If a slash is found, then the dependency string is interpreted as a (relative or absolute) pathname, and the shared object is loaded using that pathname. -.PP +.P If a shared object dependency does not contain a slash, then it is searched for in the following order: .IP (1) 5 @@ -132,7 +132,7 @@ in the filename arguments to the and .BR dlmopen (3) functions. -.PP +.P The substituted tokens are as follows: .TP .IR $ORIGIN " (or equivalently " ${ORIGIN} ) @@ -187,7 +187,7 @@ value in the auxiliary vector (see .\" .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN; .\" Don't do this!! -.PP +.P Note that the dynamic string tokens have to be quoted properly when set from a shell, to prevent their expansion as shell or environment variables. @@ -208,6 +208,14 @@ The objects in .I list are delimited by colons. .TP +.BI \-\-glibc-hwcaps-mask " list" +only search built-in subdirectories if in +.IR list . +.TP +.BI \-\-glibc-hwcaps-prepend " list" +Search glibc-hwcaps subdirectories in +.IR list . +.TP .B \-\-inhibit\-cache Do not use .IR /etc/ld.so.cache . @@ -238,6 +246,16 @@ are delimited by colons or spaces. .B \-\-list List all dependencies and how they are resolved. .TP +.BR \-\-list\-diagnostics " (since glibc 2.33)" +Print system diagnostic information in a machine-readable format, +such as some internal loader variables, +the auxiliary vector +(see +.BR getauxval (3)), +and the environment variables. +On some architectures, +the command might print additional information +(like the cpu features used in GNU indirect function selection on x86). .BR \-\-list\-tunables " (since glibc 2.33)" Print the names and values of all tunables, along with the minimum and maximum allowed values. @@ -280,6 +298,17 @@ Other environment variables treated in this way include: .BR GETCONF_DIR , .BR HOSTALIASES , .BR LOCALDOMAIN , +.BR LD_AUDIT , +.BR LD_DEBUG , +.BR LD_DEBUG_OUTPUT , +.BR LD_DYNAMIC_WEAK , +.BR LD_HWCAP_MASK , +.BR LD_LIBRARY_PATH , +.BR LD_ORIGIN_PATH , +.BR LD_PRELOAD , +.BR LD_PROFILE , +.BR LD_SHOW_AUXV , +.BR LOCALDOMAIN , .BR LOCPATH , .BR MALLOC_TRACE , .BR NIS_PATH , @@ -289,7 +318,7 @@ Other environment variables treated in this way include: .BR TMPDIR , and .BR TZDIR . -.PP +.P A binary is executed in secure-execution mode if the .B AT_SECURE entry in the auxiliary vector (see @@ -310,7 +339,7 @@ A nonzero value may have been set by a Linux Security Module. .SS Environment variables Among the more important environment variables are the following: .TP -.BR LD_ASSUME_KERNEL " (since glibc 2.2.3)" +.BR LD_ASSUME_KERNEL " (from glibc 2.2.3 to glibc 2.36)" Each shared object can inform the dynamic linker of the minimum kernel ABI version that it requires. (This requirement is encoded in an ELF note section that is viewable via @@ -457,7 +486,7 @@ If set (to any value), causes the program to list its dynamic dependencies, as if run by .BR ldd (1), instead of running normally. -.PP +.P Then there are lots of more or less obscure variables, many obsolete or only for internal use. .TP @@ -627,8 +656,11 @@ Since glibc 2.3.4, .B LD_DYNAMIC_WEAK is ignored in secure-execution mode. .TP -.BR LD_HWCAP_MASK " (since glibc 2.1)" +.BR LD_HWCAP_MASK " (from glibc 2.1 to glibc 2.38)" Mask for hardware capabilities. +Since glibc 2.26, +the option might be ignored +if glibc does not support tunables. .TP .BR LD_ORIGIN_PATH " (since glibc 2.1)" Path where the binary is found. @@ -663,7 +695,7 @@ Profiling output is appended to the file whose name is: .IP Since glibc 2.2.5, .B LD_PROFILE -is ignored in secure-execution mode. +uses a different default path in secure-execution mode. .TP .BR LD_PROFILE_OUTPUT " (since glibc 2.1)" Directory where @@ -677,10 +709,6 @@ then the default is is ignored in secure-execution mode; instead .I /var/profile is always used. -(This detail is relevant only before glibc 2.2.5, -since in later glibc versions, -.B LD_PROFILE -is also ignored in secure-execution mode.) .TP .BR LD_SHOW_AUXV " (since glibc 2.1)" If this environment variable is defined (with any value), @@ -691,7 +719,7 @@ Since glibc 2.3.4, .B LD_SHOW_AUXV is ignored in secure-execution mode. .TP -.BR LD_TRACE_PRELINKING " (since glibc 2.4)" +.BR LD_TRACE_PRELINKING " (from glibc 2.4 to glibc 2.35)" If this environment variable is defined, trace prelinking of the object whose name is assigned to this environment variable. @@ -702,7 +730,7 @@ If the object name is not recognized, .\" (This is what seems to happen, from experimenting) then all prelinking activity is traced. .TP -.BR LD_USE_LOAD_BIAS " (since glibc 2.3.3)" +.BR LD_USE_LOAD_BIAS " (from glibc 2.3.3 to glibc 2.35)" .\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html .\" Subject: [PATCH] Support LD_USE_LOAD_BIAS .\" Jakub Jelinek @@ -788,7 +816,7 @@ as a temporary workaround to a library misconfiguration issue.) .I lib*.so* shared objects .SH NOTES -.SS Hardware capabilities +.SS Legacy Hardware capabilities (from glibc 2.5 to glibc 2.37) Some shared objects are compiled using hardware-specific instructions which do not exist on every CPU. Such objects should be installed in directories whose names define the @@ -823,6 +851,65 @@ z900, z990, z9-109, z10, zarch .B x86 (32-bit only) acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx, mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm +.P +The legacy hardware capabilities support has the drawback that +each new feature added grows the search path exponentially, +because it has to be added to +every combination of the other existing features. +.P +For instance, on x86 32-bit, +if the hardware supports +.B i686 +and +.BR sse2 , +the resulting search path will be +.BR i686/sse2:i686:sse2:. . +A new capability +.B newcap +will set the search path to +.BR newcap/i686/sse2:newcap/i686:newcap/sse2:newcap:i686/sse2:i686:sse2: . +.\" +.SS glibc Hardware capabilities (from glibc 2.33) +.TP +.\" The initial discussion on various pitfalls of the old scheme is +.\" +.\" and the patchset that proposes the glibc-hwcap support is +.\" +glibc 2.33 added a new hardware capability scheme, +where under each CPU architecture, +certain levels can be defined, +grouping support for certain features or special instructions. +Each architecture level has +a fixed set of paths that it adds to the dynamic linker search list, +depending on the hardware of the machine. +Since each new architecture level is +not combined with previously existing ones, +the new scheme does not have the drawback of +growing the dynamic linker search list uncontrollably. +.P +For instance, on x86 64-bit, +if the hardware supports +.B x86_64-v3 +(for instance Intel Haswell or AMD Excavator), +the resulting search path will be +.B glibc-hwcaps/x86-64-v3:glibc-hwcaps/x86-64-v2:. +.\" The x86_64 architectures levels are defined the official ABI: +.\" +.\" The PowerPC and s390x are glibc defined ones based on chip +.\" support (which maps to ISA levels). +The following paths are currently supported, in priority order. +.TP +.B PowerPC (64-bit little-endian only) +power10, power9 +.TP +.B s390 (64-bit only) +z16, z15, z14, z13 +.TP +.B x86 (64-bit only) +x86-64-v4, x86-64-v3, x86-64-v2 +.P +glibc 2.37 removed support for the legacy hardware capabilities. +.\" .SH SEE ALSO .BR ld (1), .BR ldd (1), diff --git a/man8/ldconfig.8 b/man8/ldconfig.8 index 5bbfd86..1b51742 100644 --- a/man8/ldconfig.8 +++ b/man8/ldconfig.8 @@ -5,7 +5,7 @@ .\" .\" Modified, 6 May 2002, Michael Kerrisk, .\" Change listed order of /usr/lib and /lib -.TH ldconfig 8 2023-03-11 "Linux man-pages 6.05.01" +.TH ldconfig 8 2023-10-31 "Linux man-pages 6.7" .SH NAME ldconfig \- configure dynamic linker run-time bindings .SH SYNOPSIS @@ -49,7 +49,7 @@ while and .I /usr/lib64 are used for 64-bit libraries. -.PP +.P The cache is used by the run-time linker, .I ld.so or @@ -63,7 +63,7 @@ determining which versions should have their links updated. .B \%ldconfig should normally be run by the superuser as it may require write permission on some root owned directories and files. -.PP +.P .B \%ldconfig will look only at files that are named .I lib*.so* @@ -78,20 +78,20 @@ like this example, where the middle file .RB ( libfoo.so.1 here) is the SONAME for the library: -.PP +.P .in +4n .EX libfoo.so \-> libfoo.so.1 \-> libfoo.so.1.12 .EE .in -.PP +.P Failure to follow this pattern may result in compatibility issues after an upgrade. .SH OPTIONS .TP -.BI \-c\~ fmt -.TQ .BI \-\-format= fmt +.TQ +.BI \-c\~ fmt (Since glibc 2.2) .\" commit 45eca4d141c047950db48c69c8941163d0a61fcd Use cache format @@ -121,9 +121,9 @@ Use instead of .IR /etc/ld.so.conf . .TP -.B \-i -.TQ .B \-\-ignore\-aux\-cache +.TQ +.B \-i (Since glibc 2.7) .\" commit 27d9ffda17df4d2388687afd12897774fde39bcc Ignore auxiliary cache file. @@ -148,9 +148,9 @@ Unless is also specified, links are still updated. .TP -.B \-p -.TQ .B \-\-print\-cache +.TQ +.B \-p Print the lists of directories and candidate libraries stored in the current cache. .TP @@ -159,18 +159,18 @@ Change to and use .I root as the root directory. .TP -.B \-v -.TQ .B \-\-verbose +.TQ +.B \-v Verbose mode. Print current version number, the name of each directory as it is scanned, and any links that are created. Overrides quiet mode. .TP -.B \-V -.TQ .B \-\-version +.TQ +.B \-V Print program version. .TP .B \-X diff --git a/man8/nscd.8 b/man8/nscd.8 index 1b39b95..3d2204e 100644 --- a/man8/nscd.8 +++ b/man8/nscd.8 @@ -6,7 +6,7 @@ .\" 2008-12-05 Petr Baudis .\" Rewrite the NOTES section to reflect modern reality .\" -.TH nscd 8 2022-10-30 "Linux man-pages 6.05.01" +.TH nscd 8 2023-10-31 "Linux man-pages 6.7" .SH NAME nscd \- name service cache daemon .SH DESCRIPTION @@ -18,7 +18,7 @@ The default configuration file, determines the behavior of the cache daemon. See .BR nscd.conf (5). -.PP +.P .B nscd provides caching for accesses of the .BR passwd (5), @@ -34,7 +34,7 @@ databases through standard libc interfaces, such as .BR getgrgid (3), .BR gethostbyname (3), and others. -.PP +.P There are two caches for each database: a positive one for items found, and a negative one for items not found. @@ -70,7 +70,7 @@ In that case, you need to run the following command after changing the configuration file of the database so that .B nscd invalidates its cache: -.PP +.P .in +4n .EX $ \fBnscd \-i\fP \fI\fP diff --git a/man8/sln.8 b/man8/sln.8 index 81d9078..29d960b 100644 --- a/man8/sln.8 +++ b/man8/sln.8 @@ -2,7 +2,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH sln 8 2023-01-07 "Linux man-pages 6.05.01" +.TH sln 8 2023-10-31 "Linux man-pages 6.7" .SH NAME sln \- create symbolic links .SH SYNOPSIS @@ -20,13 +20,13 @@ program, it is statically linked. This means that if for some reason the dynamic linker is not working, .B sln can be used to make symbolic links to dynamic libraries. -.PP +.P The command line has two forms. In the first form, it creates .I dest as a new symbolic link to .IR source . -.PP +.P In the second form, .I filelist is a list of space-separated pathname pairs, @@ -34,7 +34,7 @@ and the effect is as if .B sln was executed once for each line of the file, with the two pathnames as the arguments. -.PP +.P The .B sln program supports no command-line options. diff --git a/man8/tzselect.8 b/man8/tzselect.8 index 4578090..ee03161 100644 --- a/man8/tzselect.8 +++ b/man8/tzselect.8 @@ -95,7 +95,7 @@ Output version information and exit. .SH "ENVIRONMENT VARIABLES" .TP \f3AWK\fP -Name of a Posix-compliant +Name of a POSIX-compliant .B awk program (default: .BR awk ). diff --git a/man8/zdump.8 b/man8/zdump.8 index f77c0c7..c3f0bba 100644 --- a/man8/zdump.8 +++ b/man8/zdump.8 @@ -152,10 +152,9 @@ tabbed columns line up.) .nf .sp .if \n(.g .ft CR -.if t .in +.5i -.if n .in +2 +.in +2 .nr w \w'1896-01-13 'u+\n(.i -.ta \w'1896-01-13 'u +\w'12:01:26 'u +\w'-103126 'u +\w'HWT 'u +.ta \w'1896-01-13\0\0'u +\w'12:01:26\0\0'u +\w'-103126\0\0'u +\w'HWT\0\0'u TZ="Pacific/Honolulu" - - -103126 LMT 1896-01-13 12:01:26 -1030 HST diff --git a/man8/zic.8 b/man8/zic.8 index c467efe..0ad373a 100644 --- a/man8/zic.8 +++ b/man8/zic.8 @@ -95,7 +95,7 @@ as local time. .B zic will act as if the input contained a link line of the form .sp -.ti +.5i +.ti +2 .ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u Link \fItimezone\fP localtime .sp @@ -118,9 +118,15 @@ TZ strings like "EET\*-2EEST" that lack transition rules. .B zic will act as if the input contained a link line of the form .sp -.ti +.5i +.ti +2 Link \fItimezone\fP posixrules .sp +If +.I timezone +is +.q "\*-" +(the default), any already-existing link is removed. +.sp Unless .I timezone is .q "\*-" , @@ -131,12 +137,6 @@ and it should not be combined with if .IR timezone 's transitions are at standard time or Universal Time (UT) instead of local time. -.sp -If -.I timezone -is -.BR \*- , -any already-existing link is removed. .TP .BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]" Limit the applicability of output files @@ -171,7 +171,7 @@ boundaries, particularly if causes a TZif file to contain explicit entries for .RI pre- hi transitions rather than concisely representing them -with an extended POSIX TZ string. +with an extended POSIX.1-2017 TZ string. Also see the .B "\*-b slim" option for another way to shrink output size. @@ -181,10 +181,10 @@ Generate redundant trailing explicit transitions for timestamps that occur less than .I hi seconds since the Epoch, even though the transitions could be -more concisely represented via the extended POSIX TZ string. +more concisely represented via the extended POSIX.1-2017 TZ string. This option does not affect the represented timestamps. Although it accommodates nonstandard TZif readers -that ignore the extended POSIX TZ string, +that ignore the extended POSIX.1-2017 TZ string, it increases the size of the altered output files. .TP .BI "\*-t " file @@ -245,10 +245,10 @@ for .PP The output file does not contain all the information about the long-term future of a timezone, because the future cannot be summarized as -an extended POSIX TZ string. For example, as of 2023 this problem +an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem occurs for Morocco's daylight-saving rules, as these rules are based on predictions for when Ramadan will be observed, something that -an extended POSIX TZ string cannot represent. +an extended POSIX.1-2017 TZ string cannot represent. .PP The output contains data that may not be handled properly by client code designed for older @@ -330,19 +330,19 @@ abbreviation must be unambiguous in context. .PP A rule line has the form .nf -.ti +.5i +.ti +2 .ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00w\0\0'u +\w'1:00d\0\0'u .sp Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S .sp For example: -.ti +.5i +.ti +2 .sp Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00d D .sp .fi The fields that make up a rule line are: -.TP "\w'LETTER/S'u" +.TP .B NAME Gives the name of the rule set that contains this line. The name must start with a character that is neither @@ -360,24 +360,15 @@ an unquoted name should not contain characters from the set Gives the first year in which the rule applies. Any signed integer year can be supplied; the proleptic Gregorian calendar is assumed, with year 0 preceding year 1. -The word -.B minimum -(or an abbreviation) means the indefinite past. -The word -.B maximum -(or an abbreviation) means the indefinite future. Rules can describe times that are not representable as time values, with the unrepresentable times ignored; this allows rules to be portable among hosts with differing time value types. .TP .B TO Gives the final year in which the rule applies. -In addition to -.B minimum -and +The word .B maximum -(as above), -the word +(or an abbreviation) means the indefinite future, and the word .B only (or an abbreviation) may be used to repeat the value of the @@ -404,7 +395,7 @@ Month names may be abbreviated. Gives the day on which the rule takes effect. Recognized forms include: .nf -.in +.5i +.in +2 .sp .ta \w'Sun<=25\0\0'u 5 the fifth of the month @@ -413,7 +404,7 @@ lastMon the last Monday in the month Sun>=8 first Sunday on or after the eighth Sun<=25 last Sunday on or before the 25th .fi -.in -.5i +.in .sp A weekday name (e.g., .BR "Sunday" ) @@ -440,7 +431,7 @@ Gives the time of day at which the rule takes effect, relative to 00:00, the start of a calendar day. Recognized forms include: .nf -.in +.5i +.in +2 .sp .ta \w'00:19:32.13\0\0'u 2 time in hours @@ -454,7 +445,7 @@ Recognized forms include: \*-2:30 2.5 hours before 00:00 \*- equivalent to 0 .fi -.in -.5i +.in .sp Although .B zic @@ -532,18 +523,18 @@ the variable part is null. A zone line has the form .sp .nf -.ti +.5i +.ti +2 .ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u Zone NAME STDOFF RULES FORMAT [UNTIL] .sp For example: .sp -.ti +.5i +.ti +2 Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00 .sp .fi The fields that make up a zone line are: -.TP "\w'STDOFF'u" +.TP .B NAME The name of the timezone. This is the name used in creating the time conversion information file for the @@ -663,15 +654,15 @@ For example: .br .ne 7 .nf -.in +2m +.in +2 .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\*-\0\0'u +\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u .sp # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S Rule US 1967 2006 - Oct lastSun 2:00 0 S Rule US 1967 1973 - Apr lastSun 2:00 1:00 D -.ta \w'Zone\0\0America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u -# Zone\0\0NAME STDOFF RULES FORMAT [UNTIL] -Zone\0\0America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00 +.ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u +# Zone NAME STDOFF RULES FORMAT [UNTIL] +Zone America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00 \*-6:00 US C%sT .sp .in @@ -687,13 +678,13 @@ interprets this more sensibly as a single transition from 02:00 CST (\*-05) to A link line has the form .sp .nf -.ti +.5i +.ti +2 .ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u Link TARGET LINK-NAME .sp For example: .sp -.ti +.5i +.ti +2 Link Europe/Istanbul Asia/Istanbul .sp .fi @@ -717,7 +708,7 @@ For example: .sp .ne 3 .nf -.in +2m +.in +2 .ta \w'Zone\0\0'u +\w'Greenwich\0\0'u Link Greenwich G_M_T Link Etc/GMT Greenwich @@ -737,13 +728,13 @@ The file that describes leap seconds can have leap lines and an expiration line. Leap lines have the following form: .nf -.ti +.5i +.ti +2 .ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u .sp Leap YEAR MONTH DAY HH:MM:SS CORR R/S .sp For example: -.ti +.5i +.ti +2 .sp Leap 2016 Dec 31 23:59:60 + S .sp @@ -791,13 +782,13 @@ option is used. .PP The expiration line, if present, has the form: .nf -.ti +.5i +.ti +2 .ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u .sp Expires YEAR MONTH DAY HH:MM:SS .sp For example: -.ti +.5i +.ti +2 .sp Expires 2020 Dec 28 00:00:00 .sp @@ -816,7 +807,7 @@ Here is an extended example of .B zic input, intended to illustrate many of its features. .nf -.in +2m +.in +2 .ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u .sp # Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S diff --git a/scripts/FIXME_list.sh b/scripts/FIXME_list.sh index 59ba3c0..cdaef76 100755 --- a/scripts/FIXME_list.sh +++ b/scripts/FIXME_list.sh @@ -9,7 +9,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -23,7 +23,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -40,10 +40,10 @@ while getopts "a" optname; do # Even show FIXMEs that aren't generally interesting. (Typically # these FIXMEs are notes to the maintainer to reverify something # at a future date.) - - show_all="y" + + show_all="y" ;; - + *) echo "Unknown option: $OPTARG" exit 1 ;; @@ -64,15 +64,15 @@ for dir in "$@"; do do cat "$page" | awk -v SHOW_ALL=$show_all -v PAGE_NAME="$page" \ ' - BEGIN { - page_FIXME_cnt = 0; + BEGIN { + page_FIXME_cnt = 0; } - - /FIXME/ { - + + /FIXME/ { + # /.\" FIXME . / ==> do not display this FIXME, unless # -a command-line option was supplied - + if ($0 ~ /^\.\\" FIXME \./ ) FIXME_type = "hidden" else if ($0 ~ /^\.\\" FIXME *\?/ ) @@ -85,26 +85,26 @@ for dir in "$@"; do print PAGE_NAME; } page_FIXME_cnt++; - - finished = 0; - do { - print $0; - - # Implicit end of FIXME is end-of-file or a line + + finished = 0; + do { + print $0; + + # Implicit end of FIXME is end-of-file or a line # that is not a comment - + if (getline == 0) finished = 1; - - if (!($0 ~ /^.\\"/)) + + if (!($0 ~ /^.\\"/)) finished = 1; - + # /.\" .$/ ==> Explicit end of FIXME - - if ($0 ~ /^.\\" \.$/) + + if ($0 ~ /^.\\" \.$/) finished = 1; } while (!finished); - + print ""; } } diff --git a/scripts/LinuxManBook/BuildLinuxMan.pl b/scripts/LinuxManBook/BuildLinuxMan.pl deleted file mode 100755 index 7d96057..0000000 --- a/scripts/LinuxManBook/BuildLinuxMan.pl +++ /dev/null @@ -1,249 +0,0 @@ -#!/usr/bin/perl -w -# -# BuildLinuxMan.pl : Build Linux manpages book -# Deri James : 15 Dec 2022 -# -# Params:- -# -# $1 = Directory holding the man pages -# -# (C) Copyright 2022, Deri James -# -# This program is free software; you can redistribute it and/or -# modify it under the terms of the GNU General Public License -# as published by the Free Software Foundation; either version 2 -# of the License, or (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details -# (http://www.gnu.org/licenses/gpl-2.0.html). -# - -use strict; - -my $dir=shift || '.'; -my @aliases=`egrep -l '^\\.so' $dir/man*/*`; -my %alias; -my %target; -my $inTS=0; -my $inBlock=0; - -my %Sections= -( - "1" => "General Commands Manual", - "2" => "System Calls Manual", - "2type" => "System Calls Manual (types)", - "3" => "Library Functions Manual", - "3const" => "Library Functions Manual (constants)", - "3head" => "Library Functions Manual (headers)", - "3type" => "Library Functions Manual (types)", - "4" => "Kernel Interfaces Manual", - "5" => "File Formats Manual", - "6" => "Games Manual", - "7" => "Miscellaneous Information Manual", - "8" => "System Manager's Manual", - "9" => "Kernel Developer's Manual", -); - -my $Section=''; - -LoadAlias(); -BuildBook(); - -my $cmdstring="-Tpdf -k -pet -M. -F. -mandoc -manmark -dpaper=a4 -P-pa4 -rC1 -rCHECKSTYLE=3"; - -system("groff -Tpdf -ms LMBfront.t -Z > LMBfront.Z"); -system("groff -z -dPDF.EXPORT=1 -dLABEL.REFS=1 T $cmdstring 2>&1 | LC_ALL=C grep '^\\. *ds' | groff -Tpdf $cmdstring - T -Z > LinuxManBook.Z"); -system("./gropdf -F. LMBfront.Z LinuxManBook.Z > LinuxManBook.pdf"); -unlink "LinuxManBook.Z","LMBfront.Z"; # If you want to clean up - -# Aliases are the man pages which .so another man page, so build a hash of them so -# that when we are processing referenced man page we can add the target for the -# bookmark. - -sub LoadAlias -{ - foreach my $fn (@aliases) - { - chomp($fn); - my (@pth)=split('/',$fn); - my $nm=pop(@pth); - my $bkmark="$1_$2" if $nm=~m/(.*)\.(\w+)/; - - if (open(F,"<$fn")) - { - while () - { - next if m/^\.\\"/; - - if (m/^.so\s+(man\w+\/(.+)\.(.+?))$/) - { - $alias{$bkmark}=["$2_$3",$2,$3]; - push(@{$target{"$2_$3"}},$bkmark); - last; - } - else - { - print STDERR "Alias fail: $fn\n"; - } - } - - close(F); - } - else - { - print STDERR "Open fail: $fn\n"; - } - } -} - -sub BuildBook -{ - open(BK,">T"); - - foreach my $fn (sort sortman glob("$dir/man*/*")) - { - my ($nm,$sec,$srt)=GetNmSec($fn); - - my $bkmark="$1_$2" if $nm=~m/(.*)\.(\w+)/; - my $title= "$1\\($2\\)"; - -# If this is an alias, just add it to the outline panel. - - if (exists($alias{$bkmark})) - { - print BK ".eo\n.device ps:exec [/Dest /$alias{$bkmark}->[0] /Title ($title) /Level 2 /OUT pdfmark\n.ec\n"; - print BK ".if dPDF.EXPORT .tm .ds pdf:look($bkmark) $alias{$bkmark}->[1]($alias{$bkmark}->[2])\n"; - next; - } - - print BK ".\\\" >>>>>> $1($2) <<<<<<\n"; - - if (open(F,'<',$fn)) - { - while () - { - if (m/^\.\\"/) - { - print BK $_; - next; - } - - chomp; - -# This code is to determine whether we are within a tbl block and in a text block -# T{ and T}. This is fudge code particularly for the syscalls(7) page. - - $inTS=1 if m/\.TS/; - $inTS=0,$inBlock=0 if m/\.TE/; - - s/\r$//; # In case edited under windows i.e. CR/LF - s/\s+$//; - next if !$_; -# s/^\s+//; - - if (m/^\.BR\s+([-\w\\.]+)\s+\((.+?)\)(.*)/) - { - my $bkmark="$1"; - my $sec=$2; - my $after=$3; - my $dest=$bkmark; - $dest=~s/\\-/-/g; - $_=".MR \"$bkmark\" \"$sec\" \"$after\" \"$dest\""; - } - - s/^\.BI \\fB/.BI /; - s/^\.BR\s+(\S+)\s*$/.B $1/; - s/^\.BI\s+(\S+)\s*$/.B $1/; - s/^\.IR\s+(\S+)\s*$/.I $1/; - -# Fiddling for syscalls(7) :-( - - if ($inTS) - { - my @cols=split(/\t/,$_); - - foreach my $c (@cols) - { - $inBlock+=()=$c=~m/T\{/g; - $inBlock-=()=$c=~m/T\}/g; - - my $mtch=$c=~s/\s*\\fB([-\w.]+)\\fP\((\w+)\)/\n.MR $1 $2 \\c\n/g; - $c="T{\n${c}\nT}" if $mtch and !$inBlock; - } - - $_=join("\t",@cols); - s/\n\n/\n/g; - } - - if (m/^\.TH\s+([-\w\\.]+)\s+(\w+)/) - { - - # if new section add top level bookmark - - if ($sec ne $Section) - { - print BK ".nr PDFOUTLINE.FOLDLEVEL 1\n.fl\n"; - print BK ".pdfbookmark 1 $Sections{$sec}\n"; - print BK ".nr PDFOUTLINE.FOLDLEVEL 2\n"; - $Section=$sec; - } - - print BK "$_\n"; - -# Add a level two bookmark. We don't set it in the TH macro since the name passed -# may be different from the filename, i.e. file = unimplemented.2, TH = UNIMPLEMENTED 2 - - print BK ".pdfbookmark -T $bkmark 2 $1($2)\n"; - -# If this page is referenced by an alias plant a destination label for the alias. - - if (exists($target{$bkmark})) - { - foreach my $targ (@{$target{$bkmark}}) - { - print BK ".pdf*href.set $targ\n"; - } - } - - next; - } - - print BK "$_\n"; - - } - - close(F); - - } - } - - close(BK); -} - -sub GetNmSec -{ - my (@pth)=split('/',shift); - my $nm=pop(@pth); - my $sec=substr(pop(@pth),3); - my $srt=$nm; - $srt=~s/^_+//; - $srt="$sec/$srt"; - return($nm,$sec,$srt); -} - -sub sortman -{ -# Sort - ignore case but frig it so that intro is the first entry. - - my (undef,$s1,$c)=GetNmSec($a); - my (undef,$s2,$d)=GetNmSec($b); - - my $cmp=$s1 cmp $s2; - return $cmp if $cmp; - return -1 if ($c=~m/\/intro/ and $d!~m/\/intro/); - return 1 if ($d=~m/\/intro/ and $c!~m/\/intro/); - return (lc($c) cmp lc($d)); -} diff --git a/scripts/LinuxManBook/LMBfront.roff b/scripts/LinuxManBook/LMBfront.roff new file mode 100644 index 0000000..fdf1a98 --- /dev/null +++ b/scripts/LinuxManBook/LMBfront.roff @@ -0,0 +1,33 @@ +.de Hl +.br +\l'\\n[.l]u-\\n[.i]u\&\\$1' +.br +.. +.ps 10 +.vs 12 +.po 2c +.ll 17c +.sp 2.5c +\Z@\D't 8p'@ +.Hl +\D't 0' +.sp .6i +.ad r +.ps 52 +\m[maroon]GNU/Linux\m[] +.sp 18p +.ps 16 +\f[BMB]THE MAN-PAGES BOOK\fP +.sp 6i +.ps 12 +\f[HB]Maintainers:\fP +.sp 2p +.ps 10 +\f[HB]Alejandro Colomar 2020 - present (5.09 - HEAD) +.brp +Michael Kerrisk 2004 - 2021 (2.00 - 5.13) +.brp +Andries Brouwer 1995 - 2004 (1.6 - 1.70) +.brp +Rik Faith 1993 - 1995 \0(1.0 - 1.5)\fP +.bp diff --git a/scripts/LinuxManBook/LMBfront.t b/scripts/LinuxManBook/LMBfront.t deleted file mode 100644 index c034dd5..0000000 --- a/scripts/LinuxManBook/LMBfront.t +++ /dev/null @@ -1,38 +0,0 @@ -.ig - front.t -.. -.de Hl -.br -\l'\\n[.l]u-\\n[.i]u\&\\$1' -.br -.. -.ps 10 -.vs 12 -.nr PS 10 -.nr VS 12 -.nr SS_prefix 1v -.nr do-page 0 -.Nh 0 0 -.\" .so utp.mac -.\" .utp -\Z@\D't 8p'@ -.Hl -\D't 0' -.sp .6i -.DS R -.ps 52 -\m[maroon]GNU/Linux\m[] -.sp 18p -.ps 16 -\f[BMB]THE MAN-PAGES BOOK\fP -.sp 30p -.sp 1.4i -.ps 12 -\f[HB]Maintainers:\fP -.sp 2p -.ps 10 -\f[HB]Alejandro Colomar 2020 - present (5.09 - HEAD) -Michael Kerrisk 2004 - 2021 (2.00 - 5.13) -Andries Brouwer 1995 - 2004 (1.6 - 1.70) -Rik Faith 1993 - 1995 \0(1.0 - 1.5)\fP -.DE diff --git a/scripts/LinuxManBook/an-ext.tmac b/scripts/LinuxManBook/an-ext.tmac deleted file mode 100644 index e2f5c48..0000000 --- a/scripts/LinuxManBook/an-ext.tmac +++ /dev/null @@ -1,282 +0,0 @@ -.\" groff extension macros for man(7) package -.\" -.\" Copyright (C) 2007-2022 Free Software Foundation, Inc. -.\" -.\" Written by Eric S. Raymond -.\" Werner Lemberg -.\" G. Branden Robinson -.\" -.\" You may freely use, modify and/or distribute this file. -.\" -.\" The code below provides extension macros for the 'man' macro -.\" package. Care has been taken to make the code portable; groff -.\" extensions are properly hidden so that all troff implementations can -.\" use it without changes. -.\" -.\" With groff, this file is sourced by the 'man' macro package itself. -.\" Man page authors who are concerned about portability might add the -.\" used macros directly to the prologue of the man page(s). -. -. -.\" Convention: Auxiliary macros and registers start with 'm' followed -.\" by an uppercase letter or digit. -. -. -.\" Protect against being sourced twice. -.nr mZ +1 -.if \n(mZ>1 \ -. nx -. -.\" Define this to your implementation's constant-width typeface. -.ds mC CW -. -.\" In AT&T troff, there was no register exposing the hyphenation mode, -.\" and no way to save and restore it. Set this to a reasonable value -.\" for your implementation and preference. -.ie !\n(.g \ -. nr mJ 1 -.el \ -. do nr mJ \n[.hy] -. -.\" Check if we're using grohtml or grotty, and therefore support URIs. -.nr mH 0 -.nr mY 0 -.nr mU 0 -.if \n(.g \{\ -. if '\*(.T'html' \ -. nr mH 1 -. if '\*(.T'ascii' \ -. nr mY 1 -. if '\*(.T'cp1047' \ -. nr mY 1 -. if '\*(.T'latin1' \ -. nr mY 1 -. if '\*(.T'utf8' \ -. nr mY 1 -. nr mU \n(mH+\n(mY -.\} -. -. -.\" groff has glyph entities for angle brackets. -.ie \n(.g \{\ -. ds mL \(la\" -. ds mR \(ra\" -.\} -.el \{\ -. ds mL <\" -. ds mR >\" -.\} -. -.nr mS 0 -. -. -.\" Declare start of command synopsis. Sets up hanging indentation. -.de SY -. ie !\\n(mS \{\ -. nh -. nr mS 1 -. nr mA \\n(.j -. ad l -. nr mI \\n(.i -. \} -. el \{\ -. br -. ns -. \} -. -. nr mT \w'\fB\\$1\fP\ ' -. HP \\n(mTu -. B "\\$1" -.. -. -. -.\" End of command synopsis. Restores adjustment. -.de YS -. in \\n(mIu -. ad \\n(mA -. hy \\n(mJ -. nr mS 0 -.. -. -.\" Prepare link text for mail/web hyperlinks. `MT` and `UR` call this. -.de mV -. ds m1 \\$1\" -. \" Save the indentation and line length. We want the diversion to -. \" format as if it has an indentation of zero (that comes for free -. \" when we switch environments), but we want the line length reduced -. \" by the amount of indentation that obtains when we output it. -. nr mK \\n(.l -. nr mI \\n(.i -. \" We can only hyperlink if we're not in a diversion. -. nr mD 0 -. if '\\n(.z'' .nr mD 1 -. if \\n(mD&\\nU&\\n(mU \{\ -. \" Start diversion in a new environment. -. do ev link-text-env -. do di link-text-div -. ll (\\n(mKu-\\n(mIu) -. \} -. rr mK -.. -. -.\" Start URL. -.de UR -. mV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 -.. -. -. -.\" End URL. -.de UE -. ie \\n(mD&\\nU&\\n(mU \{\ -. br -. di -. ev -. -. \" Has there been at least one input line of hyperlinked text? -. ie \\n(dn \{\ -. if \\n(mH \ -\X^html:^\c -. if \\n(mY \ -\X^tty: link \\*(m1^\c -. \" Strip off the final newline of the diversion and emit it. -. do chop link-text-div -. do link-text-div -\c -. if \\n(mH \ -\X^html:^\c -. if \\n(mY \ -\X^tty: link^\c -. \} -. el \{\ -. if \\n(mH \ -\X^html:\\*(m1^\c -. if \\n(mY \ -\X^tty: link \\*(m1^\\*(m1\X^tty: link^\c -. \} -\&\\$*\" -. \} -. el \{\ -. nh -\\*(mL\\*(m1\\*(mR\\$1 -. do shift -. ie \n(.g .if \\n(.$ \&\\$*\" -. el .if \\n(.$>1 \&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\" -. hy \\n(mJ -. \} -. rr mD -.. -. -. -.\" Start email address. -.de MT -. mV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 -.. -. -. -.\" End email address. -.de ME -. ie \\n(mD&\\nU&\\n(mU \{\ -. br -. di -. ev -. -. \" Has there been at least one input line of hyperlinked text? -. ie \\n(dn \{\ -. if \\n(mH \ -\X^html:^\c -. if \\n(mY \ -\X^tty: link mailto:\\*(m1^\c -. \" Strip off the final newline of the diversion and emit it. -. do chop link-text-div -. do link-text-div -\c -. if \\n(mH \ -\X^html:^\c -. if \\n(mY \ -\X^tty: link^\c -. \} -. el \{\ -. if \\n(mH \ -\X^html:\\*(m1^\c -. if \\n(mY \ -\X^tty: link mailto:\\*(m1^\\*(m1\X^tty: link^\c -. \} -\&\\$*\" -. \} -. el \{\ -. nh -\\*(mL\\*(m1\\*(mR\\$1 -. do shift -. ie \n(.g .if \\n(.$ \&\\$*\" -. el .if \\n(.$>1 \&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\" -. hy \\n(mJ -. \} -. rr mD -.. -. -. -.\" Set a man page cross reference. -.\" .MR page-topic page-section [trailing-text] -.if \n(.g .ig -.de MR -. nh -. ie \\n(.$=1 \ -. I \\$1 -. el \ -. IR \\$1 (\\$2)\\$3 -. hy \\n(mJ -.. -. -. -.\" Continuation line for .TP header. -.de TQ -. br -. ns -. TP \\$1\" no doublequotes around argument! -.. -. -. -.\" Start example. -.if \n(.g .ig -.de EX -. br -. if !\\n(mX \{\ -. nr mF \\n(.f -. nr mP \\n(PD -. nr PD 1v -. nf -. ft \\*(mC -. nr mX 1 -. \} -.. -. -. -.\" End example. -.if \n(.g .ig -.de EE -. br -. if \\n(mX \{\ -. ft \\n(mF -. nr PD \\n(mP -. fi -. nr mX 0 -. \} -.. -. -. -.\" Start display. -.de DS -. \" XXX to be written -.. -. -. -.\" End display. -.de DE -. \" XXX to be written -.. -. -.\" Local Variables: -.\" mode: nroff -.\" fill-column: 72 -.\" End: -.\" vim: set filetype=groff textwidth=72: diff --git a/scripts/LinuxManBook/an.tmac b/scripts/LinuxManBook/an.tmac index 298fd8a..26fbef6 100644 --- a/scripts/LinuxManBook/an.tmac +++ b/scripts/LinuxManBook/an.tmac @@ -1,6 +1,6 @@ .\" groff implementation of man(7) package .\" -.\" Copyright (C) 1989-2022 Free Software Foundation, Inc. +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. .\" Written by James Clark (jjc@jclark.com) .\" Enhanced by: Werner Lemberg .\" Larry Kollar @@ -89,7 +89,7 @@ .\" Define alternate requests to handle continuous rendering. .\" .\" This .ne replacement avoids page breaks; instead, the page length is -.\" increased to the necessary amount (this is needed for tables). +.\" increased to the necessary amount. .de an-ne . ie \\n[.$] .nr an-amount (v;\\$*) . el .nr an-amount 1v @@ -128,13 +128,13 @@ . pl +1v . nf . ti 0 -\D'l \\n[LL]u 0' +. nop \D'l \\n[LL]u 0' . fi . \} . \} . rr an-TH-was-called . ch an-header -. bp +. an*break-page-with-new-number .. . .\" Move macros into place for continuous rendering. @@ -176,13 +176,18 @@ . nr an-saved-prevailing-indent1 \\n[IN] .. . -.\" Cause a page transition to a new man(7) document. Clear the page -.\" header trap so it is not sprung with stale information. Update the -.\" page number depending on the C (consecutive numbering) register. -.de an-start-new-document -. ch an-header +.\" Break the page and update its number depending on the C (consecutive +.\" numbering) register. +.\" +.\" Corner case: if formatting multiple documents and P (starting page +.\" number) is defined but C is not set, start numbering each document +.\" at \n[P]. Not strictly necessary if not switching macro packages. +.de an*break-page-with-new-number . ie \\n[C] .bp (\\n[%] + 1) \" argument NOT redundant before page 1 -. el .bp 1 +. el \{\ +. ie r P .bp \\n[P] +. el .bp 1 +. \} .. . .\" Localize manual section titles for English. @@ -197,7 +202,7 @@ . ds an*section8 System Manager's Manual\" . ds an*section9 Kernel Developer's Manual\" .. -.\" Remove '\%' from string used as bookmark destination +. .de an*cln . ds \\$1 . als an*cln:res \\$1 @@ -212,8 +217,9 @@ . .\" Write a bookmark/anchor/link target $2 at hierarchical depth $1. .de an*bookmark -. if '\\*[.T]'pdf' \{\ -. ie (\\$1=2) .pdfbookmark -T "\\*[an*page-ref-bm-nm]" \\$1 \\$2 +. if \\n[an*is-output-pdf] \{\ +. if (\\n[.$]>2) .an*cln an*page-ref-nm \\$3\" +. ie (\\$1=1) .pdfbookmark -T "\\*[an*page-ref-nm]" \\$1 \\$2 . el .pdfbookmark \\$1 \\$2 . \} .. @@ -229,11 +235,15 @@ . . \" If batch processing (rendering multiple) man page documents, we . \" must handle the end of a previous document. -. if !\\n[an-is-first-page-of-document] \{\ -. ie \\n[cR] .an-end -. el .an-start-new-document -. nr an-is-first-page-of-document 1 +. if \\n[an*need-titles-reset] \{\ +. if \\n[cR] .an-end +. +. \" Clear the page header trap so it is not sprung with stale +. \" information. +. ch an-header +. an*break-page-with-new-number . \} +. if \\n[C] .rr P . . nr an-TH-was-called 1 \" an-end can make certain assumptions. . @@ -244,7 +254,7 @@ . fam \\*[an*body-family] . ft R . -. nr PS 10z \" default point size +. nr PS 10z \" default type size . nr PS-SS 10z . nr PS-SH 10.95z . nr VS 12p @@ -351,7 +361,7 @@ . ev . . \" HTML gets the topic without any abbreviation, since it's metadata. -. if \\n[an-is-output-html] \{\ +. if \\n[an*is-output-html] \{\ . DEVTAG-TL . nop \\*[an*topic] . DEVTAG-EO-TL @@ -364,14 +374,15 @@ . . if !\\n[cR] \{\ . wh 0 an-header -. ie r FT .nr an-footer-location \\n[FT] -. el .nr an-footer-location (-.5i) -. wh (2u * \\n[an-footer-location]u) an-break-body-text -. wh \\n[an-footer-location]u an-footer +. ie r FT .nr an*footer-location \\n[FT] +. el .nr an*footer-location (-.5i) +. wh \\n[an*footer-location]u an-footer +. wh (\\n[an*footer-location]u - .5i) an-break-body-text +. rr an*footer-location . \} . \} . -. nr an-is-first-page-of-document 0 +. nr an*need-titles-reset 1 .. . .\" Support legacy AT&T and BSD Unix man pages. @@ -379,7 +390,7 @@ .\" Designate an AT&T Unix man page. .\" .AT [system-id[ release-id]] .de1 AT -\\*[an-deprecation-warn]\\ +. nop \\*[an-deprecation-warn]\\ . ds an-extra2 "7th Edition\" . if "\\$1"3" .ds an-extra2 "7th Edition\" . if "\\$1"4" .ds an-extra2 "System III\" @@ -395,7 +406,7 @@ .\" Designate a BSD Unix man page. .\" .UC [system-id] .de1 UC -\\*[an-deprecation-warn]\\ +. nop \\*[an-deprecation-warn]\\ . ds an-extra2 "3rd Berkeley Distribution\" . if "\\$1"3" .ds an-extra2 "3rd Berkeley Distribution\" . if "\\$1"4" .ds an-extra2 "4th Berkeley Distribution\" @@ -409,15 +420,15 @@ . .\" Restore tab stops to defaults. .de1 DT -\\*[an-deprecation-warn]\\ +. nop \\*[an-deprecation-warn]\\ . an-reset-tab-stops .. . .\" Restore inter-paragraph spacing to default (or set it to argument). .\" .PD [distance] .de1 PD -\\*[an-deprecation-warn]\\ -\\*[an-reset-paragraph-spacing]\\ +. nop \\*[an-deprecation-warn]\\ +. nop \\*[an-reset-paragraph-spacing]\\ .. . .\" Write the page header; can be redefined by man.local. @@ -473,9 +484,9 @@ . while (\\n[an-header-width] >= \\n[.lt]) \{\ . \" The page topic is too long; trim some bits out of the middle. . length an*topic-length \\*[an*topic-string] -. \" roff division rounds integers toward zero. Remove an additional -. \" character on each side of the midpoint to account for the -. \" ellipsis we add later. +. \" roff uses truncating division. Remove an additional character +. \" on each side of the midpoint to account for the ellipsis we add +. \" later. . nr an-mark1 (\\n[an*topic-length] / 2 - 2) . nr an-mark2 (\\n[an*topic-length] / 2 + 2) . ds an-prefix \\*[an*topic-string]\" @@ -706,7 +717,7 @@ contains unsupported escape sequence . if \\n[.$] \{\ . ds an-section-heading \\$*\" . if \\n[CS] .stringup an-section-heading -. an*bookmark 3 \E*[an-section-heading] +. an*bookmark 3 "\\*[an-section-heading]" \&\\*[an-section-heading] . \} . if \\n[an-remap-I-style-in-headings] .ftr I I @@ -732,7 +743,7 @@ contains unsupported escape sequence . if \\n[an-remap-I-style-in-headings] .ftr I \\*[an-heading-family]BI . if \\n[.$] \{\ . ds an*subsection-heading \\$*\" -. an*bookmark 4 \E*[an*subsection-heading] +. an*bookmark 4 "\\*[an*subsection-heading]" . nop \&\\$* . \} . if \\n[an-remap-I-style-in-headings] .ftr I I @@ -763,8 +774,7 @@ contains unsupported escape sequence .. . .\" Set arguments (or next input line producing written or drawn output -.\" if none) in bold style at smaller -.\" type size. +.\" if none) in bold style at smaller type size. .de1 SB . it 1 an-input-trap . ps -1 @@ -810,7 +820,7 @@ contains unsupported escape sequence . el \{\ . ie (\\n[.$] > 1) .TP "\\$2" . el .TP -\&\\$1 +. nop \&\\$1 . \} .. . @@ -831,11 +841,11 @@ contains unsupported escape sequence .\" .\" Implementation notes: .\" -.\" We always emit a non-printing input break \& before the first -.\" argument. This is necessary only when the calling man page is in -.\" compatibility mode; it works around the surprising AT&T semantics of -.\" \f escapes at the beginning of an input line. See "Implementation -.\" differences" in groff_diff(7) or the groff Texinfo manual. +.\" We always emit a dummy character \& before the first argument. This +.\" is necessary only when the calling man page is in compatibility +.\" mode; it works around the surprising AT&T semantics of \f escapes at +.\" the beginning of an input line. See "Implementation differences" in +.\" groff_diff(7) or the groff Texinfo manual. .\" .\" The italic correction escapes can be visually confusing. We apply .\" the following rules, always on the same input line. @@ -868,7 +878,7 @@ contains unsupported escape sequence . shift 2 . \} . if \\n[.$] .as an-result \f[B]\\$1\" -\\*[an-result] +. nop \\*[an-result] . rm an-result . ft R . \} @@ -885,7 +895,7 @@ contains unsupported escape sequence . shift 2 . \} . if \\n[.$] .as an-result \f[B]\\$1\" -\\*[an-result] +. nop \\*[an-result] . rm an-result . ft R . \} @@ -902,7 +912,7 @@ contains unsupported escape sequence . shift 2 . \} . if \\n[.$] .as an-result \,\f[I]\\$1\/\" -\\*[an-result] +. nop \\*[an-result] . rm an-result . ft R . \} @@ -919,7 +929,7 @@ contains unsupported escape sequence . shift 2 . \} . if \\n[.$] .as an-result \,\f[I]\\$1\/\" -\\*[an-result] +. nop \\*[an-result] . rm an-result . ft R . \} @@ -936,7 +946,7 @@ contains unsupported escape sequence . shift 2 . \} . if \\n[.$] .as an-result \f[R]\\$1\" -\\*[an-result] +. nop \\*[an-result] . rm an-result . ft R . \} @@ -953,14 +963,14 @@ contains unsupported escape sequence . shift 2 . \} . if \\n[.$] .as an-result \f[R]\\$1\" -\\*[an-result] +. nop \\*[an-result] . rm an-result . ft R . \} .. . .\" Start a relative inset level (by the amount given in the argument). -.\" .RS [indent] +.\" .RS [inset-amount] .de1 RS . nr an-saved-margin\\n[an-inset-level] \\n[an-margin] . nr an-saved-prevailing-indent\\n[an-inset-level] \ @@ -1004,7 +1014,7 @@ contains unsupported escape sequence .\" specified) for a command synopsis. .\" .OP flag [option-parameter] .de1 OP -\\*[an-deprecation-warn]\\ +. nop \\*[an-deprecation-warn]\\ . if ((\\n[.$] < 1) : (\\n[.$] > 2)) \ . an-style-warn .\\$0 expects 1 or 2 arguments, got \\n[.$] . ie (\\n[.$] > 1) \ @@ -1063,26 +1073,163 @@ contains unsupported escape sequence . nr an*is-in-example 0 .. . +.\" Store the argument and begin a diversion for link text. +.de an*begin-hyperlink +. ds an*hyperlink \\$1\" +. \" We want the diversion to format as if it has an indentation of +. \" zero (that comes for free when we switch environments), and we +. \" want the line length reduced by the amount of indentation that +. \" obtains when we output it. +. nr an*saved-line-length \\n[.l] +. nr an*saved-indentation \\n[.i] +. \" We can only hyperlink if we're not in a diversion. +. \" XXX: There's no fundamental reason for that, just a simple matter +. \" of macro programming. +. nr an*is-in-link-text-diversion 0 +. if '\\n(.z'' .nr an*is-in-link-text-diversion 1 +. if (\\n[an*is-in-link-text-diversion] & \\n[an*do-hyperlink]) \{\ +. \" Start diversion in a new environment. +. ev an*link-text-env +. di an*link-text-div +. ll (\\n[an*saved-line-length]u - \\n[an*saved-indentation]u) +. \} +. rr an*saved-indentation +. rr an*saved-line-length +.. +. +.\" Emit hyperlinked text with optional trailing text. +.\" +.\" The caller should set the `an*prefix` string if the hyperlink should +.\" be prefixed with a scheme; for example, email addresses get +.\" "mailto:", but this need not be visible when rendering an email +.\" address on a device incapable of hyperlinking. +.de an*end-hyperlink +. ie (\\n[an*is-in-link-text-diversion] & \\n[an*do-hyperlink]) \{\ +. br +. di +. ev +. +. \" Was any link text present? +. ie \\n[dn] \{\ +. if \\n[an*is-output-html] \ +. nop \X^html:^\c +. if \\n[an*is-output-terminal] \ +. nop \X^tty: link \\*[an*prefix]\\*[an*hyperlink]^\c +. \" Strip off the final newline of the diversion and emit it. +. chop an*link-text-div +. an*link-text-div +\c\" XXX: If we .nop this, HTML output is corrupted (Savannah #63470). +. if \\n[an*is-output-html] \ +. nop \X^html:^\c +. if \\n[an*is-output-terminal] \ +. nop \X^tty: link^\c +. \} +. \" If there was no link text, format URI as its own link text. We +. \" don't add angle brackets here. +. el \{\ +. if \\n[an*is-output-html] \ +. nop \X^html:\ +\\*[an*hyperlink]^\c +. if \\n[an*is-output-terminal] \ +. nop \X^tty: link \\*[an*prefix]\\*[an*hyperlink]^\ +\\*[an*hyperlink]\X^tty: link^\c +. \} +. nop \&\\$1\" +. \} +. \" If not hyperlinking, format URI in angle brackets. There was no +. \" diversion, so the link text has already been formatted normally. +. el \{\ +. nh +. nop \\[la]\\*[an*hyperlink]\\[ra]\\$1 +. hy \\n[an*hyphenation-mode] +. \} +. +. rr an*is-in-link-text-diversion +.. +. +.\" Begin email hyperlink. Input until the next `ME` call is stored in +.\" a diversion; it becomes the link text for the hyperlinked address. +.\" .MT nobody@example.com +.de1 MT +. if !(\\n[.$] = 1) \ +. an-style-warn .\\$0 expects 1 argument, got \\n[.$] +. ds an*prefix mailto: +. an*begin-hyperlink \\$1 +.. +. +.\" End email hyperlink. The optional argument supplies trailing +.\" punctuation (or, rarely, other text) after link text. +.\" .ME [trailing-text] +.de1 ME +. an*end-hyperlink \\$1 +. rm an*prefix +.. +. +.\" Begin web hyperlink. Input until the next `UE` call is stored in +.\" a diversion; it becomes the link text for the hyperlinked address. +.\" .UR nobody@example.com +.de1 UR +. if !(\\n[.$] = 1) \ +. an-style-warn .\\$0 expects 1 argument, got \\n[.$] +. ds an*prefix \" empty +. an*begin-hyperlink \\$1 +.. +. +.\" End web hyperlink. The optional argument supplies trailing +.\" punctuation (or, rarely, other text) after link text. +.\" .UE [trailing-text] +.de1 UE +. an*end-hyperlink \\$1 +. rm an*prefix +.. +. +.\" There is no standardized format for man page URLs, but the default +.\" is expected to work (or be harmlessly ignored) everywhere except +.\" macOS. Override in man.local if desired. +.nr an*MR-URL-format 1 +. .\" Set a man page cross reference. .\" .MR page-topic page-section [trailing-text] .de1 MR -. if ((\\n[.$] < 2) : (\\n[.$] > 3)) \ -. an-style-warn .\\$0 expects 2 or 3 arguments, got \\n[.$] -. nh -. if (\\n[U] & \\n[mU]) \{\ -. if \\n(mH \ -\X^html:^\c -. if \\n(mY \ -\X^tty: link man:\\$1(\\$2)^\c +. if ((\\n[.$] < 2) : (\\n[.$] > 4)) \ +. an-style-warn .\\$0 expects 2 to 4 arguments, got \\n[.$] +. ie \\n[an*is-output-pdf] \{\ +. nh +. ds an*title \\\\$4 +. if '\\\\*[an*title]'' .ds an*title \\\\$1 +. ie \\n(.$=1 \ +. I \\$1 +. el \{\ +. an*cln an*page-ref-nm \\*[an*title]_\\$2 +. ie d pdf:look(\\*[an*page-ref-nm]) .pdfhref L -D \\*[an*page-ref-nm] -A "\\$3" -- \fI\\$1\fP(\\$2) +. el .IR \\$1 (\\$2)\\$3 +. \} +. hy \\n(mJ . \} -\&\\*[an-lic]\f[\\*[MF]]\\$1\\*[an-ic]\f[R](\\$2)\c -. if (\\n[U] & \\n[mU]) \{\ -. if \\n(mH \ -\X^html:^\c -. if \\n(mY \ -\X^tty: link^\c +. el \{\ +. ds an*url man:\\$1(\\$2)\" used everywhere but macOS +. if (\\n[an*MR-URL-format] = 2) \ +. ds an*url x-man-page://\\$2/\\$1\" macOS/Mac OS X since 10.3 +. if (\\n[an*MR-URL-format] = 3) \ +. ds an*url man:\\$1.\\$2\" Bwana (Mac OS X) +. if (\\n[an*MR-URL-format] = 4) \ +. ds an*url x-man-doc://\\$2/\\$1\" ManOpen (Mac OS X pre-2005) +. nh +. if \\n[an*do-hyperlink] \{\ +. if \\n[an*is-output-html] \ +. nop \X^html:^\c +. if \\n[an*is-output-terminal] \ +. nop \X^tty: link \\*[an*url]^\c +. \} +. nop \&\\*[an-lic]\f[\\*[MF]]\\$1\\*[an-ic]\f[R](\\$2)\c +. if \\n[an*do-hyperlink] \{\ +. if \\n[an*is-output-html] \ +. nop \X^html:^\c +. if \\n[an*is-output-terminal] \ +. nop \X^tty: link^\c +. \} +. nop \&\\$3 . \} -\&\\$3 . hy \\n[an*hyphenation-mode] .. . @@ -1093,7 +1240,7 @@ contains unsupported escape sequence . \" If continuous rendering, tell tbl not to use keeps. . ie \\n[cR] .nr 3usekeeps 0 . el .nr 3usekeeps 1 -. if \\n[an-is-output-html] \{\ +. if \\n[an*is-output-html] \{\ . nr an-TS-ll \\n[.l] . ll 1000n . \} @@ -1107,7 +1254,7 @@ contains unsupported escape sequence .\" End table. .de1 TE . HTML-IMAGE-END -. if \\n[an-is-output-html] .ll \\n[an-TS-ll]u +. if \\n[an*is-output-html] .ll \\n[an-TS-ll]u . if !r TW .if !\\n[an-was-tbl-failure-reported] \{\ . ds an-msg tbl preprocessor failed, or it or soelim was not run;\" . as an-msg " table(s) likely not rendered\" @@ -1122,7 +1269,7 @@ contains unsupported escape sequence . .\" Start equation. .de1 EQ -. if \\n[an-is-output-html] \{\ +. if \\n[an*is-output-html] \{\ . nr an-EQ-ll \\n[.l] . ll 1000n . \} @@ -1132,32 +1279,17 @@ contains unsupported escape sequence .\" End equation. .de1 EN . HTML-IMAGE-END -. if \\n[an-is-output-html] .ll \\n[an-EQ-ll]u +. if \\n[an*is-output-html] .ll \\n[an-EQ-ll]u .. . -.\" Define R "string". Some ms(7) veterans confusedly use '.R' in man -.\" pages to try to switch to the roman font style. Attempt to catch -.\" this misuse by checking for arguments and warning about it. -.de1 R -\c -. ie \\n[.$] \{\ -. ds an-msg 'R' is a string (producing the registered sign),\" -. as an-msg " not a macro\" -. an-warn \\*[an-msg] -. rm an-msg -. nop \\$* -. \} -. el \{\ -. ie c\[rg] .nop \[rg]\c -. el .nop (Reg.)\c -. \} -.. . .\" === Define strings. === .\" .\" These strings must work in compatibility mode also. . .ds S \s'\\n(PSu'\" +.ie c\[rg] .ds R \(rg\" +.el .ds R (Reg.)\" .ie c\[tm] .ds Tm \(tm\" .el .ds Tm (TM)\" .ie c\[lq] .ds lq \(lq\" @@ -1178,12 +1310,28 @@ contains unsupported escape sequence .nr an-devtag-needs-end-of-heading 0 .nr an-devtag-needs-second-column 0 . -.nr an-is-first-page-of-document 1 -. -.nr an-is-output-html 0 -.if '\*[.T]'html' .nr an-is-output-html 1 -. -.ds an*body-family T \" Times +.\" Track whether the strings that set header and footer text need to be +.\" reconfigured. This happens when batch-rendering and starting a new +.\" page. +.nr an*need-titles-reset 0 +. +.nr an*is-output-html 0 +.if '\*[.T]'html' .nr an*is-output-html 1 +.nr an*is-output-pdf 0 +.if '\*[.T]'pdf' .nr an*is-output-pdf 1 +.nr an*is-output-terminal 0 +.if '\*(.T'ascii' .nr an*is-output-terminal 1 +.if '\*(.T'cp1047' .nr an*is-output-terminal 1 +.if '\*(.T'latin1' .nr an*is-output-terminal 1 +.if '\*(.T'utf8' .nr an*is-output-terminal 1 +. +.nr an*can-hyperlink 0 +.if ( \n[an*is-output-html] \ + : \n[an*is-output-pdf] \ + : \n[an*is-output-terminal]) \ +. nr an*can-hyperlink 1 +. +.ds an*body-family \n[.fam] \" Times .ds an*example-family C \" Courier . .\" Map monospaced fonts to standard styles for groff's nroff devices. @@ -1194,6 +1342,10 @@ contains unsupported escape sequence . ftr CBI BI .\} . +.\" undocumented register; unset to test an-ext.tmac extension macros +.if !r mG \ +. nr mG 1 +. .\" Load man macro extensions. .mso an-ext.tmac . @@ -1203,7 +1355,7 @@ contains unsupported escape sequence .\" Set each rendering parameter only if its -[dr] option or man.local .\" did not. . -.if '\*[.T]'pdf' \{\ +.if \n[an*is-output-pdf] \{\ . \" FIXME: The following registers are documented only in pdf.tmac. . if !r PDFOUTLINE.FOLDLEVEL .nr PDFOUTLINE.FOLDLEVEL 1 . if !r PDFHREF.VIEW.LEADING .nr PDFHREF.VIEW.LEADING 10p @@ -1225,11 +1377,11 @@ contains unsupported escape sequence . nr C 0 .el \ . if !\n[C] \ -. if \n[an-is-output-html] \{\ +. if \n[an*is-output-html] \{\ . tm \*[an]: consecutive page numbering required for HTML output . nr C 1 . \} -.if \n[an-is-output-html] \ +.if \n[an*is-output-html] \ . nr C 1 .if r ps4html \ . nr C 1 @@ -1251,7 +1403,7 @@ contains unsupported escape sequence . nr D 0 .el \ . if \n[D] \ -. if \n[an-is-output-html] \{\ +. if \n[an*is-output-html] \{\ . tm \*[an]: ignoring double-sided layout in HTML output . nr D 0 . \} @@ -1269,14 +1421,22 @@ contains unsupported escape sequence . ie \n[cR] \ . ds an-msg footer distance when continuously rendering\" . el \{\ +. nr an*tmp 1v +. ds an*help " (1v=\n[an*tmp]u)\" . ie (\n[FT] : (\n[FT] = 0)) \ -. ds an-msg non-negative footer distance: \n[FT]u\" +. ds an-msg non-negative footer distance: \n[FT]u\*[an*help]\" . el \{\ -. ie (-(\n[FT]) > (\n[.p] / 2)) \ -. ds an-msg implausibly large footer distance: \n[FT]u\" +. ie (-(\n[FT]) > (\n[.p] / 2)) \{\ +. ds an-msg implausibly large footer distance:\" +. as an-msg " \n[FT]u\*[an*help]\" +. \} . el \ -. if ((v;\n[FT]) < 1v) \ -. ds an-msg implausibly small footer distance: \n[FT]u\" +. if (-(\n[FT]) < 1v) \{\ +. ds an-msg implausibly small footer distance:\" +. as an-msg " \n[FT]u\*[an*help]\" +. \} +. rm an*help +. rr an*tmp . \} . \} . if d an-msg \{\ @@ -1319,7 +1479,7 @@ contains unsupported escape sequence .\" internal purposes like image embedding. Page numbers are not .\" rendered at all in continuous rendering mode. .if r P \{\ -. if \n[an-is-output-html] \ +. if \n[an*is-output-html] \ . if !(\n[P] = 1) \ . ds an-msg in HTML output\" . if \n[cR] \ @@ -1331,11 +1491,32 @@ contains unsupported escape sequence . rm an-msg .\} . -.if !r ps4html \ -. if r P \ -. pn 0\n[P] +.\" Setting the page number turns out to be tricky when batch rendering +.\" and switching macro packages. We must use different techniques +.\" depending on whether the transition to the first output page has +.\" happened yet. If it has not, `nl` will be `-1` and we use `pn`. If +.\" it has, we set `%`. Technically this is fragile since in theory a +.\" page could assign a negative value to `nl`. We might then be +.\" justified in saying they've broken the macro package and they get to +.\" keep both pieces. But if not, consider using a nonce register, +.\" initially set but then permanently cleared adjacent to this logic, +.\" and whose state is shared with mdoc (and andoc.tmac, if necessary). +.\" +.\" Also, we can't use the `P` register with grohtml at all. +.ie r ps4html \{\ +. if r P \{\ +. tm \*[an]: ignoring starting page number in HTML output +. rr P +. \} +.\} +.el \{\ +. if r P \{\ +. ie (\n[nl] = -1) .pn 0\n[P] +. el .nr % 0\n[P] +. \} +.\} . -.\" point size +.\" type size .if !r S \{\ . nr S 10 . if '\*[.T]'X75-12' \ @@ -1348,10 +1529,13 @@ contains unsupported escape sequence .if !r SN \ . nr SN 3n . -.\" URI enablement +.\" URI enablement desired .if !r U \ . nr U 1 . +.nr an*do-hyperlink 0 +.if (\n[U] & \n[an*can-hyperlink]) .nr an*do-hyperlink 1 +. .\" page number after which to apply letter suffixes .\" .\" Unlike most of these parameters, we do not set a default for X; only @@ -1359,7 +1543,7 @@ contains unsupported escape sequence .\" in continuous rendering mode. .if r X \{\ . af an-page-letter a -. if \n[an-is-output-html] \ +. if \n[an*is-output-html] \ . ds an-msg in HTML output\" . if \n[cR] \ . ds an-msg when continuously rendering @@ -1414,7 +1598,7 @@ contains unsupported escape sequence . .\" If rendering HTML, suppress headers and footers. .nr an-suppress-header-and-footer 0 -.if \n[an-is-output-html] .nr an-suppress-header-and-footer 1 +.if \n[an*is-output-html] .nr an-suppress-header-and-footer 1 .if r ps4html .nr an-suppress-header-and-footer 1 . .cp \n[*groff_an_tmac_C] diff --git a/scripts/LinuxManBook/andoc.tmac b/scripts/LinuxManBook/andoc.tmac deleted file mode 100644 index 8a3d61d..0000000 --- a/scripts/LinuxManBook/andoc.tmac +++ /dev/null @@ -1,114 +0,0 @@ -.\" andoc.tmac -.\" -.\" Load either an.tmac or doc.tmac. Multiple man pages can be handled. -.\" -.\" -.\" Copyright (C) 1991-2020 Free Software Foundation, Inc. -.\" Written by Werner Lemberg (wl@gnu.org), -.\" based on a patch from Tadziu Hoffmann. -.\" -.\" This file is part of groff. -.\" -.\" groff is free software; you can redistribute it and/or modify it -.\" under the terms of the GNU General Public License as published by -.\" the Free Software Foundation, either version 3 of the License, or -.\" (at your option) any later version. -.\" -.\" groff is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public -.\" License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program. If not, see -.\" . -.\" -. -.if !\n(.g \ -. ab andoc.tmac: macros require groff extensions; aborting -. -.do nr *groff_andoc_tmac_C \n[.cp] -.cp 0 -. -.als andoc-em em -.als andoc-bp bp -.als andoc-ne ne -. -. -.\" We must not use '.de1' for 'reload-doc' or 'reload-man'! 'doc.tmac' -.\" unconditionally switches compatibility mode off, but '.de1' would -.\" ignore this, restoring the mode that was active before. Similarly, -.\" we have to switch back to the original compatibility mode for man -.\" documents in case there is a mix of mdoc and man input files. -.\" -.\" Due to a bug in GNU troff it necessary to have a no-op line between -.\" '.do' and '\*'. -. -. -.de reload-doc -. \" Flush any partially collected output line and write page footer in -. \" continuous rendering mode. -. do if d an-end \ -. do an-end -. -. \" Remove traps planted by an.tmac. -. do ch an-header -. do ch an-break-body-text -. do ch an-footer -. -. do als em andoc-em -. do als bp andoc-bp -. do als ne andoc-ne -. do blm \" no blank line trap -. do lsm \" no leading space trap -. em \" no end-of-input trap -. -. do rm Dd \" force reinitialization of doc.tmac -. do mso doc.tmac -. -. do als TH reload-man -. -\\*(Dd\\ -.. -. -.de reload-man -. \" Flush any partially collected output line and write page footer in -. \" continuous rendering mode. -. do if d doc-end-macro \ -. do doc-end-macro -. -. \" Remove traps planted by mdoc/doc-{n,dit}roff. -. do ch doc-header -. do ch doc-footer -. -. do als em andoc-em -. do als bp andoc-bp -. do als ne andoc-ne -. do blm \" no blank line trap -. em \" no end-of-input trap -. -. do rm TH \" force reinitialization of an.tmac -. do mso an.tmac -. -. do als Dd reload-doc -. -\\*(TH\\ -.. -. -.als TH reload-man -.als Dd reload-doc -. -.\" dummy equation macros -- eqnrc is read before .TH or .Dd is parsed -.de EQ -.. -.de EN -.. -. -.cp \n[*groff_andoc_tmac_C] -.do rr *groff_andoc_tmac_C -. -.\" Local Variables: -.\" mode: nroff -.\" fill-column: 72 -.\" End: -.\" vim: set filetype=groff textwidth=72: diff --git a/scripts/LinuxManBook/anmark.tmac b/scripts/LinuxManBook/anmark.tmac deleted file mode 100644 index 95e9459..0000000 --- a/scripts/LinuxManBook/anmark.tmac +++ /dev/null @@ -1,22 +0,0 @@ -.nr PDFOUTLINE.FOLDLEVEL 1 -.defcolor pdf:href.colour rgb 0.00 0.25 0.75 -.pdfinfo /Title "The Linux man-pages Book" -.special S TINOR -.de EnD -.. -.am reload-man -.de MR EnD -. nh -. ds an*title \\\\$4 -. if '\\\\*[an*title]'' .ds an*title \\\\$1 -. an*cln an*par "\\\\*[an*title]_\\\\$2\" -. ie \\\\n(.$=1 \ -. I \\\\$1 -. el \{\ -. ie d pdf:look(\\\\*[an*par]) .pdfhref L -D \\\\*[an*par] -A "\\\\$3" -- \fI\\\\$1\fP(\\\\$2) -. el .IR \\\\$1 (\\\\$2)\\\\$3 -. \} -. hy \\\\n(mJ -.EnD -.. -. diff --git a/scripts/LinuxManBook/build.sh b/scripts/LinuxManBook/build.sh new file mode 100755 index 0000000..fcb8b83 --- /dev/null +++ b/scripts/LinuxManBook/build.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env -Sbash +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: GPL-3.0-or-later + + +test -v CAT || CAT=cat; +test -v PRECONV || PRECONV=preconv; +test -v PIC || PIC=pic; +test -v TBL || TBL=tbl; +test -v EQN || EQN=eqn; +test -v TROFF || TROFF=troff; +test -v GROPDF || GROPDF=gropdf; + + +( + $CAT "$(dirname "$0")"/LMBfront.roff; + $CAT "$(dirname "$0")"/an.tmac; + "$(dirname "$0")"/prepare.pl "$1"; +) \ +| $PRECONV \ +| $PIC \ +| $TBL \ +| $EQN -Tpdf \ +| $TROFF -Tpdf -F"$(dirname "$0")" -dpaper=a4 \ +| $GROPDF -F"$(dirname "$0")" -pa4; diff --git a/scripts/LinuxManBook/en.tmac b/scripts/LinuxManBook/en.tmac deleted file mode 100644 index 441ca29..0000000 --- a/scripts/LinuxManBook/en.tmac +++ /dev/null @@ -1,77 +0,0 @@ -.\" English localization for groff -.\" -.\" Copyright (C) 2021-2022 Free Software Foundation, Inc. -.\" Written by G. Branden Robinson -.\" -.\" This file is part of groff. -.\" -.\" groff is free software; you can redistribute it and/or modify it -.\" under the terms of the GNU General Public License as published by -.\" the Free Software Foundation, either version 3 of the License, or -.\" (at your option) any later version. -.\" -.\" groff is distributed in the hope that it will be useful, but WITHOUT -.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public -.\" License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program. If not, see -.\" . -.\" -.\" Please send comments to groff@gnu.org. -. -.do nr *groff_en_tmac_C \n[.cp] -.cp 0 -. -. -.\" If changing from an existing locale, we need to preserve the state -.\" of the "suppress hyphenation before a page location trap" bit. -.nr locale*use-trap-hyphenation-mode 0 -.if d locale \ -. if \n[.hy]=\n[\*[locale]*hyphenation-mode-trap] \ -. nr locale*use-trap-hyphenation-mode 1 -. -. -.ds locale english\" -. -.ss 12 -. -.\" Set up hyphenation. -. -.\" English hyphenation (\lefthyphenmin=2, \righthyphenmin=3) -.nr \*[locale]*hyphenation-mode-base 4 -.nr \*[locale]*hyphenation-mode-trap 6 -. -.ie \n[locale*use-trap-hyphenation-mode] \ -. hy \n[\*[locale]*hyphenation-mode-trap] -.el \ -. hy \n[\*[locale]*hyphenation-mode-base] -. -.rr locale*use-trap-hyphenation-mode -. -.hla en -.hpf hyphen.en -.hpfa hyphenex.en -. -. -.\" man package -.if d an \ -. an*reset-hyphenation-mode -. -. -.\" me package -.if d @R \{\ -. ds _td_format \\*(mo \\n(dy, \\n(y4\" -. ld -.\} -. -. -.cp \n[*groff_en_tmac_C] -.do rr *groff_en_tmac_C -. -.\" Local Variables: -.\" mode: nroff -.\" fill-column: 72 -.\" End: -.\" vim: set filetype=groff textwidth=72: diff --git a/scripts/LinuxManBook/gropdf b/scripts/LinuxManBook/gropdf deleted file mode 100755 index 8474e58..0000000 --- a/scripts/LinuxManBook/gropdf +++ /dev/null @@ -1,3710 +0,0 @@ -#!/bin/perl -w -# -# gropdf : PDF post processor for groff -# -# Copyright (C) 2011-2018 Free Software Foundation, Inc. -# Written by Deri James (and KUBO Koichi) -# - -# This file is part of groff. -# -# groff is free software; you can redistribute it and/or modify it under -# the terms of the GNU General Public License as published by the Free -# Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# groff is distributed in the hope that it will be useful, but WITHOUT ANY -# WARRANTY; without even the implied warranty of MERCHANTABILITY or -# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -# for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -use strict; -use Getopt::Long qw(:config bundling); -use Encode; - -my $use_suppl_font = 1; -my $use_unicode_bookmark = 1; - -use constant -{ - WIDTH => 0, - CHRCODE => 1, - PSNAME => 2, - ASSIGNED => 3, - USED => 4, - SUPPL => 5, -}; - -my $gotzlib=0; - -my $rc = eval -{ - require Compress::Zlib; - Compress::Zlib->import(); - 1; -}; - -if($rc) -{ - $gotzlib=1; -} -else -{ - Msg(0,"Perl module Compress::Zlib not available - cannot compress this pdf"); -} - -my %cfg; - -$cfg{GROFF_VERSION}='1.22.4'; -$cfg{GROFF_FONT_PATH}='/usr/share/groff/site-font:/usr/share/groff/1.22.4/font:/usr/lib/font'; -$cfg{RT_SEP}=':'; -binmode(STDOUT); - -my @obj; # Array of PDF objects -my $objct=0; # Count of Objects -my $fct=0; # Output count -my %fnt; # Used fonts -my $lct=0; # Input Line Count -my $src_name=''; -my %env; # Current environment -my %fontlst; # Fonts Loaded -my $rot=0; # Portrait -my %desc; # Contents of DESC -my %download; # Contents of downlopad file -my $pages; # Pointer to /Pages object -my $devnm='devpdf'; -my $cpage; # Pointer to current pages -my $cpageno=0; # Object no of current page -my $cat; # Pointer to catalogue -my $dests; # Pointer to Dests -my @mediabox=(0,0,595,842); -my @defaultmb=(0,0,595,842); -my $stream=''; # Current Text/Graphics stream -my $cftsz=10; # Current font sz -my $cft; # Current Font -my $cftsup=0; # Current Font (supplemental) -my $lwidth=1; # current linewidth -my $linecap=1; -my $linejoin=1; -my $textcol=''; # Current groff text -my $fillcol=''; # Current groff fill -my $curfill=''; # Current PDF fill -my $strkcol=''; -my $curstrk=''; -my @lin=(); # Array holding current line of text -my @ahead=(); # Buffer used to hol the next line -my $mode='g'; # Graphic (g) or Text (t) mode; -my $xpos=0; # Current X position -my $ypos=0; # Current Y position -my $tmxpos=0; -my $kernadjust=0; -my $curkern=0; -my $widtbl; # Pointer to width table for current font size -my $origwidtbl; # Pointer to width table -my $krntbl; # Pointer to kern table -my $matrix="1 0 0 1"; -my $whtsz; # Current width of a space -my $poschg=0; # V/H pending -my $fontchg=0; # font change pending -my $tnum=2; # flatness of B-Spline curve -my $tden=3; # flatness of B-Spline curve -my $linewidth=40; -my $w_flg=0; -my $nomove=0; -my $pendmv=0; -my $gotT=0; -my $suppress=0; # Suppress processing? -my %incfil; # Included Files -my @outlev=([0,undef,0,0]); # Structure pdfmark /OUT entries -my $curoutlev=\@outlev; -my $curoutlevno=0; # Growth point for @curoutlev -my $Foundry=''; -my $xrev=0; # Reverse x direction of font -my $matrixchg=0; -my $wt=-1; -my $thislev=1; -my $mark=undef; -my $suspendmark=undef; - - - -my $n_flg=1; -my $pginsert=-1; # Growth point for kids array -my %pgnames; # 'names' of pages for switchtopage -my @outlines=(); # State of Bookmark Outlines at end of each page -my $custompaper=0; # Has there been an X papersize -my $textenccmap=''; # CMap for groff text.enc encoding -my @XOstream=(); -my @PageAnnots={}; -my $noslide=0; -my $transition={PAGE => {Type => '/Trans', S => '', D => 1, Dm => '/H', M => '/I', Di => 0, SS => 1.0, B => 0}, - BLOCK => {Type => '/Trans', S => '', D => 1, Dm => '/H', M => '/I', Di => 0, SS => 1.0, B => 0}}; -my $firstpause=0; -my $present=0; - -$noslide=1 if exists($ENV{GROPDF_NOSLIDE}) and $ENV{GROPDF_NOSLIDE}; - -my %ppsz=( 'ledger'=>[1224,792], - 'legal'=>[612,1008], - 'letter'=>[612,792], - 'a0'=>[2384,3370], - 'a1'=>[1684,2384], - 'a2'=>[1191,1684], - 'a3'=>[842,1191], - 'a4'=>[595,842], - 'a5'=>[420,595], - 'a6'=>[297,420], - 'a7'=>[210,297], - 'a8'=>[148,210], - 'a9'=>[105,148], - 'a10'=>[73,105], - 'isob0'=>[2835,4008], - 'isob1'=>[2004,2835], - 'isob2'=>[1417,2004], - 'isob3'=>[1001,1417], - 'isob4'=>[709,1001], - 'isob5'=>[499,709], - 'isob6'=>[354,499], - 'c0'=>[2599,3677], - 'c1'=>[1837,2599], - 'c2'=>[1298,1837], - 'c3'=>[918,1298], - 'c4'=>[649,918], - 'c5'=>[459,649], - 'c6'=>[323,459] ); - -my $ucmap=<<'EOF'; -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (Adobe) -/Ordering (UCS) -/Supplement 0 ->> def -/CMapName /Adobe-Identity-UCS def -/CMapType 2 def -1 begincodespacerange -<0000> -endcodespacerange -2 beginbfrange -<008b> <008f> [<00660066> <00660069> <0066006c> <006600660069> <00660066006C>] -<00ad> <00ad> <002d> -endbfrange -endcmap -CMapName currentdict /CMap defineresource pop -end -end -EOF - -my $fd; -my $frot; -my $fpsz; -my $embedall=0; -my $debug=0; -my $version=0; -my $stats=0; -my $unicodemap; -my @idirs; - -#Load_Config(); - -GetOptions("F=s" => \$fd, 'I=s' => \@idirs, 'l' => \$frot, 'p=s' => \$fpsz, 'd!' => \$debug, 'v' => \$version, 'version' => \$version, 'e' => \$embedall, 'y=s' => \$Foundry, 's' => \$stats, 'u:s' => \$unicodemap); - -unshift(@idirs,'.'); - -if ($version) -{ - print "GNU gropdf (groff) version $cfg{GROFF_VERSION}\n"; - exit; -} - -if (defined($unicodemap)) -{ - if ($unicodemap eq '') - { - $ucmap=''; - } - elsif (-r $unicodemap) - { - local $/; - open(F,"<$unicodemap") or die "gropdf: Failed to open '$unicodemap'"; - ($ucmap)=(); - close(F); - } - else - { - Msg(0,"Failed to find '$unicodemap' - ignoring"); - } -} - -# Search for 'font directory': paths in -f opt, shell var GROFF_FONT_PATH, default paths - -my $fontdir=$cfg{GROFF_FONT_PATH}; -$fontdir=$ENV{GROFF_FONT_PATH}.$cfg{RT_SEP}.$fontdir if exists($ENV{GROFF_FONT_PATH}); -$fontdir=$fd.$cfg{RT_SEP}.$fontdir if defined($fd); - -$rot=90 if $frot; -$matrix="0 1 -1 0" if $frot; - -LoadDownload(); -LoadDesc(); - -my $unitwidth=$desc{unitwidth}; -my $papersz=$desc{papersize}; -$papersz=lc($fpsz) if $fpsz; - -$env{FontHT}=0; -$env{FontSlant}=0; -MakeMatrix(); - -if (substr($papersz,0,1) eq '/' and -r $papersz) -{ - if (open(P,"<$papersz")) - { - while (

) - { - chomp; - s/# .*//; - next if $_ eq ''; - $papersz=$_; - last - } - - close(P); - } -} - -if ($papersz=~m/([\d.]+)([cipP]),([\d.]+)([cipP])/) -{ - @defaultmb=@mediabox=(0,0,ToPoints($3,$4),ToPoints($1,$2)); -} -elsif (exists($ppsz{$papersz})) -{ - @defaultmb=@mediabox=(0,0,$ppsz{$papersz}->[0],$ppsz{$papersz}->[1]); -} - -my (@dt)=localtime($ENV{SOURCE_DATE_EPOCH} || time); -my $dt=PDFDate(\@dt); - -my %info=('Creator' => "(groff version $cfg{GROFF_VERSION})", - 'Producer' => "(gropdf version $cfg{GROFF_VERSION})", - 'ModDate' => "($dt)", - 'CreationDate' => "($dt)"); - -while (<>) -{ - chomp; - s/\r$//; - $lct++; - - do # The ahead buffer behaves like 'ungetc' - {{ - if (scalar(@ahead)) - { - $_=shift(@ahead); - } - - - my $cmd=substr($_,0,1); - next if $cmd eq '#'; # just a comment - my $lin=substr($_,1); - - while ($cmd eq 'w') - { - $cmd=substr($lin,0,1); - $lin=substr($lin,1); - $w_flg=1 if $gotT; - } - - $lin=~s/^\s+//; -# $lin=~s/\s#.*?$//; # remove comment - $stream.="\% $_\n" if $debug; - - do_x($lin),next if ($cmd eq 'x'); - next if $suppress; - do_p($lin),next if ($cmd eq 'p'); - do_f($lin),next if ($cmd eq 'f'); - do_s($lin),next if ($cmd eq 's'); - do_m($lin),next if ($cmd eq 'm'); - do_D($lin),next if ($cmd eq 'D'); - do_V($lin),next if ($cmd eq 'V'); - do_v($lin),next if ($cmd eq 'v'); - do_t($lin),next if ($cmd eq 't'); - do_u($lin),next if ($cmd eq 'u'); - do_C($lin),next if ($cmd eq 'C'); - do_c($lin),next if ($cmd eq 'c'); - do_N($lin),next if ($cmd eq 'N'); - do_h($lin),next if ($cmd eq 'h'); - do_H($lin),next if ($cmd eq 'H'); - do_n($lin),next if ($cmd eq 'n'); - - my $tmp=scalar(@ahead); - }} until scalar(@ahead) == 0; - -} - -exit 0 if $lct==0; - -if ($cpageno > 0) -{ - my $trans='BLOCK'; - - $trans='PAGE' if $firstpause; - - if (scalar(@XOstream)) - { - MakeXO() if $stream; - $stream=join("\n",@XOstream)."\n"; - } - - my %t=%{$transition->{$trans}}; - $cpage->{MediaBox}=\@mediabox if $custompaper; - $cpage->{Trans}=FixTrans(\%t) if $t{S}; - - if ($#PageAnnots >= 0) - { - @{$cpage->{Annots}}=@PageAnnots; - } - - PutObj($cpageno); - OutStream($cpageno+1); -} - -$cat->{PageMode}='/FullScreen' if $present; - -PutOutlines(\@outlev); - -PutObj(1); - -my $info=BuildObj(++$objct,\%info); - -PutObj($objct); - -foreach my $fontno (keys %fontlst) -{ - my $o=$fontlst{$fontno}->{FNT}; - - foreach my $ch (@{$o->{NO}}) - { - my $psname=$o->{NAM}->{$ch->[1]}->[PSNAME] || '/.notdef'; - my $wid=$o->{NAM}->{$ch->[1]}->[WIDTH] || 0; - - push(@{$o->{DIFF}},$psname); - push(@{$o->{WIDTH}},$wid); - last if $#{$o->{DIFF}} >= 255; - } - unshift(@{$o->{DIFF}},0) if !$use_suppl_font; - my $p=GetObj($fontlst{$fontno}->{OBJ}); - - if (exists($p->{LastChar}) and $p->{LastChar} > 255) - { - $p->{LastChar} = 255; - splice(@{$o->{DIFF}},256); - splice(@{$o->{WIDTH}},256); - } - - if ($use_suppl_font) { - my $fnt = $o; - while ($fnt = $fnt->{NEXT}) { - my (@d, @w); - - foreach my $cn (0..255) { - my $ch = $fnt->{NO}->[$cn + $fnt->{SUPPL} * 256]; - if ($ch && $ch->[1] && $fnt->{NAM}->{$ch->[1]}->[USED]) { - push @d, $fnt->{NAM}->{$ch->[1]}->[PSNAME] || '/.notdef'; - push @w, $fnt->{NAM}->{$ch->[1]}->[WIDTH] || 0; - } else { - push @d, '/.notdef'; - push @w, 0; - } - } - - my $obj = BuildObj($objct + 1, { - %{$p}{qw/Type Subtype BaseFont FontDescriptor/}, - Widths => \@w, - FirstChar => 0, - LastChar => 255, - Encoding => BuildObj($objct + 2, { - Type => '/Encoding', - Differences => \@d, - }), - }); - $objct += 2; - - my $q = GetObj(2); - $q->{Resources}->{Font}->{$fnt->{NM}.'.'.$fnt->{SUPPL}} = $obj; - } - } -} - -foreach my $o (3..$objct) -{ - PutObj($o) if (!exists($obj[$o]->{XREF})); -} - -#my $encrypt=BuildObj(++$objct,{'Filter' => '/Standard', 'V' => 1, 'R' => 2, 'P' => 252}); -#PutObj($objct); -PutObj(2); - -my $xrefct=$fct; - -$objct+=1; -print "xref\n0 $objct\n0000000000 65535 f \n"; - -foreach my $xr (@obj) -{ - next if !defined($xr); - printf("%010d 00000 n \n",$xr->{XREF}); -} - -print "trailer\n<<\n/Info $info\n/Root 1 0 R\n/Size $objct\n>>\nstartxref\n$fct\n\%\%EOF\n"; -print "\% Pages=$pages->{Count}\n" if $stats; - - -sub MakeMatrix -{ - my $fontxrev=shift||0; - my @mat=($frot)?(0,1,-1,0):(1,0,0,1); - - if (!$frot) - { - if ($env{FontHT} != 0) - { - $mat[3]=sprintf('%.3f',$env{FontHT}/$cftsz); - } - - if ($env{FontSlant} != 0) - { - my $slant=$env{FontSlant}; - $slant*=$env{FontHT}/$cftsz if $env{FontHT} != 0; - my $ang=rad($slant); - - $mat[2]=sprintf('%.3f',sin($ang)/cos($ang)); - } - - if ($fontxrev) - { - $mat[0]=-$mat[0]; - } - } - - $matrix=join(' ',@mat); - $matrixchg=1; -} - -sub PutOutlines -{ - my $o=shift; - my $outlines; - - if ($#{$o} > 0) - { - # We've got Outlines to deal with - my $openct=$curoutlev->[0]->[2]; - - while ($thislev-- > 1) - { - my $nxtoutlev=$curoutlev->[0]->[1]; - $nxtoutlev->[0]->[2]+=$openct if $curoutlev->[0]->[3]==1; - $openct=0 if $nxtoutlev->[0]->[3]==-1; - $curoutlev=$nxtoutlev; - } - - $cat->{Outlines}=BuildObj(++$objct,{'Count' => abs($o->[0]->[0])+$o->[0]->[2]}); - $outlines=$obj[$objct]->{DATA}; - } - else - { - return; - } - - SetOutObj($o); - - $outlines->{First}=$o->[1]->[2]; - $outlines->{Last}=$o->[$#{$o}]->[2]; - - LinkOutObj($o,$cat->{Outlines}); -} - -sub SetOutObj -{ - my $o=shift; - - for my $j (1..$#{$o}) - { - my $ono=BuildObj(++$objct,$o->[$j]->[0]); - $o->[$j]->[2]=$ono; - - SetOutObj($o->[$j]->[1]) if $#{$o->[$j]->[1]} > -1; - } -} - -sub LinkOutObj -{ - my $o=shift; - my $parent=shift; - - for my $j (1..$#{$o}) - { - my $op=GetObj($o->[$j]->[2]); - - $op->{Next}=$o->[$j+1]->[2] if ($j < $#{$o}); - $op->{Prev}=$o->[$j-1]->[2] if ($j > 1); - $op->{Parent}=$parent; - - if ($#{$o->[$j]->[1]} > -1) - { - $op->{Count}=$o->[$j]->[1]->[0]->[2]*$o->[$j]->[1]->[0]->[3];# if exists($op->{Count}) and $op->{Count} > 0; - $op->{First}=$o->[$j]->[1]->[1]->[2]; - $op->{Last}=$o->[$j]->[1]->[$#{$o->[$j]->[1]}]->[2]; - LinkOutObj($o->[$j]->[1],$o->[$j]->[2]); - } - } -} - -sub GetObj -{ - my $ono=shift; - ($ono)=split(' ',$ono); - return($obj[$ono]->{DATA}); -} - - - -sub PDFDate -{ - my $dt=shift; - return(sprintf("D:%04d%02d%02d%02d%02d%02d%+03d'00'",$dt->[5]+1900,$dt->[4]+1,$dt->[3],$dt->[2],$dt->[1],$dt->[0],( localtime time() + 3600*( 12 - (gmtime)[2] ) )[2] - 12)); -} - -sub ToPoints -{ - my $num=shift; - my $unit=shift; - - if ($unit eq 'i') - { - return($num*72); - } - elsif ($unit eq 'c') - { - return int($num*72/2.54); - } - elsif ($unit eq 'm') # millimetres - { - return int($num*72/25.4); - } - elsif ($unit eq 'p') - { - return($num); - } - elsif ($unit eq 'P') - { - return($num*6); - } - elsif ($unit eq 'z') - { - return($num/$unitwidth); - } - else - { - Msg(1,"Unknown scaling factor '$unit'"); - } -} - -sub Load_Config -{ - open(CFG,") - { - chomp; - my ($key,$val)=split(/ ?= ?/); - - $cfg{$key}=$val; - } - - close(CFG); -} - -sub LoadDownload -{ - my $f; - my $found=0; - - my (@dirs)=split($cfg{RT_SEP},$fontdir); - - foreach my $dir (@dirs) - { - $f=undef; - OpenFile(\$f,$dir,"download"); - next if !defined($f); - $found++; - - while (<$f>) - { - chomp; - s/#.*$//; - next if $_ eq ''; - my ($foundry,$name,$file)=split(/\t+/); - if (substr($file,0,1) eq '*') - { - next if !$embedall; - $file=substr($file,1); - } - - $download{"$foundry $name"}=$file; - } - - close($f); - } - - Msg(1,"Failed to open 'download'") if !$found; -} - -sub OpenFile -{ - my $f=shift; - my $dirs=shift; - my $fnm=shift; - - if (substr($fnm,0,1) eq '/' or substr($fnm,1,1) eq ':') # dos - { - return if -r "$fnm" and open($$f,"<$fnm"); - } - - my (@dirs)=split($cfg{RT_SEP},$dirs); - - foreach my $dir (@dirs) - { - last if -r "$dir/$devnm/$fnm" and open($$f,"<$dir/$devnm/$fnm"); - } -} - -sub LoadDesc -{ - my $f; - - OpenFile(\$f,$fontdir,"DESC"); - Msg(1,"Failed to open 'DESC'") if !defined($f); - - while (<$f>) - { - chomp; - s/#.*$//; - next if $_ eq ''; - my ($name,$prms)=split(' ',$_,2); - $desc{lc($name)}=$prms; - } - - close($f); -} - -sub rad { $_[0]*3.14159/180 } - -my $InPicRotate=0; - -sub do_x -{ - my $l=shift; - my ($xcmd,@xprm)=split(' ',$l); - $xcmd=substr($xcmd,0,1); - - if ($xcmd eq 'T') - { - Msg(0,"Expecting a pdf pipe (got $xprm[0])") if $xprm[0] ne substr($devnm,3); - } - elsif ($xcmd eq 'f') # Register Font - { - $xprm[1]="${Foundry}-$xprm[1]" if $Foundry ne ''; - LoadFont($xprm[0],$xprm[1]); - } - elsif ($xcmd eq 'F') # Source File (for errors) - { - $env{SourceFile}=$xprm[0]; - } - elsif ($xcmd eq 'H') # FontHT - { - $xprm[0]/=$unitwidth; - $xprm[0]=0 if $xprm[0] == $cftsz; - $env{FontHT}=$xprm[0]; - MakeMatrix(); - } - elsif ($xcmd eq 'S') # FontSlant - { - $env{FontSlant}=$xprm[0]; - MakeMatrix(); - } - elsif ($xcmd eq 'i') # Initialise - { - if ($objct == 0) - { - $objct++; - @defaultmb=@mediabox; - BuildObj($objct,{'Pages' => BuildObj($objct+1, - {'Kids' => [], - 'Count' => 0, - 'Type' => '/Pages', - 'Rotate' => $rot, - 'MediaBox' => \@defaultmb, - 'Resources' => - {'Font' => {}, - 'ProcSet' => ['/PDF', '/Text', '/ImageB', '/ImageC', '/ImageI']} - } - ), - 'Type' => '/Catalog'}); - - $cat=$obj[$objct]->{DATA}; - $objct++; - $pages=$obj[2]->{DATA}; - Put("%PDF-1.4\n\x25\xe2\xe3\xcf\xd3\n"); - } - } - elsif ($xcmd eq 'X') - { - # There could be extended args - do - {{ - LoadAhead(1); - if (substr($ahead[0],0,1) eq '+') - { - $l.="\n".substr($ahead[0],1); - shift(@ahead); - } - }} until $#ahead==0; - - ($xcmd,@xprm)=split(' ',$l); - $xcmd=substr($xcmd,0,1); - - if ($xprm[0]=~m/^(.+:)(.+)/) - { - splice(@xprm,1,0,$2); - $xprm[0]=$1; - } - - my $par=join(' ',@xprm[1..$#xprm]); - - if ($xprm[0] eq 'ps:') - { - if ($xprm[1] eq 'invis') - { - $suppress=1; - } - elsif ($xprm[1] eq 'endinvis') - { - $suppress=0; - } - elsif ($par=~m/exec gsave currentpoint 2 copy translate (.+) rotate neg exch neg exch translate/) - { - # This is added by gpic to rotate a single object - - my $theta=-rad($1); - - IsGraphic(); - my ($curangle,$hyp)=RtoP($xpos,GraphY($ypos)); - my ($x,$y)=PtoR($theta+$curangle,$hyp); - $stream.="q\n".sprintf("%.3f %.3f %.3f %.3f %.3f %.3f cm",cos($theta),sin($theta),-sin($theta),cos($theta),$xpos-$x,GraphY($ypos)-$y)."\n"; - $InPicRotate=1; - } - elsif ($par=~m/exec grestore/ and $InPicRotate) - { - IsGraphic(); - $stream.="Q\n"; - $InPicRotate=0; - } - elsif ($par=~m/exec (\d) setlinejoin/) - { - IsGraphic(); - $linejoin=$1; - $stream.="$linejoin j\n"; - } - elsif ($par=~m/exec (\d) setlinecap/) - { - IsGraphic(); - $linecap=$1; - $stream.="$linecap J\n"; - } - elsif ($par=~m/exec %%%%PAUSE/i and !$noslide) - { - my $trans='BLOCK'; - - if ($firstpause) - { - $trans='PAGE'; - $firstpause=0; - } - MakeXO(); - NewPage($trans); - $present=1; - } - elsif ($par=~m/exec %%%%BEGINONCE/) - { - if ($noslide) - { - $suppress=1; - } - else - { - my $trans='BLOCK'; - - if ($firstpause) - { - $trans='PAGE'; - $firstpause=0; - } - MakeXO(); - NewPage($trans); - $present=1; - } - } - elsif ($par=~m/exec %%%%ENDONCE/) - { - if ($noslide) - { - $suppress=0; - } - else - { - MakeXO(); - NewPage('BLOCK'); - $cat->{PageMode}='/FullScreen'; - pop(@XOstream); - } - } - elsif ($par=~m/\[(.+) pdfmark/) - { - my $pdfmark=$1; - $pdfmark=~s((\d{4,6}) u)(sprintf("%.1f",$1/$desc{sizescale}))eg; - $pdfmark=~s(\\\[u00(..)\])(chr(hex($1)))eg; - - if ($pdfmark=~m/(.+) \/DOCINFO/) - { - my @xwds=split(' ',"<< $1 >>"); - my $docinfo=ParsePDFValue(\@xwds); - - foreach my $k (keys %{$docinfo}) - { - $info{$k}=$docinfo->{$k} if $k ne 'Producer'; - } - } - elsif ($pdfmark=~m/(.+) \/DOCVIEW/) - { - my @xwds=split(' ',"<< $1 >>"); - my $docview=ParsePDFValue(\@xwds); - - foreach my $k (keys %{$docview}) - { - $cat->{$k}=$docview->{$k} if !exists($cat->{$k}); - } - } - elsif ($pdfmark=~m/(.+) \/DEST/) - { - my @xwds=split(' ',"<< $1 >>"); - my $dest=ParsePDFValue(\@xwds); - foreach my $v (@{$dest->{View}}) - { - $v=GraphY(abs($v)) if substr($v,0,1) eq '-'; - } - unshift(@{$dest->{View}},"$cpageno 0 R"); - - if (!defined($dests)) - { - $cat->{Dests}=BuildObj(++$objct,{}); - $dests=$obj[$objct]->{DATA}; - } - - my $k=substr($dest->{Dest},1); - $dests->{$k}=$dest->{View}; - } - elsif ($pdfmark=~m/(.+) \/ANN/) - { - my $l=$1; - $l=~s/Color/C/; - $l=~s/Action/A/; - $l=~s/Title/T/; - $l=~s'/Subtype /URI'/S /URI'; - my @xwds=split(' ',"<< $l >>"); - my $annotno=BuildObj(++$objct,ParsePDFValue(\@xwds)); - my $annot=$obj[$objct]; - $annot->{DATA}->{Type}='/Annot'; - FixRect($annot->{DATA}->{Rect}); # Y origin to ll - FixPDFColour($annot->{DATA}); - push(@PageAnnots,$annotno); - } - elsif ($pdfmark=~m/(.+) \/OUT/) - { - my $t=$1; - $t=~s/\\\) /\\\\\) /g; - $t=~s/\\e/\\\\/g; - $t=~m/(^.*\/Title \()(.*)(\).*)/; - my ($pre,$title,$post)=($1,$2,$3); - if ($use_unicode_bookmark && - $title =~ s/\\\[u([0-9A-F_]+)\]/join( - '', map { pack "U", hex } split '_', $1 - )/eg) { - $title = join '', map sprintf("\\%o", $_), - unpack "C*", encode("utf16", $title); - } - $title=~s/(?>"); - my $out=ParsePDFValue(\@xwds); - - my $this=[$out,[]]; - - if (exists($out->{Level})) - { - my $lev=abs($out->{Level}); - my $levsgn=sgn($out->{Level}); - delete($out->{Level}); - - if ($lev > $thislev) - { - my $thisoutlev=$curoutlev->[$#{$curoutlev}]->[1]; - $thisoutlev->[0]=[0,$curoutlev,0,$levsgn]; - $curoutlev=$thisoutlev; - $curoutlevno=$#{$curoutlev}; - $thislev++; - } - elsif ($lev < $thislev) - { - my $openct=$curoutlev->[0]->[2]; - - while ($thislev > $lev) - { - my $nxtoutlev=$curoutlev->[0]->[1]; - $nxtoutlev->[0]->[2]+=$openct if $curoutlev->[0]->[3]==1; - $openct=0 if $nxtoutlev->[0]->[3]==-1; - $curoutlev=$nxtoutlev; - $thislev--; - } - - $curoutlevno=$#{$curoutlev}; - } - -# push(@{$curoutlev},$this); - splice(@{$curoutlev},++$curoutlevno,0,$this); - $curoutlev->[0]->[2]++; - } - else - { - # This code supports old pdfmark.tmac, unused by pdf.tmac - while ($curoutlev->[0]->[0] == 0 and defined($curoutlev->[0]->[1])) - { - $curoutlev=$curoutlev->[0]->[1]; - } - - $curoutlev->[0]->[0]--; - $curoutlev->[0]->[2]++; - push(@{$curoutlev},$this); - - - if (exists($out->{Count}) and $out->{Count} != 0) - { - push(@{$this->[1]},[abs($out->{Count}),$curoutlev,0,sgn($out->{Count})]); - $curoutlev=$this->[1]; - - if ($out->{Count} > 0) - { - my $p=$curoutlev; - - while (defined($p)) - { - $p->[0]->[2]+=$out->{Count}; - $p=$p->[0]->[1]; - } - } - } - } - } - } - } - elsif (lc($xprm[0]) eq 'pdf:') - { - if (lc($xprm[1]) eq 'import') - { - my $fil=$xprm[2]; - my $llx=$xprm[3]; - my $lly=$xprm[4]; - my $urx=$xprm[5]; - my $ury=$xprm[6]; - my $wid=$xprm[7]; - my $hgt=$xprm[8]||-1; - my $mat=[1,0,0,1,0,0]; - - if (!exists($incfil{$fil})) - { - if ($fil=~m/\.pdf$/) - { - $incfil{$fil}=LoadPDF($fil,$mat,$wid,$hgt,"import"); - } - elsif ($fil=~m/\.swf$/) - { - my $xscale=$wid/($urx-$llx+1); - my $yscale=($hgt<=0)?$xscale:($hgt/($ury-$lly+1)); - $hgt=($ury-$lly+1)*$yscale; - - if ($rot) - { - $mat->[3]=$xscale; - $mat->[0]=$yscale; - } - else - { - $mat->[0]=$xscale; - $mat->[3]=$yscale; - } - - $incfil{$fil}=LoadSWF($fil,[$llx,$lly,$urx,$ury],$mat); - } - else - { - Msg(0,"Unknown filetype '$fil'"); - return undef; - } - } - - if (defined($incfil{$fil})) - { - IsGraphic(); - if ($fil=~m/\.pdf$/) - { - my $bbox=$incfil{$fil}->[1]; - my $xscale=d3($wid/($bbox->[2]-$bbox->[0]+1)); - my $yscale=d3(($hgt<=0)?$xscale:($hgt/($bbox->[3]-$bbox->[1]+1))); - $wid=($bbox->[2]-$bbox->[0])*$xscale; - $hgt=($bbox->[3]-$bbox->[1])*$yscale; - $ypos+=$hgt; - $stream.="q $xscale 0 0 $yscale ".PutXY($xpos,$ypos)." cm"; - $stream.=" 0 1 -1 0 0 0 cm" if $rot; - $stream.=" /$incfil{$fil}->[0] Do Q\n"; - } - elsif ($fil=~m/\.swf$/) - { - $stream.=PutXY($xpos,$ypos)." m /$incfil{$fil} Do\n"; - } - } - } - elsif (lc($xprm[1]) eq 'pdfpic') - { - my $fil=$xprm[2]; - my $flag=uc($xprm[3]||'-L'); - my $wid=GetPoints($xprm[4])||-1; - my $hgt=GetPoints($xprm[5]||-1); - my $ll=GetPoints($xprm[6]||0); - my $mat=[1,0,0,1,0,0]; - - if (!exists($incfil{$fil})) - { - $incfil{$fil}=LoadPDF($fil,$mat,$wid,$hgt,"pdfpic"); - } - - if (defined($incfil{$fil})) - { - IsGraphic(); - my $bbox=$incfil{$fil}->[1]; - $wid=($bbox->[2]-$bbox->[0]) if $wid <= 0; - my $xscale=d3($wid/($bbox->[2]-$bbox->[0])); - my $yscale=d3(($hgt<=0)?$xscale:($hgt/($bbox->[3]-$bbox->[1]))); - $xscale=($wid<=0)?$yscale:$xscale; - $xscale=$yscale if $yscale < $xscale; - $yscale=$xscale if $xscale < $yscale; - $wid=($bbox->[2]-$bbox->[0])*$xscale; - $hgt=($bbox->[3]-$bbox->[1])*$yscale; - - if ($flag eq '-C' and $ll > $wid) - { - $xpos=int(($ll-$wid)/2); - } - elsif ($flag eq '-R' and $ll > $wid) - { - $xpos=$ll-$wid; - } - - $ypos+=$hgt; - $stream.="q $xscale 0 0 $yscale ".PutXY($xpos,$ypos)." cm"; - $stream.=" 0 1 -1 0 0 0 cm" if $rot; - $stream.=" /$incfil{$fil}->[0] Do Q\n"; - } - } - elsif (lc($xprm[1]) eq 'xrev') - { - $xrev=!$xrev; - } - elsif (lc($xprm[1]) eq 'markstart') - { - $mark={'rst' => ($xprm[2]+$xprm[4])/$unitwidth, 'rsb' => ($xprm[3]-$xprm[4])/$unitwidth, 'xpos' => $xpos-($xprm[4]/$unitwidth), - 'ypos' => $ypos, 'lead' => $xprm[4]/$unitwidth, 'pdfmark' => join(' ',@xprm[5..$#xprm])}; - } - elsif (lc($xprm[1]) eq 'markend') - { - PutHotSpot($xpos) if defined($mark); - $mark=undef; - } - elsif (lc($xprm[1]) eq 'marksuspend') - { - $suspendmark=$mark; - $mark=undef; - } - elsif (lc($xprm[1]) eq 'markrestart') - { - $mark=$suspendmark; - $suspendmark=undef; - } - elsif (lc($xprm[1]) eq 'pagename') - { - if ($pginsert > -1) - { - $pgnames{$xprm[2]}=$pages->{Kids}->[$pginsert]; - } - else - { - $pgnames{$xprm[2]}='top'; - } - } - elsif (lc($xprm[1]) eq 'switchtopage') - { - my $ba=$xprm[2]; - my $want=$xprm[3]; - - if ($pginsert > -1) - { - if (!defined($want) or $want eq '') - { - # no before/after - $want=$ba; - $ba='before'; - } - - if (!defined($ba) or $ba eq '' or $want eq 'bottom') - { - $pginsert=$#{$pages->{Kids}}; - } - elsif ($want eq 'top') - { - $pginsert=-1; - } - else - { - if (exists($pgnames{$want})) - { - my $ref=$pgnames{$want}; - - if ($ref eq 'top') - { - $pginsert=-1; - } - else - { - FIND: while (1) - { - foreach my $j (0..$#{$pages->{Kids}}) - { - if ($ref eq $pages->{Kids}->[$j]) - { - if ($ba eq 'before') - { - $pginsert=$j-1; - last FIND; - } - elsif ($ba eq 'after') - { - $pginsert=$j; - last FIND; - } - else - { - Msg(0,"Parameter must be top|bottom|before|after not '$ba'"); - last FIND; - } - } - - } - - Msg(0,"Can't find page ref '$ref'"); - last FIND - - } - } - } - else - { - Msg(0,"Can't find page named '$want'"); - } - } - - if ($pginsert < 0) - { - ($curoutlev,$curoutlevno,$thislev)=(\@outlev,0,1); - } - else - { - ($curoutlev,$curoutlevno,$thislev)=(@{$outlines[$pginsert]}); - } - } - } - elsif (lc($xprm[1]) eq 'transition' and !$noslide) - { - if (uc($xprm[2]) eq 'PAGE' or uc($xprm[2] eq 'SLIDE')) - { - $transition->{PAGE}->{S}='/'.ucfirst($xprm[3]) if $xprm[3] and $xprm[3] ne '.'; - $transition->{PAGE}->{D}=$xprm[4] if $xprm[4] and $xprm[4] ne '.'; - $transition->{PAGE}->{Dm}='/'.$xprm[5] if $xprm[5] and $xprm[5] ne '.'; - $transition->{PAGE}->{M}='/'.$xprm[6] if $xprm[6] and $xprm[6] ne '.'; - $xprm[7]='/None' if $xprm[7] and uc($xprm[7]) eq 'NONE'; - $transition->{PAGE}->{Di}=$xprm[7] if $xprm[7] and $xprm[7] ne '.'; - $transition->{PAGE}->{SS}=$xprm[8] if $xprm[8] and $xprm[8] ne '.'; - $transition->{PAGE}->{B}=$xprm[9] if $xprm[9] and $xprm[9] ne '.'; - } - elsif (uc($xprm[2]) eq 'BLOCK') - { - $transition->{BLOCK}->{S}='/'.ucfirst($xprm[3]) if $xprm[3] and $xprm[3] ne '.'; - $transition->{BLOCK}->{D}=$xprm[4] if $xprm[4] and $xprm[4] ne '.'; - $transition->{BLOCK}->{Dm}='/'.$xprm[5] if $xprm[5] and $xprm[5] ne '.'; - $transition->{BLOCK}->{M}='/'.$xprm[6] if $xprm[6] and $xprm[6] ne '.'; - $xprm[7]='/None' if $xprm[7] and uc($xprm[7]) eq 'NONE'; - $transition->{BLOCK}->{Di}=$xprm[7] if $xprm[7] and $xprm[7] ne '.'; - $transition->{BLOCK}->{SS}=$xprm[8] if $xprm[8] and $xprm[8] ne '.'; - $transition->{BLOCK}->{B}=$xprm[9] if $xprm[9] and $xprm[9] ne '.'; - } - - $present=1; - } - } - elsif (lc(substr($xprm[0],0,9)) eq 'papersize') - { - my ($px,$py)=split(',',substr($xprm[0],10)); - $px=GetPoints($px); - $py=GetPoints($py); - @mediabox=(0,0,$px,$py); - my @mb=@mediabox; - $matrixchg=1; - $custompaper=1; - $cpage->{MediaBox}=\@mb; - } - } -} - -sub FixPDFColour -{ - my $o=shift; - my $a=$o->{C}; - my @r=(); - my $c=$a->[0]; - - if ($#{$a}==3) - { - if ($c > 1) - { - foreach my $j (0..2) - { - push(@r,sprintf("%1.3f",$a->[$j]/0xffff)); - } - - $o->{C}=\@r; - } - } - elsif (substr($c,0,1) eq '#') - { - if (length($c) == 7) - { - foreach my $j (0..2) - { - push(@r,sprintf("%1.3f",hex(substr($c,$j*2+1,2))/0xff)); - } - - $o->{C}=\@r; - } - elsif (length($c) == 14) - { - foreach my $j (0..2) - { - push(@r,sprintf("%1.3f",hex(substr($c,$j*4+2,4))/0xffff)); - } - - $o->{C}=\@r; - } - } -} - -sub PutHotSpot -{ - my $endx=shift; - my $l=$mark->{pdfmark}; - $l=~s/Color/C/; - $l=~s/Action/A/; - $l=~s'/Subtype /URI'/S /URI'; - $l=~s(\\\[u00(..)\])(chr(hex($1)))eg; - my @xwds=split(' ',"<< $l >>"); - my $annotno=BuildObj(++$objct,ParsePDFValue(\@xwds)); - my $annot=$obj[$objct]; - $annot->{DATA}->{Type}='/Annot'; - $annot->{DATA}->{Rect}=[$mark->{xpos},$mark->{ypos}-$mark->{rsb},$endx+$mark->{lead},$mark->{ypos}-$mark->{rst}]; - FixPDFColour($annot->{DATA}); - FixRect($annot->{DATA}->{Rect}); # Y origin to ll - push(@PageAnnots,$annotno); -} - -sub sgn -{ - return(1) if $_[0] > 0; - return(-1) if $_[0] < 0; - return(0); -} - -sub FixRect -{ - my $rect=shift; - - return if !defined($rect); - $rect->[1]=GraphY($rect->[1]); - $rect->[3]=GraphY($rect->[3]); -} - -sub GetPoints -{ - my $val=shift; - - $val=ToPoints($1,$2) if ($val and $val=~m/(-?[\d.]+)([cipnz])/); - - return $val; -} - -# Although the PDF reference mentions XObject/Form as a way of incorporating an external PDF page into -# the current PDF, it seems not to work with any current PDF reader (although I am told (by Leonard Rosenthol, -# who helped author the PDF ISO standard) that Acroread 9 does support it, empiorical observation shows otherwise!!). -# So... do it the hard way - full PDF parser and merge required objects!!! - -# sub BuildRef -# { -# my $fil=shift; -# my $bbox=shift; -# my $mat=shift; -# my $wid=($bbox->[2]-$bbox->[0])*$mat->[0]; -# my $hgt=($bbox->[3]-$bbox->[1])*$mat->[3]; -# -# if (!open(PDF,"<$fil")) -# { -# Msg(0,"Failed to open '$fil'"); -# return(undef); -# } -# -# my (@f)=(); -# -# close(PDF); -# -# $objct++; -# my $xonm="XO$objct"; -# -# $pages->{'Resources'}->{'XObject'}->{$xonm}=BuildObj($objct,{'Type' => '/XObject', -# 'Subtype' => '/Form', -# 'BBox' => $bbox, -# 'Matrix' => $mat, -# 'Resources' => $pages->{'Resources'}, -# 'Ref' => {'Page' => '1', -# 'F' => BuildObj($objct+1,{'Type' => '/Filespec', -# 'F' => "($fil)", -# 'EF' => {'F' => BuildObj($objct+2,{'Type' => '/EmbeddedFile'})} -# }) -# } -# }); -# -# $obj[$objct]->{STREAM}="q 1 0 0 1 0 0 cm -# q BT -# 1 0 0 1 0 0 Tm -# .5 g .5 G -# /F5 20 Tf -# (Proxy) Tj -# ET Q -# 0 0 m 72 0 l s -# Q\n"; -# -# # $obj[$objct]->{STREAM}=PutXY($xpos,$ypos)." m ".PutXY($xpos+$wid,$ypos)." l ".PutXY($xpos+$wid,$ypos+$hgt)." l ".PutXY($xpos,$ypos+$hgt)." l f\n"; -# $obj[$objct+2]->{STREAM}=join('',@f); -# PutObj($objct); -# PutObj($objct+1); -# PutObj($objct+2); -# $objct+=2; -# return($xonm); -# } - -sub LoadSWF -{ - my $fil=shift; - my $bbox=shift; - my $mat=shift; - my $wid=($bbox->[2]-$bbox->[0])*$mat->[0]; - my $hgt=($bbox->[3]-$bbox->[1])*$mat->[3]; - my (@path)=split('/',$fil); - my $node=pop(@path); - - if (!open(PDF,"<$fil")) - { - Msg(0,"Failed to open '$fil'"); - return(undef); - } - - my (@f)=(); - - close(PDF); - - $objct++; - my $xonm="XO$objct"; - - $pages->{'Resources'}->{'XObject'}->{$xonm}=BuildObj($objct,{'Type' => '/XObject', 'BBox' => $bbox, 'Matrix' => $mat, 'FormType' => 1, 'Subtype' => '/Form', 'Length' => 0, 'Type' => "/XObject"}); - $obj[$objct]->{STREAM}=''; - PutObj($objct); - $objct++; - my $asset=BuildObj($objct,{'EF' => {'F' => BuildObj($objct+1,{})}, - 'F' => "($node)", - 'Type' => '/Filespec', - 'UF' => "($node)"}); - - PutObj($objct); - $objct++; - $obj[$objct]->{STREAM}=join('',@f); - PutObj($objct); - $objct++; - my $config=BuildObj($objct,{'Instances' => [BuildObj($objct+1,{'Params' => { 'Binding' => '/Background'}, 'Asset' => $asset})], - 'Subtype' => '/Flash'}); - - PutObj($objct); - $objct++; - PutObj($objct); - $objct++; - - my ($x,$y)=split(' ',PutXY($xpos,$ypos)); - - push(@{$cpage->{Annots}},BuildObj($objct,{'RichMediaContent' => {'Subtype' => '/Flash', 'Configurations' => [$config], 'Assets' => {'Names' => [ "($node)", $asset ] }}, - 'P' => "$cpageno 0 R", - 'RichMediaSettings' => { 'Deactivation' => { 'Condition' => '/PI', - 'Type' => '/RichMediaDeactivation'}, - 'Activation' => { 'Condition' => '/PV', - 'Type' => '/RichMediaActivation'}}, - 'F' => 68, - 'Subtype' => '/RichMedia', - 'Type' => '/Annot', - 'Rect' => "[ $x $y ".($x+$wid)." ".($y+$hgt)." ]", - 'Border' => [0,0,0]})); - - PutObj($objct); - - return $xonm; -} - -sub OpenInc -{ - my $fn=shift; - my $fnm=$fn; - my $F; - - if (substr($fnm,0,1) eq '/' or substr($fnm,1,1) eq ':') # dos - { - if (-r $fnm and open($F,"<$fnm")) - { - return($F,$fnm); - } - } - else - { - foreach my $dir (@idirs) - { - $fnm="$dir/$fn"; - - if (-r "$fnm" and open($F,"<$fnm")) - { - return($F,$fnm); - } - } - } - - return(undef,$fn); -} - -sub LoadPDF -{ - my $pdfnm=shift; - my $mat=shift; - my $wid=shift; - my $hgt=shift; - my $type=shift; - my $pdf; - my $pdftxt=''; - my $strmlen=0; - my $curobj=-1; - my $instream=0; - my $cont; - my $adj=0; - my $keepsep=$/; - - my ($PD,$PDnm)=OpenInc($pdfnm); - - if (!defined($PD)) - { - Msg(0,"Failed to open PDF '$pdfnm'"); - return undef; - } - - my $hdr=<$PD>; - - $/="\r",$adj=1 if (length($hdr) > 10); - - while (<$PD>) - { - chomp; - - s/\n//; - - if (m/endstream(\s+.*)?$/) - { - $instream=0; - $_="endstream"; - $_.=$1 if defined($1) - } - - next if $instream; - - if (m'/Length\s+(\d+)(\s+\d+\s+R)?') - { - if (!defined($2)) - { - $strmlen=$1; - } - else - { - $strmlen=0; - } - } - - if (m'^(\d+) \d+ obj') - { - $curobj=$1; - $pdf->[$curobj]->{OBJ}=undef; - } - - if (m'stream\s*$' and ! m/^endstream/) - { - if ($curobj > -1) - { - $pdf->[$curobj]->{STREAMPOS}=[tell($PD)+$adj,$strmlen]; - seek($PD,$strmlen,1); - $instream=1; - } - else - { - Msg(0,"Parsing PDF '$pdfnm' failed"); - return undef; - } - } - - $pdftxt.=$_.' '; - } - - close($PD); - - open(PD,"<$PDnm"); -# $pdftxt=~s/\]/ \]/g; - my (@pdfwds)=split(' ',$pdftxt); - my $wd; - - while ($wd=nextwd(\@pdfwds),length($wd)) - { - if ($wd=~m/\d+/ and defined($pdfwds[1]) and $pdfwds[1]=~m/^obj(.*)/) - { - $curobj=$wd; - shift(@pdfwds); shift(@pdfwds); - unshift(@pdfwds,$1) if defined($1) and length($1); - $pdf->[$curobj]->{OBJ}=ParsePDFObj(\@pdfwds); - } - elsif ($wd eq 'trailer' and !exists($pdf->[0]->{OBJ})) - { - $pdf->[0]->{OBJ}=ParsePDFObj(\@pdfwds); - } - else - { -# print "Skip '$wd'\n"; - } - } - - my $catalog=${$pdf->[0]->{OBJ}->{Root}}; - my $page=FindPage(1,$pdf); - my $xobj=++$objct; - - # Load the streamas - - foreach my $o (@{$pdf}) - { - if (exists($o->{STREAMPOS})) - { - my $l; - - $l=$o->{OBJ}->{Length} if exists($o->{OBJ}->{Length}); - - $l=$pdf->[$$l]->{OBJ} if (defined($l) && ref($l) eq 'OBJREF'); - - Msg(1,"Unable to determine length of stream \@$o->{STREAMPOS}->[0]") if !defined($l); - - sysseek(PD,$o->{STREAMPOS}->[0],0); - Msg(0,'Failed to read all the stream') if $l != sysread(PD,$o->{STREAM},$l); - - if ($gotzlib and exists($o->{OBJ}->{'Filter'}) and $o->{OBJ}->{'Filter'} eq '/FlateDecode') - { - $o->{STREAM}=Compress::Zlib::uncompress($o->{STREAM}); - delete($o->{OBJ }->{'Filter'}); - } - } - } - - close(PD); - - # Find BBox - my $BBox; - my $insmap={}; - - foreach my $k (qw( MediaBox ArtBox TrimBox BleedBox CropBox )) - { - $BBox=FindKey($pdf,$page,$k); - last if $BBox; - } - - $BBox=[0,0,595,842] if !defined($BBox); - - $wid=($BBox->[2]-$BBox->[0]+1) if $wid==0; - my $xscale=d3(abs($wid)/($BBox->[2]-$BBox->[0]+1)); - my $yscale=d3(($hgt<=0)?$xscale:(abs($hgt)/($BBox->[3]-$BBox->[1]+1))); - $hgt=($BBox->[3]-$BBox->[1]+1)*$yscale; - - if ($type eq "import") - { - $mat->[0]=$xscale; - $mat->[3]=$yscale; - } - - # Find Resource - - my $res=FindKey($pdf,$page,'Resources'); - my $xonm="XO$xobj"; - - # Map inserted objects to current PDF - - MapInsValue($pdf,$page,'',$insmap,$xobj,$pdf->[$page]->{OBJ}); -# -# Many PDFs include 'Resources' at the 'Page' level but if 'Resources' is held at a higher level (i.e 'Pages') -# then we need to include its objects as well. -# - MapInsValue($pdf,$page,'',$insmap,$xobj,$res) if !exists($pdf->[$page]->{OBJ}->{Resources}); - - # Copy Resources - - my %incres=%{$res}; - - $incres{ProcSet}=['/PDF', '/Text', '/ImageB', '/ImageC', '/ImageI']; - - ($mat->[4],$mat->[5])=split(' ',PutXY($xpos,$ypos)); - $pages->{'Resources'}->{'XObject'}->{$xonm}=BuildObj($xobj,{'Type' => '/XObject', 'BBox' => $BBox, 'Name' => "/$xonm", 'FormType' => 1, 'Subtype' => '/Form', 'Length' => 0, 'Type' => "/XObject", 'Resources' => \%incres}); - - BuildStream($xobj,$pdf,$pdf->[$page]->{OBJ}->{Contents}); - - $/=$keepsep; - return([$xonm,$BBox] ); -} - -sub BuildStream -{ - my $xobj=shift; - my $pdf=shift; - my $val=shift; - my $strm=''; - my $objs; - my $refval=ref($val); - - if ($refval eq 'OBJREF') - { - push(@{$objs}, $val); - } - elsif ($refval eq 'ARRAY') - { - $objs=$val; - } - else - { - Msg(0,"unexpected 'Contents'"); - } - - foreach my $o (@{$objs}) - { - $strm.="\n" if $strm; - $strm.=$pdf->[$$o]->{STREAM} if exists($pdf->[$$o]->{STREAM}); - } - - $obj[$xobj]->{STREAM}=$strm; -} - - -sub MapInsHash -{ - my $pdf=shift; - my $o=shift; - my $insmap=shift; - my $parent=shift; - my $val=shift; - - - foreach my $k (keys(%{$val})) - { - MapInsValue($pdf,$o,$k,$insmap,$parent,$val->{$k}) if $k ne 'Contents'; - } -} - -sub MapInsValue -{ - my $pdf=shift; - my $o=shift; - my $k=shift; - my $insmap=shift; - my $parent=shift; - my $val=shift; - my $refval=ref($val); - - if ($refval eq 'OBJREF') - { - if ($k ne 'Parent') - { - if (!exists($insmap->{IMP}->{$$val})) - { - $objct++; - $insmap->{CUR}->{$objct}=$$val; - $insmap->{IMP}->{$$val}=$objct; - $obj[$objct]->{DATA}=$pdf->[$$val]->{OBJ}; - $obj[$objct]->{STREAM}=$pdf->[$$val]->{STREAM} if exists($pdf->[$$val]->{STREAM}); - MapInsValue($pdf,$$val,'',$insmap,$o,$pdf->[$$val]->{OBJ}); - } - - $$val=$insmap->{IMP}->{$$val}; - } - else - { - $$val=$parent; - } - } - elsif ($refval eq 'ARRAY') - { - foreach my $v (@{$val}) - { - MapInsValue($pdf,$o,'',$insmap,$parent,$v) - } - } - elsif ($refval eq 'HASH') - { - MapInsHash($pdf,$o,$insmap,$parent,$val); - } - -} - -sub FindKey -{ - my $pdf=shift; - my $page=shift; - my $k=shift; - - if (exists($pdf->[$page]->{OBJ}->{$k})) - { - my $val=$pdf->[$page]->{OBJ}->{$k}; - $val=$pdf->[$$val]->{OBJ} if ref($val) eq 'OBJREF'; - return($val); - } - else - { - if (exists($pdf->[$page]->{OBJ}->{Parent})) - { - return(FindKey($pdf,${$pdf->[$page]->{OBJ}->{Parent}},$k)); - } - } - - return(undef); -} - -sub FindPage -{ - my $wantpg=shift; - my $pdf=shift; - my $catalog=${$pdf->[0]->{OBJ}->{Root}}; - my $pages=${$pdf->[$catalog]->{OBJ}->{Pages}}; - - return(NextPage($pdf,$pages,\$wantpg)); -} - -sub NextPage -{ - my $pdf=shift; - my $pages=shift; - my $wantpg=shift; - my $ret; - - if ($pdf->[$pages]->{OBJ}->{Type} eq '/Pages') - { - foreach my $kid (@{$pdf->[$pages]->{OBJ}->{Kids}}) - { - $ret=NextPage($pdf,$$kid,$wantpg); - last if $$wantpg<=0; - } - } - elsif ($pdf->[$pages]->{OBJ}->{Type} eq '/Page') - { - $$wantpg--; - $ret=$pages; - } - - return($ret); -} - -sub nextwd -{ - my $pdfwds=shift; - - my $wd=shift(@{$pdfwds}); - - return('') if !defined($wd); - - if ($wd=~m/^(.*?)(<<|>>|(?:(?>') - { - last; - } - - my (@w)=split('/',$wd,3); - - if ($w[0]) - { - Msg(0,"PDF Dict Key '$wd' does not start with '/'"); - exit 1; - } - else - { - unshift(@{$pdfwds},"/$w[2]") if $w[2]; - $wd=$w[1]; - (@w)=split('\(',$wd,2); - $wd=$w[0]; - unshift(@{$pdfwds},"($w[1]") if defined($w[1]); - (@w)=split('\<',$wd,2); - $wd=$w[0]; - unshift(@{$pdfwds},"<$w[1]") if defined($w[1]); - - $rtn->{$wd}=ParsePDFValue($pdfwds); - } - } - - return($rtn); -} - -sub ParsePDFValue -{ - my $pdfwds=shift; - my $rtn; - my $wd=nextwd($pdfwds); - - if ($wd=~m/^\d+$/ and $pdfwds->[0]=~m/^\d+$/ and $pdfwds->[1]=~m/^R(\]|\>|\/)?/) - { - shift(@{$pdfwds}); - if (defined($1) and length($1)) - { - $pdfwds->[0]=substr($pdfwds->[0],1); - } - else - { - shift(@{$pdfwds}); - } - return(bless(\$wd,'OBJREF')); - } - - if ($wd eq '<<') - { - return(ParsePDFHash($pdfwds)); - } - - if ($wd eq '[') - { - return(ParsePDFArray($pdfwds)); - } - - if ($wd=~m/(.*?)(\(.*)$/) - { - if (defined($1) and length($1)) - { - unshift(@{$pdfwds},$2); - $wd=$1; - } - else - { - return(ParsePDFString($wd,$pdfwds)); - } - } - - if ($wd=~m/(.*?)(\<.*)$/) - { - if (defined($1) and length($1)) - { - unshift(@{$pdfwds},$2); - $wd=$1; - } - else - { - return(ParsePDFHexString($wd,$pdfwds)); - } - } - - if ($wd=~m/(.+?)(\/.*)$/) - { - if (defined($2) and length($2)) - { - unshift(@{$pdfwds},$2); - $wd=$1; - } - } - - return($wd); -} - -sub ParsePDFString -{ - my $wd=shift; - my $rtn=''; - my $pdfwds=shift; - my $lev=0; - - while (length($wd)) - { - $rtn.=' ' if length($rtn); - - while ($wd=~m/(?)(.*)/) - { - unshift(@{$pdfwds},$2) if defined($2) and length($2); - $rtn=$1; - } - - return($rtn); -} - -sub ParsePDFArray -{ - my $pdfwds=shift; - my $rtn=[]; - my $wd; - - while (1) - { - $wd=ParsePDFValue($pdfwds); - last if $wd eq ']' or length($wd)==0; - push(@{$rtn},$wd); - } - - return($rtn); -} - -sub Msg -{ - my ($lev,$msg)=@_; - - print STDERR "$env{SourceFile}: " if exists($env{SourceFile}); - print STDERR "$msg\n"; - exit 1 if $lev; -} - -sub PutXY -{ - my ($x,$y)=(@_); - - if ($frot) - { - return(d3($y)." ".d3($x)); - } - else - { - $y=$mediabox[3]-$y; - return(d3($x)." ".d3($y)); - } -} - -sub GraphY -{ - my $y=shift; - - if ($frot) - { - return($y); - } - else - { - return($mediabox[3]-$y); - } -} - -sub Put -{ - my $msg=shift; - - print $msg; - $fct+=length($msg); -} - -sub PutObj -{ - my $ono=shift; - my $msg="$ono 0 obj "; - $obj[$ono]->{XREF}=$fct; - if (exists($obj[$ono]->{STREAM})) - { - if ($gotzlib && !$debug && !exists($obj[$ono]->{DATA}->{'Filter'})) - { - $obj[$ono]->{STREAM}=Compress::Zlib::compress($obj[$ono]->{STREAM}); - $obj[$ono]->{DATA}->{'Filter'}='/FlateDecode'; - } - - $obj[$ono]->{DATA}->{'Length'}=length($obj[$ono]->{STREAM}); - } - PutField(\$msg,$obj[$ono]->{DATA}); - PutStream(\$msg,$ono) if exists($obj[$ono]->{STREAM}); - Put($msg."endobj\n"); -} - -sub PutStream -{ - my $msg=shift; - my $ono=shift; - - # We could 'flate' here - $$msg.="stream\n$obj[$ono]->{STREAM}endstream\n"; -} - -sub PutField -{ - my $pmsg=shift; - my $fld=shift; - my $term=shift||"\n"; - my $typ=ref($fld); - - if ($typ eq '') - { - $$pmsg.="$fld$term"; - } - elsif ($typ eq 'ARRAY') - { - $$pmsg.='['; - foreach my $cell (@{$fld}) - { - PutField($pmsg,$cell,' '); - } - $$pmsg.="]$term"; - } - elsif ($typ eq 'HASH') - { - $$pmsg.='<< '; - foreach my $key (sort keys %{$fld}) - { - $$pmsg.="/$key "; - PutField($pmsg,$fld->{$key}); - } - $$pmsg.=">>$term"; - } - elsif ($typ eq 'OBJREF') - { - $$pmsg.="$$fld 0 R$term"; - } -} - -sub BuildObj -{ - my $ono=shift; - my $val=shift; - - $obj[$ono]->{DATA}=$val; - - return("$ono 0 R "); -} - -sub LoadFont -{ - my $fontno=shift; - my $fontnm=shift; - my $ofontnm=$fontnm; - - return $fontlst{$fontno}->{OBJ} if (exists($fontlst{$fontno})); - - my $f; - OpenFile(\$f,$fontdir,"$fontnm"); - - if (!defined($f) and $Foundry) - { - # Try with no foundry - $fontnm=~s/.*?-//; - OpenFile(\$f,$fontdir,$fontnm); - } - - Msg(1,"Failed to open font '$ofontnm'") if !defined($f); - - my $foundry=''; - $foundry=$1 if $fontnm=~m/^(.*?)-/; - my $stg=1; - my %fnt; - my @fntbbox=(0,0,0,0); - my $capheight=0; - my $lastchr=0; - my $lastnm; - my $t1flags=0; - my $fixwid=-1; - my $ascent=0; - my $charset=''; - - $fnt{NM} = 'F'.$fontno; - $fnt{SUPPL} = 0; - my @remap = (128..138, 145..255); # ignore ligatures. see text.enc. - $fnt{REMAP} = \@remap; - my @used; - $used[$_] = 1 for 0..255; - $used[$_] = 0 for @remap; - - while (<$f>) - { - chomp; - - s/^ +//; - s/^#.*// if $stg == 1; - next if $_ eq ''; - - if ($stg == 1) - { - my ($key,$val)=split(' ',$_,2); - - $key=lc($key); - $stg=2,next if $key eq 'kernpairs'; - $stg=3,next if lc($_) eq 'charset'; - - $fnt{$key}=$val - } - elsif ($stg == 2) - { - $stg=3,next if lc($_) eq 'charset'; - - my ($ch1,$ch2,$k)=split; -# $fnt{KERN}->{$ch1}->{$ch2}=$k; - } - else - { - my (@r)=split; - my (@p)=split(',',$r[1]); - - if ($r[1] eq '"') - { - $fnt{NAM}->{$r[0]}=$fnt{NAM}->{$lastnm}; - next; - } - - $r[0]='u0020' if $r[3] == 32; - $r[0]="u00".hex($r[3]) if $r[0] eq '---'; -# next if $r[3] >255; - if ($fnt{NAM}->{$r[0]}) { - #Msg(0, "$r[0], $r[3], /$r[4] - dup in $ofontnm") if $debug; - next; - } - $fnt{NAM}->{$r[0]}=[$p[0],$r[3],'/'.$r[4],$r[3],0]; - $fnt{NAM}->{$r[0]}->[SUPPL] = 0; - $fnt{NAM}->{$r[0]}->[USED] = $used[$r[3]]; - $fnt{NO}->[$r[3]]=[$r[0],$r[0]]; - $lastnm=$r[0]; - $lastchr=$r[3] if $r[3] > $lastchr; - $fixwid=$p[0] if $fixwid == -1; - $fixwid=-2 if $fixwid > 0 and $p[0] != $fixwid; - - $fntbbox[1]=-$p[2] if defined($p[2]) and -$p[2] < $fntbbox[1]; - $fntbbox[2]=$p[0] if $p[0] > $fntbbox[2]; - $fntbbox[3]=$p[1] if defined($p[1]) and $p[1] > $fntbbox[3]; - $ascent=$p[1] if defined($p[1]) and $p[1] > $ascent and $r[3] >= 32 and $r[3] < 128; - $charset.='/'.$r[4] if defined($r[4]); - $capheight=$p[1] if length($r[4]) == 1 and $r[4] ge 'A' and $r[4] le 'Z' and $p[1] > $capheight; - } - } - - close($f); - - foreach my $j (0..$lastchr) - { - $fnt{NO}->[$j]=['',''] if !defined($fnt{NO}->[$j]); - } - - my $fno=0; - my $slant=0; - $fnt{DIFF}=[]; - $fnt{WIDTH}=[]; - $fnt{NAM}->{''}=[0,-1,'/.notdef',-1,0]; - $fnt{NAM}->{''}->[SUPPL] = 0; - $slant=-$fnt{'slant'} if exists($fnt{'slant'}); - $fnt{'spacewidth'}=700 if !exists($fnt{'spacewidth'}); - - $t1flags|=2**0 if $fixwid > -1; - $t1flags|=(exists($fnt{'special'}))?2**2:2**5; - $t1flags|=2**6 if $slant != 0; - my $fontkey="$foundry $fnt{internalname}"; - - if (exists($download{$fontkey})) - { - # Not a Base Font - my ($l1,$l2,$l3,$t1stream)=GetType1($download{$fontkey}); - Msg(0,"Incorrect font format for '$fontkey' ($l1)") if !defined($t1stream); - $fno=++$objct; - $fontlst{$fontno}->{OBJ}=BuildObj($objct, - {'Type' => '/Font', - 'Subtype' => '/Type1', - 'BaseFont' => '/'.$fnt{internalname}, - 'Widths' => $fnt{WIDTH}, - 'FirstChar' => 0, - 'LastChar' => $lastchr, - 'Encoding' => BuildObj($objct+1, - {'Type' => '/Encoding', - 'Differences' => $fnt{DIFF} - } - ), - 'FontDescriptor' => BuildObj($objct+2, - {'Type' => '/FontDescriptor', - 'FontName' => '/'.$fnt{internalname}, - 'Flags' => $t1flags, - 'FontBBox' => \@fntbbox, - 'ItalicAngle' => $slant, - 'Ascent' => $ascent, - 'Descent' => $fntbbox[1], - 'CapHeight' => $capheight, - 'StemV' => 0, -# 'CharSet' => "($charset)", - 'FontFile' => BuildObj($objct+3, - {'Length1' => $l1, - 'Length2' => $l2, - 'Length3' => $l3 - } - ) - } - ) - } - ); - - $objct+=3; - $fontlst{$fontno}->{NM}='/'.$fnt{NM}; - $pages->{'Resources'}->{'Font'}->{$fnt{NM}}=$fontlst{$fontno}->{OBJ}; - $fontlst{$fontno}->{FNT}=\%fnt; - $obj[$objct]->{STREAM}=$t1stream; - - } - else - { - $fno=++$objct; - $fontlst{$fontno}->{OBJ}=BuildObj($objct, - {'Type' => '/Font', - 'Subtype' => '/Type1', - 'BaseFont' => '/'.$fnt{internalname}, - 'Widths' => $fnt{WIDTH}, - 'FirstChar' => 0, - 'LastChar' => $lastchr, - 'Encoding' => BuildObj($objct+1, - {'Type' => '/Encoding', - 'Differences' => $fnt{DIFF} - } - ), - 'FontDescriptor' => BuildObj($objct+2, - {'Type' => '/FontDescriptor', - 'FontName' => '/'.$fnt{internalname}, - 'Flags' => $t1flags, - 'FontBBox' => \@fntbbox, - 'ItalicAngle' => $slant, - 'Ascent' => $ascent, - 'Descent' => $fntbbox[1], - 'CapHeight' => $capheight, - 'StemV' => 0, - 'CharSet' => "($charset)", - } - ) - } - ); - - $objct+=2; - $fontlst{$fontno}->{NM}='/'.$fnt{NM}; - $pages->{'Resources'}->{'Font'}->{$fnt{NM}}=$fontlst{$fontno}->{OBJ}; - $fontlst{$fontno}->{FNT}=\%fnt; - } - - if (defined($fnt{encoding}) and $fnt{encoding} eq 'text.enc' and $ucmap ne '') - { - if ($textenccmap eq '') - { - $textenccmap = BuildObj($objct+1,{}); - $objct++; - $obj[$objct]->{STREAM}=$ucmap; - } - $obj[$fno]->{DATA}->{'ToUnicode'}=$textenccmap; - } - -# PutObj($fno); -# PutObj($fno+1); -# PutObj($fno+2) if defined($obj[$fno+2]); -# PutObj($fno+3) if defined($obj[$fno+3]); -} - -sub GetType1 -{ - my $file=shift; - my ($l1,$l2,$l3); # Return lengths - my ($head,$body,$tail); # Font contents - my $f; - - OpenFile(\$f,$fontdir,"$file"); - Msg(1,"Failed to open '$file'") if !defined($f); - - $head=GetChunk($f,1,"currentfile eexec"); - $body=$tail=''; - $body=GetChunk($f,2,"00000000") if !eof($f); - $tail=GetChunk($f,3,"cleartomark") if !eof($f); - - $l1=length($head); - $l2=length($body); - $l3=length($tail); - - return($l1,$l2,$l3,"$head$body$tail"); -} - -sub GetChunk -{ - my $F=shift; - my $segno=shift; - my $ascterm=shift; - my ($type,$hdr,$chunk,@msg); - binmode($F); - my $enc="ascii"; - - while (1) - { - # There may be multiple chunks of the same type - - my $ct=read($F,$hdr,2); - - if ($ct==2) - { - if (substr($hdr,0,1) eq "\x80") - { - # binary chunk - - my $chunktype=ord(substr($hdr,1,1)); - $enc="binary"; - - if (defined($type) and $type != $chunktype) - { - seek($F,-2,1); - last; - } - - $type=$chunktype; - return if $chunktype == 3; - - $ct=read($F,$hdr,4); - - Msg(1,"Failed to read binary segment length"), return if $ct != 4; - - my $sl=unpack('V',$hdr); - my $data; - my $chk=read($F,$data,$sl); - - Msg(1 ,"Failed to read binary segment"), return if $chk != $sl; - - $chunk.=$data; - } - else - { - # ascii chunk - - my $hex=0; - seek($F,-2,1); - my $ct=0; - - while (1) - { - my $lin=<$F>; - - last if !$lin; - - $hex=1,$enc.=" hex" if $segno == 2 and !$ct and $lin=~m/^[A-F0-9a-f]{4,4}/; - - if ($segno !=2 and $lin=~m/^(.*$ascterm\n?)(.*)/) - { - $chunk.=$1; - seek($F,-length($2)-1,1) if $2; - last; - } - elsif ($segno == 2 and $lin=~m/^(.*?)($ascterm.*)/) - { - $chunk.=$1; - seek($F,-length($2)-1,1) if $2; - last; - } - - chomp($lin), $lin=pack('H*',$lin) if $hex; - $chunk.=$lin; $ct++; - } - - last; - } - } - else - { - push(@msg,"Failed to read 2 header bytes"); - } - } - - return $chunk; -} - -sub OutStream -{ - my $ono=shift; - - IsGraphic(); - $stream.="Q\n"; - $obj[$ono]->{STREAM}=$stream; - $obj[$ono]->{DATA}->{Length}=length($stream); - $stream=''; - PutObj($ono); -} - -sub do_p -{ - my $trans='BLOCK'; - - $trans='PAGE' if $firstpause; - NewPage($trans); - @XOstream=(); - @PageAnnots=(); - $firstpause=1; -} - -sub FixTrans -{ - my $t=shift; - my $style=$t->{S}; - - if ($style) - { - delete($t->{Dm}) if $style ne '/Split' and $style ne '/Blinds'; - delete($t->{M}) if !($style eq '/Split' or $style eq '/Box' or $style eq '/Fly'); - delete($t->{Di}) if !($style eq '/Wipe' or $style eq '/Glitter' or $style eq '/Fly' or $style eq '/Cover' or $style eq '/Uncover' or $style eq '/Push') or ($style eq '/Fly' and $t->{Di} eq '/None' and $t->{SS} != 1); - delete($t->{SS}) if !($style eq '/Fly'); - delete($t->{B}) if !($style eq '/Fly'); - } - - return($t); -} - -sub NewPage -{ - my $trans=shift; - # Start of pages - - if ($cpageno > 0) - { - if ($#XOstream>=0) - { - MakeXO() if $stream; - $stream=join("\n",@XOstream,''); - } - - my %t=%{$transition->{$trans}}; - $cpage->{MediaBox}=\@mediabox if $custompaper; - $cpage->{Trans}=FixTrans(\%t) if $t{S}; - - if ($#PageAnnots >= 0) - { - @{$cpage->{Annots}}=@PageAnnots; - } - - PutObj($cpageno); - OutStream($cpageno+1); - } - - $cpageno=++$objct; - - my $thispg=BuildObj($objct, - {'Type' => '/Page', - 'Group' => {'CS' => '/DeviceRGB', 'S' => '/Transparency'}, - 'Parent' => '2 0 R', - 'Contents' => [ BuildObj($objct+1, - {'Length' => 0} - ) ], - } - ); - - splice(@{$pages->{Kids}},++$pginsert,0,$thispg); - splice(@outlines,$pginsert,0,[$curoutlev,$#{$curoutlev}+1,$thislev]); - - $objct+=1; - $cpage=$obj[$cpageno]->{DATA}; - $pages->{'Count'}++; - $stream="q 1 0 0 1 0 0 cm\n$linejoin J\n$linecap j\n0.4 w\n"; - $stream.=$strkcol."\n", $curstrk=$strkcol if $strkcol ne ''; - $mode='g'; - $curfill=''; -# @mediabox=@defaultmb; -} - -sub MakeXO -{ - $stream.="%mode=$mode\n"; - IsGraphic(); - $stream.="Q\n"; - my $xobj=++$objct; - my $xonm="XO$xobj"; - $pages->{'Resources'}->{'XObject'}->{$xonm}=BuildObj($xobj,{'Type' => '/XObject', 'BBox' => \@mediabox, 'Name' => "/$xonm", 'FormType' => 1, 'Subtype' => '/Form', 'Length' => 0, 'Type' => "/XObject"}); - $obj[$xobj]->{STREAM}=$stream; - $stream=''; - push(@XOstream,"q") if $#XOstream==-1; - push(@XOstream,"/$xonm Do"); -} - -sub do_f -{ - my $par=shift; - my $fnt=$fontlst{$par}->{FNT}; - -# IsText(); - $cft="$par"; - $cftsup=0; - $fontchg=1; -# $stream.="/F$cft $cftsz Tf\n" if $cftsz; - $widtbl=CacheWid($par); - $origwidtbl=[]; - - foreach my $w (@{$fnt->{NO}}) - { - push(@{$origwidtbl},$fnt->{NAM}->{$w->[1]}->[WIDTH]); - } - -# $krntbl=$fnt->{KERN}; -} - -sub CacheWid -{ - my $par=shift; - - if (!defined($fontlst{$par}->{CACHE}->{$cftsz})) - { - $fontlst{$par}->{CACHE}->{$cftsz}=BuildCache($fontlst{$par}->{FNT}); - } - - return($fontlst{$par}->{CACHE}->{$cftsz}); -} - -sub BuildCache -{ - my $fnt=shift; - my @cwid; - $origwidtbl=[]; - - foreach my $w (@{$fnt->{NO}}) - { - my $wid=(defined($w) and defined($w->[1]))?$fnt->{NAM}->{$w->[1]}->[WIDTH]:0; - push(@cwid,$wid*$cftsz); - push(@{$origwidtbl},$wid); - } - - return(\@cwid); -} - -sub IsText -{ - if ($mode eq 'g') - { - $xpos+=$pendmv/$unitwidth; - $stream.="q BT\n$matrix ".PutXY($xpos,$ypos)." Tm\n"; - $poschg=0; - $fontchg=0; - $pendmv=0; - $matrixchg=0; - $tmxpos=$xpos; - $stream.=$textcol."\n", $curfill=$textcol if $textcol ne $curfill; - if (defined($cft)) - { - $whtsz=$fontlst{$cft}->{FNT}->{spacewidth}*$cftsz; - $stream.="/F$cft"; - $stream.=".$cftsup" if $cftsup; - $stream.=" $cftsz Tf\n"; - } - $stream.="$curkern Tc\n"; - } - - if ($poschg or $matrixchg) - { - PutLine(0) if $matrixchg; - $stream.="$matrix ".PutXY($xpos,$ypos)." Tm\n", $poschg=0; - $tmxpos=$xpos; - $matrixchg=0; - $stream.="$curkern Tc\n"; - } - - if ($fontchg) - { - PutLine(0); - if (defined($cft)) - { - $whtsz=$fontlst{$cft}->{FNT}->{spacewidth}*$cftsz; - $stream.="/F$cft"; - $stream.=".$cftsup" if $cftsup; - $stream.=" $cftsz Tf\n"; - $fontchg=0; - } - } - - $mode='t'; -} - -sub IsGraphic -{ - if ($mode eq 't') - { - PutLine(); - $stream.="ET Q\n"; - $xpos+=($pendmv-$nomove)/$unitwidth; - $pendmv=0; - $nomove=0; - $stream.=$strkcol."\n", $curstrk=$strkcol if $strkcol ne $curstrk; - $curfill=$fillcol; - } - $mode='g'; -} - -sub do_s -{ - my $par=shift; - $par/=$unitwidth; - - if ($par != $cftsz and defined($cft)) - { - PutLine(); - $cftsz=$par; - Set_LWidth() if $lwidth < 1; -# $stream.="/F$cft $cftsz Tf\n"; - $fontchg=1; - $widtbl=CacheWid($cft); - } - else - { - $cftsz=$par; - Set_LWidth() if $lwidth < 1; - } -} - -sub Set_LWidth -{ - IsGraphic(); - $stream.=((($desc{res}/(72*$desc{sizescale}))*$linewidth*$cftsz)/1000)." w\n"; - return; -} - -sub do_m -{ - # Groff uses /m[] for text & graphic stroke, and /M[] (DF?) for graphic fill. - # PDF uses G/RG/K for graphic stroke, and g/rg/k for text & graphic fill. - # - # This means that we must maintain g/rg/k state separately for text colour & graphic fill (this is - # probably why 'gs' maintains separate graphic states for text & graphics when distilling PS -> PDF). - # - # To facilitate this:- - # - # $textcol = current groff stroke colour - # $fillcol = current groff fill colour - # $curfill = current PDF fill colour - - my $par=shift; - my $mcmd=substr($par,0,1); - - $par=substr($par,1); - $par=~s/^ +//; - -# IsGraphic(); - - $textcol=set_col($mcmd,$par,0); - $strkcol=set_col($mcmd,$par,1); - - if ($mode eq 't') - { - PutLine(); - $stream.=$textcol."\n"; - $curfill=$textcol; - } - else - { - $stream.="$strkcol\n"; - $curstrk=$strkcol; - } -} - -sub set_col -{ - my $mcmd=shift; - my $par=shift; - my $upper=shift; - my @oper=('g','k','rg'); - - @oper=('G','K','RG') if $upper; - - if ($mcmd eq 'd') - { - # default colour - return("0 $oper[0]"); - } - - my (@c)=split(' ',$par); - - if ($mcmd eq 'c') - { - # Text CMY - return(d3($c[0]/65535).' '.d3($c[1]/65535).' '.d3($c[2]/65535)." 0 $oper[1]"); - } - elsif ($mcmd eq 'k') - { - # Text CMYK - return(d3($c[0]/65535).' '.d3($c[1]/65535).' '.d3($c[2]/65535).' '.d3($c[3]/65535)." $oper[1]"); - } - elsif ($mcmd eq 'g') - { - # Text Grey - return(d3($c[0]/65535)." $oper[0]"); - } - elsif ($mcmd eq 'r') - { - # Text RGB0 - return(d3($c[0]/65535).' '.d3($c[1]/65535).' '.d3($c[2]/65535)." $oper[2]"); - } -} - -sub do_D -{ - my $par=shift; - my $Dcmd=substr($par,0,1); - - $par=substr($par,1); - $xpos+=$pendmv/$unitwidth; - $pendmv=0; - - IsGraphic(); - - if ($Dcmd eq 'F') - { - my $mcmd=substr($par,0,1); - - $par=substr($par,1); - $par=~s/^ +//; - - $fillcol=set_col($mcmd,$par,0); - $stream.="$fillcol\n"; - $curfill=$fillcol; - } - elsif ($Dcmd eq 'f') - { - my $mcmd=substr($par,0,1); - - $par=substr($par,1); - $par=~s/^ +//; - ($par)=split(' ',$par); - - if ($par >= 0 and $par <= 1000) - { - $fillcol=set_col('g',int((1000-$par)*65535/1000),0); - } - else - { - $fillcol=lc($textcol); - } - - $stream.="$fillcol\n"; - $curfill=$fillcol; - } - elsif ($Dcmd eq '~') - { - # B-Spline - my (@p)=split(' ',$par); - my ($nxpos,$nypos); - - foreach my $p (@p) { $p/=$unitwidth; } - $stream.=PutXY($xpos,$ypos)." m\n"; - $xpos+=($p[0]/2); - $ypos+=($p[1]/2); - $stream.=PutXY($xpos,$ypos)." l\n"; - - for (my $i=0; $i < $#p-1; $i+=2) - { - $nxpos=(($p[$i]*$tnum)/(2*$tden)); - $nypos=(($p[$i+1]*$tnum)/(2*$tden)); - $stream.=PutXY(($xpos+$nxpos),($ypos+$nypos))." "; - $nxpos=($p[$i]/2 + ($p[$i+2]*($tden-$tnum))/(2*$tden)); - $nypos=($p[$i+1]/2 + ($p[$i+3]*($tden-$tnum))/(2*$tden)); - $stream.=PutXY(($xpos+$nxpos),($ypos+$nypos))." "; - $nxpos=(($p[$i]-$p[$i]/2) + $p[$i+2]/2); - $nypos=(($p[$i+1]-$p[$i+1]/2) + $p[$i+3]/2); - $stream.=PutXY(($xpos+$nxpos),($ypos+$nypos))." c\n"; - $xpos+=$nxpos; - $ypos+=$nypos; - } - - $xpos+=($p[$#p-1]-$p[$#p-1]/2); - $ypos+=($p[$#p]-$p[$#p]/2); - $stream.=PutXY($xpos,$ypos)." l\nS\n"; - $poschg=1; - } - elsif ($Dcmd eq 'p' or $Dcmd eq 'P') - { - # Polygon - my (@p)=split(' ',$par); - my ($nxpos,$nypos); - - foreach my $p (@p) { $p/=$unitwidth; } - $stream.=PutXY($xpos,$ypos)." m\n"; - - for (my $i=0; $i < $#p; $i+=2) - { - $xpos+=($p[$i]); - $ypos+=($p[$i+1]); - $stream.=PutXY($xpos,$ypos)." l\n"; - } - - if ($Dcmd eq 'p') - { - $stream.="s\n"; - } - else - { - $stream.="f\n"; - } - $poschg=1; - } - elsif ($Dcmd eq 'c') - { - # Stroke circle - $par=substr($par,1); - my (@p)=split(' ',$par); - - DrawCircle($p[0],$p[0]); - $stream.="s\n"; - $poschg=1; - } - elsif ($Dcmd eq 'C') - { - # Fill circle - $par=substr($par,1); - my (@p)=split(' ',$par); - - DrawCircle($p[0],$p[0]); - $stream.="f\n"; - $poschg=1; - } - elsif ($Dcmd eq 'e') - { - # Stroke ellipse - $par=substr($par,1); - my (@p)=split(' ',$par); - - DrawCircle($p[0],$p[1]); - $stream.="s\n"; - $poschg=1; - } - elsif ($Dcmd eq 'E') - { - # Fill ellipse - $par=substr($par,1); - my (@p)=split(' ',$par); - - DrawCircle($p[0],$p[1]); - $stream.="f\n"; - $poschg=1; - } - elsif ($Dcmd eq 'l') - { - # Line To - $par=substr($par,1); - my (@p)=split(' ',$par); - - foreach my $p (@p) { $p/=$unitwidth; } - $stream.=PutXY($xpos,$ypos)." m\n"; - $xpos+=$p[0]; - $ypos+=$p[1]; - $stream.=PutXY($xpos,$ypos)." l\n"; - - $stream.="S\n"; - $poschg=1; - } - elsif ($Dcmd eq 't') - { - # Line Thickness - $par=substr($par,1); - my (@p)=split(' ',$par); - - foreach my $p (@p) { $p/=$unitwidth; } - # $xpos+=$p[0]*100; # WTF!!! - #int lw = ((font::res/(72*font::sizescale))*linewidth*env->size)/1000; - $p[0]=(($desc{res}/(72*$desc{sizescale}))*$linewidth*$cftsz)/1000 if $p[0] < 0; - $lwidth=$p[0]; - $stream.="$p[0] w\n"; - $poschg=1; - $xpos+=$lwidth; - } - elsif ($Dcmd eq 'a') - { - # Arc - $par=substr($par,1); - my (@p)=split(' ',$par); - my $rad180=3.14159; - my $rad360=$rad180*2; - my $rad90=$rad180/2; - - foreach my $p (@p) { $p/=$unitwidth; } - - # Documentation is wrong. Groff does not use Dh1,Dv1 as centre of the circle! - - my $centre=adjust_arc_centre(\@p); - - # Using formula here : http://www.tinaja.com/glib/bezcirc2.pdf - # First calculate angle between start and end point - - my ($startang,$r)=RtoP(-$centre->[0],$centre->[1]); - my ($endang,$r2)=RtoP(($p[0]+$p[2])-$centre->[0],-($p[1]+$p[3]-$centre->[1])); - $endang+=$rad360 if $endang < $startang; - my $totang=($endang-$startang)/4; # do it in 4 pieces - - # Now 1 piece - - my $x0=cos($totang/2); - my $y0=sin($totang/2); - my $x3=$x0; - my $y3=-$y0; - my $x1=(4-$x0)/3; - my $y1=((1-$x0)*(3-$x0))/(3*$y0); - my $x2=$x1; - my $y2=-$y1; - - # Rotate to start position and draw 4 pieces - - foreach my $j (0..3) - { - PlotArcSegment($totang/2+$startang+$j*$totang,$r,$xpos+$centre->[0],GraphY($ypos+$centre->[1]),$x0,$y0,$x1,$y1,$x2,$y2,$x3,$y3); - } - - $xpos+=$p[0]+$p[2]; - $ypos+=$p[1]+$p[3]; - - $poschg=1; - } -} - -sub deg -{ - return int($_[0]*180/3.14159); -} - -sub adjust_arc_centre -{ - # Taken from geometry.cpp - - # We move the center along a line parallel to the line between - # the specified start point and end point so that the center - # is equidistant between the start and end point. - # It can be proved (using Lagrange multipliers) that this will - # give the point nearest to the specified center that is equidistant - # between the start and end point. - - my $p=shift; - my @c; - my $x = $p->[0] + $p->[2]; # (x, y) is the end point - my $y = $p->[1] + $p->[3]; - my $n = $x*$x + $y*$y; - if ($n != 0) - { - $c[0]= $p->[0]; - $c[1] = $p->[1]; - my $k = .5 - ($c[0]*$x + $c[1]*$y)/$n; - $c[0] += $k*$x; - $c[1] += $k*$y; - return(\@c); - } - else - { - return(undef); - } -} - - -sub PlotArcSegment -{ - my ($ang,$r,$transx,$transy,$x0,$y0,$x1,$y1,$x2,$y2,$x3,$y3)=@_; - my $cos=cos($ang); - my $sin=sin($ang); - my @mat=($cos,$sin,-$sin,$cos,0,0); - my $lw=$lwidth/$r; - - $stream.="q $r 0 0 $r $transx $transy cm ".join(' ',@mat)." cm $lw w $x0 $y0 m $x1 $y1 $x2 $y2 $x3 $y3 c S Q\n"; -} - -sub DrawCircle -{ - my $hd=shift; - my $vd=shift; - my $hr=$hd/2/$unitwidth; - my $vr=$vd/2/$unitwidth; - my $kappa=0.5522847498; - $hd/=$unitwidth; - $vd/=$unitwidth; - - - $stream.=PutXY(($xpos+$hd),$ypos)." m\n"; - $stream.=PutXY(($xpos+$hd),($ypos+$vr*$kappa))." ".PutXY(($xpos+$hr+$hr*$kappa),($ypos+$vr))." ".PutXY(($xpos+$hr),($ypos+$vr))." c\n"; - $stream.=PutXY(($xpos+$hr-$hr*$kappa),($ypos+$vr))." ".PutXY(($xpos),($ypos+$vr*$kappa))." ".PutXY(($xpos),($ypos))." c\n"; - $stream.=PutXY(($xpos),($ypos-$vr*$kappa))." ".PutXY(($xpos+$hr-$hr*$kappa),($ypos-$vr))." ".PutXY(($xpos+$hr),($ypos-$vr))." c\n"; - $stream.=PutXY(($xpos+$hr+$hr*$kappa),($ypos-$vr))." ".PutXY(($xpos+$hd),($ypos-$vr*$kappa))." ".PutXY(($xpos+$hd),($ypos))." c\n"; - $xpos+=$hd; - - $poschg=1; -} - -sub FindCircle -{ - my ($x1,$y1,$x2,$y2,$x3,$y3)=@_; - my ($Xo, $Yo); - - my $x=$x2+$x3; - my $y=$y2+$y3; - my $n=$x**2+$y**2; - - if ($n) - { - my $k=.5-($x2*$x + $y2*$y)/$n; - return(sqrt($n),$x2+$k*$x,$y2+$k*$y); - } - else - { - return(-1); - } - -} - -sub PtoR -{ - my ($theta,$r)=@_; - - return($r*cos($theta),$r*sin($theta)); -} - -sub RtoP -{ - my ($x,$y)=@_; - - return(atan2($y,$x),sqrt($x**2+$y**2)); -} - -sub PutLine -{ - - my $f=shift; - - IsText() if !defined($f); - - return if (scalar(@lin) == 0) or (!defined($lin[0]->[0]) and $#lin == 0); - -# $stream.="% --- wht=$whtsz, pend=$pendmv, nomv=$nomove\n" if $debug; - $pendmv-=$nomove; - $lin[$#lin]->[1]=-$pendmv/$cftsz if ($pendmv != 0); - - foreach my $wd (@lin) - { - next if !defined($wd->[0]); - $wd->[0]=~s/\\/\\\\/g; - $wd->[0]=~s/\(/\\(/g; - $wd->[0]=~s/\)/\\)/g; - $wd->[0]=~s/!\|!\|/\\/g; - $wd->[1]=d3($wd->[1]); - } - - if (0) - { - if (scalar(@lin) == 1 and (!defined($lin[0]->[1]) or $lin[0]->[1] == 0)) - { - $stream.="($lin[0]->[0]) Tj\n"; - } - else - { - $stream.="["; - - foreach my $wd (@lin) - { - $stream.="($wd->[0]) " if defined($wd->[0]); - $stream.="$wd->[1] " if defined($wd->[1]) and $wd->[1] != 0; - } - - $stream.="] TJ\n"; - } - } - else - { - if (scalar(@lin) == 1 and (!defined($lin[0]->[1]) or $lin[0]->[1] == 0)) - { - $stream.="0 Tw ($lin[0]->[0]) Tj\n"; - } - else - { - if ($wt>=-1 or $#lin == 0 or $lin[0]->[1]>=0) - { - $stream.="0 Tw ["; - - foreach my $wd (@lin) - { - $stream.="($wd->[0]) " if defined($wd->[0]); - $stream.="$wd->[1] " if defined($wd->[1]) and $wd->[1] != 0; - } - - $stream.="] TJ\n"; - } - else - { - # $stream.="\%dg 0 Tw ["; - # - # foreach my $wd (@lin) - # { - # $stream.="($wd->[0]) " if defined($wd->[0]); - # $stream.="$wd->[1] " if defined($wd->[1]) and $wd->[1] != 0; - # } - # - # $stream.="] TJ\n"; - # - # my $wt=$lin[0]->[1]||0; - - # while ($wt < -$whtsz/$cftsz) - # { - # $wt+=$whtsz/$cftsz; - # } - - $stream.=sprintf( "%.3f Tw ",-($whtsz+$wt*$cftsz)/$unitwidth-$curkern ); - if (!defined($lin[0]->[0]) and defined($lin[0]->[1])) - { - $stream.="[ $lin[0]->[1] ("; - shift @lin; - } - else - { - $stream.="[("; - } - - foreach my $wd (@lin) - { - my $wwt=$wd->[1]||0; - - while ($wwt <= $wt+.1) - { - $wwt-=$wt; - $wd->[0].=' '; - } - - if (abs($wwt) < .1 or $wwt == 0) - { - $stream.="$wd->[0]" if defined($wd->[0]); - } - else - { - $wwt=sprintf("%.3f",$wwt); - $stream.="$wd->[0]) $wwt (" if defined($wd->[0]); - } - } - $stream.=")] TJ\n"; - } - } - } - - @lin=(); - $xpos+=$pendmv/$unitwidth; - $pendmv=0; - $nomove=0; - $wt=-1; -} - -sub d3 -{ - return(sprintf("%.3f",shift || 0)); -} - -sub LoadAhead -{ - my $no=shift; - - foreach my $j (1..$no) - { - my $lin=<>; - chomp($lin); - $lin=~s/\r$//; - $lct++; - - push(@ahead,$lin); - $stream.="%% $lin\n" if $debug; - } -} - -sub do_V -{ - my $par=shift; - - if ($mode eq 't') - { - PutLine(); - } - else - { - $xpos+=$pendmv/$unitwidth; - $pendmv=0; - } - - $ypos=$par/$unitwidth; - - LoadAhead(1); - - if (substr($ahead[0],0,1) eq 'H') - { - $xpos=substr($ahead[0],1)/$unitwidth; - - $nomove=$pendmv=0; - @ahead=(); - - } - - $poschg=1; -} - -sub do_v -{ - my $par=shift; - - PutLine() if $mode eq 't'; - - $ypos+=$par/$unitwidth; - - $poschg=1; -} - -sub TextWid -{ - my $txt=shift; - my $sup=shift; - my $fnt=shift; - my $w=0; - my $ck=0; - - foreach my $c (split('',$txt)) - { - my $cn=ord($c); - $cn+=$sup*256; - $widtbl->[$cn]=$origwidtbl->[$cn]*$cftsz if !defined($widtbl->[$cn]); - $w+=$widtbl->[$cn]; - } - - $ck=length($txt)*$curkern; - - return(($w/$unitwidth)+$ck); -} - -sub do_t -{ - my $par=shift; - my $fnt=$fontlst{$cft}->{FNT}; - my $sup = shift || 0; - $fontchg=1 if $cftsup != $sup; - $cftsup = $sup; - - if ($kernadjust != $curkern) - { - PutLine(); - $stream.="$kernadjust Tc\n"; - $curkern=$kernadjust; - } - - my $par2=$par; - $par2=~s/^!\|!\|(\d\d\d)/chr(oct($1))/e; - - foreach my $j (0..length($par2)-1) - { - my $cn=ord(substr($par2,$j,1)); - $cn+=$sup*256; - my $chnm=$fnt->{NO}->[$cn]->[1]; - - if (!$fnt->{NAM}->{$chnm}->[USED]) - { - my ($cn2, $sup2) = RemapChr($cn, $fnt, $chnm); - $stream.="% MMM Remap $cn,$sup to $cn2,$sup2\n" if $debug; - Msg(0, "got: $fnt->{NM}.$sup2; expected: $fnt->{NM}.$sup\n") if $sup != $sup2; - - #if ($cn2) - { - substr($par2,$j,1)=chr($cn2); - - if ($par=~m/^!\|!\|(\d\d\d)/) - { - substr($par,4,3)=sprintf("%03o",$cn2); - } - else - { - substr($par,$j,1)=chr($cn2); - } - } - } - } - my $wid=TextWid($par2,$sup,$fnt); - - $par=reverse(split('',$par)) if $xrev and $par!~m/^!\|!\|(\d\d\d)/; - - if ($n_flg and defined($mark)) - { - $mark->{ypos}=$ypos; - $mark->{xpos}=$xpos; - } - - $n_flg=0; - IsText(); - - $xpos+=$wid; - $xpos+=($pendmv-$nomove)/$unitwidth; - - $stream.="% == '$par'=$wid 'xpos=$xpos\n" if $debug; - - # $pendmv = 'h' move since last 't' - # $nomove = width of char(s) added by 'C', 'N' or 'c' - # $w-flg = 'w' seen since last t - - if ($fontchg) - { - PutLine(); - if (defined($cft)) - { - $whtsz=$fontlst{$cft}->{FNT}->{spacewidth} * $cftsz; - $stream.="/F$cft"; - $stream.=".$cftsup" if $cftsup; - $stream.=" $cftsz Tf\n"; - $fontchg=0; - } - } - - $gotT=1; - - $stream.="% --- wht=$whtsz, pend=$pendmv, nomv=$nomove\n" if $debug; - -# if ($w_flg && $#lin > -1) -# { -# $lin[$#lin]->[0].=' '; -# $pendmv-=$whtsz; -# $dontglue=1 if $pendmv==0; -# } - - $wt=-$pendmv/$cftsz if $w_flg and $wt==-1; - $pendmv-=$nomove; - $nomove=0; - $w_flg=0; - - if ($xrev) - { - PutLine(0) if $#lin > -1; - MakeMatrix(1); - $stream.="$matrix ".PutXY($xpos,$ypos)." Tm\n", $poschg=0; - $stream.="$curkern Tc\n"; - $stream.="0 Tw "; - $stream.="($par) Tj\n"; - MakeMatrix(); - $stream.="$matrix ".PutXY($xpos,$ypos)." Tm\n", $poschg=0; - $matrixchg=0; - $stream.="$curkern Tc\n"; - return; - } - - if ($pendmv) - { - if ($#lin == -1) - { - push(@lin,[undef,-$pendmv/$cftsz]); - } - else - { - $lin[$#lin]->[1]=-$pendmv/$cftsz; - } - - push(@lin,[$par,undef]); -# $xpos+=$pendmv/$unitwidth; - $pendmv=0 - } - else - { - if ($#lin == -1) - { - push(@lin,[$par,undef]); - } - else - { - $lin[$#lin]->[0].=$par; - } - } -} - -sub do_u -{ - my $par=shift; - - $par=m/([+-]?\d+) (.*)/; - $kernadjust=$1/$unitwidth; - do_t($2); - $kernadjust=0; -} - -sub do_h -{ - $pendmv+=shift; -} - -sub do_H -{ - my $par=shift; - - if ($mode eq 't') - { - PutLine(); - } - else - { - $xpos+=$pendmv/$unitwidth; - $pendmv=0; - } - - my $newx=$par/$unitwidth; - $stream.=sprintf("%.3f",$newx-$tmxpos)." 0 Td\n" if $mode eq 't'; - $tmxpos=$xpos=$newx; - $pendmv=$nomove=0; -} - -sub do_C -{ - my $par=shift; - - do_t(FindChar($par)); - $nomove=$fontlst{$cft}->{FNT}->{NAM}->{$par}->[WIDTH]*$cftsz ; -} - -sub FindChar -{ - my $chnm=shift; - my $fnt=$fontlst{$cft}->{FNT}; - - if (exists($fnt->{NAM}->{$chnm})) - { - my ($ch,$sup,$used)=@{$fnt->{NAM}->{$chnm}}[ASSIGNED,SUPPL,USED]; - ($ch,$sup) = RemapChr($ch,$fnt,$chnm) if !$used; - return ($ch<32)? sprintf("!|!|%03o",$ch) : chr($ch), $sup; - } - else - { - return(' '); - } -} - -sub RemapChr -{ - my $ch=shift; - my $fnt=shift; - my $chnm=shift; - my $unused; - - if ($use_suppl_font) { - - while (defined(my $un = shift @{$fnt->{REMAP}})) { - my $ux = $un + $fnt->{SUPPL} * 256; - my $glyph = $fnt->{NO}->[$ux]->[1]; - $unused = $un, last if !$glyph || !$fnt->{NAM}->{$glyph}->[USED]; - } - - if (!defined $unused) { - if (!$fnt->{NEXT}) { - my $fnt2 = { - %{$fnt}{qw/NM NO NAM/}, - SUPPL => $fnt->{SUPPL} + 1, - REMAP => [ 0..31, 33..255 ], - }; - $fnt->{NEXT} = $fnt2; - } - return RemapChr($ch, $fnt->{NEXT}, $chnm); - } - - my $ux = $unused + $fnt->{SUPPL} * 256; - my $glyph = $fnt->{NO}->[$ux]->[1]; - delete($fontlst{$cft}->{CACHE}->{$cftsz}); - @{$fnt->{NAM}->{$chnm}}[ASSIGNED, SUPPL, USED] = ($unused, $fnt->{SUPPL}, 1); - $fnt->{NO}->[$ux]->[1] = $chnm; - $widtbl = CacheWid($cft); - - $stream .= "% AAA Assign $chnm ($ch) to $unused ($fnt->{SUPPL})\n" if $debug; - - $ch = $unused; - return ($ch, $fnt->{SUPPL}); - } - - foreach my $un (0..$#{$fnt->{NO}}) - { - next if $un >= 139 and $un <= 144; - $unused=$un,last if $fnt->{NO}->[$un]->[1] eq ''; - } - - if (!defined $unused) - { - foreach my $un (128..255) - { - next if $un >= 139 and $un <= 144; - my $glyph=$fnt->{NO}->[$un]->[1]; - $unused=$un,last if $fnt->{NAM}->{$glyph}->[USED] == 0; - } - } - - if (defined $unused && $unused <= 255) - { - my $glyph=$fnt->{NO}->[$unused]->[1]; - delete($fontlst{$cft}->{CACHE}->{$cftsz}); - $fnt->{NAM}->{$chnm}->[ASSIGNED]=$unused; - $fnt->{NO}->[$unused]->[1]=$chnm; - $widtbl=CacheWid($cft); - - $stream.="% AAA Assign $chnm ($ch) to $unused\n" if $debug; - - $ch=$unused; - return($ch,0); - } - else - { - Msg(0,"Too many glyphs used in font '$cft'"); - return(32,0); - } -} - -sub do_c -{ - my $par=shift; - - push(@ahead,substr($par,1)); - $par=substr($par,0,1); - my $ch=ord($par); - do_N($ch); -} - -sub do_N -{ - my $par=shift; - my $fnt=$fontlst{$cft}->{FNT}; - - if (!defined($fnt->{NO}->[$par])) - { - Msg(0,"No chr($par) in font $fnt->{internalname}"); - return; - } - - my $chnm=$fnt->{NO}->[$par]->[0]; - do_C($chnm); -} - -sub do_n -{ - $gotT=0; - PutLine(0); - $pendmv=$nomove=0; - $n_flg=1; - @lin=(); - PutHotSpot($xpos) if defined($mark); -} - - -1; -######################################################################## -### Emacs settings -# Local Variables: -# mode: CPerl -# End: diff --git a/scripts/LinuxManBook/hyphen.en b/scripts/LinuxManBook/hyphen.en deleted file mode 100644 index bd9b757..0000000 --- a/scripts/LinuxManBook/hyphen.en +++ /dev/null @@ -1,5018 +0,0 @@ -% title: Hyphenation patterns for American English -% copyright: Copyright (C) 1990, 2004, 2005 Gerard D.C. Kuiken -% notice: This file is part of the hyph-utf8 package. -% See http://www.hyphenation.org/tex for more information. -% language: -% name: English, American spelling -% tag: en-us -% version: 2005-05-30 -% authors: -% - -% name: Gerard D.C. Kuiken -% licence: -% text: > -% Copying and distribution of this file, with or without modification, -% are permitted in any medium without royalty provided the copyright -% notice and this notice are preserved. -% hyphenmins: -% typesetting: -% left: 2 -% right: 3 -% changes: -% March 1, 1990 Initial release -% May 30, 2005 Added copyright notice, no patterns change. -% texlive: -% encoding: ascii -% babelname: usenglishmax -% legacy_patterns: ushyphmax.tex -% message: Hyphenation patterns for American English -% package: english -% known_bugs: -% de-mo-c-rat: 'instead of dem-o-crat (see GitHub issue #15)' -% ========================================== -% -% ushyphmax.tex -- patterns for more hyphenation pattern memory (12000+). -% Also known as ushyphen.max. -% -% Needs extended pattern memory. -% Hyphenation trie becomes 7283 with 377 ops. -% -% These patterns are based on the Hyphenation Exception Log -% published in TUGboat, Volume 10 (1989), No. 3, pp. 337-341, -% and a large number of incorrectly hyphenated words not yet published. -% If added to Liang's before the closing bracket } of \patterns, -% the patterns run errorfree as far as known at this moment. -% -% These patterns find all admissible hyphens of the words in -% the Exception Log. ushyph2.tex is a smaller set. -% -% Please send bugs or suggestions to tex-live (at) tug.org. -% -% 2005-05-30 (karl): in the past, ushyphmax.tex was a file containing -% only the additional patterns, without the \patterns command, etc. -% This turned out not to be very useful, since in practice the TeX -% distributions need one self-contained file for a language. Therefore, -% ushyphmax.tex now contains both the additional patterns from -% Dr. Kuiken, and the original patterns and hyphenations from Knuth's -% hyphen.tex. -% -% The Plain TeX hyphenation tables. -\patterns{ % just type if you're not using INITEX -.ach4 -.ad4der -.af1t -.al3t -.am5at -.an5c -.ang4 -.ani5m -.ant4 -.an3te -.anti5s -.ar5s -.ar4tie -.ar4ty -.as3c -.as1p -.as1s -.aster5 -.atom5 -.au1d -.av4i -.awn4 -.ba4g -.ba5na -.bas4e -.ber4 -.be5ra -.be3sm -.be5sto -.bri2 -.but4ti -.cam4pe -.can5c -.capa5b -.car5ol -.ca4t -.ce4la -.ch4 -.chill5i -.ci2 -.cit5r -.co3e -.co4r -.cor5ner -.de4moi -.de3o -.de3ra -.de3ri -.des4c -.dictio5 -.do4t -.du4c -.dumb5 -.earth5 -.eas3i -.eb4 -.eer4 -.eg2 -.el5d -.el3em -.enam3 -.en3g -.en3s -.eq5ui5t -.er4ri -.es3 -.eu3 -.eye5 -.fes3 -.for5mer -.ga2 -.ge2 -.gen3t4 -.ge5og -.gi5a -.gi4b -.go4r -.hand5i -.han5k -.he2 -.hero5i -.hes3 -.het3 -.hi3b -.hi3er -.hon5ey -.hon3o -.hov5 -.id4l -.idol3 -.im3m -.im5pin -.in1 -.in3ci -.ine2 -.in2k -.in3s -.ir5r -.is4i -.ju3r -.la4cy -.la4m -.lat5er -.lath5 -.le2 -.leg5e -.len4 -.lep5 -.lev1 -.li4g -.lig5a -.li2n -.li3o -.li4t -.mag5a5 -.mal5o -.man5a -.mar5ti -.me2 -.mer3c -.me5ter -.mis1 -.mist5i -.mon3e -.mo3ro -.mu5ta -.muta5b -.ni4c -.od2 -.odd5 -.of5te -.or5ato -.or3c -.or1d -.or3t -.os3 -.os4tl -.oth3 -.out3 -.ped5al -.pe5te -.pe5tit -.pi4e -.pio5n -.pi2t -.pre3m -.ra4c -.ran4t -.ratio5na -.ree2 -.re5mit -.res2 -.re5stat -.ri4g -.rit5u -.ro4q -.ros5t -.row5d -.ru4d -.sci3e -.self5 -.sell5 -.se2n -.se5rie -.sh2 -.si2 -.sing4 -.st4 -.sta5bl -.sy2 -.ta4 -.te4 -.ten5an -.th2 -.ti2 -.til4 -.tim5o5 -.ting4 -.tin5k -.ton4a -.to4p -.top5i -.tou5s -.trib5ut -.un1a -.un3ce -.under5 -.un1e -.un5k -.un5o -.un3u -.up3 -.ure3 -.us5a -.ven4de -.ve5ra -.wil5i -.ye4 -4ab. -a5bal -a5ban -abe2 -ab5erd -abi5a -ab5it5ab -ab5lat -ab5o5liz -4abr -ab5rog -ab3ul -a4car -ac5ard -ac5aro -a5ceou -ac1er -a5chet -4a2ci -a3cie -ac1in -a3cio -ac5rob -act5if -ac3ul -ac4um -a2d -ad4din -ad5er. -2adi -a3dia -ad3ica -adi4er -a3dio -a3dit -a5diu -ad4le -ad3ow -ad5ran -ad4su -4adu -a3duc -ad5um -ae4r -aeri4e -a2f -aff4 -a4gab -aga4n -ag5ell -age4o -4ageu -ag1i -4ag4l -ag1n -a2go -3agog -ag3oni -a5guer -ag5ul -a4gy -a3ha -a3he -ah4l -a3ho -ai2 -a5ia -a3ic. -ai5ly -a4i4n -ain5in -ain5o -ait5en -a1j -ak1en -al5ab -al3ad -a4lar -4aldi -2ale -al3end -a4lenti -a5le5o -al1i -al4ia. -ali4e -al5lev -4allic -4alm -a5log. -a4ly. -4alys -5a5lyst -5alyt -3alyz -4ama -am5ab -am3ag -ama5ra -am5asc -a4matis -a4m5ato -am5era -am3ic -am5if -am5ily -am1in -ami4no -a2mo -a5mon -amor5i -amp5en -a2n -an3age -3analy -a3nar -an3arc -anar4i -a3nati -4and -ande4s -an3dis -an1dl -an4dow -a5nee -a3nen -an5est. -a3neu -2ang -ang5ie -an1gl -a4n1ic -a3nies -an3i3f -an4ime -a5nimi -a5nine -an3io -a3nip -an3ish -an3it -a3niu -an4kli -5anniz -ano4 -an5ot -anoth5 -an2sa -an4sco -an4sn -an2sp -ans3po -an4st -an4sur -antal4 -an4tie -4anto -an2tr -an4tw -an3ua -an3ul -a5nur -4ao -apar4 -ap5at -ap5ero -a3pher -4aphi -a4pilla -ap5illar -ap3in -ap3ita -a3pitu -a2pl -apoc5 -ap5ola -apor5i -apos3t -aps5es -a3pu -aque5 -2a2r -ar3act -a5rade -ar5adis -ar3al -a5ramete -aran4g -ara3p -ar4at -a5ratio -ar5ativ -a5rau -ar5av4 -araw4 -arbal4 -ar4chan -ar5dine -ar4dr -ar5eas -a3ree -ar3ent -a5ress -ar4fi -ar4fl -ar1i -ar5ial -ar3ian -a3riet -ar4im -ar5inat -ar3io -ar2iz -ar2mi -ar5o5d -a5roni -a3roo -ar2p -ar3q -arre4 -ar4sa -ar2sh -4as. -as4ab -as3ant -ashi4 -a5sia. -a3sib -a3sic -5a5si4t -ask3i -as4l -a4soc -as5ph -as4sh -as3ten -as1tr -asur5a -a2ta -at3abl -at5ac -at3alo -at5ap -ate5c -at5ech -at3ego -at3en. -at3era -ater5n -a5terna -at3est -at5ev -4ath -ath5em -a5then -at4ho -ath5om -4ati. -a5tia -at5i5b -at1ic -at3if -ation5ar -at3itu -a4tog -a2tom -at5omiz -a4top -a4tos -a1tr -at5rop -at4sk -at4tag -at5te -at4th -a2tu -at5ua -at5ue -at3ul -at3ura -a2ty -au4b -augh3 -au3gu -au4l2 -aun5d -au3r -au5sib -aut5en -au1th -a2va -av3ag -a5van -ave4no -av3era -av5ern -av5ery -av1i -avi4er -av3ig -av5oc -a1vor -3away -aw3i -aw4ly -aws4 -ax4ic -ax4id -ay5al -aye4 -ays4 -azi4er -azz5i -5ba. -bad5ger -ba4ge -bal1a -ban5dag -ban4e -ban3i -barbi5 -bari4a -bas4si -1bat -ba4z -2b1b -b2be -b3ber -bbi4na -4b1d -4be. -beak4 -beat3 -4be2d -be3da -be3de -be3di -be3gi -be5gu -1bel -be1li -be3lo -4be5m -be5nig -be5nu -4bes4 -be3sp -be5str -3bet -bet5iz -be5tr -be3tw -be3w -be5yo -2bf -4b3h -bi2b -bi4d -3bie -bi5en -bi4er -2b3if -1bil -bi3liz -bina5r4 -bin4d -bi5net -bi3ogr -bi5ou -bi2t -3bi3tio -bi3tr -3bit5ua -b5itz -b1j -bk4 -b2l2 -blath5 -b4le. -blen4 -5blesp -b3lis -b4lo -blun4t -4b1m -4b3n -bne5g -3bod -bod3i -bo4e -bol3ic -bom4bi -bon4a -bon5at -3boo -5bor. -4b1ora -bor5d -5bore -5bori -5bos4 -b5ota -both5 -bo4to -bound3 -4bp -4brit -broth3 -2b5s2 -bsor4 -2bt -bt4l -b4to -b3tr -buf4fer -bu4ga -bu3li -bumi4 -bu4n -bunt4i -bu3re -bus5ie -buss4e -5bust -4buta -3butio -b5uto -b1v -4b5w -5by. -bys4 -1ca -cab3in -ca1bl -cach4 -ca5den -4cag4 -2c5ah -ca3lat -cal4la -call5in -4calo -can5d -can4e -can4ic -can5is -can3iz -can4ty -cany4 -ca5per -car5om -cast5er -cas5tig -4casy -ca4th -4cativ -cav5al -c3c -ccha5 -cci4a -ccompa5 -ccon4 -ccou3t -2ce. -4ced. -4ceden -3cei -5cel. -3cell -1cen -3cenc -2cen4e -4ceni -3cent -3cep -ce5ram -4cesa -3cessi -ces5si5b -ces5t -cet4 -c5e4ta -cew4 -2ch -4ch. -4ch3ab -5chanic -ch5a5nis -che2 -cheap3 -4ched -che5lo -3chemi -ch5ene -ch3er. -ch3ers -4ch1in -5chine. -ch5iness -5chini -5chio -3chit -chi2z -3cho2 -ch4ti -1ci -3cia -ci2a5b -cia5r -ci5c -4cier -5cific. -4cii -ci4la -3cili -2cim -2cin -c4ina -3cinat -cin3em -c1ing -c5ing. -5cino -cion4 -4cipe -ci3ph -4cipic -4cista -4cisti -2c1it -cit3iz -5ciz -ck1 -ck3i -1c4l4 -4clar -c5laratio -5clare -cle4m -4clic -clim4 -cly4 -c5n -1co -co5ag -coe2 -2cog -co4gr -coi4 -co3inc -col5i -5colo -col3or -com5er -con4a -c4one -con3g -con5t -co3pa -cop3ic -co4pl -4corb -coro3n -cos4e -cov1 -cove4 -cow5a -coz5e -co5zi -c1q -cras5t -5crat. -5cratic -cre3at -5cred -4c3reta -cre4v -cri2 -cri5f -c4rin -cris4 -5criti -cro4pl -crop5o -cros4e -cru4d -4c3s2 -2c1t -cta4b -ct5ang -c5tant -c2te -c3ter -c4ticu -ctim3i -ctu4r -c4tw -cud5 -c4uf -c4ui -cu5ity -5culi -cul4tis -3cultu -cu2ma -c3ume -cu4mi -3cun -cu3pi -cu5py -cur5a4b -cu5ria -1cus -cuss4i -3c4ut -cu4tie -4c5utiv -4cutr -1cy -cze4 -1d2a -5da. -2d3a4b -dach4 -4daf -2dag -da2m2 -dan3g -dard5 -dark5 -4dary -3dat -4dativ -4dato -5dav4 -dav5e -5day -d1b -d5c -d1d4 -2de. -deaf5 -deb5it -de4bon -decan4 -de4cil -de5com -2d1ed -4dee. -de5if -deli4e -del5i5q -de5lo -d4em -5dem. -3demic -dem5ic. -de5mil -de4mons -demor5 -1den -de4nar -de3no -denti5f -de3nu -de1p -de3pa -depi4 -de2pu -d3eq -d4erh -5derm -dern5iz -der5s -des2 -d2es. -de1sc -de2s5o -des3ti -de3str -de4su -de1t -de2to -de1v -dev3il -4dey -4d1f -d4ga -d3ge4t -dg1i -d2gy -d1h2 -5di. -1d4i3a -dia5b -di4cam -d4ice -3dict -3did -5di3en -d1if -di3ge -di4lato -d1in -1dina -3dine. -5dini -di5niz -1dio -dio5g -di4pl -dir2 -di1re -dirt5i -dis1 -5disi -d4is3t -d2iti -1di1v -d1j -d5k2 -4d5la -3dle. -3dled -3dles. -4dless -2d3lo -4d5lu -2dly -d1m -4d1n4 -1do -3do. -do5de -5doe -2d5of -d4og -do4la -doli4 -do5lor -dom5iz -do3nat -doni4 -doo3d -dop4p -d4or -3dos -4d5out -do4v -3dox -d1p -1dr -drag5on -4drai -dre4 -drea5r -5dren -dri4b -dril4 -dro4p -4drow -5drupli -4dry -2d1s2 -ds4p -d4sw -d4sy -d2th -1du -d1u1a -du2c -d1uca -duc5er -4duct. -4ducts -du5el -du4g -d3ule -dum4be -du4n -4dup -du4pe -d1v -d1w -d2y -5dyn -dy4se -dys5p -e1a4b -e3act -ead1 -ead5ie -ea4ge -ea5ger -ea4l -eal5er -eal3ou -eam3er -e5and -ear3a -ear4c -ear5es -ear4ic -ear4il -ear5k -ear2t -eart3e -ea5sp -e3ass -east3 -ea2t -eat5en -eath3i -e5atif -e4a3tu -ea2v -eav3en -eav5i -eav5o -2e1b -e4bel. -e4bels -e4ben -e4bit -e3br -e4cad -ecan5c -ecca5 -e1ce -ec5essa -ec2i -e4cib -ec5ificat -ec5ifie -ec5ify -ec3im -eci4t -e5cite -e4clam -e4clus -e2col -e4comm -e4compe -e4conc -e2cor -ec3ora -eco5ro -e1cr -e4crem -ec4tan -ec4te -e1cu -e4cul -ec3ula -2e2da -4ed3d -e4d1er -ede4s -4edi -e3dia -ed3ib -ed3ica -ed3im -ed1it -edi5z -4edo -e4dol -edon2 -e4dri -e4dul -ed5ulo -ee2c -eed3i -ee2f -eel3i -ee4ly -ee2m -ee4na -ee4p1 -ee2s4 -eest4 -ee4ty -e5ex -e1f -e4f3ere -1eff -e4fic -5efici -efil4 -e3fine -ef5i5nite -3efit -efor5es -e4fuse. -4egal -eger4 -eg5ib -eg4ic -eg5ing -e5git5 -eg5n -e4go. -e4gos -eg1ul -e5gur -5egy -e1h4 -eher4 -ei2 -e5ic -ei5d -eig2 -ei5gl -e3imb -e3inf -e1ing -e5inst -eir4d -eit3e -ei3th -e5ity -e1j -e4jud -ej5udi -eki4n -ek4la -e1la -e4la. -e4lac -elan4d -el5ativ -e4law -elaxa4 -e3lea -el5ebra -5elec -e4led -el3ega -e5len -e4l1er -e1les -el2f -el2i -e3libe -e4l5ic. -el3ica -e3lier -el5igib -e5lim -e4l3ing -e3lio -e2lis -el5ish -e3liv3 -4ella -el4lab -ello4 -e5loc -el5og -el3op. -el2sh -el4ta -e5lud -el5ug -e4mac -e4mag -e5man -em5ana -em5b -e1me -e2mel -e4met -em3ica -emi4e -em5igra -em1in2 -em5ine -em3i3ni -e4mis -em5ish -e5miss -em3iz -5emniz -emo4g -emoni5o -em3pi -e4mul -em5ula -emu3n -e3my -en5amo -e4nant -ench4er -en3dic -e5nea -e5nee -en3em -en5ero -en5esi -en5est -en3etr -e3new -en5ics -e5nie -e5nil -e3nio -en3ish -en3it -e5niu -5eniz -4enn -4eno -eno4g -e4nos -en3ov -en4sw -ent5age -4enthes -en3ua -en5uf -e3ny. -4en3z -e5of -eo2g -e4oi4 -e3ol -eop3ar -e1or -eo3re -eo5rol -eos4 -e4ot -eo4to -e5out -e5ow -e2pa -e3pai -ep5anc -e5pel -e3pent -ep5etitio -ephe4 -e4pli -e1po -e4prec -ep5reca -e4pred -ep3reh -e3pro -e4prob -ep4sh -ep5ti5b -e4put -ep5uta -e1q -equi3l -e4q3ui3s -er1a -era4b -4erand -er3ar -4erati. -2erb -er4bl -er3ch -er4che -2ere. -e3real -ere5co -ere3in -er5el. -er3emo -er5ena -er5ence -4erene -er3ent -ere4q -er5ess -er3est -eret4 -er1h -er1i -e1ria4 -5erick -e3rien -eri4er -er3ine -e1rio -4erit -er4iu -eri4v -e4riva -er3m4 -er4nis -4ernit -5erniz -er3no -2ero -er5ob -e5roc -ero4r -er1ou -er1s -er3set -ert3er -4ertl -er3tw -4eru -eru4t -5erwau -e1s4a -e4sage. -e4sages -es2c -e2sca -es5can -e3scr -es5cu -e1s2e -e2sec -es5ecr -es5enc -e4sert. -e4serts -e4serva -4esh -e3sha -esh5en -e1si -e2sic -e2sid -es5iden -es5igna -e2s5im -es4i4n -esis4te -esi4u -e5skin -es4mi -e2sol -es3olu -e2son -es5ona -e1sp -es3per -es5pira -es4pre -2ess -es4si4b -estan4 -es3tig -es5tim -4es2to -e3ston -2estr -e5stro -estruc5 -e2sur -es5urr -es4w -eta4b -eten4d -e3teo -ethod3 -et1ic -e5tide -etin4 -eti4no -e5tir -e5titio -et5itiv -4etn -et5ona -e3tra -e3tre -et3ric -et5rif -et3rog -et5ros -et3ua -et5ym -et5z -4eu -e5un -e3up -eu3ro -eus4 -eute4 -euti5l -eu5tr -eva2p5 -e2vas -ev5ast -e5vea -ev3ell -evel3o -e5veng -even4i -ev1er -e5verb -e1vi -ev3id -evi4l -e4vin -evi4v -e5voc -e5vu -e1wa -e4wag -e5wee -e3wh -ewil5 -ew3ing -e3wit -1exp -5eyc -5eye. -eys4 -1fa -fa3bl -fab3r -fa4ce -4fag -fain4 -fall5e -4fa4ma -fam5is -5far -far5th -fa3ta -fa3the -4fato -fault5 -4f5b -4fd -4fe. -feas4 -feath3 -fe4b -4feca -5fect -2fed -fe3li -fe4mo -fen2d -fend5e -fer1 -5ferr -fev4 -4f1f -f4fes -f4fie -f5fin. -f2f5is -f4fly -f2fy -4fh -1fi -fi3a -2f3ic. -4f3ical -f3ican -4ficate -f3icen -fi3cer -fic4i -5ficia -5ficie -4fics -fi3cu -fi5del -fight5 -fil5i -fill5in -4fily -2fin -5fina -fin2d5 -fi2ne -f1in3g -fin4n -fis4ti -f4l2 -f5less -flin4 -flo3re -f2ly5 -4fm -4fn -1fo -5fon -fon4de -fon4t -fo2r -fo5rat -for5ay -fore5t -for4i -fort5a -fos5 -4f5p -fra4t -f5rea -fres5c -fri2 -fril4 -frol5 -2f3s -2ft -f4to -f2ty -3fu -fu5el -4fug -fu4min -fu5ne -fu3ri -fusi4 -fus4s -4futa -1fy -1ga -gaf4 -5gal. -3gali -ga3lo -2gam -ga5met -g5amo -gan5is -ga3niz -gani5za -4gano -gar5n4 -gass4 -gath3 -4gativ -4gaz -g3b -gd4 -2ge. -2ged -geez4 -gel4in -ge5lis -ge5liz -4gely -1gen -ge4nat -ge5niz -4geno -4geny -1geo -ge3om -g4ery -5gesi -geth5 -4geto -ge4ty -ge4v -4g1g2 -g2ge -g3ger -gglu5 -ggo4 -gh3in -gh5out -gh4to -5gi. -1gi4a -gia5r -g1ic -5gicia -g4ico -gien5 -5gies. -gil4 -g3imen -3g4in. -gin5ge -5g4ins -5gio -3gir -gir4l -g3isl -gi4u -5giv -3giz -gl2 -gla4 -glad5i -5glas -1gle -gli4b -g3lig -3glo -glo3r -g1m -g4my -gn4a -g4na. -gnet4t -g1ni -g2nin -g4nio -g1no -g4non -1go -3go. -gob5 -5goe -3g4o4g -go3is -gon2 -4g3o3na -gondo5 -go3ni -5goo -go5riz -gor5ou -5gos. -gov1 -g3p -1gr -4grada -g4rai -gran2 -5graph. -g5rapher -5graphic -4graphy -4gray -gre4n -4gress. -4grit -g4ro -gruf4 -gs2 -g5ste -gth3 -gu4a -3guard -2gue -5gui5t -3gun -3gus -4gu4t -g3w -1gy -2g5y3n -gy5ra -h3ab4l -hach4 -hae4m -hae4t -h5agu -ha3la -hala3m -ha4m -han4ci -han4cy -5hand. -han4g -hang5er -hang5o -h5a5niz -han4k -han4te -hap3l -hap5t -ha3ran -ha5ras -har2d -hard3e -har4le -harp5en -har5ter -has5s -haun4 -5haz -haz3a -h1b -1head -3hear -he4can -h5ecat -h4ed -he5do5 -he3l4i -hel4lis -hel4ly -h5elo -hem4p -he2n -hena4 -hen5at -heo5r -hep5 -h4era -hera3p -her4ba -here5a -h3ern -h5erou -h3ery -h1es -he2s5p -he4t -het4ed -heu4 -h1f -h1h -hi5an -hi4co -high5 -h4il2 -himer4 -h4ina -hion4e -hi4p -hir4l -hi3ro -hir4p -hir4r -his3el -his4s -hith5er -hi2v -4hk -4h1l4 -hlan4 -h2lo -hlo3ri -4h1m -hmet4 -2h1n -h5odiz -h5ods -ho4g -hoge4 -hol5ar -3hol4e -ho4ma -home3 -hon4a -ho5ny -3hood -hoon4 -hor5at -ho5ris -hort3e -ho5ru -hos4e -ho5sen -hos1p -1hous -house3 -hov5el -4h5p -4hr4 -hree5 -hro5niz -hro3po -4h1s2 -h4sh -h4tar -ht1en -ht5es -h4ty -hu4g -hu4min -hun5ke -hun4t -hus3t4 -hu4t -h1w -h4wart -hy3pe -hy3ph -hy2s -2i1a -i2al -iam4 -iam5ete -i2an -4ianc -ian3i -4ian4t -ia5pe -iass4 -i4ativ -ia4tric -i4atu -ibe4 -ib3era -ib5ert -ib5ia -ib3in -ib5it. -ib5ite -i1bl -ib3li -i5bo -i1br -i2b5ri -i5bun -4icam -5icap -4icar -i4car. -i4cara -icas5 -i4cay -iccu4 -4iceo -4ich -2ici -i5cid -ic5ina -i2cip -ic3ipa -i4cly -i2c5oc -4i1cr -5icra -i4cry -ic4te -ictu2 -ic4t3ua -ic3ula -ic4um -ic5uo -i3cur -2id -i4dai -id5anc -id5d -ide3al -ide4s -i2di -id5ian -idi4ar -i5die -id3io -idi5ou -id1it -id5iu -i3dle -i4dom -id3ow -i4dr -i2du -id5uo -2ie4 -ied4e -5ie5ga -ield3 -ien5a4 -ien4e -i5enn -i3enti -i1er. -i3esc -i1est -i3et -4if. -if5ero -iff5en -if4fr -4ific. -i3fie -i3fl -4ift -2ig -iga5b -ig3era -ight3i -4igi -i3gib -ig3il -ig3in -ig3it -i4g4l -i2go -ig3or -ig5ot -i5gre -igu5i -ig1ur -i3h -4i5i4 -i3j -4ik -i1la -il3a4b -i4lade -i2l5am -ila5ra -i3leg -il1er -ilev4 -il5f -il1i -il3ia -il2ib -il3io -il4ist -2ilit -il2iz -ill5ab -4iln -il3oq -il4ty -il5ur -il3v -i4mag -im3age -ima5ry -imenta5r -4imet -im1i -im5ida -imi5le -i5mini -4imit -im4ni -i3mon -i2mu -im3ula -2in. -i4n3au -4inav -incel4 -in3cer -4ind -in5dling -2ine -i3nee -iner4ar -i5ness -4inga -4inge -in5gen -4ingi -in5gling -4ingo -4ingu -2ini -i5ni. -i4nia -in3io -in1is -i5nite. -5initio -in3ity -4ink -4inl -2inn -2i1no -i4no4c -ino4s -i4not -2ins -in3se -insur5a -2int. -2in4th -in1u -i5nus -4iny -2io -4io. -ioge4 -io2gr -i1ol -io4m -ion3at -ion4ery -ion3i -io5ph -ior3i -i4os -io5th -i5oti -io4to -i4our -2ip -ipe4 -iphras4 -ip3i -ip4ic -ip4re4 -ip3ul -i3qua -iq5uef -iq3uid -iq3ui3t -4ir -i1ra -ira4b -i4rac -ird5e -ire4de -i4ref -i4rel4 -i4res -ir5gi -ir1i -iri5de -ir4is -iri3tu -5i5r2iz -ir4min -iro4g -5iron. -ir5ul -2is. -is5ag -is3ar -isas5 -2is1c -is3ch -4ise -is3er -3isf -is5han -is3hon -ish5op -is3ib -isi4d -i5sis -is5itiv -4is4k -islan4 -4isms -i2so -iso5mer -is1p -is2pi -is4py -4is1s -is4sal -issen4 -is4ses -is4ta. -is1te -is1ti -ist4ly -4istral -i2su -is5us -4ita. -ita4bi -i4tag -4ita5m -i3tan -i3tat -2ite -it3era -i5teri -it4es -2ith -i1ti -4itia -4i2tic -it3ica -5i5tick -it3ig -it5ill -i2tim -2itio -4itis -i4tism -i2t5o5m -4iton -i4tram -it5ry -4itt -it3uat -i5tud -it3ul -4itz. -i1u -2iv -iv3ell -iv3en. -i4v3er. -i4vers. -iv5il. -iv5io -iv1it -i5vore -iv3o3ro -i4v3ot -4i5w -ix4o -4iy -4izar -izi4 -5izont -5ja -jac4q -ja4p -1je -jer5s -4jestie -4jesty -jew3 -jo4p -5judg -3ka. -k3ab -k5ag -kais4 -kal4 -k1b -k2ed -1kee -ke4g -ke5li -k3en4d -k1er -kes4 -k3est. -ke4ty -k3f -kh4 -k1i -5ki. -5k2ic -k4ill -kilo5 -k4im -k4in. -kin4de -k5iness -kin4g -ki4p -kis4 -k5ish -kk4 -k1l -4kley -4kly -k1m -k5nes -1k2no -ko5r -kosh4 -k3ou -kro5n -4k1s2 -k4sc -ks4l -k4sy -k5t -k1w -lab3ic -l4abo -laci4 -l4ade -la3dy -lag4n -lam3o -3land -lan4dl -lan5et -lan4te -lar4g -lar3i -las4e -la5tan -4lateli -4lativ -4lav -la4v4a -2l1b -lbin4 -4l1c2 -lce4 -l3ci -2ld -l2de -ld4ere -ld4eri -ldi4 -ld5is -l3dr -l4dri -le2a -le4bi -left5 -5leg. -5legg -le4mat -lem5atic -4len. -3lenc -5lene. -1lent -le3ph -le4pr -lera5b -ler4e -3lerg -3l4eri -l4ero -les2 -le5sco -5lesq -3less -5less. -l3eva -lev4er. -lev4era -lev4ers -3ley -4leye -2lf -l5fr -4l1g4 -l5ga -lgar3 -l4ges -lgo3 -2l3h -li4ag -li2am -liar5iz -li4as -li4ato -li5bi -5licio -li4cor -4lics -4lict. -l4icu -l3icy -l3ida -lid5er -3lidi -lif3er -l4iff -li4fl -5ligate -3ligh -li4gra -3lik -4l4i4l -lim4bl -lim3i -li4mo -l4im4p -l4ina -1l4ine -lin3ea -lin3i -link5er -li5og -4l4iq -lis4p -l1it -l2it. -5litica -l5i5tics -liv3er -l1iz -4lj -lka3 -l3kal -lka4t -l1l -l4law -l2le -l5lea -l3lec -l3leg -l3lel -l3le4n -l3le4t -ll2i -l2lin4 -l5lina -ll4o -lloqui5 -ll5out -l5low -2lm -l5met -lm3ing -l4mod -lmon4 -2l1n2 -3lo. -lob5al -lo4ci -4lof -3logic -l5ogo -3logu -lom3er -5long -lon4i -l3o3niz -lood5 -5lope. -lop3i -l3opm -lora4 -lo4rato -lo5rie -lor5ou -5los. -los5et -5losophiz -5losophy -los4t -lo4ta -loun5d -2lout -4lov -2lp -lpa5b -l3pha -l5phi -lp5ing -l3pit -l4pl -l5pr -4l1r -2l1s2 -l4sc -l2se -l4sie -4lt -lt5ag -ltane5 -l1te -lten4 -ltera4 -lth3i -l5ties. -ltis4 -l1tr -ltu2 -ltur3a -lu5a -lu3br -luch4 -lu3ci -lu3en -luf4 -lu5id -lu4ma -5lumi -l5umn. -5lumnia -lu3o -luo3r -4lup -luss4 -lus3te -1lut -l5ven -l5vet4 -2l1w -1ly -4lya -4lyb -ly5me -ly3no -2lys4 -l5yse -1ma -2mab -ma2ca -ma5chine -ma4cl -mag5in -5magn -2mah -maid5 -4mald -ma3lig -ma5lin -mal4li -mal4ty -5mania -man5is -man3iz -4map -ma5rine. -ma5riz -mar4ly -mar3v -ma5sce -mas4e -mas1t -5mate -math3 -ma3tis -4matiza -4m1b -mba4t5 -m5bil -m4b3ing -mbi4v -4m5c -4me. -2med -4med. -5media -me3die -m5e5dy -me2g -mel5on -mel4t -me2m -mem1o3 -1men -men4a -men5ac -men4de -4mene -men4i -mens4 -mensu5 -3ment -men4te -me5on -m5ersa -2mes -3mesti -me4ta -met3al -me1te -me5thi -m4etr -5metric -me5trie -me3try -me4v -4m1f -2mh -5mi. -mi3a -mid4a -mid4g -mig4 -3milia -m5i5lie -m4ill -min4a -3mind -m5inee -m4ingl -min5gli -m5ingly -min4t -m4inu -miot4 -m2is -mis4er. -mis5l -mis4ti -m5istry -4mith -m2iz -4mk -4m1l -m1m -mma5ry -4m1n -mn4a -m4nin -mn4o -1mo -4mocr -5mocratiz -mo2d1 -mo4go -mois2 -moi5se -4mok -mo5lest -mo3me -mon5et -mon5ge -moni3a -mon4ism -mon4ist -mo3niz -monol4 -mo3ny. -mo2r -4mora. -mos2 -mo5sey -mo3sp -moth3 -m5ouf -3mous -mo2v -4m1p -mpara5 -mpa5rab -mpar5i -m3pet -mphas4 -m2pi -mpi4a -mp5ies -m4p1in -m5pir -mp5is -mpo3ri -mpos5ite -m4pous -mpov5 -mp4tr -m2py -4m3r -4m1s2 -m4sh -m5si -4mt -1mu -mula5r4 -5mult -multi3 -3mum -mun2 -4mup -mu4u -4mw -1na -2n1a2b -n4abu -4nac. -na4ca -n5act -nag5er. -nak4 -na4li -na5lia -4nalt -na5mit -n2an -nanci4 -nan4it -nank4 -nar3c -4nare -nar3i -nar4l -n5arm -n4as -nas4c -nas5ti -n2at -na3tal -nato5miz -n2au -nau3se -3naut -nav4e -4n1b4 -ncar5 -n4ces. -n3cha -n5cheo -n5chil -n3chis -nc1in -nc4it -ncour5a -n1cr -n1cu -n4dai -n5dan -n1de -nd5est. -ndi4b -n5d2if -n1dit -n3diz -n5duc -ndu4r -nd2we -2ne. -n3ear -ne2b -neb3u -ne2c -5neck -2ned -ne4gat -neg5ativ -5nege -ne4la -nel5iz -ne5mi -ne4mo -1nen -4nene -3neo -ne4po -ne2q -n1er -nera5b -n4erar -n2ere -n4er5i -ner4r -1nes -2nes. -4nesp -2nest -4nesw -3netic -ne4v -n5eve -ne4w -n3f -n4gab -n3gel -nge4n4e -n5gere -n3geri -ng5ha -n3gib -ng1in -n5git -n4gla -ngov4 -ng5sh -n1gu -n4gum -n2gy -4n1h4 -nha4 -nhab3 -nhe4 -3n4ia -ni3an -ni4ap -ni3ba -ni4bl -ni4d -ni5di -ni4er -ni2fi -ni5ficat -n5igr -nik4 -n1im -ni3miz -n1in -5nine. -nin4g -ni4o -5nis. -nis4ta -n2it -n4ith -3nitio -n3itor -ni3tr -n1j -4nk2 -n5kero -n3ket -nk3in -n1kl -4n1l -n5m -nme4 -nmet4 -4n1n2 -nne4 -nni3al -nni4v -nob4l -no3ble -n5ocl -4n3o2d -3noe -4nog -noge4 -nois5i -no5l4i -5nologis -3nomic -n5o5miz -no4mo -no3my -no4n -non4ag -non5i -n5oniz -4nop -5nop5o5li -nor5ab -no4rary -4nosc -nos4e -nos5t -no5ta -1nou -3noun -nov3el3 -nowl3 -n1p4 -npi4 -npre4c -n1q -n1r -nru4 -2n1s2 -ns5ab -nsati4 -ns4c -n2se -n4s3es -nsid1 -nsig4 -n2sl -ns3m -n4soc -ns4pe -n5spi -nsta5bl -n1t -nta4b -nter3s -nt2i -n5tib -nti4er -nti2f -n3tine -n4t3ing -nti4p -ntrol5li -nt4s -ntu3me -nu1a -nu4d -nu5en -nuf4fe -n3uin -3nu3it -n4um -nu1me -n5umi -3nu4n -n3uo -nu3tr -n1v2 -n1w4 -nym4 -nyp4 -4nz -n3za -4oa -oad3 -o5a5les -oard3 -oas4e -oast5e -oat5i -ob3a3b -o5bar -obe4l -o1bi -o2bin -ob5ing -o3br -ob3ul -o1ce -och4 -o3chet -ocif3 -o4cil -o4clam -o4cod -oc3rac -oc5ratiz -ocre3 -5ocrit -octor5a -oc3ula -o5cure -od5ded -od3ic -odi3o -o2do4 -odor3 -od5uct. -od5ucts -o4el -o5eng -o3er -oe4ta -o3ev -o2fi -of5ite -ofit4t -o2g5a5r -og5ativ -o4gato -o1ge -o5gene -o5geo -o4ger -o3gie -1o1gis -og3it -o4gl -o5g2ly -3ogniz -o4gro -ogu5i -1ogy -2ogyn -o1h2 -ohab5 -oi2 -oic3es -oi3der -oiff4 -oig4 -oi5let -o3ing -oint5er -o5ism -oi5son -oist5en -oi3ter -o5j -2ok -o3ken -ok5ie -o1la -o4lan -olass4 -ol2d -old1e -ol3er -o3lesc -o3let -ol4fi -ol2i -o3lia -o3lice -ol5id. -o3li4f -o5lil -ol3ing -o5lio -o5lis. -ol3ish -o5lite -o5litio -o5liv -olli4e -ol5ogiz -olo4r -ol5pl -ol2t -ol3ub -ol3ume -ol3un -o5lus -ol2v -o2ly -om5ah -oma5l -om5atiz -om2be -om4bl -o2me -om3ena -om5erse -o4met -om5etry -o3mia -om3ic. -om3ica -o5mid -om1in -o5mini -5ommend -omo4ge -o4mon -om3pi -ompro5 -o2n -on1a -on4ac -o3nan -on1c -3oncil -2ond -on5do -o3nen -on5est -on4gu -on1ic -o3nio -on1is -o5niu -on3key -on4odi -on3omy -on3s -onspi4 -onspir5a -onsu4 -onten4 -on3t4i -ontif5 -on5um -onva5 -oo2 -ood5e -ood5i -oo4k -oop3i -o3ord -oost5 -o2pa -ope5d -op1er -3opera -4operag -2oph -o5phan -o5pher -op3ing -o3pit -o5pon -o4posi -o1pr -op1u -opy5 -o1q -o1ra -o5ra. -o4r3ag -or5aliz -or5ange -ore5a -o5real -or3ei -ore5sh -or5est. -orew4 -or4gu -4o5ria -or3ica -o5ril -or1in -o1rio -or3ity -o3riu -or2mi -orn2e -o5rof -or3oug -or5pe -3orrh -or4se -ors5en -orst4 -or3thi -or3thy -or4ty -o5rum -o1ry -os3al -os2c -os4ce -o3scop -4oscopi -o5scr -os4i4e -os5itiv -os3ito -os3ity -osi4u -os4l -o2so -os4pa -os4po -os2ta -o5stati -os5til -os5tit -o4tan -otele4g -ot3er. -ot5ers -o4tes -4oth -oth5esi -oth3i4 -ot3ic. -ot5ica -o3tice -o3tif -o3tis -oto5s -ou2 -ou3bl -ouch5i -ou5et -ou4l -ounc5er -oun2d -ou5v -ov4en -over4ne -over3s -ov4ert -o3vis -oviti4 -o5v4ol -ow3der -ow3el -ow5est -ow1i -own5i -o4wo -oy1a -1pa -pa4ca -pa4ce -pac4t -p4ad -5pagan -p3agat -p4ai -pain4 -p4al -pan4a -pan3el -pan4ty -pa3ny -pa1p -pa4pu -para5bl -par5age -par5di -3pare -par5el -p4a4ri -par4is -pa2te -pa5ter -5pathic -pa5thy -pa4tric -pav4 -3pay -4p1b -pd4 -4pe. -3pe4a -pear4l -pe2c -2p2ed -3pede -3pedi -pedia4 -ped4ic -p4ee -pee4d -pek4 -pe4la -peli4e -pe4nan -p4enc -pen4th -pe5on -p4era. -pera5bl -p4erag -p4eri -peri5st -per4mal -perme5 -p4ern -per3o -per3ti -pe5ru -per1v -pe2t -pe5ten -pe5tiz -4pf -4pg -4ph. -phar5i -phe3no -ph4er -ph4es. -ph1ic -5phie -ph5ing -5phisti -3phiz -ph2l -3phob -3phone -5phoni -pho4r -4phs -ph3t -5phu -1phy -pi3a -pian4 -pi4cie -pi4cy -p4id -p5ida -pi3de -5pidi -3piec -pi3en -pi4grap -pi3lo -pi2n -p4in. -pind4 -p4ino -3pi1o -pion4 -p3ith -pi5tha -pi2tu -2p3k2 -1p2l2 -3plan -plas5t -pli3a -pli5er -4plig -pli4n -ploi4 -plu4m -plum4b -4p1m -2p3n -po4c -5pod. -po5em -po3et5 -5po4g -poin2 -5point -poly5t -po4ni -po4p -1p4or -po4ry -1pos -pos1s -p4ot -po4ta -5poun -4p1p -ppa5ra -p2pe -p4ped -p5pel -p3pen -p3per -p3pet -ppo5site -pr2 -pray4e -5preci -pre5co -pre3em -pref5ac -pre4la -pre3r -p3rese -3press -pre5ten -pre3v -5pri4e -prin4t3 -pri4s -pris3o -p3roca -prof5it -pro3l -pros3e -pro1t -2p1s2 -p2se -ps4h -p4sib -2p1t -pt5a4b -p2te -p2th -pti3m -ptu4r -p4tw -pub3 -pue4 -puf4 -pul3c -pu4m -pu2n -pur4r -5pus -pu2t -5pute -put3er -pu3tr -put4ted -put4tin -p3w -qu2 -qua5v -2que. -3quer -3quet -2rab -ra3bi -rach4e -r5acl -raf5fi -raf4t -r2ai -ra4lo -ram3et -r2ami -rane5o -ran4ge -r4ani -ra5no -rap3er -3raphy -rar5c -rare4 -rar5ef -4raril -r2as -ration4 -rau4t -ra5vai -rav3el -ra5zie -r1b -r4bab -r4bag -rbi2 -rbi4f -r2bin -r5bine -rb5ing. -rb4o -r1c -r2ce -rcen4 -r3cha -rch4er -r4ci4b -rc4it -rcum3 -r4dal -rd2i -rdi4a -rdi4er -rdin4 -rd3ing -2re. -re1al -re3an -re5arr -5reav -re4aw -r5ebrat -rec5oll -rec5ompe -re4cre -2r2ed -re1de -re3dis -red5it -re4fac -re2fe -re5fer. -re3fi -re4fy -reg3is -re5it -re1li -re5lu -r4en4ta -ren4te -re1o -re5pin -re4posi -re1pu -r1er4 -r4eri -rero4 -re5ru -r4es. -re4spi -ress5ib -res2t -re5stal -re3str -re4ter -re4ti4z -re3tri -reu2 -re5uti -rev2 -re4val -rev3el -r5ev5er. -re5vers -re5vert -re5vil -rev5olu -re4wh -r1f -rfu4 -r4fy -rg2 -rg3er -r3get -r3gic -rgi4n -rg3ing -r5gis -r5git -r1gl -rgo4n -r3gu -rh4 -4rh. -4rhal -ri3a -ria4b -ri4ag -r4ib -rib3a -ric5as -r4ice -4rici -5ricid -ri4cie -r4ico -rid5er -ri3enc -ri3ent -ri1er -ri5et -rig5an -5rigi -ril3iz -5riman -rim5i -3rimo -rim4pe -r2ina -5rina. -rin4d -rin4e -rin4g -ri1o -5riph -riph5e -ri2pl -rip5lic -r4iq -r2is -r4is. -ris4c -r3ish -ris4p -ri3ta3b -r5ited. -rit5er. -rit5ers -rit3ic -ri2tu -rit5ur -riv5el -riv3et -riv3i -r3j -r3ket -rk4le -rk4lin -r1l -rle4 -r2led -r4lig -r4lis -rl5ish -r3lo4 -r1m -rma5c -r2me -r3men -rm5ers -rm3ing -r4ming. -r4mio -r3mit -r4my -r4nar -r3nel -r4ner -r5net -r3ney -r5nic -r1nis4 -r3nit -r3niv -rno4 -r4nou -r3nu -rob3l -r2oc -ro3cr -ro4e -ro1fe -ro5fil -rok2 -ro5ker -5role. -rom5ete -rom4i -rom4p -ron4al -ron4e -ro5n4is -ron4ta -1room -5root -ro3pel -rop3ic -ror3i -ro5ro -ros5per -ros4s -ro4the -ro4ty -ro4va -rov5el -rox5 -r1p -r4pea -r5pent -rp5er. -r3pet -rp4h4 -rp3ing -r3po -r1r4 -rre4c -rre4f -r4reo -rre4st -rri4o -rri4v -rron4 -rros4 -rrys4 -4rs2 -r1sa -rsa5ti -rs4c -r2se -r3sec -rse4cr -rs5er. -rs3es -rse5v2 -r1sh -r5sha -r1si -r4si4b -rson3 -r1sp -r5sw -rtach4 -r4tag -r3teb -rten4d -rte5o -r1ti -rt5ib -rti4d -r4tier -r3tig -rtil3i -rtil4l -r4tily -r4tist -r4tiv -r3tri -rtroph4 -rt4sh -ru3a -ru3e4l -ru3en -ru4gl -ru3in -rum3pl -ru2n -runk5 -run4ty -r5usc -ruti5n -rv4e -rvel4i -r3ven -rv5er. -r5vest -r3vey -r3vic -rvi4v -r3vo -r1w -ry4c -5rynge -ry3t -sa2 -2s1ab -5sack -sac3ri -s3act -5sai -salar4 -sal4m -sa5lo -sal4t -3sanc -san4de -s1ap -sa5ta -5sa3tio -sat3u -sau4 -sa5vor -5saw -4s5b -scan4t5 -sca4p -scav5 -s4ced -4scei -s4ces -sch2 -s4cho -3s4cie -5scin4d -scle5 -s4cli -scof4 -4scopy -scour5a -s1cu -4s5d -4se. -se4a -seas4 -sea5w -se2c3o -3sect -4s4ed -se4d4e -s5edl -se2g -seg3r -5sei -se1le -5self -5selv -4seme -se4mol -sen5at -4senc -sen4d -s5ened -sen5g -s5enin -4sentd -4sentl -sep3a3 -4s1er. -s4erl -ser4o -4servo -s1e4s -se5sh -ses5t -5se5um -5sev -sev3en -sew4i -5sex -4s3f -2s3g -s2h -2sh. -sh1er -5shev -sh1in -sh3io -3ship -shiv5 -sho4 -sh5old -shon3 -shor4 -short5 -4shw -si1b -s5icc -3side. -5sides -5sidi -si5diz -4signa -sil4e -4sily -2s1in -s2ina -5sine. -s3ing -1sio -5sion -sion5a -si2r -sir5a -1sis -3sitio -5siu -1siv -5siz -sk2 -4ske -s3ket -sk5ine -sk5ing -s1l2 -s3lat -s2le -slith5 -2s1m -s3ma -small3 -sman3 -smel4 -s5men -5smith -smol5d4 -s1n4 -1so -so4ce -soft3 -so4lab -sol3d2 -so3lic -5solv -3som -3s4on. -sona4 -son4g -s4op -5sophic -s5ophiz -s5ophy -sor5c -sor5d -4sov -so5vi -2spa -5spai -spa4n -spen4d -2s5peo -2sper -s2phe -3spher -spho5 -spil4 -sp5ing -4spio -s4ply -s4pon -spor4 -4spot -squal4l -s1r -2ss -s1sa -ssas3 -s2s5c -s3sel -s5seng -s4ses. -s5set -s1si -s4sie -ssi4er -ss5ily -s4sl -ss4li -s4sn -sspend4 -ss2t -ssur5a -ss5w -2st. -s2tag -s2tal -stam4i -5stand -s4ta4p -5stat. -s4ted -stern5i -s5tero -ste2w -stew5a -s3the -st2i -s4ti. -s5tia -s1tic -5stick -s4tie -s3tif -st3ing -5stir -s1tle -5stock -stom3a -5stone -s4top -3store -st4r -s4trad -5stratu -s4tray -s4trid -4stry -4st3w -s2ty -1su -su1al -su4b3 -su2g3 -su5is -suit3 -s4ul -su2m -sum3i -su2n -su2r -4sv -sw2 -4swo -s4y -4syc -3syl -syn5o -sy5rin -1ta -3ta. -2tab -ta5bles -5taboliz -4taci -ta5do -4taf4 -tai5lo -ta2l -ta5la -tal5en -tal3i -4talk -tal4lis -ta5log -ta5mo -tan4de -tanta3 -ta5per -ta5pl -tar4a -4tarc -4tare -ta3riz -tas4e -ta5sy -4tatic -ta4tur -taun4 -tav4 -2taw -tax4is -2t1b -4tc -t4ch -tch5et -4t1d -4te. -tead4i -4teat -tece4 -5tect -2t1ed -te5di -1tee -teg4 -te5ger -te5gi -3tel. -teli4 -5tels -te2ma2 -tem3at -3tenan -3tenc -3tend -4tenes -1tent -ten4tag -1teo -te4p -te5pe -ter3c -5ter3d -1teri -ter5ies -ter3is -teri5za -5ternit -ter5v -4tes. -4tess -t3ess. -teth5e -3teu -3tex -4tey -2t1f -4t1g -2th. -than4 -th2e -4thea -th3eas -the5at -the3is -3thet -th5ic. -th5ica -4thil -5think -4thl -th5ode -5thodic -4thoo -thor5it -tho5riz -2ths -1tia -ti4ab -ti4ato -2ti2b -4tick -t4ico -t4ic1u -5tidi -3tien -tif2 -ti5fy -2tig -5tigu -till5in -1tim -4timp -tim5ul -2t1in -t2ina -3tine. -3tini -1tio -ti5oc -tion5ee -5tiq -ti3sa -3tise -tis4m -ti5so -tis4p -5tistica -ti3tl -ti4u -1tiv -tiv4a -1tiz -ti3za -ti3zen -2tl -t5la -tlan4 -3tle. -3tled -3tles. -t5let. -t5lo -4t1m -tme4 -2t1n2 -1to -to3b -to5crat -4todo -2tof -to2gr -to5ic -to2ma -tom4b -to3my -ton4ali -to3nat -4tono -4tony -to2ra -to3rie -tor5iz -tos2 -5tour -4tout -to3war -4t1p -1tra -tra3b -tra5ch -traci4 -trac4it -trac4te -tras4 -tra5ven -trav5es5 -tre5f -tre4m -trem5i -5tria -tri5ces -5tricia -4trics -2trim -tri4v -tro5mi -tron5i -4trony -tro5phe -tro3sp -tro3v -tru5i -trus4 -4t1s2 -t4sc -tsh4 -t4sw -4t3t2 -t4tes -t5to -ttu4 -1tu -tu1a -tu3ar -tu4bi -tud2 -4tue -4tuf4 -5tu3i -3tum -tu4nis -2t3up. -3ture -5turi -tur3is -tur5o -tu5ry -3tus -4tv -tw4 -4t1wa -twis4 -4two -1ty -4tya -2tyl -type3 -ty5ph -4tz -tz4e -4uab -uac4 -ua5na -uan4i -uar5ant -uar2d -uar3i -uar3t -u1at -uav4 -ub4e -u4bel -u3ber -u4bero -u1b4i -u4b5ing -u3ble. -u3ca -uci4b -uc4it -ucle3 -u3cr -u3cu -u4cy -ud5d -ud3er -ud5est -udev4 -u1dic -ud3ied -ud3ies -ud5is -u5dit -u4don -ud4si -u4du -u4ene -uens4 -uen4te -uer4il -3ufa -u3fl -ugh3en -ug5in -2ui2 -uil5iz -ui4n -u1ing -uir4m -uita4 -uiv3 -uiv4er. -u5j -4uk -u1la -ula5b -u5lati -ulch4 -5ulche -ul3der -ul4e -u1len -ul4gi -ul2i -u5lia -ul3ing -ul5ish -ul4lar -ul4li4b -ul4lis -4ul3m -u1l4o -4uls -uls5es -ul1ti -ultra3 -4ultu -u3lu -ul5ul -ul5v -um5ab -um4bi -um4bly -u1mi -u4m3ing -umor5o -um2p -unat4 -u2ne -un4er -u1ni -un4im -u2nin -un5ish -uni3v -un3s4 -un4sw -unt3ab -un4ter. -un4tes -unu4 -un5y -un5z -u4ors -u5os -u1ou -u1pe -uper5s -u5pia -up3ing -u3pl -up3p -upport5 -upt5ib -uptu4 -u1ra -4ura. -u4rag -u4ras -ur4be -urc4 -ur1d -ure5at -ur4fer -ur4fr -u3rif -uri4fic -ur1in -u3rio -u1rit -ur3iz -ur2l -url5ing. -ur4no -uros4 -ur4pe -ur4pi -urs5er -ur5tes -ur3the -urti4 -ur4tie -u3ru -2us -u5sad -u5san -us4ap -usc2 -us3ci -use5a -u5sia -u3sic -us4lin -us1p -us5sl -us5tere -us1tr -u2su -usur4 -uta4b -u3tat -4ute. -4utel -4uten -uten4i -4u1t2i -uti5liz -u3tine -ut3ing -ution5a -u4tis -5u5tiz -u4t1l -ut5of -uto5g -uto5matic -u5ton -u4tou -uts4 -u3u -uu4m -u1v2 -uxu3 -uz4e -1va -5va. -2v1a4b -vac5il -vac3u -vag4 -va4ge -va5lie -val5o -val1u -va5mo -va5niz -va5pi -var5ied -3vat -4ve. -4ved -veg3 -v3el. -vel3li -ve4lo -v4ely -ven3om -v5enue -v4erd -5vere. -v4erel -v3eren -ver5enc -v4eres -ver3ie -vermi4n -3verse -ver3th -v4e2s -4ves. -ves4te -ve4te -vet3er -ve4ty -vi5ali -5vian -5vide. -5vided -4v3iden -5vides -5vidi -v3if -vi5gn -vik4 -2vil -5vilit -v3i3liz -v1in -4vi4na -v2inc -vin5d -4ving -vio3l -v3io4r -vi1ou -vi4p -vi5ro -vis3it -vi3so -vi3su -4viti -vit3r -4vity -3viv -5vo. -voi4 -3vok -vo4la -v5ole -5volt -3volv -vom5i -vor5ab -vori4 -vo4ry -vo4ta -4votee -4vv4 -v4y -w5abl -2wac -wa5ger -wag5o -wait5 -w5al. -wam4 -war4t -was4t -wa1te -wa5ver -w1b -wea5rie -weath3 -wed4n -weet3 -wee5v -wel4l -w1er -west3 -w3ev -whi4 -wi2 -wil2 -will5in -win4de -win4g -wir4 -3wise -with3 -wiz5 -w4k -wl4es -wl3in -w4no -1wo2 -wom1 -wo5ven -w5p -wra4 -wri4 -writa4 -w3sh -ws4l -ws4pe -w5s4t -4wt -wy4 -x1a -xac5e -x4ago -xam3 -x4ap -xas5 -x3c2 -x1e -xe4cuto -x2ed -xer4i -xe5ro -x1h -xhi2 -xhil5 -xhu4 -x3i -xi5a -xi5c -xi5di -x4ime -xi5miz -x3o -x4ob -x3p -xpan4d -xpecto5 -xpe3d -x1t2 -x3ti -x1u -xu3a -xx4 -y5ac -3yar4 -y5at -y1b -y1c -y2ce -yc5er -y3ch -ych4e -ycom4 -ycot4 -y1d -y5ee -y1er -y4erf -yes4 -ye4t -y5gi -4y3h -y1i -y3la -ylla5bl -y3lo -y5lu -ymbol5 -yme4 -ympa3 -yn3chr -yn5d -yn5g -yn5ic -5ynx -y1o4 -yo5d -y4o5g -yom4 -yo5net -y4ons -y4os -y4ped -yper5 -yp3i -y3po -y4poc -yp2ta -y5pu -yra5m -yr5ia -y3ro -yr4r -ys4c -y3s2e -ys3ica -ys3io -3ysis -y4so -yss4 -ys1t -ys3ta -ysur4 -y3thin -yt3ic -y1w -za1 -z5a2b -zar2 -4zb -2ze -ze4n -ze4p -z1er -ze3ro -zet4 -2z1i -z4il -z4is -5zl -4zm -1zo -zo4m -zo5ol -zte4 -4z1z2 -z4zy -% hyphen.tex patterns end here, and additional patterns begin: -.con5gr -.de5riva -.dri5v4 -.eth1y6l1 -.eu4ler -.ev2 -.ever5si5b -.ga4s1om1 -.ge4ome -.ge5ot1 -.he3mo1 -.he3p6a -.he3roe -.in5u2t -.kil2n3i -.ko6r1te1 -.le6ices -.me4ga1l -.met4ala -.mim5i2c1 -.mi1s4ers -.ne6o3f -.noe1th -.non1e2m -.poly1s -.post1am -.pre1am -.rav5en1o -.semi5 -.sem4ic -.semid6 -.semip4 -.semir4 -.sem6is4 -.semiv4 -.sph6in1 -.spin1o -.ta5pes1tr -.te3legr -.to6pog -.to2q -.un3at5t -.un5err5 -.vi2c3ar -.we2b1l -.re1e4c -a5bolic -a2cabl -af6fish -am1en3ta5b -anal6ys -ano5a2c -ans5gr -ans3v -anti1d -an3ti1n2 -anti1re -a4pe5able -ar3che5t -ar2range -as5ymptot -ath3er1o1s -at6tes. -augh4tl -au5li5f -av3iou -back2er. -ba6r1onie -ba1thy -bbi4t -be2vie -bi5d2if -bil2lab -bio5m -bi1orb -bio1rh -b1i3tive -blan2d1 -blin2d1 -blon2d2 -bor1no5 -bo2t1u1l -brus4q -bus6i2er -bus6i2es -buss4ing -but2ed. -but4ted -cad5e1m -cat1a1s2 -4chs. -chs3hu -chie5vo -cig3a3r -cin2q -cle4ar -co6ph1o3n -cous2ti -cri3tie -croc1o1d -cro5e2co -c2tro3me6c -1cu2r1ance -2d3alone -data1b -dd5a5b -d2d5ib -de4als. -de5clar1 -de2c5lina -de3fin3iti -de2mos -des3ic -de2tic -dic1aid -dif5fra -3di1methy -di2ren -di2rer -2d1lead -2d1li2e -3do5word -dren1a5l -drif2t1a -d1ri3pleg5 -drom3e5d -d3tab -du2al. -du1op1o1l -ea4n3ies -e3chas -edg1l -ed1uling -eli2t1is -e1loa -en1dix -eo3grap -1e6p3i3neph1 -e2r3i4an. -e3spac6i -eth1y6l1ene -5eu2clid1 -feb1rua -fermi1o -3fich -fit5ted. -fla1g6el -flow2er. -3fluor -gen2cy. -ge3o1d -ght1we -g1lead -get2ic. -4g1lish -5glo5bin -1g2nac -gnet1ism -gno5mo -g2n1or. -g2noresp -2g1o4n3i1za -graph5er. -griev1 -g1utan -hair1s -ha2p3ar5r -hatch1 -hex2a3 -hite3sid -h3i5pel1a4 -hnau3z -ho6r1ic. -h2t1eou -hypo1tha -id4ios -ifac1et -ign4it -ignit1er -i4jk -im3ped3a -infra1s2 -i5nitely. -irre6v3oc -i1tesima -ith5i2l -itin5er5ar -janu3a -japan1e2s -je1re1m -1ke6ling -1ki5netic -1kovian -k3sha -la4c3i5e -lai6n3ess -lar5ce1n -l3chai -l3chil6d1 -lead6er. -lea4s1a -1lec3ta6b -le3g6en2dre -1le1noid -lith1o5g -ll1fl -l2l3ish -l5mo3nell -lo1bot1o1 -lo2ges. -load4ed. -load6er. -l3tea -lth5i2ly -lue1p -1lunk3er -1lum5bia. -3lyg1a1mi -ly5styr -ma1la1p -m2an. -man3u1sc -mar1gin1 -medi2c -med3i3cin -medio6c1 -me3gran3 -m2en. -3mi3da5b -3milita -mil2l1ag -mil5li5li -mi6n3is. -mi1n2ut1er -mi1n2ut1est -m3ma1b -5maph1ro1 -5moc1ra1t -mo5e2las -mol1e5c -mon4ey1l -mono3ch -mo4no1en -moro6n5is -mono1s6 -moth4et2 -m1ou3sin -m5shack2 -mu2dro -mul2ti5u -n3ar4chs. -n3ch2es1t -ne3back -2ne1ski -n1dieck -nd3thr -nfi6n3ites -4n5i4an. -nge5nes -ng1ho -ng1spr -nk3rup -n5less -5noc3er1os -nom1a6l -nom5e1no -n1o1mist -non1eq -non1i4so -5nop1oly. -no1vemb -ns5ceiv -ns4moo -ntre1p -obli2g1 -o3chas -odel3li -odit1ic -oerst2 -oke1st -o3les3ter -oli3gop1o1 -o1lo3n4om -o3mecha6 -onom1ic -o3norma -o3no2t1o3n -o3nou -op1ism. -or4tho3ni4t -orth1ri -or5tively -o4s3pher -o5test1er -o5tes3tor -oth3e1o1s -ou3ba3do -o6v3i4an. -oxi6d1ic -pal6mat -parag6ra4 -par4a1le -param4 -para3me -pee2v1 -phi2l3ant -phi5lat1e3l -pi2c1a3d -pli2c1ab -pli5nar -poin3ca -1pole. -poly1e -po3lyph1ono -1prema3c -pre1neu -pres2pli -pro2cess -proc3i3ty. -pro2g1e -3pseu2d -pseu3d6o3d2 -pseu3d6o3f2 -pto3mat4 -p5trol3 -pu5bes5c -quain2t1e -qu6a3si3 -quasir6 -quasis6 -quin5tes5s -qui3v4ar -r1abolic -3rab1o1loi -ra3chu -r3a3dig -radi1o6g -r2amen -3ra4m5e1triz -ra3mou -ra5n2has -ra1or -r3bin1ge -re2c3i1pr -rec5t6ang -re4t1ribu -r3ial. -riv1o1l -6rk. -rk1ho -r1krau -6rks. -r5le5qu -ro1bot1 -ro5e2las -ro5epide1 -ro3mesh -ro1tron -r3pau5li -rse1rad1i -r1thou -r1treu -r1veil -rz1sc -sales3c -sales5w -5sa3par5il -sca6p1er -sca2t1ol -s4chitz -schro1ding1 -1sci2utt -scrap4er. -scy4th1 -sem1a1ph -se3mes1t -se1mi6t5ic -sep3temb -shoe1st -sid2ed. -side5st -side5sw -si5resid -sky1sc -3slova1kia -3s2og1a1my -so2lute -3s2pace -1s2pacin -spe3cio -spher1o -spi2c1il -spokes5w -sports3c -sports3w -s3qui3to -s2s1a3chu1 -ss3hat -s2s3i4an. -s5sign5a3b -1s2tamp -s2t1ant5shi -star3tli -sta1ti -st5b -1stor1ab -strat1a1g -strib5ut -st5scr -stu1pi4d1 -styl1is -su2per1e6 -1sync -1syth3i2 -swimm6 -5tab1o1lism -ta3gon. -talk1a5 -t1a1min -t6ap6ath -5tar2rh -tch1c -tch3i1er -t1cr -teach4er. -tele2g -tele1r6o -3ter1gei -ter2ic. -t3ess2es -tha4l1am -tho3don -th1o5gen1i -tho1k2er -thy4l1an -thy3sc -2t3i4an. -ti2n3o1m -t1li2er -tolo2gy -tot3ic -trai3tor1 -tra1vers -travers3a3b -treach1e -tr4ial. -3tro1le1um -trof4ic. -tro3fit -tro1p2is -3trop1o5les -3trop1o5lis -t1ro1pol3it -tsch3ie -ttrib1ut1 -turn3ar -t1wh -ty2p5al -ua3drati -uad1ratu -u5do3ny -uea1m -u2r1al. -uri4al. -us2er. -v1ativ -v1oir5du1 -va6guer -vaude3v -1verely. -v1er1eig -ves1tite -vi1vip3a3r -voice1p -waste3w6a2 -wave1g4 -w3c -week1n -wide5sp -wo4k1en -wrap3aro -writ6er. -x1q -xquis3 -y5che3d -ym5e5try -y1stro -yes5ter1y -z3ian. -z3o1phr -z2z3w -% end of additional patterns. -} -% DEK's hyphenation exception list, from hyphen.tex; not changed. -\hyphenation{ -as-so-ciate -as-so-ciates -dec-li-na-tion -oblig-a-tory -phil-an-thropic -present -presents -project -projects -reci-procity -re-cog-ni-zance -ref-or-ma-tion -ret-ri-bu-tion -ta-ble -} diff --git a/scripts/LinuxManBook/hyphenex.en b/scripts/LinuxManBook/hyphenex.en deleted file mode 100644 index 768c0af..0000000 --- a/scripts/LinuxManBook/hyphenex.en +++ /dev/null @@ -1,115 +0,0 @@ -% Hyphenation exceptions for US English, -% based on hyphenation exception log articles in TUGboat. -% -% Copyright 2008 TeX Users Group. -% You may freely use, modify and/or distribute this file. -% -% Stripped down by the GNU roff project to only include the patterns -% that hyphenate differently when using the hyph-utf8 project's -% hyph-en-us.tex file (version 2005-05-30). -% -% Please contact the TUGboat editorial staff -% for corrections and omissions. -% -\hyphenation{ - anti-deriv-a-tive - anti-deriv-a-tives - bathy-scaphe - co-designer - co-designers - electro-mechan-i-cal - electro-mechano-acoustic - fluoro-car-bon - free-loaders - grand-uncle - grand-uncles - griev-ances - ignore-spaces - im-ped-ances - input-enc - line-spacing - meta-stable - meta-table - meta-tables - micro-eco-nomic - micro-eco-nomics - micro-econ-omy - micro-en-ter-prise - micro-en-ter-prises - micro-organ-ism - micro-organ-isms - mid-after-noon - mine-sweepers - mono-spacing - nitro-meth-ane - non-euclid-ean - ortho-nitro-toluene - para-di-methyl-benzene - para-fluoro-toluene - phe-nol-phthalein - phtha-lam-ic - phthal-ate - phthi-sis - pre-proces-sor - pre-proces-sors - re-imple-ment - re-imple-ments - re-imple-mented - re-imple-men-ta-tion - ring-leaders - round-table - round-tables - single-space - single-spaced - single-spacing - sky-scrapers - sports-writers - sub-tables - super-deri-va-tion - super-deri-va-tions - super-ego - super-egos - waste-water - Bembo - Chiang - Cohen - Duane - Engle - Engel - Hibbs - Hoek-water - Huber - Image-Magick - Krishna - Krish-na-ism - Krish-nan - Le-gendre - Lucas - MacBeth - Nietz-sche - Noord-wijker-hout - Open-Office - Pres-by-terian - Pres-by-terians - Pyong-yang - Ra-dha-krish-nan - Ravi-kumar - Reich-lin - Schwert - Skoup - Thiruv-ananda-puram - Vieth - viiith - viith - xviiith - xviith - xxiiird - xxiind - Ying-yong Shu-xue Ji-suan -} -% Here's an erratum from the aforementioned hyph-en-us.tex. -\hyphenation{ - dem-o-crat -} - -% EOF diff --git a/scripts/LinuxManBook/prepare.pl b/scripts/LinuxManBook/prepare.pl new file mode 100755 index 0000000..735cfcf --- /dev/null +++ b/scripts/LinuxManBook/prepare.pl @@ -0,0 +1,248 @@ +#!/usr/bin/perl -w +# +# BuildLinuxMan.pl : Build Linux manpages book +# Deri James (& Brian Inglis) : 15 Dec 2022 +# +# Params:- +# +# $1 = Directory holding the man pages +# +# (C) Copyright 2022, Deri James +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details +# (http://www.gnu.org/licenses/gpl-2.0.html). +# + +use strict; +use File::Basename; + +my $inTS=0; +my $inBlock=0; + +my %Sections= +( + "1" => "General Commands Manual", + "2" => "System Calls Manual", + "2type" => "System Calls Manual (types)", + "3" => "Library Functions Manual", + "3const" => "Library Functions Manual (constants)", + "3head" => "Library Functions Manual (headers)", + "3type" => "Library Functions Manual (types)", + "4" => "Kernel Interfaces Manual", + "5" => "File Formats Manual", + "6" => "Games Manual", + "7" => "Miscellaneous Information Manual", + "8" => "System Manager's Manual", + "9" => "Kernel Developer's Manual", +); + +my $dir=shift || '.'; +my $dir2=$dir; +$dir2=~tr[.][_]; +my %files; +my %aliases; +my %target; + +foreach my $al (`grep -E '^\\.so' $dir/man*/*`) +{ + #$al=~tr[.][_]; + $al=~m/^$dir\/man\d[a-z]*\/(.*):\.\s*so\s*man\d[a-z]*\/(.*)/o; + + $aliases{$1}=$2; +} + +while (my ($k,$v)=each %aliases) +{ + while (exists($aliases{$v})) { + $v=$aliases{$v}; + } +} + +foreach my $fn (glob "$dir/man*/*") +{ + my ($nm,$sec)=GetNmSec($fn,qr/\.\d[a-z]*/); + $files{"${nm}.$sec"}=[$fn,(exists($aliases{"${nm}.$sec"}))?$aliases{"${nm}.$sec"}:"${nm}.$sec"]; +} + +my $Section=''; + +BuildBook(); + +sub BuildBook +{ + print ".pdfpagenumbering D . 1\n.nr PDFOUTLINE.FOLDLEVEL 0\n.defcolor pdf:href.colour rgb 0.00 0.25 0.75\n.pdfinfo /Title \"The Linux man-pages Book\"\n.special TINOR S\n"; + + foreach my $bkmark (sort sortman keys %files) { + BuildPage($bkmark); + } +} + +sub BuildPage +{ + my $bkmark=shift; + + my $fn=$files{$bkmark}->[0]; + my ($nm,$sec,$srt)=GetNmSec($bkmark,qr/\.[\da-z]+/); + + my $title= "$nm\\($sec\\)"; + + print ".\\\" >>>>>> $nm($sec) <<<<<<\n.lf 0 $bkmark\n"; + + # If this is an alias, just add it to the outline panel. + + # if new section add top level bookmark + + if ($sec ne $Section) { + print ".nr PDFOUTLINE.FOLDLEVEL 1\n"; + print ".pdfbookmark 1 $Sections{$sec}\n"; + print ".nr PDFOUTLINE.FOLDLEVEL 2\n"; + $Section=$sec; + } + + if (exists($aliases{$bkmark})) { + print ".eo\n.device ps:exec [/Dest /$aliases{$bkmark} /Title ($title) /Level 2 /OUT pdfmark\n.ec\n.fl\n"; + return; + } + + if (open(F,'<',$fn)) { + while () { + if (m/^\.\\"/) { + print $_; + next; + } + + chomp; + + # This code is to determine whether we are within a tbl block and in a text block + # T{ and T}. This is fudge code particularly for the syscalls(7) page. + + $inTS=1 if m/\.TS/; + $inTS=0,$inBlock=0 if m/\.TE/; + + next if !$_; +# s/^\s+//; + + s/\\-/-/g if /^\.[BM]R\s+/; + + if (m/^\.BR\s+([-\w\\.]+)\s+\((.+?)\)(.*)/ or m/^\.MR\s+([-\w\\.]+)\s+(\w+)\s+(.*)/ or m/^\\fB([-\w\\.]+)\\fR\((.+?)\)(.*)$/) { + my $bkmark="$1"; + my $sec=$2; + my $after=$3; + $after=~s/\s\\".*//; + my $dest=$bkmark; + $dest=~s/\\-/-/g; + + if (exists($files{"${bkmark}.$sec"})) { + my $dest=$files{"${bkmark}.$sec"}->[1]; + $_=".pdfhref L -D \"$dest\" -A \"$after\" -- \\fI$bkmark\\fP($sec)"; + } else { + $_=".IR $bkmark ($sec)\\c\n$after"; + } + } + + s/^\.BI \\fB/.BI /; + s/^\.BR\s+(\S+)\s*$/.B $1/; + s/^\.BI\s+(\S+)\s*$/.B $1/; + s/^\.IR\s+(\S+)\s*$/.I $1/; + + # Fiddling for syscalls(7) :-( + + if ($inTS) { + my @cols=split(/\t/,$_); + + foreach my $c (@cols) { + $inBlock+=()=$c=~m/T\{/g; + $inBlock-=()=$c=~m/T\}/g; + + my $mtch=$c=~s/\s*\\fB([-\w.]+)\\fP\((\w+)\)/doMR($1,$2)/ge; + $c="T{\n${c}\nT}" if $mtch and !$inBlock; + } + + $_=join("\t",@cols); + s/\n\n/\n/g; + } + + s/\\&\././ if m/^.TH /; + + if (m/^\.TH\s+"?([-\w\\.]+)"?\s+"?(\w+)"?/) { + + print "$_\n"; + + # Add a level two bookmark. We don't set it in the TH macro since the name passed + # may be different from the filename, i.e. file = unimplemented.2, TH = UNIMPLEMENTED 2 + + print ".pdfbookmark -T $bkmark 2 $nm($sec)\n"; + + next; + } + print "$_\n"; + } + close(F); + } +} + +sub doMR +{ + my $nm=shift; + my $sec=shift; + + if (exists($files{"${nm}.$sec"})) { + return("\n.pdfhref L -D \"$files{\"${nm}.$sec\"}->[1]\" -A \"\\c\" -- \\fI$nm\\fP($sec)\n"); + } else { + return("\\fI$nm\\fP($sec)"); + } +} + +sub GetNmSec +{ + my ($nm,$pth,$sec)=fileparse($_[0],$_[1]); + $sec=substr($sec,1); + my $srt=$nm; + $srt=~s/\..+?$//; + $srt=~s/^_+//; + $srt=$1.sprintf("%04d",$2) if $srt=~m/^(.+)(\d+)$/; + #$srt="$sec/$srt"; + return($nm,$sec,$srt); +} + +# add rpmvercmp +#use RPM::VersionSort; +#use Sort::Versions; + +sub sortman +{ +# Sort - ignore case but frig it so that intro is the first entry. + + my (undef,$s1,$c)=GetNmSec($a,qr/\.\d[a-z]*/); + my (undef,$s2,$d)=GetNmSec($b,qr/\.\d[a-z]*/); + + my $cmp=$s1 cmp $s2; + + return $cmp if $cmp; + return -1 if ($c=~m/^intro/ and $d!~m/^intro/); + return 1 if ($d=~m/^intro/ and $c!~m/^intro/); + $c=~tr[-_(][!" ]; + $d=~tr[-_(][!" ]; + $cmp=lc($c) cmp lc($d); + return($c cmp $d) if $cmp == 0; + return($cmp); +} + +sub strhex +{ + my $res=''; + + foreach my $c (split('',$_[0])) { + $res.=sprintf("%02X",ord($c)); + } + + return($res); +} diff --git a/scripts/LinuxManBook/troffrc b/scripts/LinuxManBook/troffrc deleted file mode 100644 index a2784d7..0000000 --- a/scripts/LinuxManBook/troffrc +++ /dev/null @@ -1,71 +0,0 @@ -.\" startup file for GNU troff -.\" -.\" Use .do for any groff extensions so that this file works with -C. -. -.\" This is tested by pic. -.nr 0p 0 -. -.\" Load composite mappings. -.do mso composite.tmac -. -.\" Load generic fallback mappings. -.do mso fallbacks.tmac -. -.\" The groff command defines the .X register if -X was given. -.do ie r .X \ -. do ds troffrc!ps Xps.tmac -.el \ -. do ds troffrc!ps ps.tmac -.do ds troffrc!pdf pdf.tmac -.do ds troffrc!dvi dvi.tmac -.do ds troffrc!X75 X.tmac -.do ds troffrc!X75-12 X.tmac -.do ds troffrc!X100 X.tmac -.do ds troffrc!X100-12 X.tmac -.do ds troffrc!ascii tty.tmac -.do ds troffrc!latin1 tty.tmac -.do ds troffrc!utf8 tty.tmac -.do ds troffrc!cp1047 tty.tmac -.do ds troffrc!lj4 lj4.tmac -.do ds troffrc!lbp lbp.tmac -.do ds troffrc!html html.tmac -.do if d troffrc!\*[.T] \ -. do mso \*[troffrc!\*[.T]] -.do rm \ -troffrc!ps \ -troffrc!pdf \ -troffrc!dvi \ -troffrc!X75 \ -troffrc!X75-12 \ -troffrc!X100 \ -troffrc!X100-12 \ -troffrc!ascii \ -troffrc!latin1 \ -troffrc!utf8 \ -troffrc!cp1047 \ -troffrc!lj4 \ -troffrc!lbp \ -troffrc!html -. -.\" Test whether we work under EBCDIC and map the no-break space -.\" character accordingly. -.do ie '\[char97]'a' \ -. do tr \[char160]\~ -.el \ -. do tr \[char65]\~ -. -.\" Set the input localization to English. -.do mso en.tmac -. -.\" Handle paper formats on typesetting devices. -.if t .do mso papersize.tmac -. -.\" Handle Encapsulated PostScript images. -.do mso pspic.tmac -.do mso pdfpic.tmac -. -.\" Local Variables: -.\" mode: nroff -.\" fill-column: 72 -.\" End: -.\" vim: set filetype=groff textwidth=72: diff --git a/scripts/LinuxManBook/utp.mac b/scripts/LinuxManBook/utp.mac deleted file mode 100644 index ed9027a..0000000 --- a/scripts/LinuxManBook/utp.mac +++ /dev/null @@ -1,742 +0,0 @@ -.ig -vim:syntax=off - -Macros for typesetting _Unix Text Processing_. -Based on the macros from Chapter 17 and Appendix F -of that book. - -Adapted by Jon Snader as part of a project to make this classic -book available again. - -Version of 16 November 2002 -.. -.RT -.nr nH 0 \" don't number [ABCD]-heads -.nr gE 0 \" don't add chapter number to [ABCD]-heads -.nr chapter_page 0 \" avoid diag. if there's no .Se call -.ds chapter_name -\# -\# Redefine LP so that it can take an argument to suppress spacing -\# -.de par*start*nospace -.ds@auto-end -.nr \\n[.ev]:pli \\$1 -.nr \\n[.ev]:pri \\$2 -.par@reset -.ne 1v+\\n(.Vu -.. -.de LP \"Non indented paragraph. Don't skip space if \\$1 == 0 -.ie '\\$1'0' .par*start*nospace 0 0 -.el .par*start 0 0 -.nr \\n[.ev]:ai \\n[\\n[.ev]:PI] -.. -\# -\# Nh - set behavior of numbered headings -\# $1: -\# 0 - no numbering -\# 1 - number all headings -\# 2 - number A-head only -\# -\# $2 (if present): -\# 0 - don't add section numbers to headers -\# 1 - prefix headers with section number -\# -.de Nh -. nr nH \\$1 -. if !'\\$2'' .nr gE \\$2 -.. -\# -\# Square centered vertically -\# -.ds square \v'-.25v'\s6\(sq\s0\v'.25v' -\# -\# Special A-head for UTP -\# -.de utp_Ah -.sp 26p -.RT -.pdfbookmark 2 \\$1 -.ne 6 -.ps 14 -.vs 16 -.lg 0 -.ce -\fB\*[square] \\$1 \*[square]\fP -.LP 0 -.lg -.sp 18p -.ns -.if \\n[Ref] .tm Ah: \\*[PDFBOOKMARK.NAME] \\n(PN \\$1 -.. -\# -\# The [ABCD]-head macros -\# -.de standard_Ah \" A-head. $1: title -.sp 26p -.RT -.ne 6 -.ps 14 -.vs 16 -.lg 0 -.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ -\fB\c -.if \\n[nH] \{. \"if producing numbered headings -. ie \\n[gE] .sec# 2 \" if Se (chapter) macro is -. \" numbered, then this is on the second level -. el .sec# 1 \" otherwise it's on the first level -.\} -\&\\$1\fP -.LP 0 \" reset paragraph, but not font size, etc. -.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz -.lg -.sp 18p -.ns -.. -.als Ah standard_Ah -\# -.de Bh \" B-head. $1: title -.sp 23p -.pdfbookmark 3 \\$1 -.RT -.ne 6 -.ps 14 -.vs 16 -.lg 0 -\fB\c -.if '\\n[nH]'1' \{. \"if producing numbered headings -. ie \\n[gE] .sec# 3 \" if Se (chapter) macro is -. \" numbered, then this is on the third level -. el .sec# 2 \" otherwise it's on the second level -.\} -\&\\$1\fP -.LP 0 \" reset paragraph, but not font size, etc. -.lg -.sp 15.5p -.ns -.. -\# -.de Ch \" C-head. $1: title -.sp 18p -.RT -.ne 6 -.ps 12 -.vs 14 -.lg 0 -\fB\c -.if '\\n[nH]'1' \{. \"if producing numbered headings -. ie \\n[gE] .sec# 4 \" if Se (chapter) macro is -. \" numbered, then this is on the fourth level -. el .sec# 3 \" otherwise it's on the third level -.\} -\&\\$1\fP -.LP 0 \" reset paragraph, but not font size, etc. -.lg -.sp 12p -.ns -.. -\# -.de Dh \" D-head. $1: title -.sp 18p -.RT -.ne 6 -.ps 10 -.vs 12 -.lg 0 -\fB\c -.if '\\n[nH]'1' \{. \"if producing numbered headings -. ie \\n[gE] .sec# 5 \" if Se (chapter) macro is -. \" numbered, then this is on the fifth level -. el .sec# 4 \" otherwise it's on the fourth level -.\} -\&\\$1.\fP -.lg -.. -\# -\# The Section macro -\# -\# This is for Chapters and Appendices -\# -.de Se \" Section. $1: number, $2: name -. \" $3: type (Chapter, Appendix, ...) -. \" $4: non-null => don't map to uppercase -.if e \{\ -\& -.bp -.\} -.ds chapter_name \\$2 -.ie !'\\$1'' \{. \" If we have a section number -. utpbookmark -T "\\$3\\$1" 1 "\\$1. \\$2" -. ds chapter_head \\$1 -. nr is_alpha 0 -. if '\\$1'A' .set_section 1 -. if '\\$1'B' .set_section 2 -. if '\\$1'C' .set_section 3 -. if '\\$1'D' .set_section 4 -. if '\\$1'E' .set_section 5 -. if '\\$1'F' .set_section 6 -. if '\\$1'G' .set_section 7 -. if '\\$1'H' .set_section 8 -. if '\\$1'I' .set_section 9 -. if '\\$1'J' .set_section 10 -. if '\\$1'K' .set_section 11 -. if '\\$1'L' .set_section 12 -. if '\\$1'M' .set_section 13 -. if '\\$1'N' .set_section 14 -. if '\\$1'O' .set_section 15 -. if '\\$1'P' .set_section 16 -. if '\\$1'Q' .set_section 17 -. if '\\$1'R' .set_section 18 -. if '\\$1'S' .set_section 19 -. if '\\$1'T' .set_section 20 -. if '\\$1'U' .set_section 21 -. if '\\$1'V' .set_section 22 -. if '\\$1'W' .set_section 23 -. if '\\$1'X' .set_section 24 -. if '\\$1'Y' .set_section 25 -. if '\\$1'Z' .set_section 26 -. if !\\n[is_alpha] \{\ -. nr section \\$1 -. nr intH1 \\$1 -. \} -.\} -.el \{. \" Illegal Chapter Appendix number -. nr section 0 -. utpbookmark -T \\$2 1 \\$2 -. \" Might be Preface, etc. so no error diag. -.\} -.nr chapter_page2 1 \" Next page starts a chapter, so no header -.if \\n[%]>1 .bp -.nr PN \\n[%] -.ie '\\$3'NONE' .af PN i -.el .af PN 1 -.nr chapter_page 1 \" This page starts a chapter, number at bottom -.if !\\n[gE] .nr intH1 0 -.nr intH2 0 \" rescind lower level numbering -.nr intH3 0 -.nr intH4 0 -.nr intH5 0 -.nr fig_num 0 \" Reset figure number -.nr table_num 0 \" Reset table number -.format_section "\\$1" "\\$2" \\$3 \\$4 -.ie '\\$1'' \{\ -.ie '\\$2'' .if \\n[Ref] .tm Se: \\*[PDFBOOKMARK.NAME] \\n(PN \\$3 -.el .if \\n[Ref] .tm Se: \\*[PDFBOOKMARK.NAME] \\n(PN \\$1 \\$2 -.\} -.el .if \\n[Ref] .tm Se: \\*[PDFBOOKMARK.NAME] \\n(PN \\$1 \\$2 -.. -\# -\# Set section number for alphabet chapters (appendices) -\# -.de set_section -.nr intH1 \\$1 -.af intH1 A -.nr section \\$1 -.nr is_alpha 1 -.. -\# -\# Draw a horizontal line -\# -.de horizontal_line -.br -\l'\\n[.l]u-\\n[.i]u\&\\$1' -.br -.. -.als Hl horizontal_line -\# -\# Standard Section Formatting Routine -\# -.de format_standard_section -.RT -.in 0 -.lg 0 -.if '\\$4'' .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ -.sp -.na -.\" Set section type--default is Chapter -.ie !'\\$3'' \{\ -. ie '\\$3'NONE' .ds chapter_type -. el .ds chapter_type \\$3 -.\} -.el .ds chapter_type Chapter -.\" If there is a section number, output Type and section number -.if !'\\$1'' \s14\fB\\*[chapter_type] \\$1\fP\s0 -.\" If there is no section number, but there is a type, then output it -.if '\\$1'' .if !'\\$3'' \s14\fB\\*[chapter_type]\fP\s0 -.sp 5p -.\" Print the section title if there is one -\#.if !'\\$2'' \s14\fB\\$2\fP\s0 -.if !'\\$2'' \{\ -.ps 14 -.B -\&\\$2 -.R -.ps \\n[PS] \" Reset to PS in case of inline \s -.\} -.sp 6p -.ad b \" Adjust both margins -.horizontal_line \" Draw horizontal line -.if '\\$4'' .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz -.sp 3 -.ns -.. -.als format_section format_standard_section -\# -\# numbered header Macros -\# Special version of NH to generate just the string -\# Used internally. -\# -.de sec# -.nr NS \\$1 \" Current level -.if !\\n[.$] .nr NS 1 \" Default is level 1 -.if !\\n[NS] .nr NS 1 \" In case it's NULL or negative -.nr intH\\n[NS] +1 \" Increment count on current level -.\" Rescind lower levels -.if !\\n[NS]-4 .nr intH5 0 -.if !\\n[NS]-3 .nr intH4 0 -.if !\\n[NS]-2 .nr intH3 0 -.if !\\n[NS]-1 .nr intH2 0 -.\" Build up the string -.if !\\$1 .if \\n[.$] .nr intH1 1 -.ds SN \\n[intH1] -.ie \\n[NS]-1 .as SN .\\n[intH2] -.el .as SN . \" either x.y or x. -.if \\n[NS]-2 .as SN .\\n[intH3] -.if \\n[NS]-3 .as SN .\\n[intH4] -.if \\n[NS]-4 .as SN .\\n[intH5] -'ti \\n[.i]u -\\*[SN] \" print answer -.. -\# -\# Figure start and end macros -\# -.de Fs \" start figure $1: reserved space $2: float figure -.RT -.ie 'F'\\$2' \{. \" if figure can float -. nr floating_keep 1 -. KF -.\} -.el .nr floating_keep 0 -.if !'\\$1'' \{. \" if space specified -. ne \\$1 -. fl -. rs -. sp \\$1 -.\} -.. -.de Fe \" end figure $1: title -.sp -.nr fig_num +1 \" increment figure counter -.ie \\n[section] .ds figure \\*[chapter_head].\\n[fig_num] -.el .ds figure \\n[fig_num] -.ce -\f[BI]Figure \\*[figure] \\$1\fP -.sp -.if \\n[floating_keep] .KE -.. -\# -\# Table start and end macros -\# -.de Ts \" table start $1: title -.nr table_num +1 \" increment table number -.ie \\n[section] .ds table \\*[chapter_head].\\n[table_num] -.el .ds table \\n[table_num] -.sp -.ce -\f[BI]Table \\*[table] \\$1\fP -.LP -.. -.de Te -.RT -.sp -.. -\# -\# Numbered lists -\# -.nr l0 0 1 -.de Ls -.\" list start $1: A - ALPHA -.\" a - alpha -.\" B - bullet -.\" N - numeric -.\" R - ROMAN NUMERALS -.\" r - roman numerals -.\" $2: indent -.\" $3: alternate bullet character -.br -.if !'\\$1'A' .if !'\\$1'a' .if !'\\$1'B' .if !'\\$1'N' \ -. if !'\\$1'R' .if !'\\$1'r' .if !'\\$1'' \ -. tm Ls: Need A, a, B, N, R, or r as type -.nr l\\n+[l0] 0 1 -.ie '\\$1'' \{. \" set defaults -. if '\\n[l0]'1' .af l\\n[l0] 1 \"numeric at 1st level -. if '\\n[l0]'2' .af l\\n[l0] a \"alpha at 2nd level -. if '\\n[l0]'3' .af l\\n[l0] i \"roman at 3rd level -. if '\\n[l0]'4' .ds l\\n[l0] \(bu \"bullet at 4th level -. if '\\n[l0]'5' .ds l\\n[l0] \- \"dash at 5th level -. if \\n[l0]-5 .ds l\\n[l0] \(bu \"bullet above 5th level -. if \\n[l0]-3 .nr l\\n[l0] 0-1 \"mark bullet and dash as non-incrementing -.\} -.el \{\ -. if '\\$1'A' .af l\\n[l0] A -. if '\\$1'a' .af l\\n[l0] a -. if '\\$1'B' \{\ -. ie '\\$3'' .ds l\\n[l0] \(bu -. el .ds l\\n[l0] \\$3 -. nr l\\n[l0] 0-1 \"mark as non-incrementing -. \} -. if '\\$1'R' .af l\\n[l0] I -. if '\\$1'r' .af l\\n[l0] i -.\} -.ie !'\\$2'' .nr i\\n[l0] \\$2 \"set list indent -.el .nr i\\n[l0] 5 \"default indent -.RS -.. -.de Li \" List start $1 == 0: no blank line preceding -.br -.if '\\$1'0' .ns -.ie '\\n[l\\n[l0]]'-1' .intIP "\\*[l\\n[l0]]" "\\n[i\\n[l0]]" -.el \{\ -. nr l\\n[l0] +1 -. intIP "\\n[l\\n[l0]]." "\\n[i\\n[l0]]" -.\} -.. -.de Le \" List end $1 == 0: no blank line after -.br -.rr l\\n[l0] \" remove number registers -.rr i\\n[l0] -.rm l\\n[l0] \" and string register, if any -.nr l0 -1 \" back one level of nesting -.RE -.ie !\\n[l0] \{\ -. ie '\\$1'0' .LP 0 -. el .LP -.\} -.el .if !'\\$1'0' .sp \\n[PD]u -.. -\# -\# intIP - internal version of IP that centers tag -\# -.de intIP -.sp \\n[PD]u -.in \\n[\\n[.ev]:il]u*\\n[PI]u-\\n[PI]u+\\$2n -.nr indent1 \\$2n/2u+\w'\\$1' \" amount to move left -\#.nr indent2 \\$2n+\w'\\$1' \" amount to move back -\#.ta \\n[indent2]u -.ta \\n[indent1]u -.ti -\\n[indent1]u -\\$1\t\c -.. -\# -\# Printout and listing macros -\# -.ev printout \" set up the listing environment -.ns -.ps 9 -.vs 10 -.ft C -.nf -.ev -.de Ps \" printout start $1: indent -.br -.ev printout -.sp \\n[PD]u -.ie !'\\$1'' .in +\\$1n -.el .in +5n -.. -.de Pe \" printout end $1: non-null => no following space -.br -.if '\\$1'' .sp \\n[PD]u -.in -.ev -.. -\# -\# X[1-4]: Side by side virtual display screens -\# Contributed by Heinz-Jürgen Oertel -\# -.\" Macro definition -.\" window width -.\" Should be calculated, so that the width is 25 equal spaced chars -.nr my_wid \w'\f(CW12345678901234567890123456\fP' -.de X1 -.sp -.mk x_box -.nf -.\" left and right page offset -.po +(u;\\n[.ll]/40) -.ll \n[my_wid]u -.in +1n -.CW -.. -.de X2 -.mk here -.in -1n -.draw_screen \n[my_wid]u \\n[here]u-\\n[x_box]u+\\n[.v]u -.po +(u;\n[my_wid]) -.\" line length of the centered text -.ll (u;(\\n[LL]u)-(2*\n[my_wid]u)-(\\n[LL]/20u)) -.sp |\\n[x_box]u -.ce 10 -.R -.. -.de X3 -.ce 0 -.sp |\\n[x_box]u -.po +(u;(\\n[LL]u)-(2*\n[my_wid]u)-(\\n[LL]/20u)) -.ll \n[my_wid]u -.nf -.in +1n -.CW -.. -.de X4 -.in -1n -.draw_screen \n[my_wid]u \\n[here]u-\\n[x_box]u+\\n[.v]u -.R -.fi -.po \\n(POu -.ll \\n(LLu -.. -\# -\# Helvetica font change macros -\# -.de H \" Helvetica -.ie !\\n[.$] .ft H -.el \&\\$3\fH\\$1\fP\\$2 -.. -.de HB \" Helvetica Bold -.ie !\\n[.$] .ft HB -.el \&\\$3\f[HB]\\$1\fP\\$2 -.. -.de HI \" Helvetica Italic -.ie !\\n[.$] .ft HI -.el \&\\$3\f[HI]\\$1\fP\\$2 -.. -\# -\# Screen Boxes -\# -.de draw_screen \" Draw box with rounded corners, $1: wid $2: ht -.nr radius (((\\$1)0 \{\ -. br -\&\c -' bp -. ce -\fBPersonal Notes\fP -. sp 2 -. ev notes -. nf -. pers_notes -. ev -.\} -.. -\# -\# UTP top and bottom page processing -\# -.de utp_top -.ev header_footer -.nr PN \\n[%] -.if !\\n[chapter_page2] \{. \" if this page doesn't start a chapter -. ie o .tl ''\\*[chapter_name]'\\n[PN]' -. el .tl '\\n[PN]'\*[square] Unix Text Processing \*[square]'' -.\} -.ev -.. -.de utp_bottom -.ev header_footer -.if \\n[chapter_page] \{\ -. tl ''\\n[PN]'' -. nr chapter_page 0 -. nr chapter_page2 0 -.\} -.ev -.. -\#.de page -\#.mk page-vpos -\#.nr page-hpos \\n[.k] -\#.po \\n[PO]u-4n -\#.br -\#\\$1 -\#.br -\#.po \\n[PO]u -\#.sp |\\n[page-vpos]u -\#\h'|\\n[page-hpos]u' -\#.. -.de do-page \" Enable the .page macro -.nr do-page 1 -.. -.de page \" Capture the original UTP page numbers -.ds page-utp \\$1 -.if \\n[do-page] \{\ -. mk page-pos -. ev page-env -' di page-num -' nf -\\$1 -. ev -. di -. mk page-trap -. nr page-trap +.1v -. wh \\n[page-trap]u page-put -.\} -.. -.de page-put \" Place the UTP page number in the left margin -.mk page-end -.wh \\n[page-trap]u -'sp |\\n[page-pos]u -.ev page-env -'po \\n[PO]u-5n -'fi -.page-num -.br -.ev -'po \\n[PO]u -'sp |\\n[page-end]u -.. -.de ix -.ie '\\n(.z'' \{\ -. if !'\\$1'%end' \{\ -. ds ixbk ix:bm\\n+[ixno] -. pdfhref M -N \\*[ixbk] -. \} -. if \\n[Ref] .tm ix: \\$* \\n% \\*[ixbk] -.\} -.el \\!.ix \\$* -.. -\# -\# Set defaults for UTP -\# -.de utp -.ps 10 -.vs 12 -.nr PS 10 -.nr VS 12 -.nr SS_prefix 1v -.nr do-page 0 -.Nh 0 0 -.als Ah utp_Ah -.als chapter Se -.als PT utp_top -.als BT utp_bottom -.ev header_footer -.ll \\n[LL]u -.lt \\n[LL]u -.ps \\n[PS] -.vs \\n[VS] -.ev -.. -.de utpbookmark -.ie '\\*[.T]'ps' \{\ -. pdfhref M -N \\$2 -- \\$4 -. if !dpdf:href.map .tm gropdf-info:href \\$2 \\$4 -. pdfbookmark \\$3 \\$4 -.\} -.el .pdfbookmark \\$* -.. -.em EM diff --git a/scripts/README b/scripts/README index 6b29c54..2ad6bc8 100644 --- a/scripts/README +++ b/scripts/README @@ -1,4 +1,4 @@ The files in this directory are scripts for man-pages maintenance tasks. -They may be useful for downstream man-pages package maintainers or for +They may be useful for downstream man-pages package maintainers or for man-pages translators. This directory does not contain any files that need to be installed in order to use the manual pages. diff --git a/scripts/add_parens_for_own_funcs.sh b/scripts/add_parens_for_own_funcs.sh index 1bf6d2a..49ec629 100755 --- a/scripts/add_parens_for_own_funcs.sh +++ b/scripts/add_parens_for_own_funcs.sh @@ -8,13 +8,13 @@ # The problem is how to determine what is a "function name". # The approach this script takes is the following: # -# For each manual page named in the command line that contains +# For each manual page named in the command line that contains # more than one line (i.e., skip man-page link files) # Create a set of names taken from the .SH section of the -# page and from grepping all pages for names that +# page and from grepping all pages for names that # have .so links to this page # For each name obtained above -# If we can find something that looks like a prototype on +# If we can find something that looks like a prototype on # the page, then # Try to substitute instances of that name on the page. # (instances are considered to be words formatted @@ -37,7 +37,7 @@ # # and take a good look at the output. In particular, you can scan # the output for *possible* problems by looking for the pattern: /^%%%/ -# The script's output should be enough to help you determine if the +# The script's output should be enough to help you determine if the # problem is real or not. # # Suggested usage (in this case to fix pages in Section 2): @@ -48,7 +48,7 @@ # Use the "-n" option for a dry run, in order to see what would be # done, without actually doing it. # -# (And, yes, there are many ways that this script could probably be +# (And, yes, there are many ways that this script could probably be # made to work faster...) # ###################################################################### @@ -58,7 +58,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -66,7 +66,7 @@ # (http://www.gnu.org/licenses/gpl-2.0.html). # # -# +# file_base="tmp.$(basename $0)" @@ -96,7 +96,7 @@ done shift $(( $OPTIND - 1 )) -# Only process files with > 1 line -- single-line files are link files +# Only process files with > 1 line -- single-line files are link files for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ grep -v '^total'); do @@ -108,8 +108,8 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ # be our guesses about function names to look for sh_nlist=$(cat $page | \ - awk 'BEGIN { p = 0 } - /^\.SH NAME/ { p = NR } + awk 'BEGIN { p = 0 } + /^\.SH NAME/ { p = NR } /^.SH/ && NR > p { p = 0 } # Stop at the next .SH directive p > 0 && NR > p { print $0 } # These are the lines between # the two .SH directives @@ -117,8 +117,8 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ sh_nlist=$(echo $sh_nlist | sed -e 's/ *\\-.*//' -e 's/, */ /g') echo "### .SH name list:" $sh_nlist - # Some pages like msgop.2 don't actually list the function names in - # the .SH section -- but we can try using link pages to give us + # Some pages like msgop.2 don't actually list the function names in + # the .SH section -- but we can try using link pages to give us # another guess at the right function names to look for so_nlist=$(grep -l "^\\.so.*/$(echo $page| \ @@ -128,11 +128,11 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ echo "### .so name list:" $so_nlist # Combine the two lists, eliminate duplicates - + nlist=$(echo $sh_nlist $so_nlist | tr ' ' '\012' | sort -u) maybechanged=0 - + cp $page $work_dst_file rm -f $matches_for_all_names; # touch $matches_for_all_names @@ -146,7 +146,7 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ echo "########## trying $rname ##########" rm -f $matches_for_this_name - + grep "^.BR* $name *$" $page | \ >> $matches_for_this_name grep "^.BR $name [^(\"]$" $page | \ @@ -155,7 +155,7 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ >> $matches_for_this_name grep '\\fB'"$name"'\\f[PR]$' $page | \ >> $matches_for_this_name - + cat $matches_for_this_name | sed -e 's/^/### MATCH: /' cat $matches_for_this_name >> $matches_for_all_names @@ -163,10 +163,10 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ # like a function prototype for this name in the page if grep -q "$name *(" $page || \ - grep -q "$name\\\\f.[\\ ]*(" $page; then + grep -q "$name\\\\f.[\\ ]*(" $page; then # '.B name$' - # '.BR name [^("]*$ + # '.BR name [^("]*$ # (The use of [^"] in the above eliminates lines # like: .BR func " and " func # Those lines better be done manually.) @@ -211,7 +211,7 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ # If the file was changed, then: # show "diff -U" output to user; - # and count number of changed lines and compare it with what + # and count number of changed lines and compare it with what # we expected, displaying a warning if it wasn't what was expected if test $maybechanged -ne 0 && ! cmp -s $page $work_dst_file; then @@ -220,7 +220,7 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ made_matches=$(diff -U 0 $page $work_dst_file | grep '^\+[^+]' | \ wc -l | awk '{print $1}') - # The following line makes the changes -- comment it out if you + # The following line makes the changes -- comment it out if you # just want to do a dry run to see what changes would be made. if test $really_do_it -ne 0; then @@ -242,8 +242,8 @@ for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ echo "%%%%%%%%%% WARNING: NOT ENOUGH MATCHES: " \ "$made_matches < $min_match" fi - -done + +done # clean up diff --git a/scripts/convert_to_utf_8.sh b/scripts/convert_to_utf_8.sh index 28f5a72..b0d222c 100755 --- a/scripts/convert_to_utf_8.sh +++ b/scripts/convert_to_utf_8.sh @@ -17,7 +17,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the diff --git a/scripts/find_dots_no_parens.sh b/scripts/find_dots_no_parens.sh index 79d1c32..27072d3 100755 --- a/scripts/find_dots_no_parens.sh +++ b/scripts/find_dots_no_parens.sh @@ -8,13 +8,13 @@ # This script is designed to help with "by hand" tidy-ups after # the automated changes made by add_parens_for_own_funcs.sh. # -# The first argument to this script names a manual page directory where -# 'man2' and 'man3' subdirectories can be found. The pages names in -# these directories are used to generate a series of regular expressions -# that can be used to search the manual page files that are named in +# The first argument to this script names a manual page directory where +# 'man2' and 'man3' subdirectories can be found. The pages names in +# these directories are used to generate a series of regular expressions +# that can be used to search the manual page files that are named in # the remaining command-line arguments. # -# Example usage: +# Example usage: # # cd man-pages-x.yy # sh find_dots_no_parens.sh . man?/*.? > matches.log @@ -26,7 +26,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -53,7 +53,7 @@ echo "This will take probably a few moments..." 1>&2 awk_script_file=tmp.$0.awk rm -f $awk_script_file -# We grep out a few page names that are likely to generate false +# We grep out a few page names that are likely to generate false # positives... echo '{' >> $awk_script_file @@ -63,9 +63,9 @@ echo ' if ( myvar == "NOMATCHESFORTHIS" || ' >> $awk_script_file for page in $( - find $dir/man2/* $dir/man3/* -type f -name '*.[23]' | + find $dir/man2/* $dir/man3/* -type f -name '*.[23]' | egrep -v '/(stderr|stdin|stdout|errno|termios|string)\..$'); do - + base=$(basename $page | sed -e 's/\.[23]$//') echo " myvar == \"$base\" ||" >> $awk_script_file @@ -75,7 +75,7 @@ echo ' myvar == "NOMATCHESFORTHIS" )' >> $awk_script_file echo ' print $0' >> $awk_script_file echo '}' >> $awk_script_file -grep '^\.[BRI][BRI]* [a-zA-Z0-9_][a-zA-Z0-9_]*[^a-zA-Z_]*$' $* | +grep '^\.[BRI][BRI]* [a-zA-Z0-9_][a-zA-Z0-9_]*[^a-zA-Z_]*$' $* | awk -f $awk_script_file | grep -v '([0-9]*)' rm -f $awk_script_file diff --git a/scripts/find_repeated_words.sh b/scripts/find_repeated_words.sh index 747872e..2306082 100755 --- a/scripts/find_repeated_words.sh +++ b/scripts/find_repeated_words.sh @@ -15,7 +15,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -24,13 +24,13 @@ # # -for file in "$@" ; do +for file in "$@" ; do # Do not process files that are redirects. grep -qE "^\.so man.*" "$file" if test $? -ne 0; then words=$(MANWIDTH=2000 man -l "$file" 2> /dev/null | col -b | \ tr ' \008' '\012' | sed -e '/^$/d' | \ - sed 's/ *$//' | + sed 's/ *$//' | awk 'BEGIN {p=""} {if (p==$0) print p; p=$0}' | \ grep '[a-zA-Z]' | tr '\012' ' ') if test -n "$words"; then diff --git a/scripts/find_slashes_no_parens.sh b/scripts/find_slashes_no_parens.sh index 086faac..c53034a 100755 --- a/scripts/find_slashes_no_parens.sh +++ b/scripts/find_slashes_no_parens.sh @@ -8,13 +8,13 @@ # This script is designed to help with "by hand" tidy-ups after # the automated changes made by add_parens_for_own_funcs.sh. # -# The first argument to this script names a manual page directory where -# 'man2' and 'man3' subdirectories can be found. The pages names in -# these directories are used to generate a series of regular expressions -# that can be used to search the manual page files that are named in +# The first argument to this script names a manual page directory where +# 'man2' and 'man3' subdirectories can be found. The pages names in +# these directories are used to generate a series of regular expressions +# that can be used to search the manual page files that are named in # the remaining command-line arguments. # -# Example usage: +# Example usage: # # cd man-pages-x.yy # sh find_slashes_no_parens.sh . man?/*.? > matches.log @@ -26,7 +26,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -53,14 +53,14 @@ echo "This will probably take a few minutes..." 1>&2 regexp_file=tmp.$0.regexp rm -f $regexp_file -# We grep out a few page names that are likely to generate false +# We grep out a few page names that are likely to generate false # positives... for page in $( - find $dir/man2/* $dir/man3/* -type f -name '*.[23]' | + find $dir/man2/* $dir/man3/* -type f -name '*.[23]' | egrep -v '/(stderr|stdin|stdout|errno|termios|string)\..$'); do - + base=$(basename $page | sed -e 's/\.[23]$//') echo "\\\\f[BI]$base\\\\f[PB][^(]" >> $regexp_file diff --git a/scripts/man_show_fixme.sh b/scripts/man_show_fixme.sh index 6a42b33..9c64745 100755 --- a/scripts/man_show_fixme.sh +++ b/scripts/man_show_fixme.sh @@ -7,7 +7,7 @@ for f in $*; do cat $f | awk ' /^\.\\" *FIXME/ { if ($0 ~ /.*FIXME *\..*/) { - # FIXMES of the form "FIXME ." are "private" and + # FIXMES of the form "FIXME ." are "private" and # ignored by this script } else { sub("FIXME[: ]*", "") diff --git a/scripts/sortman b/scripts/sortman new file mode 100755 index 0000000..6d1d92f --- /dev/null +++ b/scripts/sortman @@ -0,0 +1,15 @@ +#!/bin/sh + +# Copyright 2023, Alejandro Colomar +# SPDX-License-Identifier: GPL-3.0-or-later + +sed -E '/\/intro./ s/.*\.([[:digit:]])/\10\t&/' \ +| sed -E '/\/intro./! s/.*\.([[:digit:]])\>/\11\t&/' \ +| sed -E '/\/intro./! s/.*\.([[:digit:]])([[:alpha:]][[:alnum:]]*\>)/\12.\2\t&/' \ +| sed -E ' s/\t(.*)/&\n\1/' \ +| sed -E '/\t/ s/\.[[:digit:]]([[:alpha:]][[:alnum:]]*)?\>.*//' \ +| sed -E '/\t/ s/\/[_-]*/\//g' \ +| sed -E '/\t/ s/[_-]/ /g' \ +| sed -E '/\t/ {N;s/\n/\t/;}' \ +| sort -fV -k1,2 \ +| cut -f3; diff --git a/scripts/unformat_parens.sh b/scripts/unformat_parens.sh index 06bbb48..37e183a 100755 --- a/scripts/unformat_parens.sh +++ b/scripts/unformat_parens.sh @@ -12,7 +12,7 @@ # .BR name () # # This script changes instances to the latter format. -# It does not fix all such instances: some will have to be +# It does not fix all such instances: some will have to be # done manually. # # Use the "-n" option for a dry run, in order to see what would be @@ -25,7 +25,7 @@ # modify it under the terms of the GNU General Public License # as published by the Free Software Foundation; either version 2 # of the License, or (at your option) any later version. -# +# # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the @@ -56,7 +56,7 @@ done shift $(( $OPTIND - 1 )) -# Only process files with > 1 line -- single-line files are link files +# Only process files with > 1 line -- single-line files are link files for page in $(wc "$@" 2> /dev/null | awk '$1 > 1 {print $4}'| \ grep -v '^total'); do diff --git a/share/lint/groff/man.ignore.grep b/share/lint/groff/man.ignore.grep deleted file mode 100644 index 912eb57..0000000 --- a/share/lint/groff/man.ignore.grep +++ /dev/null @@ -1,3 +0,0 @@ -style: .TH missing fifth argument and second argument -style: use of deprecated macro: .PD$ -style: use of deprecated macro: .UC$ diff --git a/share/lint/mandoc/man.ignore.grep b/share/lint/mandoc/man.ignore.grep deleted file mode 100644 index a2f91bc..0000000 --- a/share/lint/mandoc/man.ignore.grep +++ /dev/null @@ -1,6 +0,0 @@ -STYLE: lower case character in document title: -UNSUPP: ignoring macro in table: -WARNING: cannot parse date, using it verbatim: TH (date) -WARNING: empty block: UR -WARNING: missing date, using "": TH -WARNING: undefined escape, printing literally: \\\\ diff --git a/share/lint/mandoc/mdoc.ignore.grep b/share/lint/mandoc/mdoc.ignore.grep deleted file mode 100644 index 3fe2831..0000000 --- a/share/lint/mandoc/mdoc.ignore.grep +++ /dev/null @@ -1,5 +0,0 @@ -STYLE: legacy man(7) date format: Dd -STYLE: lower case character in document title: Dt -STYLE: operating system explicitly specified: Os -STYLE: referenced manual not found: Xr -WARNING: cross reference to self: Xr diff --git a/share/mk/build/_.mk b/share/mk/build/_.mk index bdce760..8ced940 100644 --- a/share/mk/build/_.mk +++ b/share/mk/build/_.mk @@ -1,52 +1,25 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_BUILD_INCLUDED MAKEFILE_BUILD_INCLUDED := 1 -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk -builddir := .tmp - -SYSCONFDIR := $(srcdir)/etc - _MANDIR := $(builddir)/man -MKDIR := mkdir -p -RM := rm - - -NONSO_MAN := $(shell $(FIND) $(MANDIR)/* -type f \ - | $(GREP) '$(MANEXT)' \ - | $(XARGS) $(GREP) -l '^\.TH ' \ - | $(SORT) \ - | $(SED) 's,:,\\:,g') -NONSO_MDOC := $(shell $(FIND) $(MANDIR)/* -type f \ - | $(GREP) '$(MANEXT)' \ - | $(XARGS) $(GREP) -l '^\.Dt ' \ - | $(SORT) \ - | $(SED) 's,:,\\:,g') - - -$(builddir)/%/: - +$(info MKDIR $@) - +$(MKDIR) $@ - - .PHONY: build -build: build-catman build-html build-pdf build-ps build-src; - -.PHONY: clean -clean: - $(info RM -rf $(builddir)) - $(RM) -rf $(builddir) +build: \ + build-book \ + build-catman \ + build-html \ + build-pdf \ + build-ps \ + build-ex; endif # include guard diff --git a/share/mk/build/book.mk b/share/mk/build/book.mk new file mode 100644 index 0000000..a941ced --- /dev/null +++ b/share/mk/build/book.mk @@ -0,0 +1,42 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_BOOK_INCLUDED +MAKEFILE_BUILD_BOOK_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/groff.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk +include $(MAKEFILEDIR)/configure/build-depends/moreutils.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/src.mk + + +LMBDIR := $(srcdir)/scripts/LinuxManBook +BUILDLMB := $(LMBDIR)/build.sh + + +_LMB := $(_MANDIR)/man-pages.pdf + + +$(_LMB): $(MANPAGES) $(wildcard $(LMBDIR)/* $(LMBDIR)/*/*) | $$(@D)/ + $(info $(INFO_)Build $@) + CAT='$(CAT)' \ + PRECONV='$(PRECONV)' \ + PIC='$(PIC)' \ + TBL='$(TBL)' \ + EQN='$(EQN)' \ + TROFF='$(TROFF)' \ + GROPDF='$(GROPDF)' \ + $(BUILDLMB) $(MANDIR) \ + | $(SPONGE) $@ + + +.PHONY: build-book +build-book: $(_LMB); + + +endif # include guard diff --git a/share/mk/build/catman.mk b/share/mk/build/catman.mk deleted file mode 100644 index 7b8766e..0000000 --- a/share/mk/build/catman.mk +++ /dev/null @@ -1,89 +0,0 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_CATMAN_INCLUDED -MAKEFILE_BUILD_CATMAN_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/build/groff.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk - - -groff_man_ignore_grep := $(DATAROOTDIR)/lint/groff/man.ignore.grep - -MANWIDTH ?= 80 -TROFF_CHECKSTYLE_LVL := 3 -NROFF_LINE_LENGTH := $(shell $(EXPR) $(MANWIDTH) - 2) -NROFF_OUT_DEVICE := $(shell $(LOCALE) charmap \ - | $(GREP) -i 'utf-*8' >/dev/null \ - && $(ECHO) utf8 \ - || $(ECHO) ascii) - -DEFAULT_NROFFFLAGS := \ - -T$(NROFF_OUT_DEVICE) \ - -rLL=$(NROFF_LINE_LENGTH)n \ - -rCHECKSTYLE=$(TROFF_CHECKSTYLE_LVL) \ - -ww -EXTRA_NROFFFLAGS := -NROFFFLAGS := $(DEFAULT_NROFFFLAGS) $(EXTRA_NROFFFLAGS) - -DEFAULT_GROTTYFLAGS := -c -EXTRA_GROTTYFLAGS := -GROTTYFLAGS := $(DEFAULT_GROTTYFLAGS) $(EXTRA_GROTTYFLAGS) -GROTTY := grotty - - -_CATMAN_troff := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat.troff,$(NONSO_MAN) $(NONSO_MDOC)) -_CATMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat.set,$(NONSO_MAN)) -_CATMAN_MDOC_set:= $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat.set,$(NONSO_MDOC)) -_CATMAN := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat,$(NONSO_MAN) $(NONSO_MDOC)) - - -$(_CATMAN_troff): %.cat.troff: %.eqn | $$(@D)/ - $(info EQN $@) - ! ($(EQN) -T$(NROFF_OUT_DEVICE) $(EQNFLAGS) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_CATMAN_MAN_set): %.cat.set: %.cat.troff $(groff_man_ignore_grep) | $$(@D)/ - $(info TROFF $@) - ! ($(TROFF) $(TROFFFLAGS_MAN) $(NROFFFLAGS) <$< 2>&1 >$@ \ - | $(GREP) -v -f '$(groff_man_ignore_grep)' \ - ||:; \ - ) \ - | $(GREP) ^ >&2 - -$(_CATMAN_MDOC_set): %.cat.set: %.cat.troff | $$(@D)/ - $(info TROFF $@) - ! ($(TROFF) $(TROFFFLAGS_MDOC) $(NROFFFLAGS) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_CATMAN): %.cat: %.cat.set | $$(@D)/ - $(info GROTTY $@) - $(GROTTY) $(GROTTYFLAGS) <$< >$@ - - -.PHONY: build-catman-eqn -build-catman-eqn: $(_CATMAN_troff); - -.PHONY: build-catman-troff-man -build-catman-troff-man: $(_CATMAN_MAN_set); - -.PHONY: build-catman-troff-mdoc -build-catman-troff-mdoc: $(_CATMAN_MDOC_set); - -.PHONY: build-catman-troff -build-catman-troff: build-catman-troff-man build-catman-troff-mdoc; - -.PHONY: build-catman-grotty -build-catman-grotty: $(_CATMAN); - -.PHONY: build-catman -build-catman: build-catman-grotty; - - -endif # include guard diff --git a/share/mk/build/catman/_.mk b/share/mk/build/catman/_.mk new file mode 100644 index 0000000..78aa862 --- /dev/null +++ b/share/mk/build/catman/_.mk @@ -0,0 +1,13 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_CATMAN_INCLUDED +MAKEFILE_BUILD_CATMAN_INCLUDED := 1 + + +.PHONY: build-catman +build-catman: build-catman-grotty; + + +endif # include guard diff --git a/share/mk/build/catman/eqn.mk b/share/mk/build/catman/eqn.mk new file mode 100644 index 0000000..48b6e75 --- /dev/null +++ b/share/mk/build/catman/eqn.mk @@ -0,0 +1,27 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_CATMAN_EQN_INCLUDED +MAKEFILE_BUILD_CATMAN_EQN_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/pre/tbl.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk + + +_CATMAN_troff := $(patsubst %.eqn,%.cat.troff,$(_MAN_eqn)) + + +$(_CATMAN_troff): %.cat.troff: %.eqn $(MK) | $$(@D)/ + $(info $(INFO_)EQN $@) + ! ($(EQN) -T$(NROFF_OUT_DEVICE) $(EQNFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-catman-eqn +build-catman-eqn: $(_CATMAN_troff); + + +endif # include guard diff --git a/share/mk/build/catman/grotty.mk b/share/mk/build/catman/grotty.mk new file mode 100644 index 0000000..7def414 --- /dev/null +++ b/share/mk/build/catman/grotty.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_CATMAN_GROTTY_INCLUDED +MAKEFILE_BUILD_CATMAN_GROTTY_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/catman/troff.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk + + +_CATMAN := $(patsubst %.cat.set,%.cat,$(_CATMAN_MAN_set) $(_CATMAN_MDOC_set)) + + +$(_CATMAN): %.cat: %.cat.set $(MK) | $$(@D)/ + $(info $(INFO_)GROTTY $@) + $(GROTTY) $(GROTTYFLAGS) <$< >$@ + + +.PHONY: build-catman-grotty +build-catman-grotty: $(_CATMAN); + + +endif # include guard diff --git a/share/mk/build/catman/troff.ignore.grep b/share/mk/build/catman/troff.ignore.grep new file mode 100644 index 0000000..912eb57 --- /dev/null +++ b/share/mk/build/catman/troff.ignore.grep @@ -0,0 +1,3 @@ +style: .TH missing fifth argument and second argument +style: use of deprecated macro: .PD$ +style: use of deprecated macro: .UC$ diff --git a/share/mk/build/catman/troff.mk b/share/mk/build/catman/troff.mk new file mode 100644 index 0000000..c38ba17 --- /dev/null +++ b/share/mk/build/catman/troff.mk @@ -0,0 +1,85 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_CATMAN_TROFF_INCLUDED +MAKEFILE_BUILD_CATMAN_TROFF_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/configure/xfail.mk +include $(MAKEFILEDIR)/src.mk + + +_XFAIL_CATMAN_MAN_set := \ + $(_MANDIR)/man2/fanotify_init.2.cat.set \ + $(_MANDIR)/man3/unlocked_stdio.3.cat.set \ + $(_MANDIR)/man4/console_codes.4.cat.set \ + $(_MANDIR)/man4/lirc.4.cat.set \ + $(_MANDIR)/man5/proc_pid_smaps.5.cat.set \ + $(_MANDIR)/man5/tzfile.5.cat.set \ + $(_MANDIR)/man7/ascii.7.cat.set \ + $(_MANDIR)/man7/bpf-helpers.7.cat.set \ + $(_MANDIR)/man7/charsets.7.cat.set \ + $(_MANDIR)/man7/iso_8859-1.7.cat.set \ + $(_MANDIR)/man7/iso_8859-2.7.cat.set \ + $(_MANDIR)/man7/iso_8859-3.7.cat.set \ + $(_MANDIR)/man7/iso_8859-4.7.cat.set \ + $(_MANDIR)/man7/iso_8859-5.7.cat.set \ + $(_MANDIR)/man7/iso_8859-6.7.cat.set \ + $(_MANDIR)/man7/iso_8859-7.7.cat.set \ + $(_MANDIR)/man7/iso_8859-8.7.cat.set \ + $(_MANDIR)/man7/iso_8859-9.7.cat.set \ + $(_MANDIR)/man7/iso_8859-10.7.cat.set \ + $(_MANDIR)/man7/iso_8859-11.7.cat.set \ + $(_MANDIR)/man7/iso_8859-13.7.cat.set \ + $(_MANDIR)/man7/iso_8859-14.7.cat.set \ + $(_MANDIR)/man7/iso_8859-15.7.cat.set \ + $(_MANDIR)/man7/iso_8859-16.7.cat.set \ + $(_MANDIR)/man8/tzselect.8.cat.set \ + $(_MANDIR)/man8/zdump.8.cat.set \ + $(_MANDIR)/man8/zic.8.cat.set + + + +troff_man_ignore_grep := $(MAKEFILEDIR)/build/catman/troff.ignore.grep + + +_CATMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat.set,$(NONSO_MAN)) +_CATMAN_MDOC_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat.set,$(NONSO_MDOC)) + + +ifeq ($(SKIP_XFAIL),yes) +_CATMAN_MAN_set := $(filter-out $(_XFAIL_CATMAN_MAN_set), $(_CATMAN_MAN_set)) +endif + + +$(_CATMAN_MAN_set): %.cat.set: %.cat.troff $(troff_man_ignore_grep) $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -man $(TROFFFLAGS) $(NROFFFLAGS) <$< 2>&1 >$@ \ + | $(GREP) -v -f '$(troff_man_ignore_grep)' \ + || $(TRUE); \ + ) \ + | $(GREP) ^ >&2 + +$(_CATMAN_MDOC_set): %.cat.set: %.cat.troff $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -mdoc $(TROFFFLAGS) $(NROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-catman-troff-man +build-catman-troff-man: $(_CATMAN_MAN_set); + +.PHONY: build-catman-troff-mdoc +build-catman-troff-mdoc: $(_CATMAN_MDOC_set); + +.PHONY: build-catman-troff +build-catman-troff: build-catman-troff-man build-catman-troff-mdoc; + + +endif # include guard diff --git a/share/mk/build/examples/_.mk b/share/mk/build/examples/_.mk new file mode 100644 index 0000000..c01a952 --- /dev/null +++ b/share/mk/build/examples/_.mk @@ -0,0 +1,28 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_EX_DIR_INCLUDED +MAKEFILE_BUILD_EX_DIR_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/src.mk + + +_PAGEEXDIRS := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.d/,$(NONSO_MAN)) + + +$(_PAGEEXDIRS): + +$(info $(INFO_)MKDIR $@) + +$(MKDIR) -p $@ + +$(TOUCH) $@ + + +.PHONY: build-ex +build-ex: build-ex-ld; + + +endif # include guard diff --git a/share/mk/build/examples/cc.mk b/share/mk/build/examples/cc.mk new file mode 100644 index 0000000..6513fbe --- /dev/null +++ b/share/mk/build/examples/cc.mk @@ -0,0 +1,54 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_EX_CC_INCLUDED +MAKEFILE_BUILD_EX_CC_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/examples/src.mk +include $(MAKEFILEDIR)/configure/build-depends/cc.mk +include $(MAKEFILEDIR)/configure/build-depends/cpp.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_UNITS_ex_o := \ + $(_MANDIR)/man2/bpf.2.d/bpf.o \ + $(_MANDIR)/man2/seccomp.2.d/seccomp.o \ + $(_MANDIR)/man2/sigaction.2.d/sigaction.o \ + $(_MANDIR)/man2/spu_run.2.d/spu_run.o \ + $(_MANDIR)/man2/_syscall.2.d/_syscall.o \ + $(_MANDIR)/man3/circleq.3.d/circleq.o \ + $(_MANDIR)/man3/encrypt.3.d/encrypt.o \ + $(_MANDIR)/man3/getsubopt.3.d/getsubopt.o \ + $(_MANDIR)/man3/hsearch.3.d/hsearch.o \ + $(_MANDIR)/man3/malloc_info.3.d/malloc_info.o \ + $(_MANDIR)/man3/mallopt.3.d/mallopt.o \ + $(_MANDIR)/man3/matherr.3.d/matherr.o \ + $(_MANDIR)/man3/mcheck.3.d/mcheck.o \ + $(_MANDIR)/man3/mtrace.3.d/t_mtrace.o \ + $(_MANDIR)/man3/__ppc_get_timebase.3.d/__ppc_get_timebase.o \ + $(_MANDIR)/man3/pthread_getcpuclockid.3.d/pthread_getcpuclockid.o \ + $(_MANDIR)/man3/rtime.3.d/rtime.o \ + $(_MANDIR)/man3/setbuf.3.d/setbuf.o \ + $(_MANDIR)/man3/stpncpy.3.d/stpncpy.o \ + $(_MANDIR)/man3head/printf.h.3head.d/register_printf_specifier.o + + +_UNITS_ex_o := $(patsubst %.c,%.o,$(_UNITS_ex_c)) +ifeq ($(SKIP_XFAIL),yes) +_UNITS_ex_o := $(filter-out $(_XFAIL_UNITS_ex_o), $(_UNITS_ex_o)) +endif + + +$(_UNITS_ex_o): %.o: %.c $(MK) + $(info $(INFO_)CC $@) + $(CC) -c $(CPPFLAGS) $(CFLAGS) -o $@ $< + + +.PHONY: build-ex-cc +build-ex-cc: $(_UNITS_ex_o); + + +endif # include guard diff --git a/share/mk/build/examples/ld.mk b/share/mk/build/examples/ld.mk new file mode 100644 index 0000000..9d5535d --- /dev/null +++ b/share/mk/build/examples/ld.mk @@ -0,0 +1,51 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_EX_LD_INCLUDED +MAKEFILE_BUILD_EX_LD_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/examples/cc.mk +include $(MAKEFILEDIR)/configure/build-depends/ld.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_UNITS_ex_bin := \ + $(_MANDIR)/man2/add_key.2.d/add_key \ + $(_MANDIR)/man2/keyctl.2.d/key_instantiate \ + $(_MANDIR)/man2/request_key.2.d/t_request_key \ + $(_MANDIR)/man2/select_tut.2.d/select \ + $(_MANDIR)/man2/shmop.2.d/svshm_string_read \ + $(_MANDIR)/man3/cacos.3.d/cacos \ + $(_MANDIR)/man3/cacosh.3.d/cacosh \ + $(_MANDIR)/man3/catan.3.d/catan \ + $(_MANDIR)/man3/catanh.3.d/catanh \ + $(_MANDIR)/man3/getaddrinfo_a.3.d/async \ + $(_MANDIR)/man3/inet_net_pton.3.d/inet_net_pton \ + $(_MANDIR)/man3/list.3.d/list \ + $(_MANDIR)/man3/mallinfo.3.d/mallinfo \ + $(_MANDIR)/man3/slist.3.d/slist \ + $(_MANDIR)/man3/stailq.3.d/stailq \ + $(_MANDIR)/man3/strncat.3.d/strncat \ + $(_MANDIR)/man3/tailq.3.d/tailq \ + $(_MANDIR)/man3/tsearch.3.d/tsearch + + +_UNITS_ex_bin := $(patsubst %.o,%,$(_UNITS_ex_o)) +ifeq ($(SKIP_XFAIL),yes) +_UNITS_ex_bin := $(filter-out $(_XFAIL_UNITS_ex_bin), $(_UNITS_ex_bin)) +endif + + +$(_UNITS_ex_bin): %: %.o $(MK) + $(info $(INFO_)LD $@) + $(LD) $(LDFLAGS) -o $@ $< $(LDLIBS) + + +.PHONY: build-ex-ld +build-ex-ld: $(_UNITS_ex_bin); + + +endif # include guard diff --git a/share/mk/build/examples/src.mk b/share/mk/build/examples/src.mk new file mode 100644 index 0000000..f47a713 --- /dev/null +++ b/share/mk/build/examples/src.mk @@ -0,0 +1,55 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_EX_SRC_INCLUDED +MAKEFILE_BUILD_EX_SRC_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/findutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/mandoc.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk +include $(MAKEFILEDIR)/src.mk + + +_UNITS_ex_src := \ + $(patsubst $(MANDIR)/%, $(_MANDIR)/%, \ + $(shell \ + $(FIND) $(MANDIR)/* -type f \ + | $(GREP) '$(MANEXT)' \ + | $(XARGS) $(GREP) -H '^\.\\" SRC BEGIN ' \ + | $(SED) 's,:\.\\" SRC BEGIN (,.d/,' \ + | $(SED) 's/)//' \ + | $(SORTMAN) \ + | $(SED) 's,:,\\:,g' \ + ) \ + ) +_UNITS_ex_h := $(filter %.h,$(_UNITS_ex_src)) +_UNITS_ex_c := $(filter %.c,$(_UNITS_ex_src)) + + +$(_UNITS_ex_src): $$(patsubst $(_MANDIR)/%.d,$(MANDIR)/%,$$(@D)) $(MK) | $$(@D)/ +$(_UNITS_ex_c): $$(filter $$(@D)/%.h,$(_UNITS_ex_h)) +$(_UNITS_ex_src): + $(info $(INFO_)SED $@) + <$< \ + $(SED) -n \ + -e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \ + -e '/^\.SH EXAMPLES/p' \ + -e "/^\... SRC BEGIN ($(@F))$$/,/^\... SRC END$$/p" \ + | $(MANDOC) -Tutf8 \ + | $(HEAD) -n-2 \ + | $(SED) '/^[^ ]/d' \ + | $(SED) 's/^ //' \ + >$@ + + +.PHONY: build-ex-src +build-ex-src: $(_UNITS_ex_src); + + +endif # include guard diff --git a/share/mk/build/groff.mk b/share/mk/build/groff.mk deleted file mode 100644 index 2a5a3de..0000000 --- a/share/mk/build/groff.mk +++ /dev/null @@ -1,39 +0,0 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_GROFF_INCLUDED -MAKEFILE_BUILD_GROFF_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk - - -DEFAULT_EQNFLAGS := -EXTRA_EQNFLAGS := -EQNFLAGS := $(DEFAULT_EQNFLAGS) $(EXTRA_EQNFLAGS) -EQN := eqn - -DEFAULT_TROFFFLAGS := -wbreak -EXTRA_TROFFFLAGS := -TROFFFLAGS := $(DEFAULT_TROFFFLAGS) $(EXTRA_TROFFFLAGS) -TROFF := troff - -DEFAULT_TROFFFLAGS_MAN := \ - $(TROFFFLAGS) \ - -man -EXTRA_TROFFFLAGS_MAN := -TROFFFLAGS_MAN := $(DEFAULT_TROFFFLAGS_MAN) $(EXTRA_TROFFFLAGS_MAN) - -DEFAULT_TROFFFLAGS_MDOC := \ - $(TROFFFLAGS) \ - -mdoc -EXTRA_TROFFFLAGS_MDOC := -TROFFFLAGS_MDOC := $(DEFAULT_TROFFFLAGS_MDOC) $(EXTRA_TROFFFLAGS_MDOC) - - -endif # include guard diff --git a/share/mk/build/html.mk b/share/mk/build/html.mk deleted file mode 100644 index 084654d..0000000 --- a/share/mk/build/html.mk +++ /dev/null @@ -1,42 +0,0 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_HTML_INCLUDED -MAKEFILE_BUILD_HTML_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk - - -htmlext := .html -_HTMLDIR := $(builddir)/html - - -DEFAULT_MAN2HTMLFLAGS := -EXTRA_MAN2HTMLFLAGS := -MAN2HTMLFLAGS := $(DEFAULT_MAN2HTMLFLAGS) $(EXTRA_MAN2HTMLFLAGS) -MAN2HTML := man2html - - -_HTMLPAGES := $(patsubst $(MANDIR)/%,$(_HTMLDIR)/%$(htmlext),$(MANPAGES)) - - -# Use with -# make MAN2HTMLFLAGS=whatever html -# The sed removes the lines "Content-type: text/html\n\n" -$(_HTMLPAGES): $(_HTMLDIR)/%$(htmlext): $(MANDIR)/% | $$(@D)/ - $(info MAN2HTML $@) - $(MAN2HTML) $(MAN2HTMLFLAGS) $< \ - | $(SED) -e 1,2d >$@ - - -.PHONY: build-html html -build-html html: $(_HTMLPAGES); - - -endif # include guard diff --git a/share/mk/build/html/_.mk b/share/mk/build/html/_.mk new file mode 100644 index 0000000..b3e3041 --- /dev/null +++ b/share/mk/build/html/_.mk @@ -0,0 +1,13 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_HTML_INCLUDED +MAKEFILE_BUILD_HTML_INCLUDED := 1 + + +.PHONY: build-html +build-html: build-html-post-grohtml; + + +endif # include guard diff --git a/share/mk/build/html/post-grohtml.mk b/share/mk/build/html/post-grohtml.mk new file mode 100644 index 0000000..fe77776 --- /dev/null +++ b/share/mk/build/html/post-grohtml.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_HTML_POST_GROHTML_INCLUDED +MAKEFILE_BUILD_HTML_POST_GROHTML_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/html/troff.mk +include $(MAKEFILEDIR)/configure/build-depends/groff.mk + + +_HTMLMAN := $(patsubst %.html.set,%.html,$(_HTMLMAN_MAN_set) $(_HTMLMAN_MDOC_set)) + + +$(_HTMLMAN): %.html: %.html.set $(MK) | $$(@D)/ + $(info $(INFO_)POST_GROHTML $@) + $(POST_GROHTML) $(POST_GROHTMLFLAGS) <$< >$@ + + +.PHONY: build-html-post-grohtml +build-html-post-grohtml: $(_HTMLMAN); + + +endif # include guard diff --git a/share/mk/build/html/troff.mk b/share/mk/build/html/troff.mk new file mode 100644 index 0000000..010c211 --- /dev/null +++ b/share/mk/build/html/troff.mk @@ -0,0 +1,58 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_HTML_TROFF_INCLUDED +MAKEFILE_BUILD_HTML_TROFF_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/configure/xfail.mk +include $(MAKEFILEDIR)/src.mk + + +_XFAIL_HTMLMAN_MAN_set := \ + $(_MANDIR)/man2/fanotify_init.2.html.set \ + $(_MANDIR)/man2/membarrier.2.html.set \ + $(_MANDIR)/man5/proc.5.html.set \ + $(_MANDIR)/man7/bpf-helpers.7.html.set \ + $(_MANDIR)/man7/charsets.7.html.set \ + $(_MANDIR)/man7/iso_8859-16.7.html.set \ + $(_MANDIR)/man7/iso_8859-6.7.html.set \ + $(_MANDIR)/man8/zic.8.html.set + + +_HTMLMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.html.set,$(NONSO_MAN)) +_HTMLMAN_MDOC_set:= $(patsubst $(MANDIR)/%,$(_MANDIR)/%.html.set,$(NONSO_MDOC)) + + +ifeq ($(SKIP_XFAIL),yes) +_HTMLMAN_MAN_set := $(filter-out $(_XFAIL_HTMLMAN_MAN_set), $(_HTMLMAN_MAN_set)) +endif + + +$(_HTMLMAN_MAN_set): %.html.set: %.eqn $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -man -Thtml $(TROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + +$(_HTMLMAN_MDOC_set): %.html.set: %.eqn $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -mdoc -Thtml $(TROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-html-troff-man +build-html-troff-man: $(_HTMLMAN_MAN_set); + +.PHONY: build-html-troff-mdoc +build-html-troff-mdoc: $(_HTMLMAN_MDOC_set); + +.PHONY: build-html-troff +build-html-troff: build-html-troff-man build-html-troff-mdoc; + + +endif # include guard diff --git a/share/mk/build/pdf.mk b/share/mk/build/pdf.mk deleted file mode 100644 index 380c6c6..0000000 --- a/share/mk/build/pdf.mk +++ /dev/null @@ -1,68 +0,0 @@ -######################################################################## -# Copyright 2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_PDF_INCLUDED -MAKEFILE_BUILD_PDF_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/build/groff.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk - - -DEFAULT_GROPDFFLAGS := -EXTRA_GROPDFFLAGS := -GROPDFFLAGS := $(DEFAULT_GROPDFFLAGS) $(EXTRA_GROPDFFLAGS) -GROPDF := gropdf - - -_PDFMAN_troff := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.pdf.troff,$(NONSO_MAN) $(NONSO_MDOC)) -_PDFMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.pdf.set,$(NONSO_MAN)) -_PDFMAN_MDOC_set:= $(patsubst $(MANDIR)/%,$(_MANDIR)/%.pdf.set,$(NONSO_MDOC)) -_PDFMAN := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.pdf,$(NONSO_MAN) $(NONSO_MDOC)) - - -$(_PDFMAN_troff): %.pdf.troff: %.eqn | $$(@D)/ - $(info EQN $@) - ! ($(EQN) -Tpdf $(EQNFLAGS) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_PDFMAN_MAN_set): %.pdf.set: %.pdf.troff | $$(@D)/ - $(info TROFF $@) - ! ($(TROFF) -Tpdf $(TROFFFLAGS_MAN) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_PDFMAN_MDOC_set): %.pdf.set: %.pdf.troff | $$(@D)/ - $(info TROFF $@) - ! ($(TROFF) -Tpdf $(TROFFFLAGS_MDOC) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_PDFMAN): %.pdf: %.pdf.set | $$(@D)/ - $(info GROPDF $@) - $(GROPDF) $(GROPDFFLAGS) <$< >$@ - - -.PHONY: build-pdf-eqn -build-pdf-eqn: $(_PDFMAN_troff); - -.PHONY: build-pdf-troff-man -build-pdf-troff-man: $(_PDFMAN_MAN_set); - -.PHONY: build-pdf-troff-mdoc -build-pdf-troff-mdoc: $(_PDFMAN_MDOC_set); - -.PHONY: build-pdf-troff -build-pdf-troff: build-pdf-troff-man build-pdf-troff-mdoc; - -.PHONY: build-pdf-gropdf -build-pdf-gropdf: $(_PDFMAN); - -.PHONY: build-pdf -build-pdf: build-pdf-gropdf; - - -endif # include guard diff --git a/share/mk/build/pdf/_.mk b/share/mk/build/pdf/_.mk new file mode 100644 index 0000000..f6660aa --- /dev/null +++ b/share/mk/build/pdf/_.mk @@ -0,0 +1,13 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PDF_INCLUDED +MAKEFILE_BUILD_PDF_INCLUDED := 1 + + +.PHONY: build-pdf +build-pdf: build-pdf-gropdf; + + +endif # include guard diff --git a/share/mk/build/pdf/eqn.mk b/share/mk/build/pdf/eqn.mk new file mode 100644 index 0000000..bb0598b --- /dev/null +++ b/share/mk/build/pdf/eqn.mk @@ -0,0 +1,27 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PDF_EQN_INCLUDED +MAKEFILE_BUILD_PDF_EQN_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/pre/tbl.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk + + +_PDFMAN_troff := $(patsubst %.eqn,%.pdf.troff,$(_MAN_eqn)) + + +$(_PDFMAN_troff): %.pdf.troff: %.eqn $(MK) | $$(@D)/ + $(info $(INFO_)EQN $@) + ! ($(EQN) -Tpdf $(EQNFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-pdf-eqn +build-pdf-eqn: $(_PDFMAN_troff); + + +endif # include guard diff --git a/share/mk/build/pdf/gropdf.mk b/share/mk/build/pdf/gropdf.mk new file mode 100644 index 0000000..0913122 --- /dev/null +++ b/share/mk/build/pdf/gropdf.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PDF_GROPDF_INCLUDED +MAKEFILE_BUILD_PDF_GROPDF_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/pdf/troff.mk +include $(MAKEFILEDIR)/configure/build-depends/groff.mk + + +_PDFMAN := $(patsubst %.pdf.set,%.pdf,$(_PDFMAN_MAN_set) $(_PDFMAN_MDOC_set)) + + +$(_PDFMAN): %.pdf: %.pdf.set $(MK) | $$(@D)/ + $(info $(INFO_)GROPDF $@) + $(GROPDF) $(GROPDFFLAGS) <$< >$@ + + +.PHONY: build-pdf-gropdf +build-pdf-gropdf: $(_PDFMAN); + + +endif # include guard diff --git a/share/mk/build/pdf/troff.mk b/share/mk/build/pdf/troff.mk new file mode 100644 index 0000000..5254d5d --- /dev/null +++ b/share/mk/build/pdf/troff.mk @@ -0,0 +1,75 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PDF_TROFF_INCLUDED +MAKEFILE_BUILD_PDF_TROFF_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/configure/xfail.mk +include $(MAKEFILEDIR)/src.mk + + +_XFAIL_PDFMAN_MAN_set := \ + $(_MANDIR)/man1/iconv.1.pdf.set \ + $(_MANDIR)/man2/fanotify_init.2.pdf.set \ + $(_MANDIR)/man2/syscall.2.pdf.set \ + $(_MANDIR)/man3/newlocale.3.pdf.set \ + $(_MANDIR)/man7/address_families.7.pdf.set \ + $(_MANDIR)/man7/armscii-8.7.pdf.set \ + $(_MANDIR)/man7/ascii.7.pdf.set \ + $(_MANDIR)/man7/bpf-helpers.7.pdf.set \ + $(_MANDIR)/man7/charsets.7.pdf.set \ + $(_MANDIR)/man7/cp1251.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-2.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-3.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-4.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-5.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-6.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-7.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-8.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-10.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-11.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-13.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-14.7.pdf.set \ + $(_MANDIR)/man7/iso_8859-16.7.pdf.set \ + $(_MANDIR)/man7/koi8-r.7.pdf.set \ + $(_MANDIR)/man7/koi8-u.7.pdf.set \ + $(_MANDIR)/man7/vdso.7.pdf.set + + +_PDFMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.pdf.set,$(NONSO_MAN)) +_PDFMAN_MDOC_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.pdf.set,$(NONSO_MDOC)) + + +ifeq ($(SKIP_XFAIL),yes) +_PDFMAN_MAN_set := $(filter-out $(_XFAIL_PDFMAN_MAN_set), $(_PDFMAN_MAN_set)) +endif + + +$(_PDFMAN_MAN_set): %.pdf.set: %.pdf.troff $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -man -Tpdf $(TROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + +$(_PDFMAN_MDOC_set): %.pdf.set: %.pdf.troff $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -mdoc -Tpdf $(TROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-pdf-troff-man +build-pdf-troff-man: $(_PDFMAN_MAN_set); + +.PHONY: build-pdf-troff-mdoc +build-pdf-troff-mdoc: $(_PDFMAN_MDOC_set); + +.PHONY: build-pdf-troff +build-pdf-troff: build-pdf-troff-man build-pdf-troff-mdoc; + + +endif # include guard diff --git a/share/mk/build/pre.mk b/share/mk/build/pre.mk deleted file mode 100644 index 4c458fa..0000000 --- a/share/mk/build/pre.mk +++ /dev/null @@ -1,47 +0,0 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_PRE_INCLUDED -MAKEFILE_BUILD_PRE_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk - - -DEFAULT_PRECONVFLAGS := -EXTRA_PRECONVFLAGS := -PRECONVFLAGS := $(DEFAULT_PRECONVFLAGS) $(EXTRA_PRECONVFLAGS) -PRECONV := preconv - -TBL := tbl - - -_MAN_tbl := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.tbl,$(NONSO_MAN) $(NONSO_MDOC)) -_MAN_eqn := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.eqn,$(NONSO_MAN) $(NONSO_MDOC)) - - -$(_MAN_tbl): $(_MANDIR)/%.tbl: $(MANDIR)/% | $$(@D)/ - $(info PRECONV $@) - $(PRECONV) $(PRECONVFLAGS) $< >$@ - -$(_MAN_eqn): %.eqn: %.tbl | $$(@D)/ - $(info TBL $@) - $(TBL) <$< >$@ - - -.PHONY: build-pre-preconv -build-pre-preconv: $(_MAN_tbl); - -.PHONY: build-pre-tbl -build-pre-tbl: $(_MAN_eqn); - -.PHONY: build-pre -build-pre: build-pre-tbl; - - -endif # include guard diff --git a/share/mk/build/pre/_.mk b/share/mk/build/pre/_.mk new file mode 100644 index 0000000..f0e86f4 --- /dev/null +++ b/share/mk/build/pre/_.mk @@ -0,0 +1,13 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PRE_INCLUDED +MAKEFILE_BUILD_PRE_INCLUDED := 1 + + +.PHONY: build-pre +build-pre: build-pre-tbl; + + +endif # include guard diff --git a/share/mk/build/pre/preconv.mk b/share/mk/build/pre/preconv.mk new file mode 100644 index 0000000..73aa1da --- /dev/null +++ b/share/mk/build/pre/preconv.mk @@ -0,0 +1,27 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PRE_PRECONV_INCLUDED +MAKEFILE_BUILD_PRE_PRECONV_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/src.mk + + +_MAN_tbl := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.tbl,$(NONSO_MAN) $(NONSO_MDOC)) + + +$(_MAN_tbl): $(_MANDIR)/%.tbl: $(MANDIR)/% $(MK) | $$(@D)/ + $(info $(INFO_)PRECONV $@) + $(PRECONV) $(PRECONVFLAGS) $< >$@ + + +.PHONY: build-pre-preconv +build-pre-preconv: $(_MAN_tbl); + + +endif # include guard diff --git a/share/mk/build/pre/tbl.mk b/share/mk/build/pre/tbl.mk new file mode 100644 index 0000000..24486f8 --- /dev/null +++ b/share/mk/build/pre/tbl.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PRE_TBL_INCLUDED +MAKEFILE_BUILD_PRE_TBL_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/pre/preconv.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk + + +_MAN_eqn := $(patsubst %.tbl,%.eqn,$(_MAN_tbl)) + + +$(_MAN_eqn): %.eqn: %.tbl $(MK) | $$(@D)/ + $(info $(INFO_)TBL $@) + $(TBL) <$< >$@ + + +.PHONY: build-pre-tbl +build-pre-tbl: $(_MAN_eqn); + + +endif # include guard diff --git a/share/mk/build/ps.mk b/share/mk/build/ps.mk deleted file mode 100644 index 5b29dc1..0000000 --- a/share/mk/build/ps.mk +++ /dev/null @@ -1,68 +0,0 @@ -######################################################################## -# Copyright 2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_PS_INCLUDED -MAKEFILE_BUILD_PS_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/build/groff.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk - - -DEFAULT_GROPSFLAGS := -EXTRA_GROPSFLAGS := -GROPSFLAGS := $(DEFAULT_GROPSFLAGS) $(EXTRA_GROPSFLAGS) -GROPS := grops - - -_PSMAN_troff := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.ps.troff,$(NONSO_MAN) $(NONSO_MDOC)) -_PSMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.ps.set,$(NONSO_MAN)) -_PSMAN_MDOC_set:= $(patsubst $(MANDIR)/%,$(_MANDIR)/%.ps.set,$(NONSO_MDOC)) -_PSMAN := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.ps,$(NONSO_MAN) $(NONSO_MDOC)) - - -$(_PSMAN_troff): %.ps.troff: %.eqn | $$(@D)/ - $(info EQN $@) - ! ($(EQN) -Tps $(EQNFLAGS) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_PSMAN_MAN_set): %.ps.set: %.ps.troff | $$(@D)/ - $(info TROFF $@) - ! ($(TROFF) -Tps $(TROFFFLAGS_MAN) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_PSMAN_MDOC_set): %.ps.set: %.ps.troff | $$(@D)/ - $(info TROFF $@) - ! ($(TROFF) -Tps $(TROFFFLAGS_MDOC) <$< 2>&1 >$@) \ - | $(GREP) ^ >&2 - -$(_PSMAN): %.ps: %.ps.set | $$(@D)/ - $(info GROPS $@) - $(GROPS) $(GROPSFLAGS) <$< >$@ - - -.PHONY: build-ps-eqn -build-ps-eqn: $(_PSMAN_troff); - -.PHONY: build-ps-troff-man -build-ps-troff-man: $(_PSMAN_MAN_set); - -.PHONY: build-ps-troff-mdoc -build-ps-troff-mdoc: $(_PSMAN_MDOC_set); - -.PHONY: build-ps-troff -build-ps-troff: build-ps-troff-man build-ps-troff-mdoc; - -.PHONY: build-ps-grops -build-ps-grops: $(_PSMAN); - -.PHONY: build-ps -build-ps: build-ps-grops; - - -endif # include guard diff --git a/share/mk/build/ps/_.mk b/share/mk/build/ps/_.mk new file mode 100644 index 0000000..b92ebfc --- /dev/null +++ b/share/mk/build/ps/_.mk @@ -0,0 +1,13 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PS_INCLUDED +MAKEFILE_BUILD_PS_INCLUDED := 1 + + +.PHONY: build-ps +build-ps: build-ps-grops; + + +endif # include guard diff --git a/share/mk/build/ps/eqn.mk b/share/mk/build/ps/eqn.mk new file mode 100644 index 0000000..a4c921e --- /dev/null +++ b/share/mk/build/ps/eqn.mk @@ -0,0 +1,27 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PS_EQN_INCLUDED +MAKEFILE_BUILD_PS_EQN_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/pre/tbl.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk + + +_PSMAN_troff := $(patsubst %.eqn,%.ps.troff,$(_MAN_eqn)) + + +$(_PSMAN_troff): %.ps.troff: %.eqn $(MK) | $$(@D)/ + $(info $(INFO_)EQN $@) + ! ($(EQN) -Tps $(EQNFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-ps-eqn +build-ps-eqn: $(_PSMAN_troff); + + +endif # include guard diff --git a/share/mk/build/ps/grops.mk b/share/mk/build/ps/grops.mk new file mode 100644 index 0000000..cca9b44 --- /dev/null +++ b/share/mk/build/ps/grops.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PS_GROPS_INCLUDED +MAKEFILE_BUILD_PS_GROPS_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/ps/troff.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk + + +_PSMAN := $(patsubst %.ps.set,%.ps,$(_PSMAN_MAN_set) $(_PSMAN_MDOC_set)) + + +$(_PSMAN): %.ps: %.ps.set $(MK) | $$(@D)/ + $(info $(INFO_)GROPS $@) + $(GROPS) $(GROPSFLAGS) <$< >$@ + + +.PHONY: build-ps-grops +build-ps-grops: $(_PSMAN); + + +endif # include guard diff --git a/share/mk/build/ps/troff.mk b/share/mk/build/ps/troff.mk new file mode 100644 index 0000000..1492821 --- /dev/null +++ b/share/mk/build/ps/troff.mk @@ -0,0 +1,75 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_BUILD_PS_TROFF_INCLUDED +MAKEFILE_BUILD_PS_TROFF_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/groff-base.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/configure/xfail.mk +include $(MAKEFILEDIR)/src.mk + + +_XFAIL_PSMAN_MAN_set := \ + $(_MANDIR)/man1/iconv.1.ps.set \ + $(_MANDIR)/man2/fanotify_init.2.ps.set \ + $(_MANDIR)/man2/syscall.2.ps.set \ + $(_MANDIR)/man3/newlocale.3.ps.set \ + $(_MANDIR)/man7/address_families.7.ps.set \ + $(_MANDIR)/man7/armscii-8.7.ps.set \ + $(_MANDIR)/man7/ascii.7.ps.set \ + $(_MANDIR)/man7/bpf-helpers.7.ps.set \ + $(_MANDIR)/man7/charsets.7.ps.set \ + $(_MANDIR)/man7/cp1251.7.ps.set \ + $(_MANDIR)/man7/iso_8859-2.7.ps.set \ + $(_MANDIR)/man7/iso_8859-3.7.ps.set \ + $(_MANDIR)/man7/iso_8859-4.7.ps.set \ + $(_MANDIR)/man7/iso_8859-5.7.ps.set \ + $(_MANDIR)/man7/iso_8859-6.7.ps.set \ + $(_MANDIR)/man7/iso_8859-7.7.ps.set \ + $(_MANDIR)/man7/iso_8859-8.7.ps.set \ + $(_MANDIR)/man7/iso_8859-10.7.ps.set \ + $(_MANDIR)/man7/iso_8859-11.7.ps.set \ + $(_MANDIR)/man7/iso_8859-13.7.ps.set \ + $(_MANDIR)/man7/iso_8859-14.7.ps.set \ + $(_MANDIR)/man7/iso_8859-16.7.ps.set \ + $(_MANDIR)/man7/koi8-r.7.ps.set \ + $(_MANDIR)/man7/koi8-u.7.ps.set \ + $(_MANDIR)/man7/vdso.7.ps.set + + +_PSMAN_MAN_set := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.ps.set,$(NONSO_MAN)) +_PSMAN_MDOC_set:= $(patsubst $(MANDIR)/%,$(_MANDIR)/%.ps.set,$(NONSO_MDOC)) + + +ifeq ($(SKIP_XFAIL),yes) +_PSMAN_MAN_set := $(filter-out $(_XFAIL_PSMAN_MAN_set), $(_PSMAN_MAN_set)) +endif + + +$(_PSMAN_MAN_set): %.ps.set: %.ps.troff $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -man -Tps $(TROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + +$(_PSMAN_MDOC_set): %.ps.set: %.ps.troff $(MK) | $$(@D)/ + $(info $(INFO_)TROFF $@) + ! ($(TROFF) -mdoc -Tps $(TROFFFLAGS) <$< 2>&1 >$@) \ + | $(GREP) ^ >&2 + + +.PHONY: build-ps-troff-man +build-ps-troff-man: $(_PSMAN_MAN_set); + +.PHONY: build-ps-troff-mdoc +build-ps-troff-mdoc: $(_PSMAN_MDOC_set); + +.PHONY: build-ps-troff +build-ps-troff: build-ps-troff-man build-ps-troff-mdoc; + + +endif # include guard diff --git a/share/mk/build/src.mk b/share/mk/build/src.mk deleted file mode 100644 index 365c256..0000000 --- a/share/mk/build/src.mk +++ /dev/null @@ -1,117 +0,0 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_BUILD_SRC_INCLUDED -MAKEFILE_BUILD_SRC_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/src.mk -include $(MAKEFILEDIR)/verbose.mk - - -PKGCONF_LIBS := libbsd-overlay - - -DEFAULT_CPPFLAGS := $(shell $(PKGCONF) --cflags $(PKGCONF_LIBS) $(HIDE_ERR)) -EXTRA_CPPFLAGS := -CPPFLAGS := $(DEFAULT_CPPFLAGS) $(EXTRA_CPPFLAGS) - -DEFAULT_CFLAGS := \ - -std=gnu17 \ - -Wall \ - -Wextra \ - -Wstrict-prototypes \ - -Wdeclaration-after-statement \ - -Werror \ - -Wno-error=unused-parameter \ - -Wno-error=sign-compare \ - -Wno-error=format \ - -Wno-error=uninitialized - #-Wno-error=declaration-after-statement -EXTRA_CFLAGS := -CFLAGS := $(DEFAULT_CFLAGS) $(EXTRA_CFLAGS) - -DEFAULT_LDFLAGS := \ - -Wl,--as-needed \ - -Wl,--no-allow-shlib-undefined \ - -Wl,--no-copy-dt-needed-entries \ - -Wl,--no-undefined \ - $(shell $(PKGCONF) --libs-only-L $(PKGCONF_LIBS) $(HIDE_ERR)) \ - $(shell $(PKGCONF) --libs-only-other $(PKGCONF_LIBS) $(HIDE_ERR)) -EXTRA_LDFLAGS := -LDFLAGS := $(DEFAULT_LDFLAGS) $(EXTRA_LDFLAGS) - -DEFAULT_LDLIBS := \ - -lc \ - $(shell $(PKGCONF) --libs-only-l $(PKGCONF_LIBS) $(HIDE_ERR)) -EXTRA_LDLIBS := -LDLIBS := $(DEFAULT_LDLIBS) $(EXTRA_LDLIBS) - - -CC := cc -LD := $(CC) $(CFLAGS) - - -_SRCPAGEDIRS := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.d/,$(NONSO_MAN)) - -_UNITS_src_src := $(patsubst $(MANDIR)/%,$(_MANDIR)/%,$(shell \ - $(FIND) $(MANDIR)/* -type f \ - | $(GREP) '$(MANEXT)' \ - | $(XARGS) $(GREP) -H '^\.\\" SRC BEGIN ' \ - | $(SED) 's,:\.\\" SRC BEGIN (,.d/,' \ - | $(SED) 's/)//' \ - | $(SORT) \ - | $(SED) 's,:,\\:,g')) -_UNITS_src_h := $(filter %.h,$(_UNITS_src_src)) -_UNITS_src_c := $(filter %.c,$(_UNITS_src_src)) -_UNITS_src_o := $(patsubst %.c,%.o,$(_UNITS_src_c)) -_UNITS_src_bin := $(patsubst %.c,%,$(_UNITS_src_c)) - - -$(_SRCPAGEDIRS): $(_MANDIR)/%.d/: $(MANDIR)/% - +$(info MKDIR $@) - +$(MKDIR) $@ - +touch $@ - -$(_UNITS_src_src): $$(patsubst $(_MANDIR)/%.d,$(MANDIR)/%,$$(@D)) | $$(@D)/ -$(_UNITS_src_c): $$(filter $$(@D)/%.h,$(_UNITS_src_h)) -$(_UNITS_src_src): - $(info SED $@) - <$< \ - $(SED) -n \ - -e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \ - -e '/^\.SH EXAMPLES/p' \ - -e "/^\... SRC BEGIN ($(@F))$$/,/^\... SRC END$$/p" \ - | $(MANDOC) -Tutf8 \ - | $(SED) '/^[^ ]/d' \ - | $(SED) 's/^ //' \ - >$@ - -$(_UNITS_src_o): %.o: %.c - $(info CC $@) - $(CC) -c $(CPPFLAGS) $(CFLAGS) -o $@ $< - -$(_UNITS_src_bin): %: %.o - $(info LD $@) - $(LD) $(LDFLAGS) -o $@ $< $(LDLIBS) - - -.PHONY: build-src-c -build-src-c: $(_UNITS_src_c); - -.PHONY: build-src-cc -build-src-cc: $(_UNITS_src_o); - -.PHONY: build-src-ld -build-src-ld: $(_UNITS_src_bin); - -.PHONY: build-src -build-src: build-src-ld - - -endif # include guard diff --git a/share/mk/check/_.mk b/share/mk/check/_.mk index 6326d1f..0a20317 100644 --- a/share/mk/check/_.mk +++ b/share/mk/check/_.mk @@ -1,18 +1,13 @@ -######################################################################## -# Copyright 2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_CHECK_INCLUDED MAKEFILE_CHECK_INCLUDED := 1 -check := check-catman - - .PHONY: check -check: $(check); +check: check-catman; endif # include guard diff --git a/share/mk/check/catman.mk b/share/mk/check/catman.mk deleted file mode 100644 index 8a0d3b6..0000000 --- a/share/mk/check/catman.mk +++ /dev/null @@ -1,51 +0,0 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_CHECK_CATMAN_INCLUDED -MAKEFILE_CHECK_CATMAN_INCLUDED := 1 - - -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/build/catman.mk -include $(MAKEFILEDIR)/check/_.mk -include $(MAKEFILEDIR)/src.mk - - -DEFAULT_COLFLAGS := \ - -b \ - -p \ - -x -EXTRA_COLFLAGS := -COLFLAGS := $(DEFAULT_COLFLAGS) $(EXTRA_COLFLAGS) -COL := col - - -_CHECK_catman_grep := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.cat.grep,$(NONSO_MAN) $(NONSO_MDOC)) -_CHECK_catman := $(patsubst $(MANDIR)/%,$(_MANDIR)/%.check-catman.touch,$(NONSO_MAN) $(NONSO_MDOC)) - - -$(_CHECK_catman_grep): %.grep: % | $$(@D)/ - $(info COL $@) - $(COL) $(COLFLAGS) <$< >$@ - -$(_CHECK_catman): %.check-catman.touch: %.cat.grep | $$(@D)/ - $(info GREP $@) - ! $(GREP) -n '.\{$(MANWIDTH)\}.' $< /dev/null >&2 - touch $@ - - -.PHONY: check-catman-col -check-catman-col: $(_CHECK_catman_grep); - -.PHONY: check-catman-grep -check-catman-grep: $(_CHECK_catman); - -.PHONY: check-catman -check-catman: check-catman-grep; - - -endif # include guard diff --git a/share/mk/check/catman/_.mk b/share/mk/check/catman/_.mk new file mode 100644 index 0000000..b9bf5a1 --- /dev/null +++ b/share/mk/check/catman/_.mk @@ -0,0 +1,13 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CHECK_CATMAN_INCLUDED +MAKEFILE_CHECK_CATMAN_INCLUDED := 1 + + +.PHONY: check-catman +check-catman: check-catman-grep; + + +endif # include guard diff --git a/share/mk/check/catman/col.mk b/share/mk/check/catman/col.mk new file mode 100644 index 0000000..59104fa --- /dev/null +++ b/share/mk/check/catman/col.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CHECK_CATMAN_COL_INCLUDED +MAKEFILE_CHECK_CATMAN_COL_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/catman/grotty.mk +include $(MAKEFILEDIR)/configure/build-depends/bsdextrautils.mk + + +_CHECK_catman_grep := $(patsubst %.cat,%.cat.grep,$(_CATMAN)) + + +$(_CHECK_catman_grep): %.grep: % $(MK) | $$(@D)/ + $(info $(INFO_)COL $@) + $(COL) $(COLFLAGS) <$< >$@ + + +.PHONY: check-catman-col +check-catman-col: $(_CHECK_catman_grep); + + +endif # include guard diff --git a/share/mk/check/catman/grep.mk b/share/mk/check/catman/grep.mk new file mode 100644 index 0000000..fbf99bc --- /dev/null +++ b/share/mk/check/catman/grep.mk @@ -0,0 +1,50 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CHECK_CATMAN_GREP_INCLUDED +MAKEFILE_CHECK_CATMAN_GREP_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/man.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_CHECK_catman := \ + $(_MANDIR)/man1/memusage.1.check-catman.touch \ + $(_MANDIR)/man3/mallopt.3.check-catman.touch \ + $(_MANDIR)/man4/smartpqi.4.check-catman.touch \ + $(_MANDIR)/man4/veth.4.check-catman.touch \ + $(_MANDIR)/man5/proc_buddyinfo.5.check-catman.touch \ + $(_MANDIR)/man5/proc_pid_fdinfo.5.check-catman.touch \ + $(_MANDIR)/man5/proc_pid_maps.5.check-catman.touch \ + $(_MANDIR)/man5/proc_pid_mountinfo.5.check-catman.touch \ + $(_MANDIR)/man5/proc_pid_net.5.check-catman.touch \ + $(_MANDIR)/man5/proc_timer_stats.5.check-catman.touch \ + $(_MANDIR)/man5/proc_version.5.check-catman.touch \ + $(_MANDIR)/man5/slabinfo.5.check-catman.touch \ + $(_MANDIR)/man7/keyrings.7.check-catman.touch \ + $(_MANDIR)/man7/string_copying.7.check-catman.touch \ + $(_MANDIR)/man7/uri.7.check-catman.touch + + +_CHECK_catman := $(patsubst %.cat.grep,%.check-catman.touch,$(_CHECK_catman_grep)) +ifeq ($(SKIP_XFAIL),yes) +_CHECK_catman := $(filter-out $(_XFAIL_CHECK_catman), $(_CHECK_catman)) +endif + + +$(_CHECK_catman): %.check-catman.touch: %.cat.grep $(MK) | $$(@D)/ + $(info $(INFO_)GREP $@) + ! $(GREP) -n '.\{$(MANWIDTH)\}.' $< /dev/null >&2 + $(TOUCH) $@ + + +.PHONY: check-catman-grep +check-catman-grep: $(_CHECK_catman); + + +endif # include guard diff --git a/share/mk/clean.mk b/share/mk/clean.mk new file mode 100644 index 0000000..a0908fa --- /dev/null +++ b/share/mk/clean.mk @@ -0,0 +1,19 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CLEAN_INCLUDED +MAKEFILE_CLEAN_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk + + +.PHONY: clean +clean: + $(info $(INFO_)RM -rf $(builddir)) + $(RM) -rf $(builddir) + + +endif # include guard diff --git a/share/mk/cmd.mk b/share/mk/cmd.mk deleted file mode 100644 index aa7c07c..0000000 --- a/share/mk/cmd.mk +++ /dev/null @@ -1,40 +0,0 @@ -######################################################################## -# Copyright 2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_CMD_INCLUDED -MAKEFILE_CMD_INCLUDED := 1 - - -BZIP2 := bzip2 -CP := cp -ECHO := echo -EXPR := expr -FIND := find -GIT := git -GREP := grep -GZIP := gzip -HEAD := head -INSTALL := install -LN := ln -LOCALE := locale -LZIP := lzip -MANDOC := mandoc -PKGCONF := pkgconf -SED := sed -SORT := sort -SPONGE := sponge -TAC := tac -TAIL := tail -TAR := tar -TEST := test -XARGS := xargs -XZ := xz - -INSTALL_DATA := $(INSTALL) -m 644 -INSTALL_DIR := $(INSTALL) -m 755 -d - - -endif # include guard diff --git a/share/mk/compress.mk b/share/mk/compress.mk deleted file mode 100644 index 6502930..0000000 --- a/share/mk/compress.mk +++ /dev/null @@ -1,40 +0,0 @@ -######################################################################## -# Copyright 2023 Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_COMPRESS_INCLUDED -MAKEFILE_COMPRESS_INCLUDED := 1 - - -Z := -ifeq ($(Z),) -else ifeq ($(Z),.bz2) -else ifeq ($(Z),.gz) -else ifeq ($(Z),.lz) -else ifeq ($(Z),.xz) -else -$(warning "Z": "$(Z)") -$(error Valid values for "Z": ["", ".bz2", ".gz", ".lz", ".xz"]) -endif - - -DEFAULT_BZIP2FLAGS := -EXTRA_BZIP2FLAGS := -BZIP2FLAGS := $(DEFAULT_BZIP2FLAGS) $(EXTRA_BZIP2FLAGS) - -DEFAULT_GZIPFLAGS := -EXTRA_GZIPFLAGS := -GZIPFLAGS := $(DEFAULT_GZIPFLAGS) $(EXTRA_GZIPFLAGS) - -DEFAULT_LZIPFLAGS := -EXTRA_LZIPFLAGS := -LZIPFLAGS := $(DEFAULT_LZIPFLAGS) $(EXTRA_LZIPFLAGS) - -DEFAULT_XZFLAGS := -EXTRA_XZFLAGS := -XZFLAGS := $(DEFAULT_XZFLAGS) $(EXTRA_XZFLAGS) - - -endif # include guard diff --git a/share/mk/configure/build-depends/bsdextrautils.mk b/share/mk/configure/build-depends/bsdextrautils.mk new file mode 100644 index 0000000..347e4bc --- /dev/null +++ b/share/mk/configure/build-depends/bsdextrautils.mk @@ -0,0 +1,18 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_BSDEXTRAUTILS_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_BSDEXTRAUTILS_INCLUDED := 1 + + +DEFAULT_COLFLAGS := \ + -b \ + -p \ + -x +EXTRA_COLFLAGS := +COLFLAGS := $(DEFAULT_COLFLAGS) $(EXTRA_COLFLAGS) +COL := col + + +endif # include guard diff --git a/share/mk/configure/build-depends/bzip2.mk b/share/mk/configure/build-depends/bzip2.mk new file mode 100644 index 0000000..71e6366 --- /dev/null +++ b/share/mk/configure/build-depends/bzip2.mk @@ -0,0 +1,15 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_BZIP2_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_BZIP2_INCLUDED := 1 + + +DEFAULT_BZIP2FLAGS := +EXTRA_BZIP2FLAGS := +BZIP2FLAGS := $(DEFAULT_BZIP2FLAGS) $(EXTRA_BZIP2FLAGS) +BZIP2 := bzip2 + + +endif # include guard diff --git a/share/mk/configure/build-depends/cc.mk b/share/mk/configure/build-depends/cc.mk new file mode 100644 index 0000000..85470a4 --- /dev/null +++ b/share/mk/configure/build-depends/cc.mk @@ -0,0 +1,63 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CC_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CC_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk + + +CC := gcc + + +CC_VENDOR := \ + $(shell \ + $(CC) -v 2>&1 \ + | $(SED) -n '1p;$$p' \ + | $(SED) '/gcc version/s/.*/gcc/' \ + | $(SED) '/clang version/s/.*/clang/' \ + | $(SED) '/Apple LLVM version/s/.*/clang/' \ + | $(GREP) -e '^gcc$$' -e '^clang$$' \ + || $(ECHO) unknown; \ + ) + + +COMMON_CFLAGS := \ + -O3 \ + -flto \ + -Wall \ + -Wextra \ + -Werror \ + -Wstrict-prototypes \ + -Wdeclaration-after-statement \ + -Wno-error=unused-parameter \ + -Wno-error=sign-compare \ + -Wno-error=format \ + -Wno-error=uninitialized + + +GCC_CFLAGS := -fanalyzer + + +CLANG_CFLAGS := \ + -Weverything \ + -Wno-unsafe-buffer-usage + + +DEFAULT_CFLAGS := $(COMMON_CFLAGS) + +ifeq ($(CC_VENDOR),gcc) +DEFAULT_CFLAGS += $(GCC_CFLAGS) +else ifeq ($(CC_VENDOR),clang) +DEFAULT_CFLAGS += $(CLANG_CFLAGS) +endif + +EXTRA_CFLAGS := +CFLAGS := $(DEFAULT_CFLAGS) $(EXTRA_CFLAGS) + + +endif # include guard diff --git a/share/mk/configure/build-depends/checkpatch.mk b/share/mk/configure/build-depends/checkpatch.mk new file mode 100644 index 0000000..0b29d9f --- /dev/null +++ b/share/mk/configure/build-depends/checkpatch.mk @@ -0,0 +1,19 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CHECKPATCH_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CHECKPATCH_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/src.mk + + +CHECKPATCH_CONF := $(SYSCONFDIR)/checkpatch/checkpatch.conf +DEFAULT_CHECKPATCHFLAGS := +EXTRA_CHECKPATCHFLAGS := +CHECKPATCHFLAGS := $(DEFAULT_CHECKPATCHFLAGS) $(EXTRA_CHECKPATCHFLAGS) +CHECKPATCH := checkpatch + + +endif # include guard diff --git a/share/mk/configure/build-depends/clang-tidy.mk b/share/mk/configure/build-depends/clang-tidy.mk new file mode 100644 index 0000000..2d818f9 --- /dev/null +++ b/share/mk/configure/build-depends/clang-tidy.mk @@ -0,0 +1,22 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CLANG_TIDY_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CLANG_TIDY_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/src.mk + + +CLANG_TIDY_CONF := $(SYSCONFDIR)/clang-tidy/config.yaml +DEFAULT_CLANG_TIDYFLAGS := \ + --config-file=$(CLANG_TIDY_CONF) \ + --quiet \ + --use-color +EXTRA_CLANG_TIDYFLAGS := +CLANG_TIDYFLAGS := $(DEFAULT_CLANG_TIDYFLAGS) $(EXTRA_CLANG_TIDYFLAGS) +CLANG_TIDY := clang-tidy + + +endif # include guard diff --git a/share/mk/configure/build-depends/clang.mk b/share/mk/configure/build-depends/clang.mk new file mode 100644 index 0000000..b44ccb5 --- /dev/null +++ b/share/mk/configure/build-depends/clang.mk @@ -0,0 +1,19 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CLANG_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CLANG_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/cc.mk + + +DEFAULT_CLANGFLAGS := \ + $(COMMON_CFLAGS) \ + $(CLANG_CFLAGS) +EXTRA_CLANGFLAGS := +CLANGFLAGS := $(DEFAULT_CLANGFLAGS) $(EXTRA_CLANGFLAGS) + + +endif # include guard diff --git a/share/mk/configure/build-depends/coreutils.mk b/share/mk/configure/build-depends/coreutils.mk new file mode 100644 index 0000000..2fe97fe --- /dev/null +++ b/share/mk/configure/build-depends/coreutils.mk @@ -0,0 +1,32 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_COREUTILS_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_COREUTILS_INCLUDED := 1 + + +CAT := cat +CP := cp +ECHO := echo +EXPR := expr +HEAD := head +INSTALL := install +LN := ln +MKDIR := mkdir +REALPATH := realpath +RM := rm +SORT := sort +STAT := stat +TAC := tac +TAIL := tail +TEST := test +TOUCH := touch +TRUE := true + + +INSTALL_DATA := $(INSTALL) -m 644 +INSTALL_DIR := $(INSTALL) -m 755 -d + + +endif # include guard diff --git a/share/mk/configure/build-depends/cpp.mk b/share/mk/configure/build-depends/cpp.mk new file mode 100644 index 0000000..b720898 --- /dev/null +++ b/share/mk/configure/build-depends/cpp.mk @@ -0,0 +1,20 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CPP_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CPP_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/cc.mk +include $(MAKEFILEDIR)/configure/build-depends/pkgconf.mk +include $(MAKEFILEDIR)/configure/verbose.mk + + +DEFAULT_CPPFLAGS := $(shell $(PKGCONF_CMD) --cflags $(PKGCONF_LIBS) $(HIDE_ERR)) +EXTRA_CPPFLAGS := +CPPFLAGS := $(DEFAULT_CPPFLAGS) $(EXTRA_CPPFLAGS) +CPP := $(CC) $(CFLAGS) -E + + +endif # include guard diff --git a/share/mk/configure/build-depends/cppcheck.mk b/share/mk/configure/build-depends/cppcheck.mk new file mode 100644 index 0000000..93a9b75 --- /dev/null +++ b/share/mk/configure/build-depends/cppcheck.mk @@ -0,0 +1,24 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CPPCHECK_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CPPCHECK_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/src.mk + + +CPPCHECK_SUPPRESS := $(SYSCONFDIR)/cppcheck/cppcheck.suppress +DEFAULT_CPPCHECKFLAGS := \ + --enable=all \ + --error-exitcode=2 \ + --inconclusive \ + --quiet \ + --suppressions-list=$(CPPCHECK_SUPPRESS) +EXTRA_CPPCHECKFLAGS := +CPPCHECKFLAGS := $(DEFAULT_CPPCHECKFLAGS) $(EXTRA_CPPCHECKFLAGS) +CPPCHECK := cppcheck + + +endif # include guard diff --git a/share/mk/configure/build-depends/cpplint.mk b/share/mk/configure/build-depends/cpplint.mk new file mode 100644 index 0000000..586d646 --- /dev/null +++ b/share/mk/configure/build-depends/cpplint.mk @@ -0,0 +1,19 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_CPPLINT_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_CPPLINT_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/src.mk + + +CPPLINT_CONF := $(SYSCONFDIR)/cpplint/cpplint.cfg +DEFAULT_CPPLINTFLAGS := +EXTRA_CPPLINTFLAGS := +CPPLINTFLAGS := $(DEFAULT_CPPLINTFLAGS) $(EXTRA_CPPLINTFLAGS) +CPPLINT := cpplint + + +endif # include guard diff --git a/share/mk/configure/build-depends/diffoscope.mk b/share/mk/configure/build-depends/diffoscope.mk new file mode 100644 index 0000000..a9e48b3 --- /dev/null +++ b/share/mk/configure/build-depends/diffoscope.mk @@ -0,0 +1,12 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_DIFFOSCOPE_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_DIFFOSCOPE_INCLUDED := 1 + + +DIFFOSCOPE := diffoscope + + +endif # include guard diff --git a/share/mk/configure/build-depends/findutils.mk b/share/mk/configure/build-depends/findutils.mk new file mode 100644 index 0000000..536f921 --- /dev/null +++ b/share/mk/configure/build-depends/findutils.mk @@ -0,0 +1,13 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_FINDUTILS_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_FINDUTILS_INCLUDED := 1 + + +FIND := find +XARGS := xargs + + +endif # include guard diff --git a/share/mk/configure/build-depends/git.mk b/share/mk/configure/build-depends/git.mk new file mode 100644 index 0000000..a861bed --- /dev/null +++ b/share/mk/configure/build-depends/git.mk @@ -0,0 +1,12 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_GIT_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_GIT_INCLUDED := 1 + + +GIT := git + + +endif # include guard diff --git a/share/mk/configure/build-depends/grep.mk b/share/mk/configure/build-depends/grep.mk new file mode 100644 index 0000000..7d89691 --- /dev/null +++ b/share/mk/configure/build-depends/grep.mk @@ -0,0 +1,12 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_GREP_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_GREP_INCLUDED := 1 + + +GREP := grep + + +endif # include guard diff --git a/share/mk/configure/build-depends/groff-base.mk b/share/mk/configure/build-depends/groff-base.mk new file mode 100644 index 0000000..ab1f98d --- /dev/null +++ b/share/mk/configure/build-depends/groff-base.mk @@ -0,0 +1,72 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_GROFF_BASE_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_GROFF_BASE_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/libc-bin.mk +include $(MAKEFILEDIR)/configure/build-depends/man.mk + + +DEFAULT_PRECONVFLAGS := +EXTRA_PRECONVFLAGS := +PRECONVFLAGS := $(DEFAULT_PRECONVFLAGS) $(EXTRA_PRECONVFLAGS) +PRECONV := preconv + + +DEFAULT_PICFLAGS := +EXTRA_PICFLAGS := +PICFLAGS := $(DEFAULT_PICFLAGS) $(EXTRA_PICFLAGS) +PIC := pic + + +TBL := tbl + + +DEFAULT_EQNFLAGS := +EXTRA_EQNFLAGS := +EQNFLAGS := $(DEFAULT_EQNFLAGS) $(EXTRA_EQNFLAGS) +EQN := eqn + + +DEFAULT_TROFFFLAGS := -wbreak +EXTRA_TROFFFLAGS := +TROFFFLAGS := $(DEFAULT_TROFFFLAGS) $(EXTRA_TROFFFLAGS) +TROFF := troff + + +TROFF_CHECKSTYLE_LVL := 3 +NROFF_LINE_LENGTH := $(shell $(EXPR) $(MANWIDTH) - 2) +NROFF_OUT_DEVICE := \ + $(shell $(LOCALE) charmap \ + | $(GREP) -i 'utf-*8' >/dev/null \ + && $(ECHO) utf8 \ + || $(ECHO) ascii \ + ) + +DEFAULT_NROFFFLAGS := \ + -T$(NROFF_OUT_DEVICE) \ + -rLL=$(NROFF_LINE_LENGTH)n \ + -rCHECKSTYLE=$(TROFF_CHECKSTYLE_LVL) \ + -ww +EXTRA_NROFFFLAGS := +NROFFFLAGS := $(DEFAULT_NROFFFLAGS) $(EXTRA_NROFFFLAGS) + + +DEFAULT_GROTTYFLAGS := -c +EXTRA_GROTTYFLAGS := +GROTTYFLAGS := $(DEFAULT_GROTTYFLAGS) $(EXTRA_GROTTYFLAGS) +GROTTY := grotty + + +DEFAULT_GROPSFLAGS := +EXTRA_GROPSFLAGS := +GROPSFLAGS := $(DEFAULT_GROPSFLAGS) $(EXTRA_GROPSFLAGS) +GROPS := grops + + +endif # include guard diff --git a/share/mk/configure/build-depends/groff.mk b/share/mk/configure/build-depends/groff.mk new file mode 100644 index 0000000..ea0c7a3 --- /dev/null +++ b/share/mk/configure/build-depends/groff.mk @@ -0,0 +1,21 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_GROFF_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_GROFF_INCLUDED := 1 + + +DEFAULT_GROPDFFLAGS := +EXTRA_GROPDFFLAGS := +GROPDFFLAGS := $(DEFAULT_GROPDFFLAGS) $(EXTRA_GROPDFFLAGS) +GROPDF := gropdf + + +DEFAULT_POST_GROHTMLFLAGS := +EXTRA_POST_GROHTMLFLAGS := +POST_GROHTMLFLAGS := $(DEFAULT_POST_GROHTMLFLAGS) $(EXTRA_POST_GROHTMLFLAGS) +POST_GROHTML := post-grohtml + + +endif # include guard diff --git a/share/mk/configure/build-depends/gzip.mk b/share/mk/configure/build-depends/gzip.mk new file mode 100644 index 0000000..6633654 --- /dev/null +++ b/share/mk/configure/build-depends/gzip.mk @@ -0,0 +1,15 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_GZIP_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_GZIP_INCLUDED := 1 + + +DEFAULT_GZIPFLAGS := -n +EXTRA_GZIPFLAGS := +GZIPFLAGS := $(DEFAULT_GZIPFLAGS) $(EXTRA_GZIPFLAGS) +GZIP := gzip + + +endif # include guard diff --git a/share/mk/configure/build-depends/iwyu.mk b/share/mk/configure/build-depends/iwyu.mk new file mode 100644 index 0000000..bd5cf7f --- /dev/null +++ b/share/mk/configure/build-depends/iwyu.mk @@ -0,0 +1,17 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_IWYU_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_IWYU_INCLUDED := 1 + + +DEFAULT_IWYUFLAGS := \ + -Xiwyu --no_fwd_decls \ + -Xiwyu --error +EXTRA_IWYUFLAGS := +IWYUFLAGS := $(DEFAULT_IWYUFLAGS) $(EXTRA_IWYUFLAGS) +IWYU := iwyu + + +endif # include guard diff --git a/share/mk/configure/build-depends/ld.mk b/share/mk/configure/build-depends/ld.mk new file mode 100644 index 0000000..a78a189 --- /dev/null +++ b/share/mk/configure/build-depends/ld.mk @@ -0,0 +1,50 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_LD_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_LD_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/cc.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/pkgconf.mk +include $(MAKEFILEDIR)/configure/verbose.mk + + +LD := $(CC) $(CFLAGS) + + +LD_HAS_FUSE_LINKER_PLUGIN := \ + $(shell \ + $(ECHO) 'int main(void) {}' \ + | $(LD) -fuse-linker-plugin -x c -o /dev/null /dev/stdin $(HIDE_ERR) \ + && $(ECHO) yes \ + || $(ECHO) no; \ + ) + + +DEFAULT_LDFLAGS := \ + -Wl,--as-needed \ + -Wl,--no-allow-shlib-undefined \ + -Wl,--no-copy-dt-needed-entries \ + -Wl,--no-undefined \ + $(shell $(PKGCONF_CMD) --libs-only-L $(PKGCONF_LIBS) $(HIDE_ERR)) \ + $(shell $(PKGCONF_CMD) --libs-only-other $(PKGCONF_LIBS) $(HIDE_ERR)) + +ifeq ($(LD_HAS_FUSE_LINKER_PLUGIN),yes) +DEFAULT_LDFLAGS += -fuse-linker-plugin +endif + +EXTRA_LDFLAGS := +LDFLAGS := $(DEFAULT_LDFLAGS) $(EXTRA_LDFLAGS) + + +DEFAULT_LDLIBS := \ + -lc \ + $(shell $(PKGCONF_CMD) --libs-only-l $(PKGCONF_LIBS) $(HIDE_ERR)) +EXTRA_LDLIBS := +LDLIBS := $(DEFAULT_LDLIBS) $(EXTRA_LDLIBS) + + +endif # include guard diff --git a/share/mk/configure/build-depends/libc-bin.mk b/share/mk/configure/build-depends/libc-bin.mk new file mode 100644 index 0000000..281502b --- /dev/null +++ b/share/mk/configure/build-depends/libc-bin.mk @@ -0,0 +1,12 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_LIBC_BIN_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_LIBC_BIN_INCLUDED := 1 + + +LOCALE := locale + + +endif # include guard diff --git a/share/mk/configure/build-depends/lzip.mk b/share/mk/configure/build-depends/lzip.mk new file mode 100644 index 0000000..e18868f --- /dev/null +++ b/share/mk/configure/build-depends/lzip.mk @@ -0,0 +1,15 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_LZIP_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_LZIP_INCLUDED := 1 + + +DEFAULT_LZIPFLAGS := +EXTRA_LZIPFLAGS := +LZIPFLAGS := $(DEFAULT_LZIPFLAGS) $(EXTRA_LZIPFLAGS) +LZIP := lzip + + +endif # include guard diff --git a/share/mk/configure/build-depends/man.mk b/share/mk/configure/build-depends/man.mk new file mode 100644 index 0000000..5248d42 --- /dev/null +++ b/share/mk/configure/build-depends/man.mk @@ -0,0 +1,12 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_MAN_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_MAN_INCLUDED := 1 + + +MANWIDTH ?= 80 + + +endif # include guard diff --git a/share/mk/configure/build-depends/mandoc.mk b/share/mk/configure/build-depends/mandoc.mk new file mode 100644 index 0000000..87eccd6 --- /dev/null +++ b/share/mk/configure/build-depends/mandoc.mk @@ -0,0 +1,15 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_MANDOC_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_MANDOC_INCLUDED := 1 + + +DEFAULT_MANDOCFLAGS := -Tlint +EXTRA_MANDOCFLAGS := +MANDOCFLAGS := $(DEFAULT_MANDOCFLAGS) $(EXTRA_MANDOCFLAGS) +MANDOC := mandoc + + +endif # include guard diff --git a/share/mk/configure/build-depends/moreutils.mk b/share/mk/configure/build-depends/moreutils.mk new file mode 100644 index 0000000..69b60fa --- /dev/null +++ b/share/mk/configure/build-depends/moreutils.mk @@ -0,0 +1,12 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_MOREUTILS_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_MOREUTILS_INCLUDED := 1 + + +SPONGE := sponge + + +endif # include guard diff --git a/share/mk/configure/build-depends/pkgconf.mk b/share/mk/configure/build-depends/pkgconf.mk new file mode 100644 index 0000000..b7b5c3f --- /dev/null +++ b/share/mk/configure/build-depends/pkgconf.mk @@ -0,0 +1,27 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_PKGCONF_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_PKGCONF_INCLUDED := 1 + + +include $(MAKEFILEDIR)/src.mk +include $(MAKEFILEDIR)/configure/version.mk + + +# Compat +PKG_CONFIG := pkgconf + + +DEFAULT_PKGCONFFLAGS := +EXTRA_PKGCONFFLAGS := +PKGCONFFLAGS := $(DEFAULT_PKGCONFFLAGS) $(EXTRA_PKGCONFFLAGS) +PKGCONF := $(PKG_CONFIG) +PKGCONF_CMD := $(PKGCONF) $(PKGCONFFLAGS) + + +PKGCONF_LIBS := libbsd-overlay + + +endif # include guard diff --git a/share/mk/configure/build-depends/sed.mk b/share/mk/configure/build-depends/sed.mk new file mode 100644 index 0000000..3d1fcd8 --- /dev/null +++ b/share/mk/configure/build-depends/sed.mk @@ -0,0 +1,12 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_SED_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_SED_INCLUDED := 1 + + +SED := sed + + +endif # include guard diff --git a/share/mk/configure/build-depends/tar.mk b/share/mk/configure/build-depends/tar.mk new file mode 100644 index 0000000..3ea5537 --- /dev/null +++ b/share/mk/configure/build-depends/tar.mk @@ -0,0 +1,22 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_TAR_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_TAR_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/version.mk + + +DEFAULT_TARFLAGS := \ + --sort=name \ + --owner=root:0 \ + --group=root:0 \ + --mtime='$(DISTDATE)' +EXTRA_TARFLAGS := +TARFLAGS := $(DEFAULT_TARFLAGS) $(EXTRA_TARFLAGS) +TAR := tar + + +endif # include guard diff --git a/share/mk/configure/build-depends/xz-utils.mk b/share/mk/configure/build-depends/xz-utils.mk new file mode 100644 index 0000000..d00a3b7 --- /dev/null +++ b/share/mk/configure/build-depends/xz-utils.mk @@ -0,0 +1,15 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_BUILD_DEPENDS_XZ_UTILS_INCLUDED +MAKEFILE_CONFIGURE_BUILD_DEPENDS_XZ_UTILS_INCLUDED := 1 + + +DEFAULT_XZFLAGS := +EXTRA_XZFLAGS := +XZFLAGS := $(DEFAULT_XZFLAGS) $(EXTRA_XZFLAGS) +XZ := xz + + +endif # include guard diff --git a/share/mk/configure/directory_variables.mk b/share/mk/configure/directory_variables.mk new file mode 100644 index 0000000..e4ee616 --- /dev/null +++ b/share/mk/configure/directory_variables.mk @@ -0,0 +1,29 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_DIRECTORY_VARIABLES_INCLUDED +MAKEFILE_CONFIGURE_DIRECTORY_VARIABLES_INCLUDED := 1 + + +include $(MAKEFILEDIR)/src.mk + + +builddir := .tmp + + +DESTDIR := +prefix := /usr/local +datarootdir := $(prefix)/share +docdir := $(datarootdir)/doc +htmldir := $(docdir)/html/man +mandir := $(datarootdir)/man + + +$(foreach s, $(MANSECTIONS), \ + $(eval man$(s)dir := $(mandir)/man$(s))) +$(foreach s, $(MANSECTIONS), \ + $(eval man$(s)ext := .$(s))) + + +endif # include guard diff --git a/share/mk/configure/link_pages.mk b/share/mk/configure/link_pages.mk new file mode 100644 index 0000000..52136ef --- /dev/null +++ b/share/mk/configure/link_pages.mk @@ -0,0 +1,18 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_LINK_PAGES_INCLUDED +MAKEFILE_CONFIGURE_LINK_PAGES_INCLUDED := 1 + + +LINK_PAGES := .so +ifeq ($(LINK_PAGES),.so) +else ifeq ($(LINK_PAGES),symlink) +else +$(warning "LINK_PAGES": "$(LINK_PAGES)") +$(error Valid values for "LINK_PAGES": [".so", "symlink"]) +endif + + +endif # include guard diff --git a/share/mk/configure/src.mk b/share/mk/configure/src.mk new file mode 100644 index 0000000..2a24f4e --- /dev/null +++ b/share/mk/configure/src.mk @@ -0,0 +1,16 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_SRC_INCLUDED +MAKEFILE_CONFIGURE_SRC_INCLUDED := 1 + + +SYSCONFDIR := $(srcdir)/etc +MANDIR := $(srcdir) + + +MANSECTIONS := $(patsubst $(MANDIR)/man%/, %, $(wildcard $(MANDIR)/man*/)) + + +endif # include guard diff --git a/share/mk/configure/verbose.mk b/share/mk/configure/verbose.mk new file mode 100644 index 0000000..d6372db --- /dev/null +++ b/share/mk/configure/verbose.mk @@ -0,0 +1,12 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_VERBOSE_INCLUDED +MAKEFILE_CONFIGURE_VERBOSE_INCLUDED := 1 + + +HIDE_ERR := 2>/dev/null + + +endif # include guard diff --git a/share/mk/configure/version.mk b/share/mk/configure/version.mk new file mode 100644 index 0000000..cc89bae --- /dev/null +++ b/share/mk/configure/version.mk @@ -0,0 +1,43 @@ +# Copyright 2022-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_VERSION_INCLUDED +MAKEFILE_CONFIGURE_VERSION_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/findutils.mk +include $(MAKEFILEDIR)/configure/build-depends/git.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/verbose.mk + + +DISTNAME := man-pages-6.7 +DISTVERSION := 6.7 + + +DISTFILESCMD := \ + $(FIND) $(srcdir) -not -type d \ + | $(GREP) -v '^$(srcdir)/.git$$' \ + | $(GREP) -v '^$(srcdir)/.git/' \ + | $(GREP) -v '^$(srcdir)/.tmp/' \ + | $(GREP) -v '^$(srcdir)/.checkpatch-camelcase.' \ + | $(SORT) + +DISTDATECMD := \ + $(ECHO) '$(DISTVERSION)' \ + | if $(GREP) -- '-dirty$$' >/dev/null; then \ + $(DISTFILESCMD) \ + | $(XARGS) $(STAT) -c %y \ + | $(SORT) -n \ + | $(TAIL) -n1; \ + else \ + $(GIT) log -1 --format='%cD'; \ + fi; + + +DISTDATE := Tue, 19 Mar 2024 19:07:13 +0100 + + +endif # include guard diff --git a/share/mk/configure/xfail.mk b/share/mk/configure/xfail.mk new file mode 100644 index 0000000..44e4ede --- /dev/null +++ b/share/mk/configure/xfail.mk @@ -0,0 +1,18 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_XFAIL_INCLUDED +MAKEFILE_CONFIGURE_XFAIL_INCLUDED := 1 + + +SKIP_XFAIL := yes +ifeq ($(SKIP_XFAIL),yes) +else ifeq ($(SKIP_XFAIL),no) +else +$(warning "SKIP_XFAIL": "$(SKIP_XFAIL)") +$(error Valid values for "SKIP_XFAIL": ["yes", "no"]) +endif + + +endif # include guard diff --git a/share/mk/configure/z.mk b/share/mk/configure/z.mk new file mode 100644 index 0000000..2eec437 --- /dev/null +++ b/share/mk/configure/z.mk @@ -0,0 +1,21 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_CONFIGURE_Z_INCLUDED +MAKEFILE_CONFIGURE_Z_INCLUDED := 1 + + +Z := +ifeq ($(Z),) +else ifeq ($(Z),.bz2) +else ifeq ($(Z),.gz) +else ifeq ($(Z),.lz) +else ifeq ($(Z),.xz) +else +$(warning "Z": "$(Z)") +$(error Valid values for "Z": ["", ".bz2", ".gz", ".lz", ".xz"]) +endif + + +endif # include guard diff --git a/share/mk/dist.mk b/share/mk/dist.mk deleted file mode 100644 index b18197d..0000000 --- a/share/mk/dist.mk +++ /dev/null @@ -1,96 +0,0 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_DIST_INCLUDED -MAKEFILE_DIST_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/compress.mk -include $(MAKEFILEDIR)/install/_.mk -include $(MAKEFILEDIR)/version.mk -include $(MAKEFILEDIR)/verbose.mk - - -_DISTDIR := $(builddir)/dist - - -DEFAULT_TARFLAGS := \ - --sort=name \ - --owner=root:0 \ - --group=root:0 \ - --mtime='$(DISTDATE)' -EXTRA_TARFLAGS := -TARFLAGS := $(DEFAULT_TARFLAGS) $(EXTRA_TARFLAGS) - - -DISTFILES := $(shell $(GIT) ls-files $(HIDE_ERR) \ - | $(SED) 's,^,$(srcdir)/,' \ - | $(SED) 's,:,\\:,g') -_DISTFILES := $(patsubst $(srcdir)/%,$(_DISTDIR)/%,$(DISTFILES)) -_DISTPAGES := $(filter $(_DISTDIR)/man%,$(_DISTFILES)) -_DISTOTHERS := $(filter-out $(_DISTDIR)/man%,$(_DISTFILES)) - -DISTFILE := $(builddir)/$(DISTNAME).tar -compression := bz2 gz lz xz -dist := $(foreach x,$(compression),dist-$(x)) - - -$(builddir)/dist/%/: - +$(info INSTALL $@) - +$(INSTALL_DIR) $@ - - -$(_DISTPAGES): $(_DISTDIR)/man%: $(srcdir)/man% | $$(@D)/ - $(info INSTALL $@) - $(INSTALL_DATA) -T $< $@ - $(SED) -i '/^.TH/s/(unreleased)/$(DISTVERSION)/' $@ - $(SED) -i "/^.TH/s/(date)/$$(git log --format=%cs -1 -- $< $(HIDE_ERR))/" $@ - -$(_DISTOTHERS): $(_DISTDIR)/%: $(srcdir)/% | $$(@D)/ - $(info CP $@) - $(CP) -T $< $@ - - -$(DISTFILE): $(_DISTFILES) | $$(@D)/ - $(info TAR $@) - $(TAR) $(TARFLAGS) -cf $@ -T /dev/null - $(GIT) ls-files \ - | $(SED) 's,^,$(_DISTDIR)/,' \ - | $(XARGS) $(TAR) $(TARFLAGS) -rf $@ -C $(srcdir) \ - --transform 's,^$(_DISTDIR),$(DISTNAME),' - -$(DISTFILE).bz2: %.bz2: % | $$(@D)/ - $(info BZIP2 $@) - $(BZIP2) $(BZIP2FLAGS) -kf $< - touch $@ - -$(DISTFILE).gz: %.gz: % | $$(@D)/ - $(info GZIP $@) - $(GZIP) $(GZIPFLAGS) -knf $< - -$(DISTFILE).lz: %.lz: % | $$(@D)/ - $(info LZIP $@) - $(LZIP) $(LZIPFLAGS) -kf $< - touch $@ - -$(DISTFILE).xz: %.xz: % | $$(@D)/ - $(info XZ $@) - $(XZ) $(XZFLAGS) -kf $< - - -.PHONY: dist-tar -dist-tar: $(DISTFILE); - -.PHONY: $(dist) -$(dist): dist-%: $(DISTFILE).%; - -.PHONY: dist -dist: $(dist); - - -endif # include guard diff --git a/share/mk/dist/_.mk b/share/mk/dist/_.mk new file mode 100644 index 0000000..f6d8669 --- /dev/null +++ b/share/mk/dist/_.mk @@ -0,0 +1,25 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_INCLUDED +MAKEFILE_DIST_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk + + +_DISTDIR := $(builddir)/dist + + +$(builddir)/dist/%/: + +$(info $(INFO_)MKDIR $@) + +$(INSTALL_DIR) $@ + + +.PHONY: dist +dist: dist-tar dist-z; + + +endif # include guard diff --git a/share/mk/dist/check/_.mk b/share/mk/dist/check/_.mk new file mode 100644 index 0000000..a24b8f8 --- /dev/null +++ b/share/mk/dist/check/_.mk @@ -0,0 +1,41 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_CHECK_INCLUDED +MAKEFILE_DIST_CHECK_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk +include $(MAKEFILEDIR)/configure/version.mk + + +_DISTCHECKDIR := $(shell $(REALPATH) -m $(builddir)/distcheck) +_DISTCHECKSRCDIR := $(_DISTCHECKDIR)/$(DISTNAME) +_DISTCHECKBUILDDIR := $(_DISTCHECKDIR)/$(DISTNAME)_builddir +_DISTCHECKDESTDIR := $(_DISTCHECKDIR)/$(DISTNAME)_destdir +_DISTCHECK_MANDIR := $(_DISTCHECKBUILDDIR)/man + + +_MAKE_OPTS = \ + -C $< \ + 'builddir=$(_DISTCHECKBUILDDIR)' \ + 'DESTDIR=$(_DISTCHECKDESTDIR)' + + +distcheck-%: $(_DISTCHECKSRCDIR) $(MK) | $$(@D)/ + $(info $(INFO_)MAKE $@) + $(MAKE) $(_MAKE_OPTS) $* \ + 'INFO_= $*: ' + + +.PHONY: distcheck +distcheck: distcheck-diffoscope +distcheck: $(_DISTCHECKSRCDIR) $(MK) + $(info $(INFO_)MAKE lint build check install dist) + $(MAKE) $(_MAKE_OPTS) lint build check install dist \ + 'INFO_= distcheck: ' + + +endif # include guard diff --git a/share/mk/dist/check/diffoscope.mk b/share/mk/dist/check/diffoscope.mk new file mode 100644 index 0000000..33bcf30 --- /dev/null +++ b/share/mk/dist/check/diffoscope.mk @@ -0,0 +1,26 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_CHECK_DIFFOSCOPE_INCLUDED +MAKEFILE_DIST_CHECK_DIFFOSCOPE_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/diffoscope.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk +include $(MAKEFILEDIR)/dist/check/dist.mk +include $(MAKEFILEDIR)/dist/tar.mk + + +$(builddir)/distcheck.diffoscope.touch: $(_DISTFILE) $(REDIST) | $$(@D)/ + $(info $(INFO_)DIFFOSCOPE $^) + $(DIFFOSCOPE) $^ + $(TOUCH) $@ + + +.PHONY: distcheck-diffoscope +distcheck-diffoscope: $(builddir)/distcheck.diffoscope.touch; + + +endif # include guard diff --git a/share/mk/dist/check/dist.mk b/share/mk/dist/check/dist.mk new file mode 100644 index 0000000..ecd565b --- /dev/null +++ b/share/mk/dist/check/dist.mk @@ -0,0 +1,28 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_CHECK_DIST_INCLUDED +MAKEFILE_DIST_CHECK_DIST_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/version.mk +include $(MAKEFILEDIR)/dist/check/_.mk +include $(MAKEFILEDIR)/dist/check/tar.mk + + +REDIST := $(_DISTCHECKBUILDDIR)/$(DISTNAME).tar + + +$(REDIST): $(_DISTCHECKSRCDIR) $(MK) | $$(@D)/ + $(info $(INFO_)MAKE dist-tar) + $(MAKE) $(_MAKE_OPTS) dist-tar \ + 'INFO_= dist-tar: ' + + +.PHONY: distcheck-dist-tar +distcheck-dist-tar: $(REDIST); + + +endif # include guard diff --git a/share/mk/dist/check/tar.mk b/share/mk/dist/check/tar.mk new file mode 100644 index 0000000..bd28ce5 --- /dev/null +++ b/share/mk/dist/check/tar.mk @@ -0,0 +1,32 @@ +# Copyright 2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_CHECK_TAR_INCLUDED +MAKEFILE_DIST_CHECK_TAR_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/tar.mk +include $(MAKEFILEDIR)/configure/version.mk +include $(MAKEFILEDIR)/dist/check/_.mk +include $(MAKEFILEDIR)/dist/tar.mk + + +$(_DISTCHECKDIR)/$(DISTFILE): $(_DISTFILE) $(MK) | $$(@D)/ + $(info $(INFO_)CP $@) + $(CP) -T $< $@ + +$(_DISTCHECKSRCDIR): %: %.tar $(MK) | $$(@D)/ + $(info $(INFO_)TAR xf $<) + $(RM) -rf $@ + cd $(dir $<) \ + && $(TAR) xf $(notdir $<) + $(TOUCH) $@ + + +.PHONY: distcheck-tar +distcheck-tar: $(_DISTCHECKSRCDIR); + + +endif # include guard diff --git a/share/mk/dist/files.mk b/share/mk/dist/files.mk new file mode 100644 index 0000000..bc3f7ff --- /dev/null +++ b/share/mk/dist/files.mk @@ -0,0 +1,62 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_FILES_INCLUDED +MAKEFILE_DIST_FILES_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/git.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/verbose.mk +include $(MAKEFILEDIR)/configure/version.mk +include $(MAKEFILEDIR)/dist/_.mk + + +DISTFILES := $(shell $(DISTFILESCMD) | $(SED) 's,:,\\:,g') +_DISTFILES := $(patsubst $(srcdir)/%,$(_DISTDIR)/%,$(DISTFILES)) +_DISTPAGES := $(filter $(_DISTDIR)/man%,$(_DISTFILES)) +_DISTVERSION := $(_DISTDIR)/share/mk/configure/version.mk +_DISTOTHERS := $(filter-out $(_DISTPAGES) $(_DISTVERSION), $(_DISTFILES)) + + +FORCE_DISTVERSION := \ + $(shell \ + if $(TEST) -f $(_DISTVERSION); then \ + <$(_DISTVERSION) \ + $(GREP) \ + -e '^DISTVERSION :=' \ + -e '^DISTNAME :=' \ + -e '^DISTDATE :=' \ + | $(SED) '/^DISTVERSION := $(DISTVERSION)$$/d' \ + | $(SED) '/^DISTNAME := $(DISTNAME)$$/d' \ + | $(SED) '/^DISTDATE := $(DISTDATE)$$/d' \ + | $(GREP) ^ $(HIDE_ERR) >&2 \ + && $(ECHO) FORCE; \ + fi; \ + ) + + +$(_DISTPAGES): $(_DISTDIR)/man%: $(srcdir)/man% $(MK) | $$(@D)/ + $(info $(INFO_)SED $@) + <$< \ + $(SED) "/^.TH/s/(date)/$$($(GIT) log --format=%cs -1 -- $< $(HIDE_ERR))/" \ + | $(SED) '/^.TH/s/(unreleased)/$(DISTVERSION)/' \ + | $(INSTALL_DATA) -T /dev/stdin $@ + +$(_DISTVERSION): $(MAKEFILEDIR)/configure/version.mk $(MK) $(FORCE_DISTVERSION) | $$(@D)/ + $(info $(INFO_)SED $@) + <$< \ + $(SED) 's/^DISTVERSION *:=.*/DISTVERSION := $(DISTVERSION)/' \ + | $(SED) 's/^DISTNAME *:=.*/DISTNAME := $(DISTNAME)/' \ + | $(SED) 's/^DISTDATE *:=.*/DISTDATE := $(DISTDATE)/' \ + | $(INSTALL_DATA) -T /dev/stdin $@ + +$(_DISTOTHERS): $(_DISTDIR)/%: $(srcdir)/% $(MK) | $$(@D)/ + $(info $(INFO_)CP $@) + $(CP) -dT $< $@ + + +endif # include guard diff --git a/share/mk/dist/tar.mk b/share/mk/dist/tar.mk new file mode 100644 index 0000000..a87557f --- /dev/null +++ b/share/mk/dist/tar.mk @@ -0,0 +1,37 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_TAR_INCLUDED +MAKEFILE_DIST_TAR_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/findutils.mk +include $(MAKEFILEDIR)/configure/build-depends/git.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/build-depends/tar.mk +include $(MAKEFILEDIR)/configure/version.mk +include $(MAKEFILEDIR)/dist/_.mk +include $(MAKEFILEDIR)/dist/files.mk + + +DISTFILE := $(DISTNAME).tar +_DISTFILE := $(builddir)/$(DISTFILE) + + +$(_DISTFILE): $(_DISTFILES) $(MK) | $$(@D)/ + $(info $(INFO_)TAR $@) + $(TAR) $(TARFLAGS) -cf $@ -T /dev/null + $(DISTFILESCMD) \ + | $(SED) 's,^$(srcdir)/,$(_DISTDIR)/,' \ + | $(SORT) \ + | $(XARGS) $(TAR) $(TARFLAGS) -rf $@ -C $(srcdir) \ + --transform 's,^$(patsubst /%,%,$(_DISTDIR)),$(DISTNAME),' + + +.PHONY: dist-tar +dist-tar: $(_DISTFILE); + + +endif # include guard diff --git a/share/mk/dist/z.mk b/share/mk/dist/z.mk new file mode 100644 index 0000000..b4b34fc --- /dev/null +++ b/share/mk/dist/z.mk @@ -0,0 +1,44 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_DIST_Z_INCLUDED +MAKEFILE_DIST_Z_INCLUDED := 1 + + +include $(MAKEFILEDIR)/configure/build-depends/bzip2.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/gzip.mk +include $(MAKEFILEDIR)/configure/build-depends/lzip.mk +include $(MAKEFILEDIR)/configure/build-depends/xz-utils.mk +include $(MAKEFILEDIR)/dist/tar.mk + + +compression := bz2 gz lz xz + + +define _DISTFILE_z_rule +$(_DISTFILE).$(2): %.$(2): % $(MK) | $$$$(@D)/ + $$(info $(INFO_)$(1) $$@) + $($(1)) $($(1)FLAGS) -kf $$< + $(TOUCH) $$@ +endef + + +$(eval $(call _DISTFILE_z_rule,BZIP2,bz2)) +$(eval $(call _DISTFILE_z_rule,GZIP,gz)) +$(eval $(call _DISTFILE_z_rule,LZIP,lz)) +$(eval $(call _DISTFILE_z_rule,XZ,xz)) + + +$(foreach z, $(compression), \ + $(eval .PHONY: dist-z-$(z))) +$(foreach z, $(compression), \ + $(eval dist-z-$(z): $(_DISTFILE).$(z);)) + + +.PHONY: dist-z +dist-z: $(foreach z, $(compression), dist-z-$(z)); + + +endif # include guard diff --git a/share/mk/install/_.mk b/share/mk/install/_.mk index 751ab97..bb39de3 100644 --- a/share/mk/install/_.mk +++ b/share/mk/install/_.mk @@ -1,29 +1,20 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_INSTALL_INCLUDED MAKEFILE_INSTALL_INCLUDED := 1 -include $(MAKEFILEDIR)/cmd.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk -DESTDIR := -prefix := /usr/local - -datarootdir := $(prefix)/share -docdir := $(datarootdir)/doc - - -$(DESTDIR)%/: - +$(info INSTALL $@) +%/: + +$(info $(INFO_)MKDIR $@) +$(INSTALL_DIR) $@ %-rm: - $(info RM $*) + $(info $(INFO_)RM $*) $(RM) $* diff --git a/share/mk/install/html.mk b/share/mk/install/html.mk index 97e00ce..047df90 100644 --- a/share/mk/install/html.mk +++ b/share/mk/install/html.mk @@ -1,28 +1,27 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_INSTALL_HTML_INCLUDED MAKEFILE_INSTALL_HTML_INCLUDED := 1 -include $(MAKEFILEDIR)/build/html.mk +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/html/post-grohtml.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk include $(MAKEFILEDIR)/install/_.mk -htmldir := $(docdir) -htmldir_ := $(htmldir)/man -_htmldir := $(DESTDIR)$(htmldir_) +_htmldir := $(DESTDIR)$(htmldir) -_htmlpages := $(patsubst $(_HTMLDIR)/%,$(_htmldir)/%,$(_HTMLPAGES)) +_htmlpages := $(patsubst $(_MANDIR)/%,$(_htmldir)/%,$(_HTMLMAN)) _htmlpages_rm := $(addsuffix -rm,$(wildcard $(_htmlpages))) -$(_htmlpages): $(_htmldir)/%: $(_HTMLDIR)/% | $$(@D)/ - $(info INSTALL $@) +$(_htmlpages): $(_htmldir)/%: $(_MANDIR)/% $(MK) | $$(@D)/ + $(info $(INFO_)INSTALL $@) $(INSTALL_DATA) -T $< $@ diff --git a/share/mk/install/man.mk b/share/mk/install/man.mk index a135788..65c1ea5 100644 --- a/share/mk/install/man.mk +++ b/share/mk/install/man.mk @@ -1,139 +1,60 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_INSTALL_MAN_INCLUDED MAKEFILE_INSTALL_MAN_INCLUDED := 1 -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/compress.mk +include $(MAKEFILEDIR)/configure/build-depends/bzip2.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/findutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/gzip.mk +include $(MAKEFILEDIR)/configure/build-depends/lzip.mk +include $(MAKEFILEDIR)/configure/build-depends/moreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/build-depends/xz-utils.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk +include $(MAKEFILEDIR)/configure/z.mk include $(MAKEFILEDIR)/install/_.mk include $(MAKEFILEDIR)/src.mk -LINK_PAGES := .so -ifeq ($(LINK_PAGES),.so) -else ifeq ($(LINK_PAGES),symlink) -else -$(warning "LINK_PAGES": "$(LINK_PAGES)") -$(error Valid values for "LINK_PAGES": [".so", "symlink"]) -endif +_mandir := $(DESTDIR)$(mandir) +$(foreach s, $(MANSECTIONS), \ + $(eval _man$(s)dir := $(DESTDIR)$(man$(s)dir))) + +$(foreach s, $(MANSECTIONS), \ + $(eval _man$(s)pages := \ + $(patsubst $(MAN$(s)DIR)/%.$(s), $(_man$(s)dir)/%$(man$(s)ext)$(Z), \ + $(MAN$(s)PAGES)))) +$(foreach s, $(MANSECTIONS), \ + $(eval _man$(s)intropage := \ + $(patsubst $(MAN$(s)DIR)/%.$(s), $(_man$(s)dir)/%$(man$(s)ext)$(Z), \ + $(MAN$(s)INTROPAGE)))) +_manintropages := $(foreach s, $(MANSECTIONS), $(_man$(s)intropage)) +_manpages := $(_manintropages) $(foreach s, $(MANSECTIONS), $(_man$(s)pages)) + +_manintropages_rm := $(addsuffix -rm, $(wildcard $(_manintropages))) +$(foreach s, $(MANSECTIONS), \ + $(eval _man$(s)pages_rm := \ + $(addsuffix -rm, \ + $(wildcard $(_man$(s)pages))))) -mandir := $(datarootdir)/man -man1dir := $(mandir)/man1 -man2dir := $(mandir)/man2 -man2typedir := $(mandir)/man2type -man3dir := $(mandir)/man3 -man3constdir:= $(mandir)/man3const -man3headdir := $(mandir)/man3head -man3typedir := $(mandir)/man3type -man4dir := $(mandir)/man4 -man5dir := $(mandir)/man5 -man6dir := $(mandir)/man6 -man7dir := $(mandir)/man7 -man8dir := $(mandir)/man8 -man1ext := .1$(Z) -man2ext := .2$(Z) -man2typeext := .2type$(Z) -man3ext := .3$(Z) -man3constext:= .3const$(Z) -man3headext := .3head$(Z) -man3typeext := .3type$(Z) -man4ext := .4$(Z) -man5ext := .5$(Z) -man6ext := .6$(Z) -man7ext := .7$(Z) -man8ext := .8$(Z) - - -_mandir := $(DESTDIR)$(mandir) -_man1dir := $(DESTDIR)$(man1dir) -_man2dir := $(DESTDIR)$(man2dir) -_man2typedir := $(DESTDIR)$(man2typedir) -_man3dir := $(DESTDIR)$(man3dir) -_man3constdir := $(DESTDIR)$(man3constdir) -_man3headdir := $(DESTDIR)$(man3headdir) -_man3typedir := $(DESTDIR)$(man3typedir) -_man4dir := $(DESTDIR)$(man4dir) -_man5dir := $(DESTDIR)$(man5dir) -_man6dir := $(DESTDIR)$(man6dir) -_man7dir := $(DESTDIR)$(man7dir) -_man8dir := $(DESTDIR)$(man8dir) - -_man1pages := $(patsubst $(MANDIR)/man1/%,$(_man1dir)/%$(Z),$(MAN1PAGES)) -_man2pages := $(patsubst $(MANDIR)/man2/%,$(_man2dir)/%$(Z),$(MAN2PAGES)) -_man2typepages := $(patsubst $(MANDIR)/man2type/%,$(_man2typedir)/%$(Z),$(MAN2TYPEPAGES)) -_man3pages := $(patsubst $(MANDIR)/man3/%,$(_man3dir)/%$(Z),$(MAN3PAGES)) -_man3constpages := $(patsubst $(MANDIR)/man3const/%,$(_man3constdir)/%$(Z),$(MAN3CONSTPAGES)) -_man3headpages := $(patsubst $(MANDIR)/man3head/%,$(_man3headdir)/%$(Z),$(MAN3HEADPAGES)) -_man3typepages := $(patsubst $(MANDIR)/man3type/%,$(_man3typedir)/%$(Z),$(MAN3TYPEPAGES)) -_man4pages := $(patsubst $(MANDIR)/man4/%,$(_man4dir)/%$(Z),$(MAN4PAGES)) -_man5pages := $(patsubst $(MANDIR)/man5/%,$(_man5dir)/%$(Z),$(MAN5PAGES)) -_man6pages := $(patsubst $(MANDIR)/man6/%,$(_man6dir)/%$(Z),$(MAN6PAGES)) -_man7pages := $(patsubst $(MANDIR)/man7/%,$(_man7dir)/%$(Z),$(MAN7PAGES)) -_man8pages := $(patsubst $(MANDIR)/man8/%,$(_man8dir)/%$(Z),$(MAN8PAGES)) -_manpages := $(_man1pages) \ - $(_man2pages) $(_man2typepages) \ - $(_man3pages) $(_man3constpages) $(_man3headpages) $(_man3typepages) \ - $(_man4pages) \ - $(_man5pages) \ - $(_man6pages) \ - $(_man7pages) \ - $(_man8pages) - -_man1pages_rm := $(addsuffix -rm,$(wildcard $(_man1pages))) -_man2pages_rm := $(addsuffix -rm,$(wildcard $(_man2pages))) -_man2typepages_rm := $(addsuffix -rm,$(wildcard $(_man2typepages))) -_man3pages_rm := $(addsuffix -rm,$(wildcard $(_man3pages))) -_man3constpages_rm:= $(addsuffix -rm,$(wildcard $(_man3constpages))) -_man3headpages_rm := $(addsuffix -rm,$(wildcard $(_man3headpages))) -_man3typepages_rm := $(addsuffix -rm,$(wildcard $(_man3typepages))) -_man4pages_rm := $(addsuffix -rm,$(wildcard $(_man4pages))) -_man5pages_rm := $(addsuffix -rm,$(wildcard $(_man5pages))) -_man6pages_rm := $(addsuffix -rm,$(wildcard $(_man6pages))) -_man7pages_rm := $(addsuffix -rm,$(wildcard $(_man7pages))) -_man8pages_rm := $(addsuffix -rm,$(wildcard $(_man8pages))) - -MAN_SECTIONS := 1 2 2type 3 3const 3head 3type 4 5 6 7 8 -install_manX := $(foreach x,$(MAN_SECTIONS),install-man$(x)) -uninstall_manX := $(foreach x,$(MAN_SECTIONS),uninstall-man$(x)) - - -$(_man1pages): $(_man1dir)/%$(Z): $(MANDIR)/man1/% | $$(@D)/ -$(_man2pages): $(_man2dir)/%$(Z): $(MANDIR)/man2/% | $$(@D)/ -$(_man2typepages): $(_man2typedir)/%$(Z): $(MANDIR)/man2type/% | $$(@D)/ -$(_man3pages): $(_man3dir)/%$(Z): $(MANDIR)/man3/% | $$(@D)/ -$(_man3constpages): $(_man3constdir)/%$(Z): $(MANDIR)/man3const/% | $$(@D)/ -$(_man3headpages): $(_man3headdir)/%$(Z): $(MANDIR)/man3head/% | $$(@D)/ -$(_man3typepages): $(_man3typedir)/%$(Z): $(MANDIR)/man3type/% | $$(@D)/ -$(_man4pages): $(_man4dir)/%$(Z): $(MANDIR)/man4/% | $$(@D)/ -$(_man5pages): $(_man5dir)/%$(Z): $(MANDIR)/man5/% | $$(@D)/ -$(_man6pages): $(_man6dir)/%$(Z): $(MANDIR)/man6/% | $$(@D)/ -$(_man7pages): $(_man7dir)/%$(Z): $(MANDIR)/man7/% | $$(@D)/ -$(_man8pages): $(_man8dir)/%$(Z): $(MANDIR)/man8/% | $$(@D)/ +$(foreach s, $(MANSECTIONS), \ + $(eval $(_man$(s)pages) $(_man$(s)intropage): \ + $(_man$(s)dir)/%$(man$(s)ext)$(Z): \ + $(MAN$(s)DIR)/%.$(s) $(MK) | $$$$(@D)/)) $(_manpages): - $(info INSTALL $@) - $(INSTALL_DATA) -T $< $@ - $(SED) -i \ - -e '/^\.so /s, man1/\(.*\)\.1$$, $(notdir $(man1dir))/\1$(man1ext),' \ - -e '/^\.so /s, man2/\(.*\)\.2$$, $(notdir $(man2dir))/\1$(man2ext),' \ - -e '/^\.so /s, man2type/\(.*\)\.2type$$, $(notdir $(man2typedir))/\1$(man2typeext),' \ - -e '/^\.so /s, man3/\(.*\)\.3$$, $(notdir $(man3dir))/\1$(man3ext),' \ - -e '/^\.so /s, man3const/\(.*\)\.3const$$, $(notdir $(man3constdir))/\1$(man3constext),' \ - -e '/^\.so /s, man3head/\(.*\)\.3head$$, $(notdir $(man3headdir))/\1$(man3headext),' \ - -e '/^\.so /s, man3type/\(.*\)\.3type$$, $(notdir $(man3typedir))/\1$(man3typeext),' \ - -e '/^\.so /s, man4/\(.*\)\.4$$, $(notdir $(man4dir))/\1$(man4ext),' \ - -e '/^\.so /s, man5/\(.*\)\.5$$, $(notdir $(man5dir))/\1$(man5ext),' \ - -e '/^\.so /s, man6/\(.*\)\.6$$, $(notdir $(man6dir))/\1$(man6ext),' \ - -e '/^\.so /s, man7/\(.*\)\.7$$, $(notdir $(man7dir))/\1$(man7ext),' \ - -e '/^\.so /s, man8/\(.*\)\.8$$, $(notdir $(man8dir))/\1$(man8ext),' \ - $@ + $(info $(INFO_)INSTALL $@) + <$< \ + $(SED) $(foreach s, $(MANSECTIONS), \ + -e '/^\.so /s, man$(s)/\(.*\)\.$(s)$$, $(notdir $(man$(s)dir))/\1$(man$(s)ext)$(Z),') \ + | $(INSTALL_DATA) -T /dev/stdin $@ ifeq ($(LINK_PAGES),symlink) if $(GREP) '^\.so ' <$@ >/dev/null; then \ $(GREP) '^\.so ' <$@ \ @@ -148,55 +69,39 @@ ifeq ($(Z),.bz2) fi else ifeq ($(Z),.gz) if ! $(TEST) -L $@; then \ - $(GZIP) $(GZIPFLAGS) - <$@ \ + $(GZIP) $(GZIPFLAGS) <$@ \ | $(SPONGE) $@; \ fi else ifeq ($(Z),.lz) if ! $(TEST) -L $@; then \ - $(LZIP) $(LZIPFLAGS) - <$@ \ + $(LZIP) $(LZIPFLAGS) <$@ \ | $(SPONGE) $@; \ fi else ifeq ($(Z),.xz) if ! $(TEST) -L $@; then \ - $(XZ) $(XZFLAGS) - <$@ \ + $(XZ) $(XZFLAGS) <$@ \ | $(SPONGE) $@; \ fi endif -.PHONY: install-man1 -install-man1: $(_man1pages); -.PHONY: install-man2 -install-man2: $(_man2pages); -.PHONY: install-man2type -install-man2type: $(_man2typepages); -.PHONY: install-man3 -install-man3: $(_man3pages); -.PHONY: install-man3const -install-man3const: $(_man3constpages); -.PHONY: install-man3head -install-man3head: $(_man3headpages); -.PHONY: install-man3type -install-man3type: $(_man3typepages); -.PHONY: install-man4 -install-man4: $(_man4pages); -.PHONY: install-man5 -install-man5: $(_man5pages); -.PHONY: install-man6 -install-man6: $(_man6pages); -.PHONY: install-man7 -install-man7: $(_man7pages); -.PHONY: install-man8 -install-man8: $(_man8pages); - +.PHONY: install-manintro +install-manintro: $(_manintropages); +$(foreach s, $(MANSECTIONS), \ + $(eval .PHONY: install-man$(s))) +$(foreach s, $(MANSECTIONS), \ + $(eval install-man$(s): $(_man$(s)pages);)) .PHONY: install-man -install-man: $(install_manX); - -.PHONY: $(uninstall_manX) -$(uninstall_manX): uninstall-man%: $$(_man%pages_rm); - +install-man: install-manintro $(foreach s, $(MANSECTIONS), install-man$(s)); + +.PHONY: uninstall-manintro +uninstall-manintro: $(_manintropages_rm); +$(foreach s, $(MANSECTIONS), \ + $(eval .PHONY: uninstall-man$(s))) +$(foreach s, $(MANSECTIONS), \ + $(eval uninstall-man$(s): $(_man$(s)pages_rm);)) .PHONY: uninstall-man -uninstall-man: $(uninstall_manX); +uninstall-man: uninstall-manintro $(foreach s, $(MANSECTIONS), uninstall-man$(s)); endif # include guard diff --git a/share/mk/lint/_.mk b/share/mk/lint/_.mk index 9d93bd3..48d02fa 100644 --- a/share/mk/lint/_.mk +++ b/share/mk/lint/_.mk @@ -1,18 +1,13 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_LINT_INCLUDED MAKEFILE_LINT_INCLUDED := 1 -lint := lint-c lint-man lint-mdoc - - .PHONY: lint -lint: $(lint); +lint: lint-c lint-man lint-mdoc; endif # include guard diff --git a/share/mk/lint/c.mk b/share/mk/lint/c.mk deleted file mode 100644 index b7d80a9..0000000 --- a/share/mk/lint/c.mk +++ /dev/null @@ -1,102 +0,0 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_LINT_C_INCLUDED -MAKEFILE_LINT_C_INCLUDED := 1 - - -include $(MAKEFILEDIR)/build/src.mk -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/lint/_.mk - - -DEFAULT_CHECKPATCHFLAGS := -EXTRA_CHECKPATCHFLAGS := -CHECKPATCHFLAGS := $(DEFAULT_CHECKPATCHFLAGS) $(EXTRA_CHECKPATCHFLAGS) -CHECKPATCH := checkpatch - -clang-tidy_config := $(SYSCONFDIR)/clang-tidy/config.yaml -DEFAULT_CLANG-TIDYFLAGS := \ - --config-file=$(clang-tidy_config) \ - --quiet \ - --use-color -EXTRA_CLANG-TIDYFLAGS := -CLANG-TIDYFLAGS := $(DEFAULT_CLANG-TIDYFLAGS) $(EXTRA_CLANG-TIDYFLAGS) -CLANG-TIDY := clang-tidy - -CPPCHECK_SUPPRESS := $(SYSCONFDIR)/cppcheck/cppcheck.suppress -DEFAULT_CPPCHECKFLAGS := \ - --enable=all \ - --error-exitcode=2 \ - --inconclusive \ - --quiet \ - --suppressions-list=$(CPPCHECK_SUPPRESS) -EXTRA_CPPCHECKFLAGS := -CPPCHECKFLAGS := $(DEFAULT_CPPCHECKFLAGS) $(EXTRA_CPPCHECKFLAGS) -CPPCHECK := cppcheck - -DEFAULT_CPPLINTFLAGS := -EXTRA_CPPLINTFLAGS := -CPPLINTFLAGS := $(DEFAULT_CPPLINTFLAGS) $(EXTRA_CPPLINTFLAGS) -CPPLINT := cpplint - -DEFAULT_IWYUFLAGS := \ - -Xiwyu --no_fwd_decls \ - -Xiwyu --error -EXTRA_IWYUFLAGS := -IWYUFLAGS := $(DEFAULT_IWYUFLAGS) $(EXTRA_IWYUFLAGS) -IWYU := iwyu - - -_LINT_c_checkpatch := $(patsubst %.c,%.lint-c.checkpatch.touch,$(_UNITS_src_c)) -_LINT_c_clang-tidy := $(patsubst %.c,%.lint-c.clang-tidy.touch,$(_UNITS_src_c)) -_LINT_c_cppcheck := $(patsubst %.c,%.lint-c.cppcheck.touch,$(_UNITS_src_c)) -_LINT_c_cpplint := $(patsubst %.c,%.lint-c.cpplint.touch,$(_UNITS_src_c)) -_LINT_c_iwyu := $(patsubst %.c,%.lint-c.iwyu.touch,$(_UNITS_src_c)) - - -linters_c := checkpatch clang-tidy cppcheck cpplint iwyu -lint_c := $(foreach x,$(linters_c),lint-c-$(x)) - - -$(_LINT_c_checkpatch): %.lint-c.checkpatch.touch: %.c - $(info LINT (checkpatch) $@) - $(CHECKPATCH) $(CHECKPATCHFLAGS) -f $< - touch $@ - -$(_LINT_c_clang-tidy): %.lint-c.clang-tidy.touch: %.c - $(info LINT (clang-tidy) $@) - $(CLANG-TIDY) $(CLANG-TIDYFLAGS) $< -- $(CPPFLAGS) $(CFLAGS) 2>&1 \ - | $(SED) '/generated\.$$/d' - touch $@ - -$(_LINT_c_cppcheck): %.lint-c.cppcheck.touch: %.c - $(info LINT (cppcheck) $@) - $(CPPCHECK) $(CPPCHECKFLAGS) $< - touch $@ - -$(_LINT_c_cpplint): %.lint-c.cpplint.touch: %.c - $(info LINT (cpplint) $@) - $(CPPLINT) $(CPPLINTFLAGS) $< >/dev/null - touch $@ - -$(_LINT_c_iwyu): %.lint-c.iwyu.touch: %.c - $(info LINT (iwyu) $@) - $(IWYU) $(IWYUFLAGS) $(CPPFLAGS) $(CFLAGS) $< 2>&1 \ - | $(TAC) \ - | $(SED) '/correct/{N;d}' \ - | $(TAC) - touch $@ - - -.PHONY: $(lint_c) -$(lint_c): lint-c-%: $$(_LINT_c_%); - -.PHONY: lint-c -lint-c: $(lint_c); - - -endif # include guard diff --git a/share/mk/lint/c/_.mk b/share/mk/lint/c/_.mk new file mode 100644 index 0000000..dc2f3e2 --- /dev/null +++ b/share/mk/lint/c/_.mk @@ -0,0 +1,18 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_C_INCLUDED +MAKEFILE_LINT_C_INCLUDED := 1 + + +.PHONY: lint-c +lint-c: \ + lint-c-checkpatch \ + lint-c-clang-tidy \ + lint-c-cppcheck \ + lint-c-cpplint \ + lint-c-iwyu + + +endif # include guard diff --git a/share/mk/lint/c/checkpatch.mk b/share/mk/lint/c/checkpatch.mk new file mode 100644 index 0000000..7777a10 --- /dev/null +++ b/share/mk/lint/c/checkpatch.mk @@ -0,0 +1,35 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_C_CHECKPATCH_INCLUDED +MAKEFILE_LINT_C_CHECKPATCH_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/examples/src.mk +include $(MAKEFILEDIR)/configure/build-depends/checkpatch.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_LINT_c_checkpatch := $(_MANDIR)/man2/bpf.2.d/bpf.lint-c.checkpatch.touch + + +_LINT_c_checkpatch := $(patsubst %.c, %.lint-c.checkpatch.touch, $(_UNITS_ex_c)) +ifeq ($(SKIP_XFAIL),yes) +_LINT_c_checkpatch := $(filter-out $(_XFAIL_LINT_c_checkpatch), $(_LINT_c_checkpatch)) +endif + + +$(_LINT_c_checkpatch): %.lint-c.checkpatch.touch: %.c $(CHECKPATCH_CONF) $(MK) + $(info $(INFO_)CHECKPATCH $@) + $(CHECKPATCH) $(CHECKPATCHFLAGS) -f $< >&2 + $(TOUCH) $@ + + +.PHONY: lint-c-checkpatch +lint-c-checkpatch: $(_LINT_c_checkpatch); + + +endif # include guard diff --git a/share/mk/lint/c/clang-tidy.mk b/share/mk/lint/c/clang-tidy.mk new file mode 100644 index 0000000..fd2e536 --- /dev/null +++ b/share/mk/lint/c/clang-tidy.mk @@ -0,0 +1,188 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_C_CLANG_TIDY_INCLUDED +MAKEFILE_LINT_C_CLANG_TIDY_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/examples/src.mk +include $(MAKEFILEDIR)/configure/build-depends/clang.mk +include $(MAKEFILEDIR)/configure/build-depends/clang-tidy.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/cpp.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_LINT_c_clang_tidy := \ + $(_MANDIR)/man2/add_key.2.d/add_key.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/bpf.2.d/bpf.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/chown.2.d/chown.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/clone.2.d/clone.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/close_range.2.d/close_range.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/copy_file_range.2.d/copy_file_range.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/eventfd.2.d/eventfd.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/execve.2.d/execve.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/execve.2.d/myecho.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/futex.2.d/futex.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/getdents.2.d/getdents.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/getrlimit.2.d/getrlimit.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/ioctl_fat.2.d/display_fat_volume_id.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/ioctl_fat.2.d/ioctl_fat.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/ioctl_fat.2.d/toggle_fat_archive_flag.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/ioctl_ns.2.d/ns_show.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/ioctl_tty.2.d/tcgets.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/kcmp.2.d/kcmp.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/keyctl.2.d/key_instantiate.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/listxattr.2.d/listxattr.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/membarrier.2.d/membarrier.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/memfd_create.2.d/t_get_seals.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/memfd_create.2.d/t_memfd_create.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/mmap.2.d/mmap.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/mount_setattr.2.d/mount_setattr.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/mprotect.2.d/mprotect.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/msgop.2.d/msgop.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/open_by_handle_at.2.d/t_name_to_handle_at.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/open_by_handle_at.2.d/t_open_by_handle_at.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/perf_event_open.2.d/perf_event_open.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/pidfd_open.2.d/pidfd_open.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/pidfd_send_signal.2.d/pidfd_send_signal.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/pipe.2.d/pipe.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/pivot_root.2.d/pivot_root.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/poll.2.d/poll_input.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/process_vm_readv.2.d/process_vm_readv.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/readlink.2.d/readlink.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/recvmmsg.2.d/recvmmsg.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/request_key.2.d/t_request_key.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/sched_setaffinity.2.d/sched_setaffinity.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/seccomp.2.d/seccomp.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/seccomp_unotify.2.d/seccomp_unotify.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/select_tut.2.d/select.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/semget.2.d/t_semget.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/sendmmsg.2.d/sendmmsg.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/setns.2.d/setns.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/shmop.2.d/svshm_string_read.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/shmop.2.d/svshm_string_write.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/sigaction.2.d/sigaction.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/spu_run.2.d/spu_run.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/stat.2.d/stat.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/_syscall.2.d/_syscall.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/syscall.2.d/syscall.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/sysctl.2.d/sysctl.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/tee.2.d/tee.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/timer_create.2.d/timer_create.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/timerfd_create.2.d/timerfd_create.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/unshare.2.d/unshare.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/userfaultfd.2.d/userfaultfd.lint-c.clang-tidy.touch \ + $(_MANDIR)/man2/wait.2.d/wait.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/atexit.3.d/atexit.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/backtrace.3.d/backtrace.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/bsearch.3.d/bsearch.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/bswap.3.d/bswap.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/cacos.3.d/cacos.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/cacosh.3.d/cacosh.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/catan.3.d/catan.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/catanh.3.d/catanh.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/circleq.3.d/circleq.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/clock_getcpuclockid.3.d/clock_getcpuclockid.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/CPU_SET.3.d/CPU_SET.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/dl_iterate_phdr.3.d/dl_iterate_phdr.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/dlinfo.3.d/dlinfo.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/duplocale.3.d/duplocale.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/encrypt.3.d/encrypt.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/end.3.d/end.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/endian.3.d/endian.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/envz_add.3.d/envz_add.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/fmemopen.3.d/fmemopen.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/fopencookie.3.d/fopencookie.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/fread.3.d/fread.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/frexp.3.d/frexp.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/ftw.3.d/ftw.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/_Generic.3.d/_Generic.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getaddrinfo.3.d/client.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getaddrinfo.3.d/server.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getaddrinfo_a.3.d/async.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getaddrinfo_a.3.d/sync.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getdate.3.d/getdate.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getgrent_r.3.d/getgrent_r.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getgrouplist.3.d/getgrouplist.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getline.3.d/getline.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getopt.3.d/getopt.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getopt.3.d/getopt_long.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getprotoent_r.3.d/getprotoent_r.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getpwnam.3.d/getpwnam.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getservent_r.3.d/getservent_r.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getsubopt.3.d/getsubopt.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/getutent.3.d/getutent.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/hsearch.3.d/hsearch.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/if_nameindex.3.d/if_nameindex.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/inet.3.d/inet.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/inet_net_pton.3.d/inet_net_pton.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/inet_pton.3.d/inet_pton.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/insque.3.d/insque.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/list.3.d/list.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/mallinfo.3.d/mallinfo.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/malloc_info.3.d/malloc_info.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/mallopt.3.d/mallopt.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/matherr.3.d/matherr.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/MAX.3.d/MAX.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/mbstowcs.3.d/mbstowcs.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/mq_getattr.3.d/mq_getattr.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/mq_notify.3.d/mq_notify.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/newlocale.3.d/newlocale.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/offsetof.3.d/offsetof.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/posix_spawn.3.d/posix_spawn.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/__ppc_get_timebase.3.d/__ppc_get_timebase.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/pthread_attr_init.3.d/pthread_attr_init.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/pthread_cleanup_push.3.d/pthread_cleanup_push.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/pthread_create.3.d/pthread_create.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/pthread_getattr_np.3.d/pthread_getattr_np.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/pthread_setname_np.3.d/pthread_setname_np.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/pthread_setschedparam.3.d/pthreads_sched_test.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/qsort.3.d/qsort.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/rand.3.d/rand.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/rpmatch.3.d/rpmatch.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/rtime.3.d/rtime.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/scandir.3.d/scandir.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/sem_wait.3.d/sem_wait.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/setbuf.3.d/setbuf.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/shm_open.3.d/pshm_ucase_bounce.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/shm_open.3.d/pshm_ucase_send.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/slist.3.d/slist.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/stailq.3.d/stailq.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/static_assert.3.d/must_be.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/stpncpy.3.d/stpncpy.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strcmp.3.d/string_comp.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strcpy.3.d/strcpy.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strftime.3.d/strftime.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strsep.3.d/strsep.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strtok.3.d/strtok.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strtol.3.d/strtol.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/strverscmp.3.d/strverscmp.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/tailq.3.d/tailq.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/tsearch.3.d/tsearch.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3/wordexp.3.d/wordexp.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3const/EXIT_SUCCESS.3const.d/EXIT_SUCCESS.lint-c.clang-tidy.touch \ + $(_MANDIR)/man3head/printf.h.3head.d/register_printf_specifier.lint-c.clang-tidy.touch + + +_LINT_c_clang_tidy := $(patsubst %.c, %.lint-c.clang-tidy.touch, $(_UNITS_ex_c)) +ifeq ($(SKIP_XFAIL),yes) +_LINT_c_clang_tidy := $(filter-out $(_XFAIL_LINT_c_clang_tidy), $(_LINT_c_clang_tidy)) +endif + + +$(_LINT_c_clang_tidy): %.lint-c.clang-tidy.touch: %.c $(CLANG_TIDY_CONF) $(MK) + $(info $(INFO_)CLANG_TIDY $@) + $(CLANG_TIDY) $(CLANG_TIDYFLAGS) $< -- $(CPPFLAGS) $(CLANGFLAGS) 2>&1 \ + | $(SED) '/generated\.$$/d' >&2 + $(TOUCH) $@ + + +.PHONY: lint-c-clang-tidy +lint-c-clang-tidy: $(_LINT_c_clang_tidy); + + +endif # include guard diff --git a/share/mk/lint/c/cppcheck.mk b/share/mk/lint/c/cppcheck.mk new file mode 100644 index 0000000..5fa74ac --- /dev/null +++ b/share/mk/lint/c/cppcheck.mk @@ -0,0 +1,74 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_C_CPPCHECK_INCLUDED +MAKEFILE_LINT_C_CPPCHECK_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/examples/src.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/cppcheck.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_LINT_c_cppcheck := \ + $(_MANDIR)/man2/chown.2.d/chown.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/close_range.2.d/close_range.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/kcmp.2.d/kcmp.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/keyctl.2.d/key_instantiate.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/memfd_create.2.d/t_memfd_create.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/msgop.2.d/msgop.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/open_by_handle_at.2.d/t_open_by_handle_at.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/shmop.2.d/svshm_string_read.lint-c.cppcheck.touch \ + $(_MANDIR)/man2/unshare.2.d/unshare.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/bsearch.3.d/bsearch.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/dl_iterate_phdr.3.d/dl_iterate_phdr.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/dlopen.3.d/dlopen.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/encrypt.3.d/encrypt.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/envz_add.3.d/envz_add.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/getaddrinfo_a.3.d/async.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/getdate.3.d/getdate.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/getgrouplist.3.d/getgrouplist.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/hsearch.3.d/hsearch.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/malloc_info.3.d/malloc_info.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/mallopt.3.d/mallopt.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/matherr.3.d/matherr.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/mcheck.3.d/mcheck.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/mtrace.3.d/t_mtrace.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/newlocale.3.d/newlocale.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/pthread_attr_init.3.d/pthread_attr_init.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/pthread_create.3.d/pthread_create.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/pthread_getattr_np.3.d/pthread_getattr_np.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/pthread_getcpuclockid.3.d/pthread_getcpuclockid.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/pthread_setschedparam.3.d/pthreads_sched_test.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/setaliasent.3.d/setaliasent.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/setbuf.3.d/setbuf.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/shm_open.3.d/pshm_ucase_send.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/stpncpy.3.d/stpncpy.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/strftime.3.d/strftime.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/strncat.3.d/strncat.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/strsep.3.d/strsep.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/strtok.3.d/strtok.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/strtol.3.d/strtol.lint-c.cppcheck.touch \ + $(_MANDIR)/man3/tsearch.3.d/tsearch.lint-c.cppcheck.touch + + +_LINT_c_cppcheck := $(patsubst %.c, %.lint-c.cppcheck.touch, $(_UNITS_ex_c)) +ifeq ($(SKIP_XFAIL),yes) +_LINT_c_cppcheck := $(filter-out $(_XFAIL_LINT_c_cppcheck), $(_LINT_c_cppcheck)) +endif + + +$(_LINT_c_cppcheck): %.lint-c.cppcheck.touch: %.c $(CPPCHECK_SUPPRESS) $(MK) + $(info $(INFO_)CPPCHECK $@) + $(CPPCHECK) $(CPPCHECKFLAGS) $< + $(TOUCH) $@ + + +.PHONY: lint-c-cppcheck +lint-c-cppcheck: $(_LINT_c_cppcheck); + + +endif # include guard diff --git a/share/mk/lint/c/cpplint.mk b/share/mk/lint/c/cpplint.mk new file mode 100644 index 0000000..8eb3984 --- /dev/null +++ b/share/mk/lint/c/cpplint.mk @@ -0,0 +1,27 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_C_CPPLINT_INCLUDED +MAKEFILE_LINT_C_CPPLINT_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/examples/src.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/cpplint.mk + + +_LINT_c_cpplint := $(patsubst %.c, %.lint-c.cpplint.touch, $(_UNITS_ex_c)) + + +$(_LINT_c_cpplint): %.lint-c.cpplint.touch: %.c $(CPPLINT_CONF) $(MK) + $(info $(INFO_)CPPLINT $@) + $(CPPLINT) $(CPPLINTFLAGS) $< >/dev/null + $(TOUCH) $@ + + +.PHONY: lint-c-cpplint +lint-c-cpplint: $(_LINT_c_cpplint); + + +endif # include guard diff --git a/share/mk/lint/c/iwyu.mk b/share/mk/lint/c/iwyu.mk new file mode 100644 index 0000000..32c2c07 --- /dev/null +++ b/share/mk/lint/c/iwyu.mk @@ -0,0 +1,109 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_C_IWYU_INCLUDED +MAKEFILE_LINT_C_IWYU_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/build/examples/src.mk +include $(MAKEFILEDIR)/configure/build-depends/clang.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/cpp.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/iwyu.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/xfail.mk + + +_XFAIL_LINT_c_iwyu := \ + $(_MANDIR)/man2/clock_getres.2.d/clock_getres.lint-c.iwyu.touch \ + $(_MANDIR)/man2/getrlimit.2.d/getrlimit.lint-c.iwyu.touch \ + $(_MANDIR)/man2/listxattr.2.d/listxattr.lint-c.iwyu.touch \ + $(_MANDIR)/man2/mount_setattr.2.d/mount_setattr.lint-c.iwyu.touch \ + $(_MANDIR)/man2/recvmmsg.2.d/recvmmsg.lint-c.iwyu.touch \ + $(_MANDIR)/man2/seccomp.2.d/seccomp.lint-c.iwyu.touch \ + $(_MANDIR)/man2/seccomp_unotify.2.d/seccomp_unotify.lint-c.iwyu.touch \ + $(_MANDIR)/man2/select.2.d/select.lint-c.iwyu.touch \ + $(_MANDIR)/man2/semget.2.d/t_semget.lint-c.iwyu.touch \ + $(_MANDIR)/man2/sendmmsg.2.d/sendmmsg.lint-c.iwyu.touch \ + $(_MANDIR)/man2/_syscall.2.d/_syscall.lint-c.iwyu.touch \ + $(_MANDIR)/man2/timer_create.2.d/timer_create.lint-c.iwyu.touch \ + $(_MANDIR)/man2/userfaultfd.2.d/userfaultfd.lint-c.iwyu.touch \ + $(_MANDIR)/man3/backtrace.3.d/backtrace.lint-c.iwyu.touch \ + $(_MANDIR)/man3/bsearch.3.d/bsearch.lint-c.iwyu.touch \ + $(_MANDIR)/man3/bswap.3.d/bswap.lint-c.iwyu.touch \ + $(_MANDIR)/man3/cacos.3.d/cacos.lint-c.iwyu.touch \ + $(_MANDIR)/man3/cacosh.3.d/cacosh.lint-c.iwyu.touch \ + $(_MANDIR)/man3/catan.3.d/catan.lint-c.iwyu.touch \ + $(_MANDIR)/man3/catanh.3.d/catanh.lint-c.iwyu.touch \ + $(_MANDIR)/man3/clock_getcpuclockid.3.d/clock_getcpuclockid.lint-c.iwyu.touch \ + $(_MANDIR)/man3/CPU_SET.3.d/CPU_SET.lint-c.iwyu.touch \ + $(_MANDIR)/man3/dl_iterate_phdr.3.d/dl_iterate_phdr.lint-c.iwyu.touch \ + $(_MANDIR)/man3/dlinfo.3.d/dlinfo.lint-c.iwyu.touch \ + $(_MANDIR)/man3/duplocale.3.d/duplocale.lint-c.iwyu.touch \ + $(_MANDIR)/man3/endian.3.d/endian.lint-c.iwyu.touch \ + $(_MANDIR)/man3/envz_add.3.d/envz_add.lint-c.iwyu.touch \ + $(_MANDIR)/man3/fopencookie.3.d/fopencookie.lint-c.iwyu.touch \ + $(_MANDIR)/man3/frexp.3.d/frexp.lint-c.iwyu.touch \ + $(_MANDIR)/man3/ftw.3.d/ftw.lint-c.iwyu.touch \ + $(_MANDIR)/man3/_Generic.3.d/_Generic.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getaddrinfo.3.d/client.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getaddrinfo.3.d/server.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getgrouplist.3.d/getgrouplist.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getline.3.d/getline.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getopt.3.d/getopt_long.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getprotoent_r.3.d/getprotoent_r.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getservent_r.3.d/getservent_r.lint-c.iwyu.touch \ + $(_MANDIR)/man3/getsubopt.3.d/getsubopt.lint-c.iwyu.touch \ + $(_MANDIR)/man3/if_nameindex.3.d/if_nameindex.lint-c.iwyu.touch \ + $(_MANDIR)/man3/inet.3.d/inet.lint-c.iwyu.touch \ + $(_MANDIR)/man3/inet_net_pton.3.d/inet_net_pton.lint-c.iwyu.touch \ + $(_MANDIR)/man3/inet_pton.3.d/inet_pton.lint-c.iwyu.touch \ + $(_MANDIR)/man3/mallinfo.3.d/mallinfo.lint-c.iwyu.touch \ + $(_MANDIR)/man3/malloc_info.3.d/malloc_info.lint-c.iwyu.touch \ + $(_MANDIR)/man3/mbstowcs.3.d/mbstowcs.lint-c.iwyu.touch \ + $(_MANDIR)/man3/mq_getattr.3.d/mq_getattr.lint-c.iwyu.touch \ + $(_MANDIR)/man3/mq_notify.3.d/mq_notify.lint-c.iwyu.touch \ + $(_MANDIR)/man3/mtrace.3.d/t_mtrace.lint-c.iwyu.touch \ + $(_MANDIR)/man3/newlocale.3.d/newlocale.lint-c.iwyu.touch \ + $(_MANDIR)/man3/posix_spawn.3.d/posix_spawn.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_attr_init.3.d/pthread_attr_init.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_cleanup_push.3.d/pthread_cleanup_push.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_getattr_default_np.3.d/pthread_getattr_default_np.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_getattr_np.3.d/pthread_getattr_np.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_getcpuclockid.3.d/pthread_getcpuclockid.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_setaffinity_np.3.d/pthread_setaffinity_np.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_setname_np.3.d/pthread_setname_np.lint-c.iwyu.touch \ + $(_MANDIR)/man3/pthread_setschedparam.3.d/pthreads_sched_test.lint-c.iwyu.touch \ + $(_MANDIR)/man3/sem_wait.3.d/sem_wait.lint-c.iwyu.touch \ + $(_MANDIR)/man3/shm_open.3.d/pshm_ucase_bounce.lint-c.iwyu.touch \ + $(_MANDIR)/man3/shm_open.3.d/pshm_ucase_send.lint-c.iwyu.touch \ + $(_MANDIR)/man3/slist.3.d/slist.lint-c.iwyu.touch + + +_LINT_c_iwyu := $(patsubst %.c, %.lint-c.iwyu.touch, $(_UNITS_ex_c)) +ifeq ($(SKIP_XFAIL),yes) +_LINT_c_iwyu := $(filter-out $(_XFAIL_LINT_c_iwyu), $(_LINT_c_iwyu)) +endif + + +$(_LINT_c_iwyu): %.lint-c.iwyu.touch: %.c $(MK) + $(info $(INFO_)IWYU $@) + ! ($(IWYU) $(IWYUFLAGS) $(CPPFLAGS) $(CLANGFLAGS) $< 2>&1 \ + | $(SED) -n '/should add these lines:/,$$p' \ + | $(TAC) \ + | $(SED) '/correct/{N;d}' \ + | $(TAC) \ + || $(TRUE); \ + ) \ + | $(GREP) ^ >&2 + $(TOUCH) $@ + + +.PHONY: lint-c-iwyu +lint-c-iwyu: $(_LINT_c_iwyu); + + +endif # include guard diff --git a/share/mk/lint/man/_.mk b/share/mk/lint/man/_.mk index 8bbc01c..67ff4b8 100644 --- a/share/mk/lint/man/_.mk +++ b/share/mk/lint/man/_.mk @@ -1,16 +1,13 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_LINT_MAN_INCLUDED MAKEFILE_LINT_MAN_INCLUDED := 1 -DEFAULT_MANDOCFLAGS := -Tlint -EXTRA_MANDOCFLAGS := -MANDOCFLAGS := $(DEFAULT_MANDOCFLAGS) $(EXTRA_MANDOCFLAGS) +.PHONY: lint-man +lint-man: lint-man-mandoc lint-man-tbl; endif # include guard diff --git a/share/mk/lint/man/man.mk b/share/mk/lint/man/man.mk deleted file mode 100644 index cb1bf53..0000000 --- a/share/mk/lint/man/man.mk +++ /dev/null @@ -1,69 +0,0 @@ -######################################################################## -# Copyright 2021-2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_LINT_MAN_MAN_INCLUDED -MAKEFILE_LINT_MAN_MAN_INCLUDED := 1 - - -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/lint/_.mk -include $(MAKEFILEDIR)/lint/man/_.mk -include $(MAKEFILEDIR)/src.mk - - -mandoc_man_ignore_grep := $(DATAROOTDIR)/lint/mandoc/man.ignore.grep - -_LINT_man_mandoc :=$(patsubst $(MANDIR)/%,$(_MANDIR)/%.lint-man.mandoc.touch,$(NONSO_MAN)) -_LINT_man_tbl :=$(patsubst $(MANDIR)/%,$(_MANDIR)/%.lint-man.tbl.touch,$(NONSO_MAN)) - - -linters_man := mandoc tbl -lint_man := $(foreach x,$(linters_man),lint-man-$(x)) - - -$(_LINT_man_mandoc): $(_MANDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% $(mandoc_man_ignore_grep) | $$(@D)/ - $(info LINT (mandoc) $@) - ! ($(MANDOC) -man $(MANDOCFLAGS) $< 2>&1 \ - | $(GREP) -v -f '$(mandoc_man_ignore_grep)' \ - ||:; \ - ) \ - | $(GREP) ^ >&2 - touch $@ - -$(_LINT_man_tbl): $(_MANDIR)/%.lint-man.tbl.touch: $(MANDIR)/% | $$(@D)/ - $(info LINT (tbl comment) $@) - if $(GREP) -q '^\.TS$$' $< && ! $(HEAD) -n1 $< | $(GREP) -q '\\" t$$'; \ - then \ - >&2 $(ECHO) "$<:1: missing '\\\" t' comment:"; \ - >&2 $(HEAD) -n1 <$<; \ - exit 1; \ - fi - if $(HEAD) -n1 $< | $(GREP) -q '\\" t$$' && ! $(GREP) -q '^\.TS$$' $<; \ - then \ - >&2 $(ECHO) "$<:1: spurious '\\\" t' comment:"; \ - >&2 $(HEAD) -n1 <$<; \ - exit 1; \ - fi - if $(TAIL) -n+2 <$< | $(GREP) -q '\\" t$$'; \ - then \ - >&2 $(ECHO) "$<: spurious '\\\" t' not in first line:"; \ - >&2 $(GREP) -n '\\" t$$' $< /dev/null; \ - exit 1; \ - fi - touch $@ - - -.PHONY: lint-man-mandoc -lint-man-mandoc: $(_LINT_man_mandoc); -.PHONY: lint-man-tbl -lint-man-tbl: $(_LINT_man_tbl); - -.PHONY: lint-man -lint-man: $(lint_man); - - -endif # include guard diff --git a/share/mk/lint/man/mandoc.ignore.grep b/share/mk/lint/man/mandoc.ignore.grep new file mode 100644 index 0000000..a2f91bc --- /dev/null +++ b/share/mk/lint/man/mandoc.ignore.grep @@ -0,0 +1,6 @@ +STYLE: lower case character in document title: +UNSUPP: ignoring macro in table: +WARNING: cannot parse date, using it verbatim: TH (date) +WARNING: empty block: UR +WARNING: missing date, using "": TH +WARNING: undefined escape, printing literally: \\\\ diff --git a/share/mk/lint/man/mandoc.mk b/share/mk/lint/man/mandoc.mk new file mode 100644 index 0000000..efa69ab --- /dev/null +++ b/share/mk/lint/man/mandoc.mk @@ -0,0 +1,53 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_MAN_MANDOC_INCLUDED +MAKEFILE_LINT_MAN_MANDOC_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/mandoc.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/configure/xfail.mk +include $(MAKEFILEDIR)/lint/man/_.mk +include $(MAKEFILEDIR)/src.mk + + +_XFAIL_LINT_man_mandoc := \ + $(_MANDIR)/man3/pthread_cond_init.3.lint-man.mandoc.touch \ + $(_MANDIR)/man3/pthread_key_create.3.lint-man.mandoc.touch \ + $(_MANDIR)/man3/pthread_mutex_init.3.lint-man.mandoc.touch \ + $(_MANDIR)/man5/dir_colors.5.lint-man.mandoc.touch \ + $(_MANDIR)/man7/bpf-helpers.7.lint-man.mandoc.touch \ + $(_MANDIR)/man7/uri.7.lint-man.mandoc.touch \ + $(_MANDIR)/man8/zic.8.lint-man.mandoc.touch + + +_LINT_man_mandoc := \ + $(patsubst $(MANDIR)/%, $(_MANDIR)/%.lint-man.mandoc.touch, $(NONSO_MAN)) +ifeq ($(SKIP_XFAIL),yes) +_LINT_man_mandoc := $(filter-out $(_XFAIL_LINT_man_mandoc), $(_LINT_man_mandoc)) +endif + + +mandoc_man_ignore_grep := $(MAKEFILEDIR)/lint/man/mandoc.ignore.grep + + +$(_LINT_man_mandoc): $(_MANDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% $(mandoc_man_ignore_grep) $(MK) | $$(@D)/ + $(info $(INFO_)MANDOC $@) + ! ($(MANDOC) -man $(MANDOCFLAGS) $< 2>&1 \ + | $(GREP) -v -f '$(mandoc_man_ignore_grep)' \ + || $(TRUE); \ + ) \ + | $(GREP) ^ >&2 + $(TOUCH) $@ + + +.PHONY: lint-man-mandoc +lint-man-mandoc: $(_LINT_man_mandoc); + + +endif # include guard diff --git a/share/mk/lint/man/mdoc.mk b/share/mk/lint/man/mdoc.mk deleted file mode 100644 index 9b5f5b4..0000000 --- a/share/mk/lint/man/mdoc.mk +++ /dev/null @@ -1,44 +0,0 @@ -######################################################################## -# Copyright 2023, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_LINT_MAN_MDOC_INCLUDED -MAKEFILE_LINT_MAN_MDOC_INCLUDED := 1 - - -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/build/_.mk -include $(MAKEFILEDIR)/lint/_.mk -include $(MAKEFILEDIR)/lint/man/_.mk -include $(MAKEFILEDIR)/src.mk - - -mandoc_mdoc_ignore_grep := $(DATAROOTDIR)/lint/mandoc/mdoc.ignore.grep - -_LINT_mdoc_mandoc:=$(patsubst $(MANDIR)/%,$(_MANDIR)/%.lint-mdoc.mandoc.touch,$(NONSO_MDOC)) - - -linters_mdoc := mandoc -lint_mdoc := $(foreach x,$(linters_mdoc),lint-mdoc-$(x)) - - -$(_LINT_mdoc_mandoc): $(_MANDIR)/%.lint-mdoc.mandoc.touch: $(MANDIR)/% $(mandoc_mdoc_ignore_grep) | $$(@D)/ - $(info LINT (mandoc) $@) - ! ($(MANDOC) -mdoc $(MANDOCFLAGS) $< 2>&1 \ - | $(GREP) -v -f '$(mandoc_mdoc_ignore_grep)' \ - ||:; \ - ) \ - | $(GREP) ^ >&2 - touch $@ - - -.PHONY: $(lint_mdoc) -$(lint_mdoc): lint-mdoc-%: $$(_LINT_mdoc_%); - -.PHONY: lint-mdoc -lint-mdoc: $(lint_mdoc); - - -endif # include guard diff --git a/share/mk/lint/man/tbl.mk b/share/mk/lint/man/tbl.mk new file mode 100644 index 0000000..23e6eda --- /dev/null +++ b/share/mk/lint/man/tbl.mk @@ -0,0 +1,48 @@ +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_MAN_TBL_INCLUDED +MAKEFILE_LINT_MAN_TBL_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/src.mk +include $(MAKEFILEDIR)/lint/man/_.mk +include $(MAKEFILEDIR)/src.mk + + +_LINT_man_tbl := \ + $(patsubst $(MANDIR)/%, $(_MANDIR)/%.lint-man.tbl.touch, $(NONSO_MAN)) + + +$(_LINT_man_tbl): $(_MANDIR)/%.lint-man.tbl.touch: $(MANDIR)/% $(MK) | $$(@D)/ + $(info $(INFO_)GREP $@) + if $(GREP) -q '^\.TS$$' $< && ! $(HEAD) -n1 $< | $(GREP) -q '\\" t$$'; \ + then \ + >&2 $(ECHO) "$<:1: missing '\\\" t' comment:"; \ + >&2 $(HEAD) -n1 <$<; \ + exit 1; \ + fi + if $(HEAD) -n1 $< | $(GREP) -q '\\" t$$' && ! $(GREP) -q '^\.TS$$' $<; \ + then \ + >&2 $(ECHO) "$<:1: spurious '\\\" t' comment:"; \ + >&2 $(HEAD) -n1 <$<; \ + exit 1; \ + fi + if $(TAIL) -n+2 <$< | $(GREP) -q '\\" t$$'; \ + then \ + >&2 $(ECHO) "$<: spurious '\\\" t' not in first line:"; \ + >&2 $(GREP) -n '\\" t$$' $< /dev/null; \ + exit 1; \ + fi + $(TOUCH) $@ + + +.PHONY: lint-man-tbl +lint-man-tbl: $(_LINT_man_tbl); + + +endif # include guard diff --git a/share/mk/lint/mdoc/_.mk b/share/mk/lint/mdoc/_.mk new file mode 100644 index 0000000..0f51ee2 --- /dev/null +++ b/share/mk/lint/mdoc/_.mk @@ -0,0 +1,31 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_MDOC_INCLUDED +MAKEFILE_LINT_MDOC_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/directory_variables.mk +include $(MAKEFILEDIR)/src.mk + + +linters_mdoc := mandoc + + +$(foreach l, $(linters_mdoc), \ + $(eval _LINT_mdoc_$(l) := \ + $(patsubst $(MANDIR)/%, $(_MANDIR)/%.lint-mdoc.$(l).touch, \ + $(NONSO_MDOC)))) + + +$(foreach l, $(linters_mdoc), \ + $(eval .PHONY: lint-mdoc-$(l))) +$(foreach l, $(linters_mdoc), \ + $(eval lint-mdoc-$(l): $(_LINT_mdoc_$(l));)) +.PHONY: lint-mdoc +lint-mdoc: $(foreach l, $(linters_mdoc), lint-mdoc-$(l)); + + +endif # include guard diff --git a/share/mk/lint/mdoc/mandoc.ignore.grep b/share/mk/lint/mdoc/mandoc.ignore.grep new file mode 100644 index 0000000..4c73c59 --- /dev/null +++ b/share/mk/lint/mdoc/mandoc.ignore.grep @@ -0,0 +1,5 @@ +STYLE: legacy man(7) date format: Dd +STYLE: lower case character in document title: Dt +STYLE: operating system explicitly specified: Os +STYLE: referenced manual not found: Xr +WARNING: cross reference to self: Xr diff --git a/share/mk/lint/mdoc/mandoc.mk b/share/mk/lint/mdoc/mandoc.mk new file mode 100644 index 0000000..8b209b8 --- /dev/null +++ b/share/mk/lint/mdoc/mandoc.mk @@ -0,0 +1,30 @@ +# Copyright 2023-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception + + +ifndef MAKEFILE_LINT_MDOC_MANDOC_INCLUDED +MAKEFILE_LINT_MDOC_MANDOC_INCLUDED := 1 + + +include $(MAKEFILEDIR)/build/_.mk +include $(MAKEFILEDIR)/configure/build-depends/coreutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/mandoc.mk +include $(MAKEFILEDIR)/lint/mdoc/_.mk +include $(MAKEFILEDIR)/src.mk + + +mandoc_mdoc_ignore_grep := $(MAKEFILEDIR)/lint/mdoc/mandoc.ignore.grep + + +$(_LINT_mdoc_mandoc): $(_MANDIR)/%.lint-mdoc.mandoc.touch: $(MANDIR)/% $(mandoc_mdoc_ignore_grep) | $$(@D)/ + $(info $(INFO_)MANDOC $@) + ! ($(MANDOC) -mdoc $(MANDOCFLAGS) $< 2>&1 \ + | $(GREP) -v -f '$(mandoc_mdoc_ignore_grep)' \ + || $(TRUE); \ + ) \ + | $(GREP) ^ >&2 + $(TOUCH) $@ + + +endif # include guard diff --git a/share/mk/src.mk b/share/mk/src.mk index 65825b5..20c0037 100644 --- a/share/mk/src.mk +++ b/share/mk/src.mk @@ -1,37 +1,62 @@ -######################################################################## -# Copyright 2021-2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## +# Copyright 2021-2024, Alejandro Colomar +# SPDX-License-Identifier: LGPL-3.0-only WITH LGPL-3.0-linking-exception ifndef MAKEFILE_SRC_INCLUDED MAKEFILE_SRC_INCLUDED := 1 -include $(MAKEFILEDIR)/cmd.mk +include $(MAKEFILEDIR)/configure/build-depends/findutils.mk +include $(MAKEFILEDIR)/configure/build-depends/grep.mk +include $(MAKEFILEDIR)/configure/build-depends/sed.mk +include $(MAKEFILEDIR)/configure/src.mk -MANDIR := $(srcdir) -MANEXT := \.[0-9]\w*\(\.man\)\?\(\.in\)\?$ +SORTMAN := $(srcdir)/scripts/sortman + + +MANEXT := \(\.[[:digit:]]\([[:alpha:]][[:alnum:]]*\)\?\>\|\.man\)\+\(\.man\|\.in\)*$ MANPAGES := $(shell $(FIND) $(MANDIR)/* -type f \ | $(GREP) '$(MANEXT)' \ - | $(SORT) \ + | $(SORTMAN) \ | $(SED) 's,:,\\:,g') -MAN1PAGES := $(filter $(MANDIR)/man1/%,$(filter %.1,$(MANPAGES))) -MAN2PAGES := $(filter $(MANDIR)/man2/%,$(filter %.2,$(MANPAGES))) -MAN2TYPEPAGES := $(filter $(MANDIR)/man2type/%,$(filter %.2type,$(MANPAGES))) -MAN3PAGES := $(filter $(MANDIR)/man3/%,$(filter %.3,$(MANPAGES))) -MAN3CONSTPAGES := $(filter $(MANDIR)/man3const/%,$(filter %.3const,$(MANPAGES))) -MAN3HEADPAGES := $(filter $(MANDIR)/man3head/%,$(filter %.3head,$(MANPAGES))) -MAN3TYPEPAGES := $(filter $(MANDIR)/man3type/%,$(filter %.3type,$(MANPAGES))) -MAN4PAGES := $(filter $(MANDIR)/man4/%,$(filter %.4,$(MANPAGES))) -MAN5PAGES := $(filter $(MANDIR)/man5/%,$(filter %.5,$(MANPAGES))) -MAN6PAGES := $(filter $(MANDIR)/man6/%,$(filter %.6,$(MANPAGES))) -MAN7PAGES := $(filter $(MANDIR)/man7/%,$(filter %.7,$(MANPAGES))) -MAN8PAGES := $(filter $(MANDIR)/man8/%,$(filter %.8,$(MANPAGES))) + +MANINTROPAGES := $(shell $(FIND) $(MANDIR)/* -type f \ + | $(GREP) '$(MANEXT)' \ + | $(GREP) '/intro$(MANEXT)' \ + | $(SORTMAN) \ + | $(SED) 's,:,\\:,g') + + +$(foreach s, $(MANSECTIONS), \ + $(eval MAN$(s)DIR := $(MANDIR)/man$(s))) + +$(foreach s, $(MANSECTIONS), \ + $(eval MAN$(s)PAGES := \ + $(filter-out $(MANINTROPAGES), \ + $(filter $(MANDIR)/man$(s)/%, \ + $(filter %.$(s), \ + $(MANPAGES)))))) +$(foreach s, $(MANSECTIONS), \ + $(eval MAN$(s)INTROPAGE := \ + $(filter $(MANDIR)/man$(s)/%, \ + $(filter %.$(s), \ + $(MANINTROPAGES))))) + + +NONSO_MAN := $(shell $(FIND) $(MANDIR)/* -type f \ + | $(GREP) '$(MANEXT)' \ + | $(XARGS) $(GREP) -l '^\.TH ' \ + | $(SORTMAN) \ + | $(SED) 's,:,\\:,g') +NONSO_MDOC := $(shell $(FIND) $(MANDIR)/* -type f \ + | $(GREP) '$(MANEXT)' \ + | $(XARGS) $(GREP) -l '^\.Dt ' \ + | $(SORTMAN) \ + | $(SED) 's,:,\\:,g') endif # include guard diff --git a/share/mk/verbose.mk b/share/mk/verbose.mk deleted file mode 100644 index 2cc4450..0000000 --- a/share/mk/verbose.mk +++ /dev/null @@ -1,19 +0,0 @@ -######################################################################## -# Copyright 2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_VERBOSE_INCLUDED -MAKEFILE_VERBOSE_INCLUDED := 1 - - -ifdef V -HIDE_ERR := -else -HIDE_ERR := 2>/dev/null -.SILENT: -endif - - -endif # include guard diff --git a/share/mk/version.mk b/share/mk/version.mk deleted file mode 100644 index af3c0cb..0000000 --- a/share/mk/version.mk +++ /dev/null @@ -1,20 +0,0 @@ -######################################################################## -# Copyright 2022, Alejandro Colomar -# SPDX-License-Identifier: GPL-3.0-or-later -######################################################################## - - -ifndef MAKEFILE_VERSION_INCLUDED -MAKEFILE_VERSION_INCLUDED := 1 - - -include $(MAKEFILEDIR)/cmd.mk -include $(MAKEFILEDIR)/verbose.mk - - -DISTNAME := $(shell $(GIT) describe $(HIDE_ERR)) -DISTVERSION := $(patsubst man-pages-%,%,$(DISTNAME)) -DISTDATE := $(shell $(GIT) log -1 --format='%aD') - - -endif # include guard -- cgit v1.2.3