diff options
Diffstat (limited to 'lib/libc/sys')
251 files changed, 44127 insertions, 0 deletions
diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc new file mode 100644 index 000000000000..03c326c93711 --- /dev/null +++ b/lib/libc/sys/Makefile.inc @@ -0,0 +1,486 @@ +# @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 +# $FreeBSD$ + +# sys sources +.PATH: ${LIBC_SRCTOP}/${LIBC_ARCH}/sys ${LIBC_SRCTOP}/sys + +# Include the generated makefile containing the *complete* list +# of syscall names in MIASM. +.include "${SRCTOP}/sys/sys/syscall.mk" + +# Include machine dependent definitions. +# +# MDASM names override the default syscall names in MIASM. +# NOASM will prevent the default syscall code from being generated. +# PSEUDO generates _<sys>() and __sys_<sys>() symbols, but not <sys>(). +# +# While historically machine dependent, all architectures have the following +# declarations in common: +# +NOASM= break.o \ + exit.o \ + getlogin.o \ + sstk.o \ + yield.o +PSEUDO= _exit.o \ + _getlogin.o +.sinclude "${LIBC_SRCTOP}/${LIBC_ARCH}/sys/Makefile.inc" + +SRCS+= clock_gettime.c gettimeofday.c __vdso_gettimeofday.c +NOASM+= clock_gettime.o gettimeofday.o +PSEUDO+= _clock_gettime.o _gettimeofday.o + +# Sources common to both syscall interfaces: +SRCS+= \ + __error.c \ + interposing_table.c + +SRCS+= futimens.c utimensat.c +NOASM+= futimens.o utimensat.o +PSEUDO+= _futimens.o _utimensat.o + +SRCS+= pipe.c + +INTERPOSED = \ + accept \ + accept4 \ + aio_suspend \ + close \ + connect \ + fcntl \ + fdatasync \ + fsync \ + fork \ + kevent \ + msync \ + nanosleep \ + open \ + openat \ + poll \ + ppoll \ + pselect \ + ptrace \ + read \ + readv \ + recvfrom \ + recvmsg \ + select \ + sendmsg \ + sendto \ + setcontext \ + sigprocmask \ + sigsuspend \ + sigtimedwait \ + sigwait \ + sigwaitinfo \ + swapcontext \ + wait4 \ + wait6 \ + write \ + writev + +.if ${MACHINE_CPUARCH} == "sparc64" +SRCS+= sigaction.c +NOASM+= sigaction.o +.else +INTERPOSED+= sigaction +.endif + +SRCS+= ${INTERPOSED:S/$/.c/} +NOASM+= ${INTERPOSED:S/$/.o/} +PSEUDO+= ${INTERPOSED:C/^.*$/_&.o/} + +# Add machine dependent asm sources: +SRCS+=${MDASM} + +# Look though the complete list of syscalls (MIASM) for names that are +# not defined with machine dependent implementations (MDASM) and are +# not declared for no generation of default code (NOASM). Add each +# syscall that satisfies these conditions to the ASM list. +.for _asm in ${MIASM} +.if (${MDASM:R:M${_asm:R}} == "") +.if (${NOASM:R:M${_asm:R}} == "") +ASM+=$(_asm) +.endif +.endif +.endfor + +SASM= ${ASM:S/.o/.S/} + +SPSEUDO= ${PSEUDO:S/.o/.S/} + +SRCS+= ${SASM} ${SPSEUDO} + +SYM_MAPS+= ${LIBC_SRCTOP}/sys/Symbol.map + +# Generated files +CLEANFILES+= ${SASM} ${SPSEUDO} + +.if ${MACHINE_CPUARCH} == "amd64" || ${MACHINE_CPUARCH} == "i386" || \ + ${MACHINE_CPUARCH} == "powerpc" || ${MACHINE_ARCH:Marmv6*} +NOTE_GNU_STACK='\t.section .note.GNU-stack,"",%%progbits\n' +.else +NOTE_GNU_STACK='' +.endif + +${SASM}: + printf '#include "compat.h"\n' > ${.TARGET} + printf '#include "SYS.h"\nRSYSCALL(${.PREFIX})\n' >> ${.TARGET} + printf ${NOTE_GNU_STACK} >>${.TARGET} + +${SPSEUDO}: + printf '#include "compat.h"\n' > ${.TARGET} + printf '#include "SYS.h"\nPSEUDO(${.PREFIX:S/_//})\n' \ + >> ${.TARGET} + printf ${NOTE_GNU_STACK} >>${.TARGET} + +MAN+= abort2.2 \ + accept.2 \ + access.2 \ + acct.2 \ + adjtime.2 \ + aio_cancel.2 \ + aio_error.2 \ + aio_fsync.2 \ + aio_mlock.2 \ + aio_read.2 \ + aio_return.2 \ + aio_suspend.2 \ + aio_waitcomplete.2 \ + aio_write.2 \ + bind.2 \ + bindat.2 \ + brk.2 \ + cap_enter.2 \ + cap_fcntls_limit.2 \ + cap_ioctls_limit.2 \ + cap_rights_limit.2 \ + chdir.2 \ + chflags.2 \ + chmod.2 \ + chown.2 \ + chroot.2 \ + clock_gettime.2 \ + close.2 \ + closefrom.2 \ + connect.2 \ + connectat.2 \ + cpuset.2 \ + cpuset_getaffinity.2 \ + dup.2 \ + execve.2 \ + _exit.2 \ + extattr_get_file.2 \ + fcntl.2 \ + ffclock.2 \ + fhopen.2 \ + flock.2 \ + fork.2 \ + fsync.2 \ + getdirentries.2 \ + getdtablesize.2 \ + getfh.2 \ + getfsstat.2 \ + getgid.2 \ + getgroups.2 \ + getitimer.2 \ + getlogin.2 \ + getloginclass.2 \ + getpeername.2 \ + getpgrp.2 \ + getpid.2 \ + getpriority.2 \ + getrlimit.2 \ + getrusage.2 \ + getsid.2 \ + getsockname.2 \ + getsockopt.2 \ + gettimeofday.2 \ + getuid.2 \ + intro.2 \ + ioctl.2 \ + issetugid.2 \ + jail.2 \ + kenv.2 \ + kill.2 \ + kldfind.2 \ + kldfirstmod.2 \ + kldload.2 \ + kldnext.2 \ + kldstat.2 \ + kldsym.2 \ + kldunload.2 \ + kqueue.2 \ + ktrace.2 \ + link.2 \ + lio_listio.2 \ + listen.2 \ + lseek.2 \ + madvise.2 \ + mincore.2 \ + minherit.2 \ + mkdir.2 \ + mkfifo.2 \ + mknod.2 \ + mlock.2 \ + mlockall.2 \ + mmap.2 \ + modfind.2 \ + modnext.2 \ + modstat.2 \ + mount.2 \ + mprotect.2 \ + mq_close.2 \ + mq_getattr.2 \ + mq_notify.2 \ + mq_open.2 \ + mq_receive.2 \ + mq_send.2 \ + mq_setattr.2 \ + msgctl.2 \ + msgget.2 \ + msgrcv.2 \ + msgsnd.2 \ + msync.2 \ + munmap.2 \ + nanosleep.2 \ + nfssvc.2 \ + ntp_adjtime.2 \ + numa_getaffinity.2 \ + open.2 \ + pathconf.2 \ + pdfork.2 \ + pipe.2 \ + poll.2 \ + posix_fadvise.2 \ + posix_fallocate.2 \ + posix_openpt.2 \ + procctl.2 \ + profil.2 \ + pselect.2 \ + ptrace.2 \ + quotactl.2 \ + rctl_add_rule.2 \ + read.2 \ + readlink.2 \ + reboot.2 \ + recv.2 \ + rename.2 \ + revoke.2 \ + rfork.2 \ + rmdir.2 \ + rtprio.2 +.if !defined(NO_P1003_1B) +MAN+= sched_get_priority_max.2 \ + sched_setparam.2 \ + sched_setscheduler.2 \ + sched_yield.2 +.endif +MAN+= sctp_generic_recvmsg.2 \ + sctp_generic_sendmsg.2 \ + sctp_peeloff.2 \ + select.2 \ + semctl.2 \ + semget.2 \ + semop.2 \ + send.2 \ + setfib.2 \ + sendfile.2 \ + setgroups.2 \ + setpgid.2 \ + setregid.2 \ + setresuid.2 \ + setreuid.2 \ + setsid.2 \ + setuid.2 \ + shmat.2 \ + shmctl.2 \ + shmget.2 \ + shm_open.2 \ + shutdown.2 \ + sigaction.2 \ + sigaltstack.2 \ + sigpending.2 \ + sigprocmask.2 \ + sigqueue.2 \ + sigreturn.2 \ + sigstack.2 \ + sigsuspend.2 \ + sigwait.2 \ + sigwaitinfo.2 \ + socket.2 \ + socketpair.2 \ + stat.2 \ + statfs.2 \ + swapon.2 \ + symlink.2 \ + sync.2 \ + sysarch.2 \ + syscall.2 \ + thr_exit.2 \ + thr_kill.2 \ + thr_new.2 \ + thr_self.2 \ + thr_set_name.2 \ + thr_suspend.2 \ + thr_wake.2 \ + timer_create.2 \ + timer_delete.2 \ + timer_settime.2 \ + truncate.2 \ + umask.2 \ + undelete.2 \ + unlink.2 \ + utimensat.2 \ + utimes.2 \ + utrace.2 \ + uuidgen.2 \ + vfork.2 \ + wait.2 \ + write.2 \ + _umtx_op.2 + +MLINKS+=accept.2 accept4.2 +MLINKS+=access.2 eaccess.2 \ + access.2 faccessat.2 +MLINKS+=brk.2 sbrk.2 +MLINKS+=cap_enter.2 cap_getmode.2 +MLINKS+=cap_fcntls_limit.2 cap_fcntls_get.2 +MLINKS+=cap_ioctls_limit.2 cap_ioctls_get.2 +MLINKS+=cap_rights_limit.2 cap_rights_get.2 +MLINKS+=chdir.2 fchdir.2 +MLINKS+=chflags.2 chflagsat.2 \ + chflags.2 fchflags.2 \ + chflags.2 lchflags.2 +MLINKS+=chmod.2 fchmod.2 \ + chmod.2 fchmodat.2 \ + chmod.2 lchmod.2 +MLINKS+=chown.2 fchown.2 \ + chown.2 fchownat.2 \ + chown.2 lchown.2 +MLINKS+=clock_gettime.2 clock_getres.2 \ + clock_gettime.2 clock_settime.2 +MLINKS+=cpuset.2 cpuset_getid.2 \ + cpuset.2 cpuset_setid.2 +MLINKS+=cpuset_getaffinity.2 cpuset_setaffinity.2 +MLINKS+=dup.2 dup2.2 +MLINKS+=execve.2 fexecve.2 +MLINKS+=extattr_get_file.2 extattr.2 \ + extattr_get_file.2 extattr_delete_fd.2 \ + extattr_get_file.2 extattr_delete_file.2 \ + extattr_get_file.2 extattr_delete_link.2 \ + extattr_get_file.2 extattr_get_fd.2 \ + extattr_get_file.2 extattr_get_link.2 \ + extattr_get_file.2 extattr_list_fd.2 \ + extattr_get_file.2 extattr_list_file.2 \ + extattr_get_file.2 extattr_list_link.2 \ + extattr_get_file.2 extattr_set_fd.2 \ + extattr_get_file.2 extattr_set_file.2 \ + extattr_get_file.2 extattr_set_link.2 +MLINKS+=ffclock.2 ffclock_getcounter.2 \ + ffclock.2 ffclock_getestimate.2 \ + ffclock.2 ffclock_setestimate.2 +MLINKS+=fhopen.2 fhstat.2 fhopen.2 fhstatfs.2 +MLINKS+=fsync.2 fdatasync.2 +MLINKS+=getdirentries.2 getdents.2 +MLINKS+=getfh.2 lgetfh.2 +MLINKS+=getgid.2 getegid.2 +MLINKS+=getitimer.2 setitimer.2 +MLINKS+=getlogin.2 getlogin_r.3 +MLINKS+=getlogin.2 setlogin.2 +MLINKS+=getloginclass.2 setloginclass.2 +MLINKS+=getpgrp.2 getpgid.2 +MLINKS+=getpid.2 getppid.2 +MLINKS+=getpriority.2 setpriority.2 +MLINKS+=getrlimit.2 setrlimit.2 +MLINKS+=getsockopt.2 setsockopt.2 +MLINKS+=gettimeofday.2 settimeofday.2 +MLINKS+=getuid.2 geteuid.2 +MLINKS+=intro.2 errno.2 +MLINKS+=jail.2 jail_attach.2 \ + jail.2 jail_get.2 \ + jail.2 jail_remove.2 \ + jail.2 jail_set.2 +MLINKS+=kldunload.2 kldunloadf.2 +MLINKS+=kqueue.2 kevent.2 \ + kqueue.2 EV_SET.3 +MLINKS+=link.2 linkat.2 +MLINKS+=madvise.2 posix_madvise.2 +MLINKS+=mkdir.2 mkdirat.2 +MLINKS+=mkfifo.2 mkfifoat.2 +MLINKS+=mknod.2 mknodat.2 +MLINKS+=mlock.2 munlock.2 +MLINKS+=mlockall.2 munlockall.2 +MLINKS+=modnext.2 modfnext.2 +MLINKS+=mount.2 nmount.2 \ + mount.2 unmount.2 +MLINKS+=mq_receive.2 mq_timedreceive.2 +MLINKS+=mq_send.2 mq_timedsend.2 +MLINKS+=ntp_adjtime.2 ntp_gettime.2 +MLINKS+=numa_getaffinity.2 numa_setaffinity.2 +MLINKS+=open.2 openat.2 +MLINKS+=pathconf.2 fpathconf.2 +MLINKS+=pathconf.2 lpathconf.2 +MLINKS+=pdfork.2 pdgetpid.2\ + pdfork.2 pdkill.2 \ + pdfork.2 pdwait4.2 +MLINKS+=pipe.2 pipe2.2 +MLINKS+=poll.2 ppoll.2 +MLINKS+=rctl_add_rule.2 rctl_get_limits.2 \ + rctl_add_rule.2 rctl_get_racct.2 \ + rctl_add_rule.2 rctl_get_rules.2 \ + rctl_add_rule.2 rctl_remove_rule.2 +MLINKS+=read.2 pread.2 \ + read.2 preadv.2 \ + read.2 readv.2 +MLINKS+=readlink.2 readlinkat.2 +MLINKS+=recv.2 recvfrom.2 \ + recv.2 recvmsg.2 +MLINKS+=rename.2 renameat.2 +MLINKS+=rtprio.2 rtprio_thread.2 +.if !defined(NO_P1003_1B) +MLINKS+=sched_get_priority_max.2 sched_get_priority_min.2 \ + sched_get_priority_max.2 sched_rr_get_interval.2 +MLINKS+=sched_setparam.2 sched_getparam.2 +MLINKS+=sched_setscheduler.2 sched_getscheduler.2 +.endif +MLINKS+=select.2 FD_CLR.3 \ + select.2 FD_ISSET.3 \ + select.2 FD_SET.3 \ + select.2 FD_ZERO.3 +MLINKS+=send.2 sendmsg.2 \ + send.2 sendto.2 +MLINKS+=setpgid.2 setpgrp.2 +MLINKS+=setresuid.2 getresgid.2 \ + setresuid.2 getresuid.2 \ + setresuid.2 setresgid.2 +MLINKS+=setuid.2 setegid.2 \ + setuid.2 seteuid.2 \ + setuid.2 setgid.2 +MLINKS+=shmat.2 shmdt.2 +MLINKS+=shm_open.2 shm_unlink.2 +MLINKS+=sigwaitinfo.2 sigtimedwait.2 +MLINKS+=stat.2 fstat.2 \ + stat.2 fstatat.2 \ + stat.2 lstat.2 +MLINKS+=statfs.2 fstatfs.2 +MLINKS+=swapon.2 swapoff.2 +MLINKS+=symlink.2 symlinkat.2 +MLINKS+=syscall.2 __syscall.2 +MLINKS+=timer_settime.2 timer_getoverrun.2 \ + timer_settime.2 timer_gettime.2 +MLINKS+=thr_kill.2 thr_kill2.2 +MLINKS+=truncate.2 ftruncate.2 +MLINKS+=unlink.2 unlinkat.2 +MLINKS+=utimensat.2 futimens.2 +MLINKS+=utimes.2 futimes.2 \ + utimes.2 futimesat.2 \ + utimes.2 lutimes.2 +MLINKS+=wait.2 wait3.2 \ + wait.2 wait4.2 \ + wait.2 waitpid.2 \ + wait.2 waitid.2 \ + wait.2 wait6.2 +MLINKS+=write.2 pwrite.2 \ + write.2 pwritev.2 \ + write.2 writev.2 diff --git a/lib/libc/sys/Symbol.map b/lib/libc/sys/Symbol.map new file mode 100644 index 000000000000..489635ec0fa4 --- /dev/null +++ b/lib/libc/sys/Symbol.map @@ -0,0 +1,1047 @@ +/* + * $FreeBSD$ + */ + +/* + * It'd be nice to automatically generate the syscall symbols, but we + * don't know to what version they will eventually belong to, so for now + * it has to be manual. + */ +FBSD_1.0 { + __acl_aclcheck_fd; + __acl_aclcheck_file; + __acl_aclcheck_link; + __acl_delete_fd; + __acl_delete_file; + __acl_delete_link; + __acl_get_fd; + __acl_get_file; + __acl_get_link; + __acl_set_fd; + __acl_set_file; + __acl_set_link; + __getcwd; + __mac_execve; + __mac_get_fd; + __mac_get_file; + __mac_get_link; + __mac_get_pid; + __mac_get_proc; + __mac_set_fd; + __mac_set_file; + __mac_set_link; + __mac_set_proc; + __setugid; + __syscall; + __sysctl; + _umtx_op; + abort2; + accept; + access; + acct; + adjtime; + aio_cancel; + aio_error; + aio_fsync; + aio_read; + aio_return; + aio_suspend; + aio_waitcomplete; + aio_write; + audit; + auditctl; + auditon; + bind; + chdir; + chflags; + chmod; + chown; + chroot; + clock_getres; + clock_gettime; + clock_settime; + close; + connect; + dup; + dup2; + eaccess; + execve; + extattr_delete_fd; + extattr_delete_file; + extattr_delete_link; + extattr_get_fd; + extattr_get_file; + extattr_get_link; + extattr_list_fd; + extattr_list_file; + extattr_list_link; + extattr_set_fd; + extattr_set_file; + extattr_set_link; + extattrctl; + fchdir; + fchflags; + fchmod; + fchown; + fcntl; + fhopen; + fhstat; + fhstatfs; + flock; + fork; + fpathconf; + fstat; + fstatfs; + fsync; + futimes; + getaudit; + getaudit_addr; + getauid; + getcontext; + getdents; + getdirentries; + getdtablesize; + getegid; + geteuid; + getfh; + getfsstat; + getgid; + getgroups; + getitimer; + getpeername; + getpgid; + getpgrp; + getpid; + getppid; + getpriority; + getresgid; + getresuid; + getrlimit; + getrusage; + getsid; + getsockname; + getsockopt; + gettimeofday; + getuid; + ioctl; + issetugid; + jail; + jail_attach; + kenv; + kevent; + kill; + kldfind; + kldfirstmod; + kldload; + kldnext; + kldstat; + kldsym; + kldunload; + kldunloadf; + kqueue; + kmq_notify; /* Do we want these to be public interfaces? */ + kmq_open; /* librt uses them to provide mq_xxx. */ + kmq_setattr; + kmq_timedreceive; + kmq_timedsend; + kmq_unlink; + ksem_close; + ksem_destroy; + ksem_getvalue; + ksem_init; + ksem_open; + ksem_post; + ksem_timedwait; + ksem_trywait; + ksem_unlink; + ksem_wait; + ktrace; + lchflags; + lchmod; + lchown; + lgetfh; + link; + lio_listio; + listen; + lstat; + lutimes; + mac_syscall; + madvise; + mincore; + minherit; + mkdir; + mkfifo; + mknod; + mlock; + mlockall; + modfind; + modfnext; + modnext; + modstat; + mount; + mprotect; + msgget; + msgrcv; + msgsnd; + msgsys; + msync; + munlock; + munlockall; + munmap; + nanosleep; + netbsd_lchown; + netbsd_msync; + nfssvc; + nfstat; + nlstat; + nmount; + nstat; + ntp_adjtime; + ntp_gettime; + open; + pathconf; + pipe; + poll; + posix_openpt; + preadv; + profil; + pselect; + ptrace; + pwritev; + quotactl; + read; + readlink; + readv; + reboot; + recvfrom; + recvmsg; + rename; + revoke; + rfork; + rmdir; + rtprio; + rtprio_thread; + sched_get_priority_max; + sched_get_priority_min; + sched_getparam; + sched_getscheduler; + sched_rr_get_interval; + sched_setparam; + sched_setscheduler; + sched_yield; + select; + semget; + semop; + semsys; + sendfile; + sendmsg; + sendto; + setaudit; + setaudit_addr; + setauid; + setegid; + seteuid; + setgid; + setgroups; + setitimer; + setlogin; + setpgid; + setpriority; + setregid; + setresgid; + setresuid; + setreuid; + setrlimit; + setsid; + setsockopt; + settimeofday; + setuid; + shm_open; + shm_unlink; + shmat; + shmdt; + shmget; + shmsys; + shutdown; + sigaction; + sigaltstack; + sigpending; + sigprocmask; + sigqueue; + sigreturn; + sigsuspend; + sigtimedwait; + sigwait; + sigwaitinfo; + socket; + socketpair; + stat; + statfs; + swapoff; + swapon; + symlink; + sync; + sysarch; + syscall; + thr_create; + thr_exit; + thr_kill; + thr_kill2; + thr_new; + thr_self; + thr_set_name; + thr_suspend; + thr_wake; + ktimer_create; /* Do we want these to be public interfaces? */ + ktimer_delete; /* librt uses them to provide timer_xxx. */ + ktimer_getoverrun; + ktimer_gettime; + ktimer_settime; + umask; + undelete; + unlink; + unmount; + utimes; + utrace; + uuidgen; + vadvise; + wait4; + write; + writev; + + __error; + ftruncate; + lseek; + mmap; + pread; + pwrite; + truncate; +}; + +FBSD_1.1 { + __semctl; + closefrom; + cpuset; + cpuset_getid; + cpuset_setid; + cpuset_getaffinity; + cpuset_setaffinity; + faccessat; + fchmodat; + fchownat; + fexecve; + fstatat; + futimesat; + jail_get; + jail_set; + jail_remove; + linkat; + lpathconf; + mkdirat; + mkfifoat; + mknodat; + msgctl; + readlinkat; + renameat; + setfib; + shmctl; + symlinkat; + unlinkat; +}; + +FBSD_1.2 { + cap_enter; + cap_getmode; + getloginclass; + pdfork; + pdgetpid; + pdkill; + posix_fallocate; + rctl_get_racct; + rctl_get_rules; + rctl_get_limits; + rctl_add_rule; + rctl_remove_rule; + setloginclass; +}; + +FBSD_1.3 { + accept4; + aio_mlock; + bindat; + cap_fcntls_get; + cap_fcntls_limit; + cap_ioctls_get; + cap_ioctls_limit; + __cap_rights_get; + cap_rights_limit; + cap_sandboxed; + chflagsat; + clock_getcpuclockid2; + connectat; + ffclock_getcounter; + ffclock_getestimate; + ffclock_setestimate; + pipe2; + posix_fadvise; + procctl; + wait6; +}; + +FBSD_1.4 { + futimens; + ppoll; + utimensat; + numa_setaffinity; + numa_getaffinity; + sendmmsg; + recvmmsg; +}; + +FBSD_1.5 { + fdatasync; +}; + +FBSDprivate_1.0 { + ___acl_aclcheck_fd; + __sys___acl_aclcheck_fd; + ___acl_aclcheck_file; + __sys___acl_aclcheck_file; + ___acl_aclcheck_link; + __sys___acl_aclcheck_link; + ___acl_delete_fd; + __sys___acl_delete_fd; + ___acl_delete_file; + __sys___acl_delete_file; + ___acl_delete_link; + __sys___acl_delete_link; + ___acl_get_fd; + __sys___acl_get_fd; + ___acl_get_file; + __sys___acl_get_file; + ___acl_get_link; + __sys___acl_get_link; + ___acl_set_fd; + __sys___acl_set_fd; + ___acl_set_file; + __sys___acl_set_file; + ___acl_set_link; + __sys___acl_set_link; + ___getcwd; + __sys___getcwd; + ___mac_execve; + __sys___mac_execve; + ___mac_get_fd; + __sys___mac_get_fd; + ___mac_get_file; + __sys___mac_get_file; + ___mac_get_link; + __sys___mac_get_link; + ___mac_get_pid; + __sys___mac_get_pid; + ___mac_get_proc; + __sys___mac_get_proc; + ___mac_set_fd; + __sys___mac_set_fd; + ___mac_set_file; + __sys___mac_set_file; + ___mac_set_link; + __sys___mac_set_link; + ___mac_set_proc; + __sys___mac_set_proc; + ___semctl; + __sys___semctl; + ___setugid; + __sys___setugid; + ___syscall; + __sys___syscall; + ___sysctl; + __sys___sysctl; + __umtx_op; + __sys__umtx_op; + _abort2; + __sys_abort2; + _accept; + __sys_accept; + _accept4; + __sys_accept4; + _access; + __sys_access; + _acct; + __sys_acct; + _adjtime; + __sys_adjtime; + _aio_cancel; + __sys_aio_cancel; + _aio_error; + __sys_aio_error; + _aio_fsync; + __sys_aio_fsync; + _aio_read; + __sys_aio_read; + _aio_return; + __sys_aio_return; + _aio_suspend; + __sys_aio_suspend; + _aio_waitcomplete; + __sys_aio_waitcomplete; + _aio_write; + __sys_aio_write; + _audit; + __sys_audit; + _auditctl; + __sys_auditctl; + _auditon; + __sys_auditon; + _bind; + __sys_bind; + _chdir; + __sys_chdir; + _chflags; + __sys_chflags; + _chmod; + __sys_chmod; + _chown; + __sys_chown; + _chroot; + __sys_chroot; + _clock_getcpuclockid2; + __sys_clock_getcpuclockid2; + _clock_getres; + __sys_clock_getres; + _clock_gettime; + __sys_clock_gettime; + _clock_settime; + __sys_clock_settime; + _close; + __sys_close; + _closefrom; + __sys_closefrom; + _connect; + __sys_connect; + _cpuset; + __sys_cpuset; + _cpuset_getid; + __sys_cpuset_getid; + _cpuset_setid; + __sys_cpuset_setid; + _cpuset_getaffinity; + __sys_cpuset_getaffinity; + _cpuset_setaffinity; + __sys_cpuset_setaffinity; + _dup; + __sys_dup; + _dup2; + __sys_dup2; + _eaccess; + __sys_eaccess; + _execve; + __sys_execve; + _extattr_delete_fd; + __sys_extattr_delete_fd; + _extattr_delete_file; + __sys_extattr_delete_file; + _extattr_delete_link; + __sys_extattr_delete_link; + _extattr_get_fd; + __sys_extattr_get_fd; + _extattr_get_file; + __sys_extattr_get_file; + _extattr_get_link; + __sys_extattr_get_link; + _extattr_list_fd; + __sys_extattr_list_fd; + _extattr_list_file; + __sys_extattr_list_file; + _extattr_list_link; + __sys_extattr_list_link; + _extattr_set_fd; + __sys_extattr_set_fd; + _extattr_set_file; + __sys_extattr_set_file; + _extattr_set_link; + __sys_extattr_set_link; + _extattrctl; + __sys_extattrctl; + _fchdir; + __sys_fchdir; + _fchflags; + __sys_fchflags; + _fchmod; + __sys_fchmod; + _fchown; + __sys_fchown; + _fcntl; + __sys_fcntl; + __fcntl_compat; + _fhopen; + __sys_fhopen; + _fhstat; + __sys_fhstat; + _fhstatfs; + __sys_fhstatfs; + _flock; + __sys_flock; + _fork; + __sys_fork; + _fpathconf; + __sys_fpathconf; + _fstat; + __sys_fstat; + _fstatfs; + __sys_fstatfs; + _fsync; + __sys_fsync; + _fdatasync; + __sys_fdatasync; + _futimes; + __sys_futimes; + _getaudit; + __sys_getaudit; + _getaudit_addr; + __sys_getaudit_addr; + _getauid; + __sys_getauid; + _getcontext; + __sys_getcontext; + _getdents; + __sys_getdents; + _getdirentries; + __sys_getdirentries; + _getdtablesize; + __sys_getdtablesize; + _getegid; + __sys_getegid; + _geteuid; + __sys_geteuid; + _getfh; + __sys_getfh; + _getfsstat; + __sys_getfsstat; + _getgid; + __sys_getgid; + _getgroups; + __sys_getgroups; + _getitimer; + __sys_getitimer; + _getpeername; + __sys_getpeername; + _getpgid; + __sys_getpgid; + _getpgrp; + __sys_getpgrp; + _getpid; + __sys_getpid; + _getppid; + __sys_getppid; + _getpriority; + __sys_getpriority; + _getresgid; + __sys_getresgid; + _getresuid; + __sys_getresuid; + _getrlimit; + __sys_getrlimit; + _getrusage; + __sys_getrusage; + _getsid; + __sys_getsid; + _getsockname; + __sys_getsockname; + _getsockopt; + __sys_getsockopt; + _gettimeofday; + __sys_gettimeofday; + _getuid; + __sys_getuid; + _ioctl; + __sys_ioctl; + _issetugid; + __sys_issetugid; + _jail; + __sys_jail; + _jail_attach; + __sys_jail_attach; + _kenv; + __sys_kenv; + _kevent; + __sys_kevent; + _kill; + __sys_kill; + _kldfind; + __sys_kldfind; + _kldfirstmod; + __sys_kldfirstmod; + _kldload; + __sys_kldload; + _kldnext; + __sys_kldnext; + _kldstat; + __sys_kldstat; + _kldsym; + __sys_kldsym; + _kldunload; + __sys_kldunload; + _kldunloadf; + __sys_kldunloadf; + _kmq_notify; + __sys_kmq_notify; + _kmq_open; + __sys_kmq_open; + _kmq_setattr; + __sys_kmq_setattr; + _kmq_timedreceive; + __sys_kmq_timedreceive; + _kmq_timedsend; + __sys_kmq_timedsend; + _kmq_unlink; + __sys_kmq_unlink; + _kqueue; + __sys_kqueue; + _ksem_close; + __sys_ksem_close; + _ksem_destroy; + __sys_ksem_destroy; + _ksem_getvalue; + __sys_ksem_getvalue; + _ksem_init; + __sys_ksem_init; + _ksem_open; + __sys_ksem_open; + _ksem_post; + __sys_ksem_post; + _ksem_timedwait; + __sys_ksem_timedwait; + _ksem_trywait; + __sys_ksem_trywait; + _ksem_unlink; + __sys_ksem_unlink; + _ksem_wait; + __sys_ksem_wait; + _ktrace; + __sys_ktrace; + _lchflags; + __sys_lchflags; + _lchmod; + __sys_lchmod; + _lchown; + __sys_lchown; + _lgetfh; + __sys_lgetfh; + _link; + __sys_link; + _lio_listio; + __sys_lio_listio; + _listen; + __sys_listen; + _lstat; + __sys_lstat; + _lutimes; + __sys_lutimes; + _mac_syscall; + __sys_mac_syscall; + _madvise; + __sys_madvise; + _mincore; + __sys_mincore; + _minherit; + __sys_minherit; + _mkdir; + __sys_mkdir; + _mkfifo; + __sys_mkfifo; + _mknod; + __sys_mknod; + _mlock; + __sys_mlock; + _mlockall; + __sys_mlockall; + _modfind; + __sys_modfind; + _modfnext; + __sys_modfnext; + _modnext; + __sys_modnext; + _modstat; + __sys_modstat; + _mount; + __sys_mount; + _mprotect; + __sys_mprotect; + _msgctl; + __sys_msgctl; + _msgget; + __sys_msgget; + _msgrcv; + __sys_msgrcv; + _msgsnd; + __sys_msgsnd; + _msgsys; + __sys_msgsys; + _msync; + __sys_msync; + _munlock; + __sys_munlock; + _munlockall; + __sys_munlockall; + _munmap; + __sys_munmap; + _nanosleep; + __sys_nanosleep; + _netbsd_lchown; + __sys_netbsd_lchown; + _netbsd_msync; + __sys_netbsd_msync; + _nfssvc; + __sys_nfssvc; + _nfstat; + __sys_nfstat; + _nlstat; + __sys_nlstat; + _nmount; + __sys_nmount; + _nstat; + __sys_nstat; + _ntp_adjtime; + __sys_ntp_adjtime; + _ntp_gettime; + __sys_ntp_gettime; + _open; + __sys_open; + _openat; + __sys_openat; + _pathconf; + __sys_pathconf; + _pipe; + __sys_pipe; + _poll; + __sys_poll; + _ppoll; + __sys_ppoll; + _preadv; + __sys_preadv; + _procctl; + __sys_procctl; + _profil; + __sys_profil; + _pselect; + __sys_pselect; + _ptrace; + __sys_ptrace; + _pwritev; + __sys_pwritev; + _quotactl; + __sys_quotactl; + _read; + __sys_read; + _readlink; + __sys_readlink; + _readv; + __sys_readv; + _reboot; + __sys_reboot; + _recvfrom; + __sys_recvfrom; + _recvmsg; + __sys_recvmsg; + _rename; + __sys_rename; + _revoke; + __sys_revoke; + _rfork; + __sys_rfork; + _rmdir; + __sys_rmdir; + _rtprio; + __sys_rtprio; + _rtprio_thread; + __sys_rtprio_thread; + _sched_get_priority_max; + __sys_sched_get_priority_max; + _sched_get_priority_min; + __sys_sched_get_priority_min; + _sched_getparam; + __sys_sched_getparam; + _sched_getscheduler; + __sys_sched_getscheduler; + _sched_rr_get_interval; + __sys_sched_rr_get_interval; + _sched_setparam; + __sys_sched_setparam; + _sched_setscheduler; + __sys_sched_setscheduler; + _sched_yield; + __sys_sched_yield; + _select; + __sys_select; + _semget; + __sys_semget; + _semop; + __sys_semop; + _semsys; + __sys_semsys; + _sendfile; + __sys_sendfile; + _sendmsg; + __sys_sendmsg; + _sendto; + __sys_sendto; + _setaudit; + __sys_setaudit; + _setaudit_addr; + __sys_setaudit_addr; + _setauid; + __sys_setauid; + _setcontext; + __sys_setcontext; + _setegid; + __sys_setegid; + _seteuid; + __sys_seteuid; + _setgid; + __sys_setgid; + _setgroups; + __sys_setgroups; + _setitimer; + __sys_setitimer; + _setlogin; + __sys_setlogin; + _setpgid; + __sys_setpgid; + _setpriority; + __sys_setpriority; + _setregid; + __sys_setregid; + _setresgid; + __sys_setresgid; + _setresuid; + __sys_setresuid; + _setreuid; + __sys_setreuid; + _setrlimit; + __sys_setrlimit; + _setsid; + __sys_setsid; + _setsockopt; + __sys_setsockopt; + _settimeofday; + __sys_settimeofday; + _setuid; + __sys_setuid; + _shm_open; + __sys_shm_open; + _shm_unlink; + __sys_shm_unlink; + _shmat; + __sys_shmat; + _shmctl; + __sys_shmctl; + _shmdt; + __sys_shmdt; + _shmget; + __sys_shmget; + _shmsys; + __sys_shmsys; + _shutdown; + __sys_shutdown; + _sigaction; + __sys_sigaction; + _sigaltstack; + __sys_sigaltstack; + _sigpending; + __sys_sigpending; + _sigprocmask; + __sys_sigprocmask; + _sigqueue; + __sys_sigqueue; + _sigreturn; + __sys_sigreturn; + _sigsuspend; + __sys_sigsuspend; + _sigtimedwait; + __sys_sigtimedwait; + _sigwait; + __sigwait; + __sys_sigwait; + _sigwaitinfo; + __sys_sigwaitinfo; + _socket; + __sys_socket; + _socketpair; + __sys_socketpair; + _stat; + __sys_stat; + _statfs; + __sys_statfs; + _swapcontext; + __sys_swapcontext; + _swapoff; + __sys_swapoff; + _swapon; + __sys_swapon; + _symlink; + __sys_symlink; + _sync; + __sys_sync; + _sysarch; + __sys_sysarch; + _syscall; + __sys_syscall; + _thr_create; + __sys_thr_create; + _thr_exit; + __sys_thr_exit; + _thr_kill; + __sys_thr_kill; + _thr_kill2; + __sys_thr_kill2; + _thr_new; + __sys_thr_new; + _thr_self; + __sys_thr_self; + _thr_set_name; + __sys_thr_set_name; + _thr_suspend; + __sys_thr_suspend; + _thr_wake; + __sys_thr_wake; + _ktimer_create; + __sys_ktimer_create; + _ktimer_delete; + __sys_ktimer_delete; + _ktimer_getoverrun; + __sys_ktimer_getoverrun; + _ktimer_gettime; + __sys_ktimer_gettime; + _ktimer_settime; + __sys_ktimer_settime; + _umask; + __sys_umask; + _undelete; + __sys_undelete; + _unlink; + __sys_unlink; + _unmount; + __sys_unmount; + _utimes; + __sys_utimes; + _utrace; + __sys_utrace; + _uuidgen; + __sys_uuidgen; + _vadvise; + __sys_vadvise; + _wait4; + __sys_wait4; + _wait6; + __sys_wait6; + _write; + __sys_write; + _writev; + __sys_writev; + __set_error_selector; + nlm_syscall; + gssd_syscall; + __libc_interposing_slot; + __libc_sigwait; +}; diff --git a/lib/libc/sys/__error.c b/lib/libc/sys/__error.c new file mode 100644 index 000000000000..8a065bf72002 --- /dev/null +++ b/lib/libc/sys/__error.c @@ -0,0 +1,58 @@ +/* + * Copyright (c) 1997 John Birrell <jb@cimlogic.com.au>. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * 3. Neither the name of the author nor the names of any co-contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include "libc_private.h" + +extern int errno; + +static int * +__error_unthreaded(void) +{ + + return (&errno); +} + +static int *(*__error_selector)(void) = __error_unthreaded; + +void +__set_error_selector(int *(*arg)(void)) +{ + + __error_selector = arg; +} + +int * +__error(void) +{ + + return (__error_selector()); +} diff --git a/lib/libc/sys/__vdso_gettimeofday.c b/lib/libc/sys/__vdso_gettimeofday.c new file mode 100644 index 000000000000..0368b9787efc --- /dev/null +++ b/lib/libc/sys/__vdso_gettimeofday.c @@ -0,0 +1,156 @@ +/*- + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/elf.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include <time.h> +#include <machine/atomic.h> +#include "libc_private.h" + +static int +tc_delta(const struct vdso_timehands *th, u_int *delta) +{ + int error; + u_int tc; + + error = __vdso_gettc(th, &tc); + if (error == 0) + *delta = (tc - th->th_offset_count) & th->th_counter_mask; + return (error); +} + +/* + * Calculate the absolute or boot-relative time from the + * machine-specific fast timecounter and the published timehands + * structure read from the shared page. + * + * The lockless reading scheme is similar to the one used to read the + * in-kernel timehands, see sys/kern/kern_tc.c:binuptime(). This code + * is based on the kernel implementation. + */ +static int +binuptime(struct bintime *bt, struct vdso_timekeep *tk, int abs) +{ + struct vdso_timehands *th; + uint32_t curr, gen; + u_int delta; + int error; + + do { + if (!tk->tk_enabled) + return (ENOSYS); + + curr = atomic_load_acq_32(&tk->tk_current); + th = &tk->tk_th[curr]; + gen = atomic_load_acq_32(&th->th_gen); + *bt = th->th_offset; + error = tc_delta(th, &delta); + if (error == EAGAIN) + continue; + if (error != 0) + return (error); + bintime_addx(bt, th->th_scale * delta); + if (abs) + bintime_add(bt, &th->th_boottime); + + /* + * Ensure that the load of th_offset is completed + * before the load of th_gen. + */ + atomic_thread_fence_acq(); + } while (curr != tk->tk_current || gen == 0 || gen != th->th_gen); + return (0); +} + +static struct vdso_timekeep *tk; + +#pragma weak __vdso_gettimeofday +int +__vdso_gettimeofday(struct timeval *tv, struct timezone *tz) +{ + struct bintime bt; + int error; + + if (tz != NULL) + return (ENOSYS); + if (tk == NULL) { + error = __vdso_gettimekeep(&tk); + if (error != 0 || tk == NULL) + return (ENOSYS); + } + if (tk->tk_ver != VDSO_TK_VER_CURR) + return (ENOSYS); + error = binuptime(&bt, tk, 1); + if (error != 0) + return (error); + bintime2timeval(&bt, tv); + return (0); +} + +#pragma weak __vdso_clock_gettime +int +__vdso_clock_gettime(clockid_t clock_id, struct timespec *ts) +{ + struct bintime bt; + int abs, error; + + if (tk == NULL) { + error = _elf_aux_info(AT_TIMEKEEP, &tk, sizeof(tk)); + if (error != 0 || tk == NULL) + return (ENOSYS); + } + if (tk->tk_ver != VDSO_TK_VER_CURR) + return (ENOSYS); + switch (clock_id) { + case CLOCK_REALTIME: + case CLOCK_REALTIME_PRECISE: + case CLOCK_REALTIME_FAST: + case CLOCK_SECOND: + abs = 1; + break; + case CLOCK_MONOTONIC: + case CLOCK_MONOTONIC_PRECISE: + case CLOCK_MONOTONIC_FAST: + case CLOCK_UPTIME: + case CLOCK_UPTIME_PRECISE: + case CLOCK_UPTIME_FAST: + abs = 0; + break; + default: + return (ENOSYS); + } + error = binuptime(&bt, tk, abs); + if (error != 0) + return (error); + bintime2timespec(&bt, ts); + if (clock_id == CLOCK_SECOND) + ts->tv_nsec = 0; + return (0); +} diff --git a/lib/libc/sys/_exit.2 b/lib/libc/sys/_exit.2 new file mode 100644 index 000000000000..120ef1c9e4ef --- /dev/null +++ b/lib/libc/sys/_exit.2 @@ -0,0 +1,125 @@ +.\" Copyright (c) 1980, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)_exit.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd September 8, 2016 +.Dt EXIT 2 +.Os +.Sh NAME +.Nm _exit +.Nd terminate the calling process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn _exit "int status" +.Sh DESCRIPTION +The +.Fn _exit +system call +terminates a process with the following consequences: +.Bl -bullet +.It +All of the descriptors open in the calling process are closed. +This may entail delays, for example, waiting for output to drain; +a process in this state may not be killed, as it is already dying. +.It +If the parent process of the calling process has an outstanding +.Xr wait 2 +call +or catches the +.Dv SIGCHLD +signal, +it is notified of the calling process's termination and +the +.Fa status +is set as defined by +.Xr wait 2 . +.It +The parent process-ID of all of the calling process's existing child +processes are set to the process-ID of the calling process's reaper; +the reaper (normally the initialization process) +inherits each of these processes +(see +.Xr procctl 2 , +.Xr init 8 +and the +.Sx DEFINITIONS +section of +.Xr intro 2 ) . +.It +If the termination of the process causes any process group +to become orphaned (usually because the parents of all members +of the group have now exited; see +.Dq orphaned process group +in +.Xr intro 2 ) , +and if any member of the orphaned group is stopped, +the +.Dv SIGHUP +signal and the +.Dv SIGCONT +signal are sent to all members of the newly-orphaned process group. +.It +If the process is a controlling process (see +.Xr intro 2 ) , +the +.Dv SIGHUP +signal is sent to the foreground process group of the controlling terminal, +and all current access to the controlling terminal is revoked. +.El +.Pp +Most C programs call the library routine +.Xr exit 3 , +which flushes buffers, closes streams, unlinks temporary files, etc., +before +calling +.Fn _exit . +.Sh RETURN VALUES +The +.Fn _exit +system call +can never return. +.Sh SEE ALSO +.Xr fork 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr exit 3 , +.Xr init 8 +.Sh STANDARDS +The +.Fn _exit +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn _exit +function appeared in +.At v7 . diff --git a/lib/libc/sys/_umtx_op.2 b/lib/libc/sys/_umtx_op.2 new file mode 100644 index 000000000000..63509991ad24 --- /dev/null +++ b/lib/libc/sys/_umtx_op.2 @@ -0,0 +1,1427 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 29, 2016 +.Dt _UMTX_OP 2 +.Os +.Sh NAME +.Nm _umtx_op +.Nd interface for implementation of userspace threading synchronization primitives +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/umtx.h +.Ft int +.Fn _umtx_op "void *obj" "int op" "u_long val" "void *uaddr" "void *uaddr2" +.Sh DESCRIPTION +The +.Fn _umtx_op +system call provides kernel support for userspace implementation of +the threading synchronization primitives. +The +.Lb libthr +uses the syscall to implement +.St -p1003.1-2001 +pthread locks, like mutexes, condition variables and so on. +.Ss STRUCTURES +The operations, performed by the +.Fn _umtx_op +syscall, operate on userspace objects which are described +by the following structures. +Reserved fields and paddings are omitted. +All objects require ABI-mandated alignment, but this is not currently +enforced consistently on all architectures. +.Pp +The following flags are defined for flag fields of all structures: +.Bl -tag -width "Dv USYNC_PROCESS_SHARED" +.It Dv USYNC_PROCESS_SHARED +Allow selection of the process-shared sleep queue for the thread sleep +container, when the lock ownership cannot be granted immediately, +and the operation must sleep. +The process-shared or process-private sleep queue is selected based on +the attributes of the memory mapping which contains the first byte of +the structure, see +.Xr mmap 2 . +Otherwise, if the flag is not specified, the process-private sleep queue +is selected regardless of the memory mapping attributes, as an optimization. +.Pp +See the +.Sx SLEEP QUEUES +subsection below for more details on sleep queues. +.El +.Pp +.Bl -hang -offset indent +.It Sy Mutex +.Bd -literal +struct umutex { + volatile lwpid_t m_owner; + uint32_t m_flags; + uint32_t m_ceilings[2]; + uintptr_t m_rb_lnk; +}; +.Ed +.Pp +The +.Dv m_owner +field is the actual lock. +It contains either the thread identifier of the lock owner in the +locked state, or zero when the lock is unowned. +The highest bit set indicates that there is contention on the lock. +The constants are defined for special values: +.Bl -tag -width "Dv UMUTEX_RB_OWNERDEAD" +.It Dv UMUTEX_UNOWNED +Zero, the value stored in the unowned lock. +.It Dv UMUTEX_CONTESTED +The contenion indicator. +.It Dv UMUTEX_RB_OWNERDEAD +A thread owning the robust mutex terminated. +The mutex is in unlocked state. +.It Dv UMUTEX_RB_NOTRECOV +The robust mutex is in a non-recoverable state. +It cannot be locked until reinitialized. +.El +.Pp +The +.Dv m_flags +field may contain the following umutex-specific flags, in addition to +the common flags: +.Bl -tag -width "Dv UMUTEX_NONCONSISTENT" +.It Dv UMUTEX_PRIO_INHERIT +Mutex implements +.Em Priority Inheritance +protocol. +.It Dv UMUTEX_PRIO_PROTECT +Mutex implements +.Em Priority Protection +protocol. +.It Dv UMUTEX_ROBUST +Mutex is robust, as described in the +.Sx ROBUST UMUTEXES +section below. +.It Dv UMUTEX_NONCONSISTENT +Robust mutex is in a transient non-consistent state. +Not used by kernel. +.El +.Pp +In the manual page, mutexes not having +.Dv UMUTEX_PRIO_INHERIT +and +.Dv UMUTEX_PRIO_PROTECT +flags set, are called normal mutexes. +Each type of mutex, i.e. normal mutexes, priority-inherited mutexes, +and priority-protected mutexes, have a separate sleep queue associated +with the given key. +.Pp +For priority protected mutexes, the +.Dv m_ceilings +array contains priority ceiling values. +The +.Dv m_ceilings[0] +is the ceiling value for the mutex, as specified by +.St -p1003.1-2008 +for the +.Em Priority Protected +mutex protocol. +The +.Dv m_ceilings[1] +is used only for the unlock of a priority protected mutex, when +unlock is done in an order other than the reversed lock order. +In this case, +.Dv m_ceilings[1] +must contain the ceiling value for the last locked priority protected +mutex, for proper priority reassignment. +If, instead, the unlocking mutex was the last priority propagated +mutex locked by the thread, +.Dv m_ceilings[1] +should contain \-1. +This is required because kernel does not maintain the ordered lock list. +.It Sy Condition variable +.Bd -literal +struct ucond { + volatile uint32_t c_has_waiters; + uint32_t c_flags; + uint32_t c_clockid; +}; +.Ed +.Pp +A non-zero +.Dv c_has_waiters +value indicates that there are in-kernel waiters for the condition, +executing the +.Dv UMTX_OP_CV_WAIT +request. +.Pp +The +.Dv c_flags +field contains flags. +Only the common flags, i.e. +.Dv USYNC_PROCESS_SHARED , +are defined for ucond. +.Pp +The +.Dv c_clockid +member provides the clock identifier to use for timeout, when the +.Dv UMTX_OP_CV_WAIT +request has both the +.Dv CVWAIT_CLOCKID +flag and the timeout specified. +Valid clock identifiers are subset of the valid clock ids for the +.Xr clock_gettime 2 +syscall, namely, +.Dv CLOCK_REALTIME , +.Dv CLOCK_VIRTUAL , +.Dv CLOCK_PROF , +.Dv CLOCK_MONOTONIC , +.Dv CLOCK_UPTIME , +.Dv CLOCK_UPTIME_PRECISE , +.Dv CLOCK_UPTIME_FAST , +.Dv CLOCK_REALTIME_PRECISE , +.Dv CLOCK_REALTIME_FAST , +.Dv CLOCK_MONOTONIC_PRECISE , +.Dv CLOCK_MONOTONIC_FAST , +and +.Dv CLOCK_SECOND +are allowed. +.It Sy Reader/writer lock +.Bd -literal +struct urwlock { + volatile int32_t rw_state; + uint32_t rw_flags; + uint32_t rw_blocked_readers; + uint32_t rw_blocked_writers; +}; +.Ed +.Pp +The +.Dv rw_state +field is the actual lock. +It contains both the flags and counter of the read locks which were +granted. +Names of the +.Dv rw_state +bits are following: +.Bl -tag -width "Dv URWLOCK_WRITE_WAITERS" +.It Dv URWLOCK_WRITE_OWNER +Write lock was granted. +.It Dv URWLOCK_WRITE_WAITERS +There are write lock waiters. +.It Dv URWLOCK_READ_WAITERS +There are read lock waiters. +.It Dv URWLOCK_READER_COUNT(c) +Returns the count of currently granted read locks. +.El +.Pp +At any given time there may be only one thread to which the writer lock +is granted on the +.Vt struct rwlock , +and no threads are granted read lock. +Or, at the given time, up to +.Dv URWLOCK_MAX_READERS +threads may be granted the read lock simultaneously, but write lock is +not granted to any thread. +.Pp +The following flags for the +.Dv rw_flags +member of +.Vt struct urwlock +are defined, in addition to the common flags: +.Bl -tag -width "Dv URWLOCK_PREFER_READER" +.It Dv URWLOCK_PREFER_READER +If specified, immediately grant read lock requests when +.Dv urwlock +is already read-locked, even in presence of unsatisfied write +lock requests. +By default, if there is a write lock waiter, further read requests are +not granted, to prevent unfair write lock waiter starvation. +.El +.Pp +The +.Dv rw_blocked_readers +and +.Dv rw_blocked_writers +members contain the count of threads which are sleeping in kernel, +waiting for the associated request type to be granted. +The fields are used by kernel to update the +.Dv URWLOCK_READ_WAITERS +and +.Dv URWLOCK_WRITE_WAITERS +flags of the +.Dv rw_state +lock after requesting thread was woken up. +.It Sy Semaphore +.Bd -literal +struct _usem2 { + volatile uint32_t _count; + uint32_t _flags; +}; +.Ed +.Pp +The +.Dv _count +word represents a counting semaphore. +A non-zero value indicates an unlocked (posted) semaphore, while zero +represents the locked state. +The maximal supported semaphore count is +.Dv USEM_MAX_COUNT . +.Pp +The +.Dv _count +word, besides the counter of posts (unlocks), also contains the +.Dv USEM_HAS_WAITERS +bit, which indicates that locked semaphore has waiting threads. +.Pp +The +.Dv USEM_COUNT() +macro, applied to the +.Dv _count +word, returns the current semaphore counter, i.e. the number of posts +issued on the semaphore. +.Pp +The following bits for the +.Dv _flags +member of +.Vt struct _usem2 +are defined, in addition to the common flags: +.Bl -tag -width "Dv USEM_NAMED" +.It Dv USEM_NAMED +Flag is ignored by kernel. +.El +.It Sy Timeout parameter +.Bd -literal +struct _umtx_time { + struct timespec _timeout; + uint32_t _flags; + uint32_t _clockid; +}; +.Ed +.Pp +Several +.Fn _umtx_op +operations allow the blocking time to be limited, failing the request +if it cannot be satisfied in the specified time period. +The timeout is specified by passing either the address of +.Vt struct timespec , +or its extended variant, +.Vt struct _umtx_time , +as the +.Fa uaddr2 +argument of +.Fn _umtx_op . +They are distinguished by the +.Fa uaddr +value, which must be equal to the size of the structure pointed to by +.Fa uaddr2 , +casted to +.Vt uintptr_t . +.Pp +The +.Dv _timeout +member specifies the time when the timeout should occur. +Legal values for clock identifier +.Dv _clockid +are shared with the +.Fa clock_id +argument to the +.Xr clock_gettime 2 +function, +and use the same underlying clocks. +The specified clock is used to obtain the current time value. +Interval counting is always performed by the monotonic wall clock. +.Pp +The +.Dv _flags +argument allows the following flags to further define the timeout behaviour: +.Bl -tag -width "It Dv UMTX_ABSTIME" +.It Dv UMTX_ABSTIME +The +.Dv _timeout +value is the absolute time. +The thread will be unblocked and the request failed when specified +clock value is equal or exceeds the +.Dv _timeout. +.Pp +If the flag is absent, the timeout value is relative, that is the amount +of time, measured by the monotonic wall clock from the moment of the request +start. +.El +.El +.Ss SLEEP QUEUES +.Pp +When a locking request cannot be immediately satisfied, the thread is +typically put to +.Em sleep , +which is a non-runnable state terminated by the +.Em wake +operation. +Lock operations include a +.Em try +variant which returns an error rather than sleeping if the lock cannot +be obtained. +Also, +.Fn _umtx_op +provides requests which explicitly put the thread to sleep. +.Pp +Wakes need to know which threads to make runnable, so sleeping threads +are grouped into containers called +.Em sleep queues . +A sleep queue is identified by a key, which for +.Fn _umtx_op +is defined as the physical address of some variable. +Note that the +.Em physical +address is used, which means that same variable mapped multiple +times will give one key value. +This mechanism enables the construction of +.Em process-shared +locks. +.Pp +A related attribute of the key is shareability. +Some requests always interpret keys as private for the current process, +creating sleep queues with the scope of the current process even if +the memory is shared. +Others either select the shareability automatically from the +mapping attributes, or take additional input as the +.Dv USYNC_PROCESS_SHARED +common flag. +This is done as optimization, allowing the lock scope to be limited +regardless of the kind of backing memory. +.Pp +Only the address of the start byte of the variable specified as key is +important for determining corresponding sleep queue. +The size of the variable does not matter, so e.g. sleep on the same +address interpeted as +.Vt uint32_t +and +.Vt long +on a little-endian 64-bit platform would collide. +.Pp +The last attribute of the key is the object type. +The sleep queue to which a sleeping thread is assigned is an individual +one for simple wait requests, mutexes, rwlocks, condvars and other +primitives, even when the physical address of the key is same. +.Pp +When waking up a limited number of threads from a given sleep queue, +the highest priority threads that have been blocked for the longest on +the queue are selected. +.Ss ROBUST UMUTEXES +The +.Em robust umutexes +are provided as a substrate for a userspace library to implement +.Tn POSIX +robust mutexes. +A robust umutex must have the +.Dv UMUTEX_ROBUST +flag set. +.Pp +On thread termination, the kernel walks two lists of mutexes. +The two lists head addresses must be provided by a prior call to +.Dv UMTX_OP_ROBUST_LISTS +request. +The lists are singly-linked. +The link to next element is provided by the +.Dv m_rb_lnk +member of the +.Vt struct umutex . +.Pp +Robust list processing is aborted if the kernel finds a mutex +with any of the following conditions: +.Bl -dash -offset indent -compact +.It +the +.Dv UMUTEX_ROBUST +flag is not set +.It +not owned by the current thread, except when the mutex is pointed to +by the +.Dv robust_inactive +member of the +.Vt struct umtx_robust_lists_params , +registered for the current thread +.It +the combination of mutex flags is invalid +.It +read of the umutex memory faults +.It +the list length limit described in +.Xr libthr 3 +is reached. +.El +.Pp +Every mutex in both lists is unlocked as if the +.Dv UMTX_OP_MUTEX_UNLOCK +request is performed on it, but instead of the +.Dv UMUTEX_UNOWNED +value, the +.Dv m_owner +field is written with the +.Dv UMUTEX_RB_OWNERDEAD +value. +When a mutex in the +.Dv UMUTEX_RB_OWNERDEAD +state is locked by kernel due to the +.Dv UMTX_OP_MUTEX_TRYLOCK +and +.Dv UMTX_OP_MUTEX_LOCK +requests, the lock is granted and +.Er EOWNERDEAD +error is returned. +.Pp +Also, the kernel handles the +.Dv UMUTEX_RB_NOTRECOV +value of +.Dv the m_owner +field specially, always returning the +.Er ENOTRECOVERABLE +error for lock attempts, without granting the lock. +.Ss OPERATIONS +The following operations, requested by the +.Fa op +argument to the function, are implemented: +.Bl -tag -width "It Dv UMTX_OP_WAIT_UINT_PRIVATE" +.It Dv UMTX_OP_WAIT +Wait. +The arguments for the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to a variable of type +.Vt long . +.It Fa val +Current value of the +.Dv *obj . +.El +.Pp +The current value of the variable pointed to by the +.Fa obj +argument is compared with the +.Fa val . +If they are equal, the requesting thread is put to interruptible sleep +until woken up or the optionally specified timeout expires. +.Pp +The comparison and sleep are atomic. +In other words, if another thread writes a new value to +.Dv *obj +and then issues +.Dv UMTX_OP_WAKE , +the request is guaranteed to not miss the wakeup, +which might otherwise happen between comparison and blocking. +.Pp +The physical address of memory where the +.Fa *obj +variable is located, is used as a key to index sleeping threads. +.Pp +The read of the current value of the +.Dv *obj +variable is not guarded by barriers. +In particular, it is the user's duty to ensure the lock acquire +and release memory semantics, if the +.Dv UMTX_OP_WAIT +and +.Dv UMTX_OP_WAKE +requests are used as a substrate for implementing a simple lock. +.Pp +The request is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +.Pp +Optionally, a timeout for the request may be specified. +.It Dv UMTX_OP_WAKE +Wake the threads possibly sleeping due to +.Dv UMTX_OP_WAIT . +The arguments for the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to a variable, used as a key to find sleeping threads. +.It Fa val +Up to +.Fa val +threads are woken up by this request. +Specify +.Dv INT_MAX +to wake up all waiters. +.El +.It Dv UMTX_OP_MUTEX_TRYLOCK +Try to lock umutex. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +Operates same as the +.Dv UMTX_OP_MUTEX_LOCK +request, but returns +.Er EBUSY +instead of sleeping if the lock cannot be obtained immediately. +.It Dv UMTX_OP_MUTEX_LOCK +Lock umutex. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +Locking is performed by writing the current thread id into the +.Dv m_owner +word of the +.Vt struct umutex . +The write is atomic, preserves the +.Dv UMUTEX_CONTESTED +contention indicator, and provides the acquire barrier for +lock entrance semantic. +.Pp +If the lock cannot be obtained immediately because another thread owns +the lock, the current thread is put to sleep, with +.Dv UMUTEX_CONTESTED +bit set before. +Upon wake up, the lock conditions are re-tested. +.Pp +The request adheres to the priority protection or inheritance protocol +of the mutex, specified by the +.Dv UMUTEX_PRIO_PROTECT +or +.Dv UMUTEX_PRIO_INHERIT +flag, respectively. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +A request with a timeout specified is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +A request without timeout specified is always restarted after return +from a signal handler. +.It Dv UMTX_OP_MUTEX_UNLOCK +Unlock umutex. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +Unlocks the mutex, by writing +.Dv UMUTEX_UNOWNED +(zero) value into +.Dv m_owner +word of the +.Vt struct umutex . +The write is done with a release barrier, to provide lock leave semantic. +.Pp +If there are threads sleeping in the sleep queue associated with the +umutex, one thread is woken up. +If more than one thread sleeps in the sleep queue, the +.Dv UMUTEX_CONTESTED +bit is set together with the write of the +.Dv UMUTEX_UNOWNED +value into +.Dv m_owner . +.Pp +The request adheres to the priority protection or inheritance protocol +of the mutex, specified by the +.Dv UMUTEX_PRIO_PROTECT +or +.Dv UMUTEX_PRIO_INHERIT +flag, respectively. +See description of the +.Dv m_ceilings +member of the +.Vt struct umutex +structure for additional details of the request operation on the +priority protected protocol mutex. +.It Dv UMTX_OP_SET_CEILING +Set ceiling for the priority protected umutex. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the umutex. +.It Fa val +New ceiling value. +.It Fa uaddr +Address of a variable of type +.Vt uint32_t . +If not +.Dv NULL +and the update was successful, the previous ceiling value is +written to the location pointed to by +.Fa uaddr . +.El +.Pp +The request locks the umutex pointed to by the +.Fa obj +parameter, waiting for the lock if not immediately available. +After the lock is obtained, the new ceiling value +.Fa val +is written to the +.Dv m_ceilings[0] +member of the +.Vt struct umutex, +after which the umutex is unlocked. +.Pp +The locking does not adhere to the priority protect protocol, +to conform to the +.Tn POSIX +requirements for the +.Xr pthread_mutex_setprioceiling 3 +interface. +.It Dv UMTX_OP_CV_WAIT +Wait for a condition. +The arguments to the request are: +.Bl -tag -width "It Fa uaddr2" +.It Fa obj +Pointer to the +.Vt struct ucond . +.It Fa val +Request flags, see below. +.It Fa uaddr +Pointer to the umutex. +.It Fa uaddr2 +Optional pointer to a +.Vt struct timespec +for timeout specification. +.El +.Pp +The request must be issued by the thread owning the mutex pointed to +by the +.Fa uaddr +argument. +The +.Dv c_hash_waiters +member of the +.Vt struct ucond , +pointed to by the +.Fa obj +argument, is set to an arbitrary non-zero value, after which the +.Fa uaddr +mutex is unlocked (following the appropriate protocol), and +the current thread is put to sleep on the sleep queue keyed by +the +.Fa obj +argument. +The operations are performed atomically. +It is guaranteed to not miss a wakeup from +.Dv UMTX_OP_CV_SIGNAL +or +.Dv UMTX_OP_CV_BROADCAST +sent between mutex unlock and putting the current thread on the sleep queue. +.Pp +Upon wakeup, if the timeout expired and no other threads are sleeping in +the same sleep queue, the +.Dv c_hash_waiters +member is cleared. +After wakeup, the +.Fa uaddr +umutex is not relocked. +.Pp +The following flags are defined: +.Bl -tag -width "Dv CVWAIT_CLOCKID" +.It Dv CVWAIT_ABSTIME +Timeout is absolute. +.It Dv CVWAIT_CLOCKID +Clockid is provided. +.El +.Pp +Optionally, a timeout for the request may be specified. +Unlike other requests, the timeout value is specified directly by a +.Vt struct timespec , +pointed to by the +.Fa uaddr2 +argument. +If the +.Dv CVWAIT_CLOCKID +flag is provided, the timeout uses the clock from the +.Dv c_clockid +member of the +.Vt struct ucond , +pointed to by +.Fa obj +argument. +Otherwise, +.Dv CLOCK_REALTIME +is used, regardless of the clock identifier possibly specified in the +.Vt struct _umtx_time . +If the +.Dv CVWAIT_ABSTIME +flag is supplied, the timeout specifies absolute time value, otherwise +it denotes a relative time interval. +.Pp +The request is not restartable. +An unblocked signal delivered during +the wait always results in sleep interruption and +.Er EINTR +error. +.It Dv UMTX_OP_CV_SIGNAL +Wake up one condition waiter. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to +.Vt struct ucond . +.El +.Pp +The request wakes up at most one thread sleeping on the sleep queue keyed +by the +.Fa obj +argument. +If the woken up thread was the last on the sleep queue, the +.Dv c_has_waiters +member of the +.Vt struct ucond +is cleared. +.It Dv UMTX_OP_CV_BROADCAST +Wake up all condition waiters. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to +.Vt struct ucond . +.El +.Pp +The request wakes up all threads sleeping on the sleep queue keyed by the +.Fa obj +argument. +The +.Dv c_has_waiters +member of the +.Vt struct ucond +is cleared. +.It Dv UMTX_OP_WAIT_UINT +Same as +.Dv UMTX_OP_WAIT , +but the type of the variable pointed to by +.Fa obj +is +.Vt u_int , +i.e. 32-bit integer. +.It Dv UMTX_OP_RW_RDLOCK +Read-lock a +.Vt struct rwlock +lock. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the lock (of type +.Vt struct rwlock ) +to be read-locked. +.It Fa val +Additional flags to augment locking behaviour. +The valid flags in the +.Fa val +argument are: +.Bl -tag -width "It Dv URWLOCK_PREFER_READER" +.It Dv URWLOCK_PREFER_READER +.El +.El +.Pp +The request obtains the read lock on the specified +.Vt struct rwlock +by incrementing the count of readers in the +.Dv rw_state +word of the structure. +If the +.Dv URWLOCK_WRITE_OWNER +bit is set in the word +.Dv rw_state , +the lock was granted to a writer which has not yet relinquished +its ownership. +In this case the current thread is put to sleep until it makes sense to +retry. +.Pp +If the +.Dv URWLOCK_PREFER_READER +flag is set either in the +.Dv rw_flags +word of the structure, or in the +.Fa val +argument of the request, the presence of the threads trying to obtain +the write lock on the same structure does not prevent the current thread +from trying to obtain the read lock. +Otherwise, if the flag is not set, and the +.Dv URWLOCK_WRITE_WAITERS +flag is set in +.Dv rw_state , +the current thread does not attempt to obtain read-lock. +Instead it sets the +.Dv URWLOCK_READ_WAITERS +in the +.Dv rw_state +word and puts itself to sleep on corresponding sleep queue. +Upon wakeup, the locking conditions are re-evaluated. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +The request is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +.It Dv UMTX_OP_RW_WRLOCK +Write-lock a +.Vt struct rwlock +lock. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the lock (of type +.Vt struct rwlock ) +to be write-locked. +.El +.Pp +The request obtains a write lock on the specified +.Vt struct rwlock , +by setting the +.Dv URWLOCK_WRITE_OWNER +bit in the +.Dv rw_state +word of the structure. +If there is already a write lock owner, as indicated by the +.Dv URWLOCK_WRITE_OWNER +bit being set, or there are read lock owners, as indicated +by the read-lock counter, the current thread does not attempt to +obtain the write-lock. +Instead it sets the +.Dv URWLOCK_WRITE_WAITERS +in the +.Dv rw_state +word and puts itself to sleep on corresponding sleep queue. +Upon wakeup, the locking conditions are re-evaluated. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +The request is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +.It Dv UMTX_OP_RW_UNLOCK +Unlock rwlock. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the lock (of type +.Vt struct rwlock ) +to be unlocked. +.El +.Pp +The unlock type (read or write) is determined by the +current lock state. +Note that the +.Vt struct rwlock +does not save information about the identity of the thread which +acquired the lock. +.Pp +If there are pending writers after the unlock, and the +.Dv URWLOCK_PREFER_READER +flag is not set in the +.Dv rw_flags +member of the +.Fa *obj +structure, one writer is woken up, selected as described in the +.Sx SLEEP QUEUES +subsection. +If the +.Dv URWLOCK_PREFER_READER +flag is set, a pending writer is woken up only if there is +no pending readers. +.Pp +If there are no pending writers, or, in the case that the +.Dv URWLOCK_PREFER_READER +flag is set, then all pending readers are woken up by unlock. +.It Dv UMTX_OP_WAIT_UINT_PRIVATE +Same as +.Dv UMTX_OP_WAIT_UINT , +but unconditionally select the process-private sleep queue. +.It Dv UMTX_OP_WAKE_PRIVATE +Same as +.Dv UMTX_OP_WAKE , +but unconditionally select the process-private sleep queue. +.It Dv UMTX_OP_MUTEX_WAIT +Wait for mutex availability. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Address of the mutex. +.El +.Pp +Similarly to the +.Dv UMTX_OP_MUTEX_LOCK , +put the requesting thread to sleep if the mutex lock cannot be obtained +immediately. +The +.Dv UMUTEX_CONTESTED +bit is set in the +.Dv m_owner +word of the mutex to indicate that there is a waiter, before the thread +is added to the sleep queue. +Unlike the +.Dv UMTX_OP_MUTEX_LOCK +request, the lock is not obtained. +.Pp +The operation is not implemented for priority protected and +priority inherited protocol mutexes. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +.Pp +A request with a timeout specified is not restartable. +An unblocked signal delivered during the wait always results in sleep +interruption and +.Er EINTR +error. +A request without a timeout automatically restarts if the signal disposition +requested restart via the +.Dv SA_RESTART +flag in +.Vt struct sigaction +member +.Dv sa_flags . +.It Dv UMTX_OP_NWAKE_PRIVATE +Wake up a batch of sleeping threads. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the array of pointers. +.It Fa val +Number of elements in the array pointed to by +.Fa obj . +.El +.Pp +For each element in the array pointed to by +.Fa obj , +wakes up all threads waiting on the +.Em private +sleep queue with the key +being the byte addressed by the array element. +.It Dv UMTX_OP_MUTEX_WAKE +Check if a normal umutex is unlocked and wake up a waiter. +The arguments for the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the umutex. +.El +.Pp +If the +.Dv m_owner +word of the mutex pointed to by the +.Fa obj +argument indicates unowned mutex, which has its contention indicator bit +.Dv UMUTEX_CONTESTED +set, clear the bit and wake up one waiter in the sleep queue associated +with the byte addressed by the +.Fa obj , +if any. +Only normal mutexes are supported by the request. +The sleep queue is always one for a normal mutex type. +.Pp +This request is deprecated in favor of +.Dv UMTX_OP_MUTEX_WAKE2 +since mutexes using it cannot synchronize their own destruction. +That is, the +.Dv m_owner +word has already been set to +.Dv UMUTEX_UNOWNED +when this request is made, +so that another thread can lock, unlock and destroy the mutex +(if no other thread uses the mutex afterwards). +Clearing the +.Dv UMUTEX_CONTESTED +bit may then modify freed memory. +.It Dv UMTX_OP_MUTEX_WAKE2 +Check if a umutex is unlocked and wake up a waiter. +The arguments for the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the umutex. +.It Fa val +The umutex flags. +.El +.Pp +The request does not read the +.Dv m_flags +member of the +.Vt struct umutex ; +instead, the +.Fa val +argument supplies flag information, in particular, to determine the +sleep queue where the waiters are found for wake up. +.Pp +If the mutex is unowned, one waiter is woken up. +.Pp +If the mutex memory cannot be accessed, all waiters are woken up. +.Pp +If there is more than one waiter on the sleep queue, or there is only +one waiter but the mutex is owned by a thread, the +.Dv UMUTEX_CONTESTED +bit is set in the +.Dv m_owner +word of the +.Vt struct umutex . +.It Dv UMTX_OP_SEM2_WAIT +Wait until semaphore is available. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the semaphore (of type +.Vt struct _usem2 ) . +.El +Put the requesting thread onto a sleep queue if the semaphore counter +is zero. +If the thread is put to sleep, the +.Dv USEM_HAS_WAITERS +bit is set in the +.Dv _count +word to indicate waiters. +The function returns either due to +.Dv _count +indicating the semaphore is available (non-zero count due to post), +or due to a wakeup. +The return does not guarantee that the semaphore is available, +nor does it consume the semaphore lock on successful return. +.Pp +Optionally, a timeout for the request may be specified. +.Pp +A request with non-absolute timeout value is not restartable. +An unblocked signal delivered during such wait results in sleep +interruption and +.Er EINTR +error. +.It Dv UMTX_OP_SEM2_WAKE +Wake up waiters on semaphore lock. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa obj +Pointer to the semaphore (of type +.Vt struct _usem2 ) . +.El +.Pp +The request wakes up one waiter for the semaphore lock. +The function does not increment the semaphore lock count. +If the +.Dv USEM_HAS_WAITERS +bit was set in the +.Dv _count +word, and the last sleeping thread was woken up, the bit is cleared. +.It Dv UMTX_OP_SHM +Manage anonymous +.Tn POSIX +shared memory objects (see +.Xr shm_open 2 ) , +which can be attached to a byte of physical memory, mapped into the +process address space. +The objects are used to implement process-shared locks in +.Dv libthr . +.Pp +The +.Fa val +argument specifies the sub-request of the +.Dv UMTX_OP_SHM +request: +.Bl -tag -width "Dv UMTX_SHM_DESTROY" +.It Dv UMTX_SHM_CREAT +Creates the anonymous shared memory object, which can be looked up +with the specified key +.Fa uaddr. +If the object associated with the +.Fa uaddr +key already exists, it is returned instead of creating a new object. +The object's size is one page. +On success, the file descriptor referencing the object is returned. +The descriptor can be used for mapping the object using +.Xr mmap 2 , +or for other shared memory operations. +.It Dv UMTX_SHM_LOOKUP +Same as +.Dv UMTX_SHM_CREATE +request, but if there is no shared memory object associated with +the specified key +.Fa uaddr , +an error is returned, and no new object is created. +.It Dv UMTX_SHM_DESTROY +De-associate the shared object with the specified key +.Fa uaddr. +The object is destroyed after the last open file descriptor is closed +and the last mapping for it is destroyed. +.It Dv UMTX_SHM_ALIVE +Checks whether there is a live shared object associated with the +supplied key +.Fa uaddr . +Returns zero if there is, and an error otherwise. +This request is an optimization of the +.Dv UMTX_SHM_LOOKUP +request. +It is cheaper when only the liveness of the associated object is asked +for, since no file descriptor is installed in the process fd table +on success. +.El +.Pp +The +.Fa uaddr +argument specifies the virtual address, which backing physical memory +byte identity is used as a key for the anonymous shared object +creation or lookup. +.It Dv UMTX_OP_ROBUST_LISTS +Register the list heads for the current thread's robust mutex lists. +The arguments to the request are: +.Bl -tag -width "It Fa obj" +.It Fa val +Size of the structure passed in the +.Fa uaddr +argument. +.It Fa uaddr +Pointer to the structure of type +.Vt struct umtx_robust_lists_params . +.El +.Pp +The structure is defined as +.Bd -literal +struct umtx_robust_lists_params { + uintptr_t robust_list_offset; + uintptr_t robust_priv_list_offset; + uintptr_t robust_inact_offset; +}; +.Ed +.Pp +The +.Dv robust_list_offset +member contains address of the first element in the list of locked +robust shared mutexes. +The +.Dv robust_priv_list_offset +member contains address of the first element in the list of locked +robust private mutexes. +The private and shared robust locked lists are split to allow fast +termination of the shared list on fork, in the child. +.Pp +The +.Dv robust_inact_offset +contains a pointer to the mutex which might be locked in nearby future, +or might have been just unlocked. +It is typically set by the lock or unlock mutex implementation code +around the whole operation, since lists can be only changed race-free +when the thread owns the mutex. +The kernel inspects the +.Dv robust_inact_offset +in addition to walking the shared and private lists. +Also, the mutex pointed to by +.Dv robust_inact_offset +is handled more loosely at the thread termination time, +than other mutexes on the list. +That mutex is allowed to be not owned by the current thread, +in which case list processing is continued. +See +.Sx ROBUST UMUTEXES +subsection for details. +.El +.Sh RETURN VALUES +If successful, +all requests, except +.Dv UMTX_SHM_CREAT +and +.Dv UMTX_SHM_LOOKUP +sub-requests of the +.Dv UMTX_OP_SHM +request, will return zero. +The +.Dv UMTX_SHM_CREAT +and +.Dv UMTX_SHM_LOOKUP +return a shared memory file descriptor on success. +On error \-1 is returned, and the +.Va errno +variable is set to indicate the error. +.Sh ERRORS +The +.Fn _umtx_op +operations will return the following errors: +.Bl -tag -width "Bq Er ENOTRECOVERABLE" +.It Bq Er EFAULT +One of the arguments point to invalid memory. +.It Bq Er EINVAL +The clock identifier, specified for the +.Vt struct _umtx_time +timeout parameter, or in the +.Dv c_clockid +member of +.Vt struct ucond, +is invalid. +.It Bq Er EINVAL +The type of the mutex, encoded by the +.Dv m_flags +member of +.Vt struct umutex , +is invalid. +.It Bq Er EINVAL +The +.Dv m_owner +member of the +.Vt struct umutex +has changed the lock owner thread identifier during unlock. +.It Bq Er EINVAL +The +.Dv timeout.tv_sec +or +.Dv timeout.tv_nsec +member of +.Vt struct _umtx_time +is less than zero, or +.Dv timeout.tv_nsec +is greater than 1000000000. +.It Bq Er EINVAL +The +.Fa op +argument specifies invalid operation. +.It Bq Er EINVAL +The +.Fa uaddr +argument for the +.Dv UMTX_OP_SHM +request specifies invalid operation. +.It Bq Er EINVAL +The +.Dv UMTX_OP_SET_CEILING +request specifies non priority protected mutex. +.It Bq Er EINVAL +The new ceiling value for the +.Dv UMTX_OP_SET_CEILING +request, or one or more of the values read from the +.Dv m_ceilings +array during lock or unlock operations, is greater than +.Dv RTP_PRIO_MAX . +.It Bq Er EPERM +Unlock attempted on an object not owned by the current thread. +.It Bq Er EOWNERDEAD +The lock was requested on an umutex where the +.Dv m_owner +field was set to the +.Dv UMUTEX_RB_OWNERDEAD +value, indicating terminated robust mutex. +The lock was granted to the caller, so this error in fact +indicates success with additional conditions. +.It Bq Er ENOTRECOVERABLE +The lock was requested on an umutex which +.Dv m_owner +field is equal to the +.Dv UMUTEX_RB_NOTRECOV +value, indicating abandoned robust mutex after termination. +The lock was not granted to the caller. +.It Bq Er ENOTTY +The shared memory object, associated with the address passed to the +.Dv UMTX_SHM_ALIVE +sub-request of +.Dv UMTX_OP_SHM +request, was destroyed. +.It Bq Er ESRCH +For the +.Dv UMTX_SHM_LOOKUP , +.Dv UMTX_SHM_DESTROY , +and +.Dv UMTX_SHM_ALIVE +sub-requests of the +.Dv UMTX_OP_SHM +request, there is no shared memory object associated with the provided key. +.It Bq Er ENOMEM +The +.Dv UMTX_SHM_CREAT +sub-request of the +.Dv UMTX_OP_SHM +request cannot be satisfied, because allocation of the shared memory object +would exceed the +.Dv RLIMIT_UMTXP +resource limit, see +.Xr setrlimit 2 . +.It Bq Er EAGAIN +The maximum number of readers +.Dv ( URWLOCK_MAX_READERS ) +were already granted ownership of the given +.Vt struct rwlock +for read. +.It Bq Er EBUSY +A try mutex lock operation was not able to obtain the lock. +.It Bq Er ETIMEDOUT +The request specified a timeout in the +.Fa uaddr +and +.Fa uaddr2 +arguments, and timed out before obtaining the lock or being woken up. +.It Bq Er EINTR +A signal was delivered during wait, for a non-restartable operation. +Operations with timeouts are typically non-restartable, but timeouts +specified in absolute time may be restartable. +.It Bq Er ERESTART +A signal was delivered during wait, for a restartable operation. +Mutex lock requests without timeout specified are restartable. +The error is not returned to userspace code since restart +is handled by usual adjustment of the instruction counter. +.El +.Sh BUGS +A window between a unlocking robust mutex and resetting the pointer in the +.Dv robust_inact_offset +member of the registered +.Vt struct umtx_robust_lists_params +allows another thread to destroy the mutex, thus making the kernel inspect +freed or reused memory. +The +.Li libthr +implementation is only vulnerable to this race when operating on +a shared mutex. +A possible fix for the current implementation is to strengthen the checks +for shared mutexes before terminating them, in particular, verifying +that the mutex memory is mapped from a shared memory object allocated +by the +.Dv UMTX_OP_SHM +request. +This is not done because it is believed that the race is adequately +covered by other consistency checks, while adding the check would +prevent alternative implementations of +.Li libpthread . +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr mmap 2 , +.Xr shm_open 2 , +.Xr setrlimit 2 , +.Xr sigaction 2 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr signal 3 +.Sh STANDARDS +The +.Fn _umtx_op +system call is non-standard and is used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. diff --git a/lib/libc/sys/abort2.2 b/lib/libc/sys/abort2.2 new file mode 100644 index 000000000000..ca31d74267f3 --- /dev/null +++ b/lib/libc/sys/abort2.2 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2005 Wojciech A. Koszek <dunstan@FreeBSD.czest.pl> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 30, 2006 +.Dt ABORT2 2 +.Os +.Sh NAME +.Nm abort2 +.Nd "abort process with diagnostics" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdlib.h +.Ft void +.Fn abort2 "const char *why" "int nargs" "void **args" +.Sh DESCRIPTION +The +.Fn abort2 +system call causes the process to be killed and the specified diagnostic +message (with arguments) to be delivered by the kernel to the +.Xr syslogd 8 +daemon. +.Pp +The +.Fa why +argument points to a +.Dv NUL- Ns +terminated string specifying a reason of the program's termination +(maximum 128 characters long). +The +.Fa args +array contains pointers which will be logged numerically +(with the kernel's +.Ql %p +.Xr printf 9 +format). +The +.Fa nargs +argument specifies the number of pointers in +.Fa args +(maximum 16). +.Pp +The +.Fn abort2 +system call +is intended for use in situations where continuation of a process +is impossible or for other definitive reasons is unwanted, and normal +diagnostic channels cannot be trusted to deliver the message. +.Sh RETURN VALUES +The +.Fn abort2 +function +never returns. +.Pp +The process is killed with +.Dv SIGABRT +unless the arguments to +.Fn abort2 +are invalid, in which case +.Dv SIGKILL +is used. +.Sh EXAMPLES +.Bd -literal -compact +#include <stdlib.h> + +if (weight_kg > max_load) { + void *ptrs[3]; + + ptrs[0] = (void *)(intptr_t)weight_kg; + ptrs[1] = (void *)(intptr_t)max_load; + ptrs[2] = haystack; + abort2("Camel overloaded", 3, ptrs); +} +.Ed +.Sh SEE ALSO +.Xr abort 3 , +.Xr exit 3 +.Sh HISTORY +The +.Fn abort2 +system call first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Fn abort2 +system call was designed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +It was implemented by +.An Wojciech A. Koszek Aq Mt dunstan@freebsd.czest.pl . diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 new file mode 100644 index 000000000000..7e60ccc4ccc5 --- /dev/null +++ b/lib/libc/sys/accept.2 @@ -0,0 +1,239 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)accept.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd October 9, 2014 +.Dt ACCEPT 2 +.Os +.Sh NAME +.Nm accept , +.Nm accept4 +.Nd accept a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" +.Ft int +.Fn accept4 "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "int flags" +.Sh DESCRIPTION +The argument +.Fa s +is a socket that has been created with +.Xr socket 2 , +bound to an address with +.Xr bind 2 , +and is listening for connections after a +.Xr listen 2 . +The +.Fn accept +system call extracts the first connection request on the +queue of pending connections, creates a new socket, +and allocates a new file descriptor for the socket which +inherits the state of the +.Dv O_NONBLOCK +and +.Dv O_ASYNC +properties and the destination of +.Dv SIGIO +and +.Dv SIGURG +signals from the original socket +.Fa s . +.Pp +The +.Fn accept4 +system call is similar, +but the +.Dv O_NONBLOCK +property of the new socket is instead determined by the +.Dv SOCK_NONBLOCK +flag in the +.Fa flags +argument, +the +.Dv O_ASYNC +property is cleared, +the signal destination is cleared +and the close-on-exec flag on the new file descriptor can be set via the +.Dv SOCK_CLOEXEC +flag in the +.Fa flags +argument. +.Pp +If no pending connections are +present on the queue, and the original socket +is not marked as non-blocking, +.Fn accept +blocks the caller until a connection is present. +If the original socket +is marked non-blocking and no pending +connections are present on the queue, +.Fn accept +returns an error as described below. +The accepted socket +may not be used +to accept more connections. +The original socket +.Fa s +remains open. +.Pp +The argument +.Fa addr +is a result argument that is filled-in with +the address of the connecting entity, +as known to the communications layer. +The exact format of the +.Fa addr +argument is determined by the domain in which the communication +is occurring. +A null pointer may be specified for +.Fa addr +if the address information is not desired; +in this case, +.Fa addrlen +is not used and should also be null. +Otherwise, the +.Fa addrlen +argument +is a value-result argument; it should initially contain the +amount of space pointed to by +.Fa addr ; +on return it will contain the actual length (in bytes) of the +address returned. +This call +is used with connection-based socket types, currently with +.Dv SOCK_STREAM . +.Pp +It is possible to +.Xr select 2 +a socket for the purposes of doing an +.Fn accept +by selecting it for read. +.Pp +For certain protocols which require an explicit confirmation, +such as +.Tn ISO +or +.Tn DATAKIT , +.Fn accept +can be thought of +as merely dequeueing the next connection +request and not implying confirmation. +Confirmation can be implied by a normal read or write on the new +file descriptor, and rejection can be implied by closing the +new socket. +.Pp +For some applications, performance may be enhanced by using an +.Xr accept_filter 9 +to pre-process incoming connections. +.Pp +When using +.Fn accept , +portable programs should not rely on the +.Dv O_NONBLOCK +and +.Dv O_ASYNC +properties and the signal destination being inherited, +but should set them explicitly using +.Xr fcntl 2 ; +.Fn accept4 +sets these properties consistently, +but may not be fully portable across +.Ux +platforms. +.Sh RETURN VALUES +These calls return \-1 on error. +If they succeed, they return a non-negative +integer that is a descriptor for the accepted socket. +.Sh ERRORS +The +.Fn accept +and +.Fn accept4 +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is invalid. +.It Bq Er EINTR +The +.Fn accept +operation was interrupted. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOTSOCK +The descriptor references a file, not a socket. +.It Bq Er EINVAL +.Xr listen 2 +has not been called on the socket descriptor. +.It Bq Er EFAULT +The +.Fa addr +argument is not in a writable part of the +user address space. +.It Bo Er EWOULDBLOCK Bc or Bq Er EAGAIN +The socket is marked non-blocking and no connections +are present to be accepted. +.It Bq Er ECONNABORTED +A connection arrived, but it was closed while waiting +on the listen queue. +.El +.Pp +The +.Fn accept4 +system call will also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument is invalid. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr listen 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr accept_filter 9 +.Sh HISTORY +The +.Fn accept +system call appeared in +.Bx 4.2 . +.Pp +The +.Fn accept4 +system call appeared in +.Fx 10.0 . diff --git a/lib/libc/sys/accept.c b/lib/libc/sys/accept.c new file mode 100644 index 000000000000..38e32f2c836d --- /dev/null +++ b/lib/libc/sys/accept.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_accept, __accept); + +#pragma weak accept +int +accept(int s, struct sockaddr *addr, socklen_t *addrlen) +{ + + return (((int (*)(int, struct sockaddr *, socklen_t *)) + __libc_interposing[INTERPOS_accept])(s, addr, addrlen)); +} diff --git a/lib/libc/sys/accept4.c b/lib/libc/sys/accept4.c new file mode 100644 index 000000000000..2907b047efdc --- /dev/null +++ b/lib/libc/sys/accept4.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_accept4, __accept4); + +#pragma weak accept4 +int +accept4(int s, struct sockaddr *addr, socklen_t *addrlen, int flags) +{ + + return (((int (*)(int, struct sockaddr *, socklen_t *, int)) + __libc_interposing[INTERPOS_accept4])(s, addr, addrlen, flags)); +} diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2 new file mode 100644 index 000000000000..c70e7a2d5313 --- /dev/null +++ b/lib/libc/sys/access.2 @@ -0,0 +1,243 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)access.2 8.2 (Berkeley) 4/1/94 +.\" $FreeBSD$ +.\" +.Dd September 15, 2014 +.Dt ACCESS 2 +.Os +.Sh NAME +.Nm access , +.Nm eaccess , +.Nm faccessat +.Nd check accessibility of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn access "const char *path" "int mode" +.Ft int +.Fn eaccess "const char *path" "int mode" +.Ft int +.Fn faccessat "int fd" "const char *path" "int mode" "int flag" +.Sh DESCRIPTION +The +.Fn access +and +.Fn eaccess +system calls check the accessibility of the +file named by +the +.Fa path +argument +for the access permissions indicated by +the +.Fa mode +argument. +The value of +.Fa mode +is either the bitwise-inclusive OR of the access permissions to be +checked +.Dv ( R_OK +for read permission, +.Dv W_OK +for write permission, and +.Dv X_OK +for execute/search permission), +or the existence test +.Pq Dv F_OK . +.Pp +For additional information, see the +.Sx "File Access Permission" +section of +.Xr intro 2 . +.Pp +The +.Fn eaccess +system call uses +the effective user ID and the group access list +to authorize the request; +the +.Fn access +system call uses +the real user ID in place of the effective user ID, +the real group ID in place of the effective group ID, +and the rest of the group access list. +.Pp +The +.Fn faccessat +system call is equivalent to +.Fn access +except in the case where +.Fa path +specifies a relative path. +In this case the file whose accessibility is to be determined is +located relative to the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn faccessat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn access . +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_EACCESS +The checks for accessibility are performed using the effective user and group +IDs instead of the real user and group ID as required in a call to +.Fn access . +.El +.Pp +Even if a process's real or effective user has appropriate privileges +and indicates success for +.Dv X_OK , +the file may not actually have execute permission bits set. +Likewise for +.Dv R_OK +and +.Dv W_OK . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn access , +.Fn eaccess , +or +.Fn faccessat +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa mode +argument is invalid. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EROFS +Write access is requested for a file on a read-only file system. +.It Bq Er ETXTBSY +Write access is requested for a pure procedure (shared text) +file presently being executed. +.It Bq Er EACCES +Permission bits of the file mode do not permit the requested +access, or search permission is denied on a component of the +path prefix. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +Also, the +.Fn faccessat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr intro 2 , +.Xr stat 2 +.Sh STANDARDS +The +.Fn access +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn faccessat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn access +function appeared in +.At v7 . +The +.Fn faccessat +system call appeared in +.Fx 8.0 . +.Sh SECURITY CONSIDERATIONS +The +.Fn access +system call +is a potential security hole due to race conditions and +should never be used. +Set-user-ID and set-group-ID applications should restore the +effective user or group ID, +and perform actions directly rather than use +.Fn access +to simulate access checks for the real user or group ID. +The +.Fn eaccess +system call +likewise may be subject to races if used inappropriately. +.Pp +.Fn access +remains useful for providing clues to users as to whether operations +make sense for particular filesystem objects (e.g. 'delete' menu +item only highlighted in a writable folder ... avoiding interpretation +of the st_mode bits that the application might not understand -- +e.g. in the case of AFS). +It also allows a cheaper file existence test than +.Xr stat 2 . diff --git a/lib/libc/sys/acct.2 b/lib/libc/sys/acct.2 new file mode 100644 index 000000000000..caf1aeab3b46 --- /dev/null +++ b/lib/libc/sys/acct.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)acct.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 17, 2004 +.Dt ACCT 2 +.Os +.Sh NAME +.Nm acct +.Nd enable or disable process accounting +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn acct "const char *file" +.Sh DESCRIPTION +The +.Fn acct +system call enables or disables the collection of system accounting +records. +If the argument +.Fa file +is a null pointer, accounting is disabled. +If +.Fa file +is an +.Em existing +pathname (null-terminated), record collection is enabled and for +every process initiated which terminates under normal +conditions an accounting record is appended to +.Fa file . +Abnormal conditions of termination are reboots +or other fatal system problems. +Records for processes which never terminate cannot be +produced by +.Fn acct . +.Pp +For more information on the record structure used by +.Fn acct , +see +.In sys/acct.h +and +.Xr acct 5 . +.Pp +This call is permitted only to the super-user. +.Sh NOTES +Accounting is automatically disabled when the file system the +accounting file resides on runs out of space; it is enabled when +space once again becomes available. +The values controlling this behaviour can be modified using the following +.Xr sysctl 8 +variables: +.Bl -tag -width ".Va kern.acct_chkfreq" +.It Va kern.acct_chkfreq +Specifies the frequency (in seconds) with which free disk +space should be checked. +.It Va kern.acct_resume +The percentage of free disk space above which process +accounting will resume. +.It Va kern.acct_suspend +The percentage of free disk space below which process +accounting will suspend. +.El +.Sh RETURN VALUES +On error -1 is returned. +The file must exist and the call may be exercised only by the super-user. +.Sh ERRORS +The +.Fn acct +system call will fail if one of the following is true: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, +or the path name is not a regular file. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa file +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr acct 5 , +.Xr accton 8 , +.Xr sa 8 +.Sh HISTORY +The +.Fn acct +function appeared in +.At v7 . diff --git a/lib/libc/sys/adjtime.2 b/lib/libc/sys/adjtime.2 new file mode 100644 index 000000000000..95cfca0a464a --- /dev/null +++ b/lib/libc/sys/adjtime.2 @@ -0,0 +1,111 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)adjtime.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt ADJTIME 2 +.Os +.Sh NAME +.Nm adjtime +.Nd "correct the time to allow synchronization of the system clock" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn adjtime "const struct timeval *delta" "struct timeval *olddelta" +.Sh DESCRIPTION +The +.Fn adjtime +system call +makes small adjustments to the system time, as returned by +.Xr gettimeofday 2 , +advancing or retarding it +by the time specified by the timeval +.Fa delta . +If +.Fa delta +is negative, the clock is +slowed down by incrementing it more slowly than normal until +the correction is complete. +If +.Fa delta +is positive, a larger increment than normal +is used. +The skew used to perform the correction is generally a fraction of one percent. +Thus, the time is always +a monotonically increasing function. +A time correction from an earlier call to +.Fn adjtime +may not be finished when +.Fn adjtime +is called again. +If +.Fa olddelta +is not a null pointer, +the structure pointed to will contain, upon return, the +number of microseconds still to be corrected +from the earlier call. +.Pp +This call may be used by time servers that synchronize the clocks +of computers in a local area network. +Such time servers would slow down the clocks of some machines +and speed up the clocks of others to bring them to the average network time. +.Pp +The +.Fn adjtime +system call +is restricted to the super-user. +.Sh RETURN VALUES +.Rv -std adjtime +.Sh ERRORS +The +.Fn adjtime +system call will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +An argument points outside the process's allocated address space. +.It Bq Er EPERM +The process's effective user ID is not that of the super-user. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr gettimeofday 2 , +.Xr timed 8 , +.Xr timedc 8 +.Rs +.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD" +.%A R. Gusella +.%A S. Zatti +.Re +.Sh HISTORY +The +.Fn adjtime +system call appeared in +.Bx 4.3 . diff --git a/lib/libc/sys/aio_cancel.2 b/lib/libc/sys/aio_cancel.2 new file mode 100644 index 000000000000..3d9cbaf2ff4f --- /dev/null +++ b/lib/libc/sys/aio_cancel.2 @@ -0,0 +1,117 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 19, 2000 +.Dt AIO_CANCEL 2 +.Os +.Sh NAME +.Nm aio_cancel +.Nd cancel an outstanding asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_cancel "int fildes" "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_cancel +system call cancels the outstanding asynchronous +I/O request for the file descriptor specified in +.Fa fildes . +If +.Fa iocb +is specified, only that specific asynchronous I/O request is cancelled. +.Pp +Normal asynchronous notification occurs for cancelled requests. +Requests complete with an error result of +.Er ECANCELED . +.Sh RESTRICTIONS +The +.Fn aio_cancel +system call does not cancel asynchronous I/O requests for raw disk devices. +The +.Fn aio_cancel +system call will always return +.Dv AIO_NOTCANCELED +for file descriptors associated with raw disk devices. +.Sh RETURN VALUES +The +.Fn aio_cancel +system call returns -1 to indicate an error, or one of the following: +.Bl -tag -width Dv +.It Bq Dv AIO_CANCELED +All outstanding requests meeting the criteria specified were cancelled. +.It Bq Dv AIO_NOTCANCELED +Some requests were not cancelled, status for the requests should be +checked with +.Xr aio_error 2 . +.It Bq Dv AIO_ALLDONE +All of the requests meeting the criteria have finished. +.El +.Sh ERRORS +An error return from +.Fn aio_cancel +indicates: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fildes +argument +is an invalid file descriptor. +.El +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_cancel +system call is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_cancel +system call first appeared in +.Fx 3.0 . +The first functional implementation of +.Fn aio_cancel +appeared in +.Fx 4.0 . +.Sh AUTHORS +.An -nosplit +This +manual page was originally written by +.An Wes Peters Aq Mt wes@softweyr.com . +.An Christopher M Sedore Aq Mt cmsedore@maxwell.syr.edu +updated it when +.Fn aio_cancel +was implemented for +.Fx 4.0 . diff --git a/lib/libc/sys/aio_error.2 b/lib/libc/sys/aio_error.2 new file mode 100644 index 000000000000..030914616121 --- /dev/null +++ b/lib/libc/sys/aio_error.2 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 2, 1999 +.Dt AIO_ERROR 2 +.Os +.Sh NAME +.Nm aio_error +.Nd retrieve error status of asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_error "const struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_error +system call returns the error status of the asynchronous I/O request +associated with the structure pointed to by +.Fa iocb . +.Sh RETURN VALUES +If the asynchronous I/O request has completed successfully, +.Fn aio_error +returns 0. +If the request has not yet completed, +.Er EINPROGRESS +is returned. +If the request has completed unsuccessfully the error +status is returned as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +On failure, +.Fn aio_error +returns +.Dv -1 +and sets +.Dv errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_error +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa iocb +argument +does not reference an outstanding asynchronous I/O request. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_error +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_error +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . diff --git a/lib/libc/sys/aio_fsync.2 b/lib/libc/sys/aio_fsync.2 new file mode 100644 index 000000000000..9d5d143416b3 --- /dev/null +++ b/lib/libc/sys/aio_fsync.2 @@ -0,0 +1,178 @@ +.\" Copyright (c) 2013 Sergey Kandaurov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 19, 2016 +.Dt AIO_FSYNC 2 +.Os +.Sh NAME +.Nm aio_fsync +.Nd asynchronous file synchronization (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_fsync "int op" "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_fsync +system call allows the calling process to move all modified data +associated with the descriptor +.Fa iocb->aio_fildes +to a permanent storage device. +The call returns immediately after the synchronization request has been +enqueued to the descriptor; the synchronization may or may not have +completed at the time the call returns. +.Pp +The +.Fa op +argument can only be set to +.Dv O_SYNC +to cause all currently queued I/O operations to be completed +as if by a call to +.Xr fsync 2 . +.Pp +If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, +then the enqueued operation is submitted at a priority equal to that +of the calling process minus +.Fa iocb->aio_reqprio . +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to invalid arguments), +the call returns without having enqueued the request. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +.Fn aio_fsync +call to avoid passing bogus context information to the kernel. +.Pp +Modification of the Asynchronous I/O Control Block structure is not allowed +while the request is queued. +.Sh RETURN VALUES +.Rv -std aio_fsync +.Sh ERRORS +The +.Fn aio_fsync +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous file synchronization operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.It Bq Er EINVAL +A value of the +.Fa op +argument is not set to +.Dv O_SYNC . +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_fsync +system call is made, or asynchronously, at any time thereafter. +If they are detected at call time, +.Fn aio_fsync +returns -1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is not a valid descriptor. +.It Bq Er EINVAL +This implementation does not support synchronized I/O for this file. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr read 2 +and +.Xr write 2 +system calls, and the value returned by the +.Fn aio_error +system call is one of the error returns from the +.Xr read 2 +or +.Xr write 2 +system calls. +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_fsync +system call is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_fsync +system call first appeared in +.Fx 7.0 . diff --git a/lib/libc/sys/aio_mlock.2 b/lib/libc/sys/aio_mlock.2 new file mode 100644 index 000000000000..f7f4a2781a91 --- /dev/null +++ b/lib/libc/sys/aio_mlock.2 @@ -0,0 +1,138 @@ +.\" Copyright (c) 2013 Gleb Smirnoff <glebius@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 19, 2016 +.Dt AIO_MLOCK 2 +.Os +.Sh NAME +.Nm aio_mlock +.Nd asynchronous +.Xr mlock 2 +operation +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_mlock "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_mlock +system call allows the calling process to lock into memory the +physical pages associated with the virtual address range starting at +.Fa iocb->aio_buf +for +.Fa iocb->aio_nbytes +bytes. +The call returns immediately after the locking request has +been enqueued; the operation may or may not have completed at the time +the call returns. +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to +.Xr aio 4 +limits), +then the call returns without having enqueued the request. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +.Fn aio_mlock +call to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +memory mapping described by the virtual address range are not allowed +while the request is queued. +.Sh RETURN VALUES +.Rv -std aio_mlock +.Sh ERRORS +The +.Fn aio_mlock +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr mlock 2 +system call, and the value returned by the +.Fn aio_error +system call is one of the error returns from the +.Xr mlock 2 +system call, or +.Er ECANCELED +if the request was explicitly cancelled via a call to +.Fn aio_cancel . +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr mlock 2 , +.Xr sigevent 3 , +.Xr aio 4 +.Sh PORTABILITY +The +.Fn aio_mlock +system call is a +.Fx +extension, and should not be used in portable code. +.Sh HISTORY +The +.Fn aio_mlock +system call first appeared in +.Fx 10.0 . +.Sh AUTHORS +The system call was introduced by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 new file mode 100644 index 000000000000..bbf96cc89890 --- /dev/null +++ b/lib/libc/sys/aio_read.2 @@ -0,0 +1,222 @@ +.\" Copyright (c) 1998 Terry Lambert +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 19, 2016 +.Dt AIO_READ 2 +.Os +.Sh NAME +.Nm aio_read +.Nd asynchronous read from a file (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_read "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_read +system call allows the calling process to read +.Fa iocb->aio_nbytes +from the descriptor +.Fa iocb->aio_fildes +beginning at the offset +.Fa iocb->aio_offset +into the buffer pointed to by +.Fa iocb->aio_buf . +The call returns immediately after the read request has +been enqueued to the descriptor; the read may or may not have +completed at the time the call returns. +.Pp +If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, +then the enqueued operation is submitted at a priority equal to that +of the calling process minus +.Fa iocb->aio_reqprio . +.Pp +The +.Fa iocb->aio_lio_opcode +argument +is ignored by the +.Fn aio_read +system call. +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to invalid arguments), +then the call returns without having enqueued the request. +.Pp +If the request is successfully enqueued, the value of +.Fa iocb->aio_offset +can be modified during the request as context, so this value must +not be referenced after the request is enqueued. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +.Fn aio_read +call to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents are not allowed while the request is queued. +.Pp +If the file offset in +.Fa iocb->aio_offset +is past the offset maximum for +.Fa iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_read +.Sh DIAGNOSTICS +None. +.Sh ERRORS +The +.Fn aio_read +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous read operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_read +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, +.Fn aio_read +returns -1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid. +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +is not valid, the priority specified by +.Fa iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa iocb->aio_nbytes +is not valid. +.It Bq Er EOVERFLOW +The file is a regular file, +.Fa iocb->aio_nbytes +is greater than zero, the starting offset in +.Fa iocb->aio_offset +is before the end of the file, but is at or beyond the +.Fa iocb->aio_fildes +offset maximum. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr read 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr read 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid for reading. +.It Bq Er ECANCELED +The request was explicitly cancelled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_read +system call is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_read +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Terry Lambert Aq Mt terry@whistle.com . +.Sh BUGS +Invalid information in +.Fa iocb->_aiocb_private +may confuse the kernel. diff --git a/lib/libc/sys/aio_return.2 b/lib/libc/sys/aio_return.2 new file mode 100644 index 000000000000..df558734ed41 --- /dev/null +++ b/lib/libc/sys/aio_return.2 @@ -0,0 +1,102 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 21, 2016 +.Dt AIO_RETURN 2 +.Os +.Sh NAME +.Nm aio_return +.Nd retrieve return status of asynchronous I/O operation (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft ssize_t +.Fn aio_return "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_return +system call returns the final status of the asynchronous I/O request +associated with the structure pointed to by +.Fa iocb . +.Pp +The +.Fn aio_return +system call +should only be called once, to obtain the final status of an asynchronous +I/O operation once it has completed +.Xr ( aio_error 2 +returns something other than +.Er EINPROGRESS ) . +.Sh RETURN VALUES +If the asynchronous I/O request has completed, the status is returned +as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +Otherwise, +.Fn aio_return +returns \-1 and sets +.Va errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_return +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa iocb +argument +does not reference a completed asynchronous I/O request. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_return +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_return +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . diff --git a/lib/libc/sys/aio_suspend.2 b/lib/libc/sys/aio_suspend.2 new file mode 100644 index 000000000000..0ff25f51c5ab --- /dev/null +++ b/lib/libc/sys/aio_suspend.2 @@ -0,0 +1,117 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 2, 1999 +.Dt AIO_SUSPEND 2 +.Os +.Sh NAME +.Nm aio_suspend +.Nd suspend until asynchronous I/O operations or timeout complete (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_suspend "const struct aiocb *const iocbs[]" "int niocb" "const struct timespec *timeout" +.Sh DESCRIPTION +The +.Fn aio_suspend +system call suspends the calling process until at least one of the +specified asynchronous I/O requests have completed, a signal is +delivered, or the +.Fa timeout +has passed. +.Pp +The +.Fa iocbs +argument +is an array of +.Fa niocb +pointers to asynchronous I/O requests. +Array members containing +null pointers will be silently ignored. +.Pp +If +.Fa timeout +is not a null pointer, it specifies a maximum interval to suspend. +If +.Fa timeout +is a null pointer, the suspend blocks indefinitely. +To effect a +poll, the +.Fa timeout +should point to a zero-value timespec structure. +.Sh RETURN VALUES +If one or more of the specified asynchronous I/O requests have +completed, +.Fn aio_suspend +returns 0. +Otherwise it returns -1 and sets +.Va errno +to indicate the error, as enumerated below. +.Sh ERRORS +The +.Fn aio_suspend +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +the +.Fa timeout +expired before any I/O requests completed. +.It Bq Er EINVAL +The +.Fa iocbs +argument +contains more than +.Dv AIO_LISTIO_MAX +asynchronous I/O requests, or at least one of the requests is not +valid. +.It Bq Er EINTR +the suspend was interrupted by a signal. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_suspend +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_suspend +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . diff --git a/lib/libc/sys/aio_suspend.c b/lib/libc/sys/aio_suspend.c new file mode 100644 index 000000000000..020edf8a74fa --- /dev/null +++ b/lib/libc/sys/aio_suspend.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/aio.h> +#include "libc_private.h" + +__weak_reference(__sys_aio_suspend, __aio_suspend); + +#pragma weak aio_suspend +int +aio_suspend(const struct aiocb * const iocbs[], int niocb, + const struct timespec *timeout) +{ + + return (((int (*)(const struct aiocb * const[], int, + const struct timespec *)) + __libc_interposing[INTERPOS_aio_suspend])(iocbs, niocb, timeout)); +} diff --git a/lib/libc/sys/aio_waitcomplete.2 b/lib/libc/sys/aio_waitcomplete.2 new file mode 100644 index 000000000000..66e7208d7b48 --- /dev/null +++ b/lib/libc/sys/aio_waitcomplete.2 @@ -0,0 +1,137 @@ +.\" Copyright (c) 1999 Christopher M Sedore. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 21, 2016 +.Dt AIO_WAITCOMPLETE 2 +.Os +.Sh NAME +.Nm aio_waitcomplete +.Nd wait for the next completion of an aio request +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft ssize_t +.Fn aio_waitcomplete "struct aiocb **iocbp" "struct timespec *timeout" +.Sh DESCRIPTION +The +.Fn aio_waitcomplete +system call waits for completion of an asynchronous I/O request. +Upon completion, +.Fn aio_waitcomplete +returns the result of the function and sets +.Fa iocbp +to point to the structure associated with the original request. +If an asynchronous I/O request is completed before +.Fn aio_waitcomplete +is called, it returns immediately with the completed request. +.Pp +If +.Fa timeout +is a non-NULL pointer, it specifies a maximum interval to wait for a +asynchronous I/O request to complete. +If +.Fa timeout +is a NULL pointer, +.Fn aio_waitcomplete +waits indefinitely. +To effect a poll, the +.Fa timeout +argument should be non-NULL, pointing to a zero-valued timeval structure. +.Pp +The +.Fn aio_waitcomplete +system call also serves the function of +.Fn aio_return , +thus +.Fn aio_return +should not be called for the control block returned in +.Fa iocbp . +.Sh RETURN VALUES +If an asynchronous I/O request has completed, +.Fa iocbp +is set to point to the control block passed with the original request, +and the status is returned as described in +.Xr read 2 , +.Xr write 2 , +or +.Xr fsync 2 . +On failure, +.Fn aio_waitcomplete +returns +.Dv -1 , +sets iocbp to +.Dv NULL +and sets +.Va errno +to indicate the error condition. +.Sh ERRORS +The +.Fn aio_waitcomplete +system call fails if: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified time limit is invalid. +.It Bq Er EAGAIN +The process has not yet called +.Fn aio_read +or +.Fn aio_write . +.It Bq Er EINTR +A signal was delivered before the timeout expired and before any +asynchronous I/O requests completed. +.It Bq Er EWOULDBLOCK +.It Bq Er EINPROGRESS +The specified time limit expired before any asynchronous I/O requests +completed. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_write 2 , +.Xr fsync 2 , +.Xr read 2 , +.Xr write 2 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_waitcomplete +system call is a +.Fx Ns -specific +extension. +.Sh HISTORY +The +.Fn aio_waitcomplete +system call first appeared in +.Fx 4.0 . +.Sh AUTHORS +The +.Fn aio_waitcomplete +system call and this manual page were written by +.An Christopher M Sedore Aq Mt cmsedore@maxwell.syr.edu . diff --git a/lib/libc/sys/aio_write.2 b/lib/libc/sys/aio_write.2 new file mode 100644 index 000000000000..a3268e50ea90 --- /dev/null +++ b/lib/libc/sys/aio_write.2 @@ -0,0 +1,217 @@ +.\" Copyright (c) 1999 Softweyr LLC. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Softweyr LLC AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Softweyr LLC OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 19, 2016 +.Dt AIO_WRITE 2 +.Os +.Sh NAME +.Nm aio_write +.Nd asynchronous write to a file (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_write "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_write +system call allows the calling process to write +.Fa iocb->aio_nbytes +from the buffer pointed to by +.Fa iocb->aio_buf +to the descriptor +.Fa iocb->aio_fildes . +The call returns immediately after the write request has been enqueued +to the descriptor; the write may or may not have completed at the time +the call returns. +If the request could not be enqueued, generally due +to invalid arguments, the call returns without having enqueued the +request. +.Pp +If +.Dv O_APPEND +is set for +.Fa iocb->aio_fildes , +.Fn aio_write +operations append to the file in the same order as the calls were +made. +If +.Dv O_APPEND +is not set for the file descriptor, the write operation will occur at +the absolute position from the beginning of the file plus +.Fa iocb->aio_offset . +.Pp +If +.Dv _POSIX_PRIORITIZED_IO +is defined, and the descriptor supports it, then the enqueued +operation is submitted at a priority equal to that of the calling +process minus +.Fa iocb->aio_reqprio . +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request is successfully enqueued, the value of +.Fa iocb->aio_offset +can be modified during the request as context, so this value must not +be referenced after the request is enqueued. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the +.Fn aio_write +system call to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents are not allowed while the request is queued. +.Pp +If the file offset in +.Fa iocb->aio_offset +is past the offset maximum for +.Fa iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_write +.Sh ERRORS +The +.Fn aio_write +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous write operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_write +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, +.Fn aio_write +returns -1 and sets +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid, or is not opened for writing. +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +is not valid, the priority specified by +.Fa iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa iocb->aio_nbytes +is not valid. +.El +.Pp +If the request is successfully enqueued, but subsequently canceled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr write 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr write 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid for writing. +.It Bq Er ECANCELED +The request was explicitly canceled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_write +system call +is expected to conform to the +.St -p1003.1 +standard. +.Sh HISTORY +The +.Fn aio_write +system call first appeared in +.Fx 3.0 . +.Sh AUTHORS +This manual page was written by +.An Wes Peters Aq Mt wes@softweyr.com . +.Sh BUGS +Invalid information in +.Fa iocb->_aiocb_private +may confuse the kernel. diff --git a/lib/libc/sys/bind.2 b/lib/libc/sys/bind.2 new file mode 100644 index 000000000000..065a38165e9b --- /dev/null +++ b/lib/libc/sys/bind.2 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)bind.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd August 18, 2016 +.Dt BIND 2 +.Os +.Sh NAME +.Nm bind +.Nd assign a local protocol address to a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn bind "int s" "const struct sockaddr *addr" "socklen_t addrlen" +.Sh DESCRIPTION +The +.Fn bind +system call +assigns the local protocol address to a socket. +When a socket is created +with +.Xr socket 2 +it exists in an address family space but has no protocol address assigned. +The +.Fn bind +system call requests that +.Fa addr +be assigned to the socket. +.Sh NOTES +Binding an address in the UNIX domain creates a socket in the file +system that must be deleted by the caller when it is no longer +needed (using +.Xr unlink 2 ) . +.Pp +The rules used in address binding vary between communication domains. +Consult the manual entries in section 4 for detailed information. +.Pp +For maximum portability, you should always zero the socket address structure +before populating it and passing it to +.Fn bind . +.Sh RETURN VALUES +.Rv -std bind +.Sh ERRORS +The +.Fn bind +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +Kernel resources to complete the request are +temporarily unavailable. +.It Bq Er EBADF +The +.Fa s +argument +is not a valid descriptor. +.It Bq Er EINVAL +The socket is already bound to an address, and the protocol does not support +binding to a new address; or the socket has been shut down. +.It Bq Er EINVAL +The +.Fa addrlen +argument is not a valid length for the address family. +.It Bq Er ENOTSOCK +The +.Fa s +argument +is not a socket. +.It Bq Er EADDRNOTAVAIL +The specified address is not available from the local machine. +.It Bq Er EADDRINUSE +The specified address is already in use. +.It Bq Er EAFNOSUPPORT +Addresses in the specified address family cannot be used with this socket. +.It Bq Er EACCES +The requested address is protected, and the current user +has inadequate permission to access it. +.It Bq Er EFAULT +The +.Fa addr +argument is not in a valid part of the user +address space. +.El +.Pp +The following errors are specific to binding addresses in the UNIX domain. +.Bl -tag -width EADDRNOTAVA +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A prefix component of the path name does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er EROFS +The name would reside on a read-only file system. +.It Bq Er EISDIR +An empty pathname was specified. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr getsockname 2 , +.Xr listen 2 , +.Xr socket 2 +.Sh HISTORY +The +.Fn bind +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/bindat.2 b/lib/libc/sys/bindat.2 new file mode 100644 index 000000000000..692099092d6c --- /dev/null +++ b/lib/libc/sys/bindat.2 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 13, 2013 +.Dt BINDAT 2 +.Os +.Sh NAME +.Nm bindat +.Nd assign a local protocol address to a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Pp +.In fcntl.h +.Ft int +.Fn bindat "int fd" "int s" "const struct sockaddr *addr" "socklen_t addrlen" +.Sh DESCRIPTION +The +.Fn bindat +system call assigns the local protocol address to a socket. +It works just like the +.Xr bind 2 +system call with two exceptions: +.Pp +.Bl -enum -offset indent -compact +.It +It is limited to sockets in the PF_LOCAL domain. +.Pp +.It +If the file path stored in the +.Fa sun_path +field of the sockaddr_un structure is a relative path, it is located relative +to the directory associated with the file descriptor +.Fa fd . +If +.Fn bindat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is identical +to a call to +.Xr bind 2 . +.El +.Sh RETURN VALUES +.Rv -std bindat +.Sh ERRORS +The +.Fn bindat +system call may fail with the same errors as the +.Xr bind 2 +system call for a UNIX domain socket or with the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa sun_path +field does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er ENOTDIR +The +.Fa sun_path +field is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr connectat 2 , +.Xr socket 2 , +.Xr unix 4 +.Sh AUTHORS +The +.Nm +was developed by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. diff --git a/lib/libc/sys/brk.2 b/lib/libc/sys/brk.2 new file mode 100644 index 000000000000..0a529ee3a99a --- /dev/null +++ b/lib/libc/sys/brk.2 @@ -0,0 +1,170 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)brk.2 8.4 (Berkeley) 5/1/95 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt BRK 2 +.Os +.Sh NAME +.Nm brk , +.Nm sbrk +.Nd change data segment size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn brk "const void *addr" +.Ft void * +.Fn sbrk "intptr_t incr" +.Sh DESCRIPTION +.Bf -symbolic +The +.Fn brk +and +.Fn sbrk +functions are legacy interfaces from before the +advent of modern virtual memory management. +.Ef +.Pp +The +.Fn brk +and +.Fn sbrk +functions are used to change the amount of memory allocated in a +process's data segment. +They do this by moving the location of the +.Dq break . +The break is the first address after the end of the process's +uninitialized data segment (also known as the +.Dq BSS ) . +.Pp +The +.Fn brk +function +sets the break to +.Fa addr . +.Pp +The +.Fn sbrk +function raises the break by +.Fa incr +bytes, thus allocating at least +.Fa incr +bytes of new memory in the data segment. +If +.Fa incr +is negative, +the break is lowered by +.Fa incr +bytes. +.Sh NOTES +While the actual process data segment size maintained by the kernel will only +grow or shrink in page sizes, these functions allow setting the break +to unaligned values (i.e., it may point to any address inside the last +page of the data segment). +.Pp +The current value of the program break may be determined by calling +.Fn sbrk 0 . +See also +.Xr end 3 . +.Pp +The +.Xr getrlimit 2 +system call may be used to determine +the maximum permissible size of the +data segment. +It will not be possible to set the break +beyond +.Dq Va etext No + Va rlim.rlim_max +where the +.Va rlim.rlim_max +value is returned from a call to +.Fn getrlimit RLIMIT_DATA &rlim . +(See +.Xr end 3 +for the definition of +.Va etext ) . +.Sh RETURN VALUES +.Rv -std brk +.Pp +The +.Fn sbrk +function returns the prior break value if successful; +otherwise the value +.Po Vt "void *" Pc Ns \-1 +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn brk +and +.Fn sbrk +functions +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The requested break value was beyond the beginning of the data segment. +.It Bq Er ENOMEM +The data segment size limit, as set by +.Xr setrlimit 2 , +was exceeded. +.It Bq Er ENOMEM +Insufficient space existed in the swap area +to support the expansion of the data segment. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr getrlimit 2 , +.Xr mmap 2 , +.Xr end 3 , +.Xr free 3 , +.Xr malloc 3 +.Sh HISTORY +The +.Fn brk +function appeared in +.At v7 . +.Sh BUGS +Mixing +.Fn brk +or +.Fn sbrk +with +.Xr malloc 3 , +.Xr free 3 , +or similar functions will result in non-portable program behavior. +.Pp +Setting the break may fail due to a temporary lack of +swap space. +It is not possible to distinguish this +from a failure caused by exceeding the maximum size of +the data segment without consulting +.Xr getrlimit 2 . diff --git a/lib/libc/sys/cap_enter.2 b/lib/libc/sys/cap_enter.2 new file mode 100644 index 000000000000..c1d1e20a751a --- /dev/null +++ b/lib/libc/sys/cap_enter.2 @@ -0,0 +1,160 @@ +.\" +.\" Copyright (c) 2008-2009 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 27, 2016 +.Dt CAP_ENTER 2 +.Os +.Sh NAME +.Nm cap_enter , +.Nm cap_getmode +.Nd Capability mode system calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_enter "void" +.Ft int +.Fn cap_getmode "u_int *modep" +.Sh DESCRIPTION +.Fn cap_enter +places the current process into capability mode, a mode of execution in which +processes may only issue system calls operating on file descriptors or +reading limited global system state. +Access to global name spaces, such as file system or IPC name spaces, is +prevented. +If the process is already in a capability mode sandbox, the system call is a +no-op. +Future process descendants created with +.Xr fork 2 +or +.Xr pdfork 2 +will be placed in capability mode from inception. +.Pp +When combined with +.Xr cap_rights_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_fcntls_limit 2 , +.Fn cap_enter +may be used to create kernel-enforced sandboxes in which +appropriately-crafted applications or application components may be run. +.Pp +.Fn cap_getmode +returns a flag indicating whether or not the process is in a capability mode +sandbox. +.Sh RUN-TIME SETTINGS +If the +.Dv kern.trap_enocap +sysctl MIB is set to a non-zero value, then for any process executing in a +capability mode sandbox, any syscall which results in either an +.Er ENOTCAPABLE +or +.Er ECAPMODE +error also generates the synchronous +.Dv SIGTRAP +signal to the thread on the syscall return. +On signal delivery, the +.Va si_errno +member of the +.Fa siginfo +signal handler parameter is set to the syscall error value, +and the +.Va si_code +member is set to +.Dv TRAP_CAP . +.Pp +See also the +.Dv PROC_TRAPCAP_CTL +and +.Dv PROC_TRAPCAP_STATUS +operations of the +.Xr procctl 2 +function for similar per-process functionality. +.Sh CAVEAT +Creating effective process sandboxes is a tricky process that involves +identifying the least possible rights required by the process and then +passing those rights into the process in a safe manner. +Consumers of +.Fn cap_enter +should also be aware of other inherited rights, such as access to VM +resources, memory contents, and other process properties that should be +considered. +It is advisable to use +.Xr fexecve 2 +to create a runtime environment inside the sandbox that has as few implicitly +acquired rights as possible. +.Sh RETURN VALUES +.Rv -std cap_enter cap_getmode +.Pp +When the process is in capability mode, +.Fn cap_getmode +sets the flag to a non-zero value. +A zero value means the process is not in capability mode. +.Sh ERRORS +The +.Fn cap_enter +and +.Fn cap_getmode +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er ENOSYS +The kernel is compiled without: +.Pp +.Cd "options CAPABILITY_MODE" +.El +.Pp +The +.Fn cap_getmode +system call may also return the following error: +.Bl -tag -width Er +.It Bq Er EFAULT +Pointer +.Fa modep +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr cap_fcntls_limit 2 , +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr procctl 2 , +.Xr sysctl 2 , +.Xr fexecve 2 , +.Xr cap_sandboxed 3 , +.Xr capsicum 4 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +These functions and the capability facility were created by +.An "Robert N. M. Watson" +at the University of Cambridge Computer Laboratory with support from a grant +from Google, Inc. diff --git a/lib/libc/sys/cap_fcntls_limit.2 b/lib/libc/sys/cap_fcntls_limit.2 new file mode 100644 index 000000000000..193d97da37eb --- /dev/null +++ b/lib/libc/sys/cap_fcntls_limit.2 @@ -0,0 +1,126 @@ +.\" +.\" Copyright (c) 2012 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 27, 2014 +.Dt CAP_FCNTLS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_fcntls_limit , +.Nm cap_fcntls_get +.Nd manage allowed fcntl commands +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_fcntls_limit "int fd" "uint32_t fcntlrights" +.Ft int +.Fn cap_fcntls_get "int fd" "uint32_t *fcntlrightsp" +.Sh DESCRIPTION +If a file descriptor is granted the +.Dv CAP_FCNTL +capability right, the list of allowed +.Xr fcntl 2 +commands can be selectively reduced (but never expanded) with the +.Fn cap_fcntls_limit +system call. +.Pp +A bitmask of allowed fcntls commands for a given file descriptor can be obtained +with the +.Fn cap_fcntls_get +system call. +.Sh FLAGS +The following flags may be specified in the +.Fa fcntlrights +argument or returned in the +.Fa fcntlrightsp +argument: +.Bl -tag -width CAP_FCNTL_GETOWN +.It Dv CAP_FCNTL_GETFL +Permit +.Dv F_GETFL +command. +.It Dv CAP_FCNTL_SETFL +Permit +.Dv F_SETFL +command. +.It Dv CAP_FCNTL_GETOWN +Permit +.Dv F_GETOWN +command. +.It Dv CAP_FCNTL_SETOWN +Permit +.Dv F_SETOWN +command. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Fn cap_fcntls_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EINVAL +An invalid flag has been passed in +.Fa fcntlrights . +.It Bq Er ENOTCAPABLE +.Fa fcntlrights +would expand the list of allowed +.Xr fcntl 2 +commands. +.El +.Pp +.Fn cap_fcntls_get +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa fcntlrightsp +argument points at an invalid address. +.El +.Sh SEE ALSO +.Xr cap_ioctls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr fcntl 2 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This function was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship of the FreeBSD Foundation. diff --git a/lib/libc/sys/cap_ioctls_limit.2 b/lib/libc/sys/cap_ioctls_limit.2 new file mode 100644 index 000000000000..39f117f03087 --- /dev/null +++ b/lib/libc/sys/cap_ioctls_limit.2 @@ -0,0 +1,159 @@ +.\" +.\" Copyright (c) 2012 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 6, 2015 +.Dt CAP_IOCTLS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_ioctls_limit , +.Nm cap_ioctls_get +.Nd manage allowed ioctl commands +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds" +.Ft ssize_t +.Fn cap_ioctls_get "int fd" "unsigned long *cmds" "size_t maxcmds" +.Sh DESCRIPTION +If a file descriptor is granted the +.Dv CAP_IOCTL +capability right, the list of allowed +.Xr ioctl 2 +commands can be selectively reduced (but never expanded) with the +.Fn cap_ioctls_limit +system call. +The +.Fa cmds +argument is an array of +.Xr ioctl 2 +commands and the +.Fa ncmds +argument specifies the number of elements in the array. +There can be up to +.Va 256 +elements in the array. +Including an element that has been previously revoked will generate an error. +After a successful call only those listed in the array may be used. +.Pp +The list of allowed ioctl commands for a given file descriptor can be obtained +with the +.Fn cap_ioctls_get +system call. +The +.Fa cmds +argument points at memory that can hold up to +.Fa maxcmds +values. +The function populates the provided buffer with up to +.Fa maxcmds +elements, but always returns the total number of ioctl commands allowed for the +given file descriptor. +The total number of ioctls commands for the given file descriptor can be +obtained by passing +.Dv NULL as the +.Fa cmds +argument and +.Va 0 +as the +.Fa maxcmds +argument. +If all ioctl commands are allowed +.Dv ( CAP_IOCTL +capability right is assigned to the file descriptor and the +.Fn cap_ioctls_limit +system call was never called for this file descriptor), the +.Fn cap_ioctls_get +system call will return +.Dv CAP_IOCTLS_ALL +and will not modify the buffer pointed to by the +.Fa cmds +argument. +.Sh RETURN VALUES +.Rv -std cap_ioctls_limit +.Pp +The +.Fn cap_ioctls_get +function, if successful, returns the total number of allowed ioctl commands or +the value +.Dv CAP_IOCTLS_ALL +if all ioctls commands are allowed. +On failure the value +.Va -1 +is returned and the global variable errno is set to indicate the error. +.Sh ERRORS +.Fn cap_ioctls_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa cmds +argument points at an invalid address. +.It Bq Er EINVAL +The +.Fa ncmds +argument is greater than +.Va 256 . +.It Bq Er ENOTCAPABLE +.Fa cmds +would expand the list of allowed +.Xr ioctl 2 +commands. +.El +.Pp +.Fn cap_ioctls_get +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid descriptor. +.It Bq Er EFAULT +The +.Fa cmds +argument points at invalid address. +.El +.Sh SEE ALSO +.Xr cap_fcntls_limit 2 , +.Xr cap_rights_limit 2 , +.Xr ioctl 2 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This function was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship of the FreeBSD Foundation. diff --git a/lib/libc/sys/cap_rights_limit.2 b/lib/libc/sys/cap_rights_limit.2 new file mode 100644 index 000000000000..4663951e5029 --- /dev/null +++ b/lib/libc/sys/cap_rights_limit.2 @@ -0,0 +1,157 @@ +.\" +.\" Copyright (c) 2008-2010 Robert N. M. Watson +.\" Copyright (c) 2012-2013 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" Portions of this documentation were written by Pawel Jakub Dawidek +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 27, 2014 +.Dt CAP_RIGHTS_LIMIT 2 +.Os +.Sh NAME +.Nm cap_rights_limit +.Nd limit capability rights +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/capsicum.h +.Ft int +.Fn cap_rights_limit "int fd" "const cap_rights_t *rights" +.Sh DESCRIPTION +When a file descriptor is created by a function such as +.Xr accept 2 , +.Xr accept4 2 , +.Xr fhopen 2 , +.Xr kqueue 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr openat 2 , +.Xr pdfork 2 , +.Xr pipe 2 , +.Xr shm_open 2 , +.Xr socket 2 +or +.Xr socketpair 2 , +it is assigned all capability rights. +Those rights can be reduced (but never expanded) by using the +.Fn cap_rights_limit +system call. +Once capability rights are reduced, operations on the file descriptor will be +limited to those permitted by +.Fa rights . +.Pp +The +.Fa rights +argument should be prepared using +.Xr cap_rights_init 3 +family of functions. +.Pp +Capability rights assigned to a file descriptor can be obtained with the +.Xr cap_rights_get 3 +function. +.Pp +The complete list of the capability rights can be found in the +.Xr rights 4 +manual page. +.Sh RETURN VALUES +.Rv -std +.Sh EXAMPLES +The following example demonstrates how to limit file descriptor capability +rights to allow reading only. +.Bd -literal +cap_rights_t setrights; +char buf[1]; +int fd; + +fd = open("/tmp/foo", O_RDWR); +if (fd < 0) + err(1, "open() failed"); + +if (cap_enter() < 0) + err(1, "cap_enter() failed"); + +cap_rights_init(&setrights, CAP_READ); +if (cap_rights_limit(fd, &setrights) < 0) + err(1, "cap_rights_limit() failed"); + +buf[0] = 'X'; + +if (write(fd, buf, sizeof(buf)) > 0) + errx(1, "write() succeeded!"); + +if (read(fd, buf, sizeof(buf)) < 0) + err(1, "read() failed"); +.Ed +.Sh ERRORS +.Fn cap_rights_limit +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid active descriptor. +.It Bq Er EINVAL +An invalid right has been requested in +.Fa rights . +.It Bq Er ENOTCAPABLE +The +.Fa rights +argument contains capability rights not present for the given file descriptor. +Capability rights list can only be reduced, never expanded. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr accept4 2 , +.Xr cap_enter 2 , +.Xr fhopen 2 , +.Xr kqueue 2 , +.Xr mq_open 2 , +.Xr open 2 , +.Xr openat 2 , +.Xr pdfork 2 , +.Xr pipe 2 , +.Xr read 2 , +.Xr shm_open 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr write 2 , +.Xr cap_rights_get 3 , +.Xr cap_rights_init 3 , +.Xr err 3 , +.Xr capsicum 4 , +.Xr rights 4 +.Sh HISTORY +Support for capabilities and capabilities mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +This function was created by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship of the FreeBSD Foundation. diff --git a/lib/libc/sys/chdir.2 b/lib/libc/sys/chdir.2 new file mode 100644 index 000000000000..33940c39c51d --- /dev/null +++ b/lib/libc/sys/chdir.2 @@ -0,0 +1,132 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)chdir.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd December 11, 1993 +.Dt CHDIR 2 +.Os +.Sh NAME +.Nm chdir , +.Nm fchdir +.Nd change current working directory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn chdir "const char *path" +.Ft int +.Fn fchdir "int fd" +.Sh DESCRIPTION +The +.Fa path +argument points to the pathname of a directory. +The +.Fn chdir +system call +causes the named directory +to become the current working directory, that is, +the starting point for path searches of pathnames not beginning with +a slash, +.Ql / . +.Pp +The +.Fn fchdir +system call +causes the directory referenced by +.Fa fd +to become the current working directory, +the starting point for path searches of pathnames not beginning with +a slash, +.Ql / . +.Pp +In order for a directory to become the current directory, +a process must have execute (search) access to the directory. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chdir +system call +will fail and the current working directory will be unchanged if +one or more of the following are true: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named directory does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EACCES +Search permission is denied for any component of +the path name. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +The +.Fn fchdir +system call +will fail and the current working directory will be unchanged if +one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for the directory referenced by the +file descriptor. +.It Bq Er ENOTDIR +The file descriptor does not reference a directory. +.It Bq Er EBADF +The argument +.Fa fd +is not a valid file descriptor. +.El +.Sh SEE ALSO +.Xr chroot 2 +.Sh STANDARDS +The +.Fn chdir +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn chdir +system call appeared in +.At v7 . +The +.Fn fchdir +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/chflags.2 b/lib/libc/sys/chflags.2 new file mode 100644 index 000000000000..8dc14bd8965e --- /dev/null +++ b/lib/libc/sys/chflags.2 @@ -0,0 +1,326 @@ +.\" Copyright (c) 1989, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)chflags.2 8.3 (Berkeley) 5/2/95 +.\" $FreeBSD$ +.\" +.Dd March 22, 2013 +.Dt CHFLAGS 2 +.Os +.Sh NAME +.Nm chflags , +.Nm lchflags , +.Nm fchflags , +.Nm chflagsat +.Nd set file flags +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.In unistd.h +.Ft int +.Fn chflags "const char *path" "unsigned long flags" +.Ft int +.Fn lchflags "const char *path" "unsigned long flags" +.Ft int +.Fn fchflags "int fd" "unsigned long flags" +.Ft int +.Fn chflagsat "int fd" "const char *path" "unsigned long flags" "int atflag" +.Sh DESCRIPTION +The file whose name +is given by +.Fa path +or referenced by the descriptor +.Fa fd +has its flags changed to +.Fa flags . +.Pp +The +.Fn lchflags +system call is like +.Fn chflags +except in the case where the named file is a symbolic link, +in which case +.Fn lchflags +will change the flags of the link itself, +rather than the file it points to. +.Pp +The +.Fn chflagsat +is equivalent to either +.Fn chflags +or +.Fn lchflags +depending on the +.Fa atflag +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The values for the +.Fa atflag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, then the flags of the symbolic link are changed. +.El +.Pp +If +.Fn chflagsat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used. +If also +.Fa atflag +is zero, the behavior is identical to a call to +.Fn chflags . +.Pp +The flags specified are formed by +.Em or Ns 'ing +the following values +.Pp +.Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent +.It Dv SF_APPEND +The file may only be appended to. +.It Dv SF_ARCHIVED +The file has been archived. +This flag means the opposite of the DOS, Windows and CIFS +FILE_ATTRIBUTE_ARCHIVE attribute. +This flag has been deprecated, and may be removed in a future release. +.It Dv SF_IMMUTABLE +The file may not be changed. +.It Dv SF_NOUNLINK +The file may not be renamed or deleted. +.It Dv SF_SNAPSHOT +The file is a snapshot file. +.It Dv UF_APPEND +The file may only be appended to. +.It Dv UF_ARCHIVE +The file needs to be archived. +This flag has the same meaning as the DOS, Windows and CIFS +FILE_ATTRIBUTE_ARCHIVE attribute. +Filesystems in FreeBSD may or may not have special handling for this flag. +For instance, ZFS tracks changes to files and will set this bit when a +file is updated. +UFS only stores the flag, and relies on the application to change it when +needed. +.It Dv UF_HIDDEN +The file may be hidden from directory listings at the application's +discretion. +The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_HIDDEN attribute. +.It Dv UF_IMMUTABLE +The file may not be changed. +.It Dv UF_NODUMP +Do not dump the file. +.It Dv UF_NOUNLINK +The file may not be renamed or deleted. +.It Dv UF_OFFLINE +The file is offline, or has the Windows and CIFS FILE_ATTRIBUTE_OFFLINE +attribute. +Filesystems in FreeBSD store and display this flag, but do not provide any +special handling when it is set. +.It Dv UF_OPAQUE +The directory is opaque when viewed through a union stack. +.It Dv UF_READONLY +The file is read only, and may not be written or appended. +Filesystems may use this flag to maintain compatibility with the DOS, Windows +and CIFS FILE_ATTRIBUTE_READONLY attribute. +.It Dv UF_REPARSE +The file contains a Windows reparse point and has the Windows and CIFS +FILE_ATTRIBUTE_REPARSE_POINT attribute. +.It Dv UF_SPARSE +The file has the Windows FILE_ATTRIBUTE_SPARSE_FILE attribute. +This may also be used by a filesystem to indicate a sparse file. +.It Dv UF_SYSTEM +The file has the DOS, Windows and CIFS FILE_ATTRIBUTE_SYSTEM attribute. +Filesystems in FreeBSD may store and display this flag, but do not provide +any special handling when it is set. +.El +.Pp +If one of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK +is set a non-super-user cannot change any flags and even the super-user +can change flags only if securelevel is 0. +(See +.Xr init 8 +for details.) +.Pp +The +.Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP , +and +.Dv UF_OPAQUE +flags may be set or unset by either the owner of a file or the super-user. +.Pp +The +.Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK , +and +.Dv SF_ARCHIVED +flags may only be set or unset by the super-user. +Attempts to toggle these flags by non-super-users are rejected. +These flags may be set at any time, but normally may only be unset when +the system is in single-user mode. +(See +.Xr init 8 +for details.) +.Pp +The implementation of all flags is filesystem-dependent. +See the description of the +.Dv UF_ARCHIVE +flag above for one example of the differences in behavior. +Care should be exercised when writing applications to account for +support or lack of support of these flags in various filesystems. +.Pp +The +.Dv SF_SNAPSHOT +flag is maintained by the system and cannot be toggled. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chflags +system call will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.It Bq Er EPERM +One of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK +is set and the user is either not the super-user or +securelevel is greater than 0. +.It Bq Er EPERM +A non-super-user attempted to toggle one of +.Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK . +.It Bq Er EPERM +An attempt was made to toggle the +.Dv SF_SNAPSHOT +flag. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EOPNOTSUPP +The underlying file system does not support file flags, or +does not support all of the flags set in +.Fa flags . +.El +.Pp +The +.Fn fchflags +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is not valid. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not to a file. +.It Bq Er EPERM +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.It Bq Er EPERM +One of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK +is set and the user is either not the super-user or +securelevel is greater than 0. +.It Bq Er EPERM +A non-super-user attempted to toggle one of +.Dv SF_ARCHIVED , SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK . +.It Bq Er EPERM +An attempt was made to toggle the +.Dv SF_SNAPSHOT +flag. +.It Bq Er EROFS +The file resides on a read-only file system. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EOPNOTSUPP +The underlying file system does not support file flags, or +does not support all of the flags set in +.Fa flags . +.El +.Sh SEE ALSO +.Xr chflags 1 , +.Xr fflagstostr 3 , +.Xr strtofflags 3 , +.Xr init 8 , +.Xr mount_unionfs 8 +.Sh HISTORY +The +.Fn chflags +and +.Fn fchflags +system calls first appeared in +.Bx 4.4 . +The +.Fn lchflags +system call first appeared in +.Fx 5.0 . +The +.Fn chflagsat +system call first appeared in +.Fx 10.0 . diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 new file mode 100644 index 000000000000..332cf3a132fa --- /dev/null +++ b/lib/libc/sys/chmod.2 @@ -0,0 +1,327 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd December 1, 2013 +.Dt CHMOD 2 +.Os +.Sh NAME +.Nm chmod , +.Nm fchmod , +.Nm lchmod , +.Nm fchmodat +.Nd change mode of file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn chmod "const char *path" "mode_t mode" +.Ft int +.Fn fchmod "int fd" "mode_t mode" +.Ft int +.Fn lchmod "const char *path" "mode_t mode" +.Ft int +.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" +.Sh DESCRIPTION +The file permission bits of the file named specified by +.Fa path +or referenced by the file descriptor +.Fa fd +are changed to +.Fa mode . +The +.Fn chmod +system call verifies that the process owner (user) either owns +the file specified by +.Fa path +(or +.Fa fd ) , +or +is the super-user. +The +.Fn chmod +system call follows symbolic links to operate on the target of the link +rather than the link itself. +.Pp +The +.Fn lchmod +system call is similar to +.Fn chmod +but does not follow symbolic links. +.Pp +The +.Fn fchmodat +is equivalent to either +.Fn chmod +or +.Fn lchmod +depending on the +.Fa flag +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, defined +in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, then the mode of the symbolic link is changed. +.El +.Pp +If +.Fn fchmodat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used. +If also +.Fa flag +is zero, the behavior is identical to a call to +.Fn chmod . +.Pp +A mode is created from +.Em or'd +permission bit masks +defined in +.In sys/stat.h : +.Pp +.Bd -literal -offset indent -compact +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* R for owner */ +#define S_IWUSR 0000200 /* W for owner */ +#define S_IXUSR 0000100 /* X for owner */ + +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* R for group */ +#define S_IWGRP 0000020 /* W for group */ +#define S_IXGRP 0000010 /* X for group */ + +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* R for other */ +#define S_IWOTH 0000002 /* W for other */ +#define S_IXOTH 0000001 /* X for other */ + +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* sticky bit */ +.Ed +.Pp +The non-standard +.Dv S_ISTXT +is a synonym for +.Dv S_ISVTX . +.Pp +The +.Fx +VM system totally ignores the sticky bit +.Pq Dv S_ISVTX +for executables. +On UFS-based file systems (FFS, LFS) the sticky +bit may only be set upon directories. +.Pp +If mode +.Dv S_ISVTX +(the `sticky bit') is set on a directory, +an unprivileged user may not delete or rename +files of other users in that directory. +The sticky bit may be +set by any user on a directory which the user owns or has appropriate +permissions. +For more details of the properties of the sticky bit, see +.Xr sticky 7 . +.Pp +If mode ISUID (set UID) is set on a directory, +and the MNT_SUIDDIR option was used in the mount of the file system, +then the owner of any new files and sub-directories +created within this directory are set +to be the same as the owner of that directory. +If this function is enabled, new directories will inherit +the bit from their parents. +Execute bits are removed from +the file, and it will not be given to root. +This behavior does not change the +requirements for the user to be allowed to write the file, but only the eventual +owner after it has been created. +Group inheritance is not affected. +.Pp +This feature is designed for use on fileservers serving PC users via +ftp, SAMBA, or netatalk. +It provides security holes for shell users and as +such should not be used on shell machines, especially on home directories. +This option requires the SUIDDIR +option in the kernel to work. +Only UFS file systems support this option. +For more details of the suiddir mount option, see +.Xr mount 8 . +.Pp +Writing or changing the owner of a file +turns off the set-user-id and set-group-id bits +unless the user is the super-user. +This makes the system somewhat more secure +by protecting set-user-id (set-group-id) files +from remaining set-user-id (set-group-id) if they are modified, +at the expense of a degree of compatibility. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chmod +system call +will fail and the file mode will be unchanged if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The effective user ID does not match the owner of the file and +the effective user ID is not the super-user. +.It Bq Er EPERM +The effective user ID is not the super-user, the effective user ID do match the +owner of the file, but the group ID of the file does not match the effective +group ID nor one of the supplementary group IDs. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EFTYPE +The effective user ID is not the super-user, the mode includes the sticky bit +.Dv ( S_ISVTX ) , +and path does not refer to a directory. +.El +.Pp +The +.Fn fchmod +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The descriptor is not valid. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not to a file. +.It Bq Er EROFS +The file resides on a read-only file system. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +In addition to the +.Fn chmod +errors, +.Fn fchmodat +fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Fa AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chmod 1 , +.Xr chflags 2 , +.Xr chown 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr sticky 7 +.Sh STANDARDS +The +.Fn chmod +system call is expected to conform to +.St -p1003.1-90 , +except for the return of +.Er EFTYPE . +The +.Dv S_ISVTX +bit on directories is expected to conform to +.St -susv3 . +The +.Fn fchmodat +system call is expected to conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn chmod +function appeared in +.At v7 . +The +.Fn fchmod +system call appeared in +.Bx 4.2 . +The +.Fn lchmod +system call appeared in +.Fx 3.0 . +The +.Fn fchmodat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2 new file mode 100644 index 000000000000..32c29ff72ab5 --- /dev/null +++ b/lib/libc/sys/chown.2 @@ -0,0 +1,268 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)chown.2 8.4 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt CHOWN 2 +.Os +.Sh NAME +.Nm chown , +.Nm fchown , +.Nm lchown , +.Nm fchownat +.Nd change owner and group of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn chown "const char *path" "uid_t owner" "gid_t group" +.Ft int +.Fn fchown "int fd" "uid_t owner" "gid_t group" +.Ft int +.Fn lchown "const char *path" "uid_t owner" "gid_t group" +.Ft int +.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" +.Sh DESCRIPTION +The owner ID and group ID of the file +named by +.Fa path +or referenced by +.Fa fd +is changed as specified by the arguments +.Fa owner +and +.Fa group . +The owner of a file may change the +.Fa group +to a group of which +he or she is a member, +but the change +.Fa owner +capability is restricted to the super-user. +.Pp +The +.Fn chown +system call +clears the set-user-id and set-group-id bits +on the file +to prevent accidental or mischievous creation of +set-user-id and set-group-id programs if not executed +by the super-user. +The +.Fn chown +system call +follows symbolic links to operate on the target of the link +rather than the link itself. +.Pp +The +.Fn fchown +system call +is particularly useful when used in conjunction +with the file locking primitives (see +.Xr flock 2 ) . +.Pp +The +.Fn lchown +system call is similar to +.Fn chown +but does not follow symbolic links. +.Pp +The +.Fn fchownat +system call is equivalent to the +.Fn chown +and +.Fn lchown +except in the case where +.Fa path +specifies a relative path. +In this case the file to be changed is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, ownership of the symbolic link is changed. +.El +.Pp +If +.Fn fchownat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is identical +to a call to +.Fn chown +or +.Fn lchown +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in the +.Fa flag +argument. +.Pp +One of the owner or group id's +may be left unchanged by specifying it as -1. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chown +and +.Fn lchown +will fail and the file will be unchanged if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The operation would change the ownership, but the effective user ID is not the +super-user. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +The +.Fn fchown +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +does not refer to a valid descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not a file. +.It Bq Er EPERM +The effective user ID is not the super-user. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +In addition to the errors specified for +.Fn chown +and +.Fn lchown , +the +.Fn fchownat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chgrp 1 , +.Xr chflags 2 , +.Xr chmod 2 , +.Xr flock 2 , +.Xr chown 8 +.Sh STANDARDS +The +.Fn chown +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn fchownat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn chown +function appeared in +.At v7 . +The +.Fn fchown +system call appeared in +.Bx 4.2 . +.Pp +The +.Fn chown +system call was changed to follow symbolic links in +.Bx 4.4 . +The +.Fn lchown +system call was added in +.Fx 3.0 +to compensate for the loss of functionality. +.Pp +The +.Fn fchownat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/chroot.2 b/lib/libc/sys/chroot.2 new file mode 100644 index 000000000000..36d0364bd7f4 --- /dev/null +++ b/lib/libc/sys/chroot.2 @@ -0,0 +1,156 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)chroot.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd January 3, 2012 +.Dt CHROOT 2 +.Os +.Sh NAME +.Nm chroot +.Nd change root directory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn chroot "const char *dirname" +.Sh DESCRIPTION +The +.Fa dirname +argument +is the address of the pathname of a directory, terminated by an ASCII NUL. +The +.Fn chroot +system call causes +.Fa dirname +to become the root directory, +that is, the starting point for path searches of pathnames +beginning with +.Ql / . +.Pp +In order for a directory to become the root directory +a process must have execute (search) access for that directory. +.Pp +It should be noted that +.Fn chroot +has no effect on the process's current directory. +.Pp +This call is restricted to the super-user. +.Pp +Depending on the setting of the +.Ql kern.chroot_allow_open_directories +sysctl variable, open filedescriptors which reference directories +will make the +.Fn chroot +fail as follows: +.Pp +If +.Ql kern.chroot_allow_open_directories +is set to zero, +.Fn chroot +will always fail with +.Er EPERM +if there are any directories open. +.Pp +If +.Ql kern.chroot_allow_open_directories +is set to one (the default), +.Fn chroot +will fail with +.Er EPERM +if there are any directories open and the +process is already subject to the +.Fn chroot +system call. +.Pp +Any other value for +.Ql kern.chroot_allow_open_directories +will bypass the check for open directories +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn chroot +system call +will fail and the root directory will be unchanged if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path name is not a directory. +.It Bq Er EPERM +The effective user ID is not the super-user, or one or more +filedescriptors are open directories. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named directory does not exist. +.It Bq Er EACCES +Search permission is denied for any component of the path name. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EFAULT +The +.Fa dirname +argument +points outside the process's allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr chdir 2 , +.Xr jail 2 +.Sh HISTORY +The +.Fn chroot +system call appeared in +.Bx 4.2 . +It was marked as +.Dq legacy +in +.St -susv2 , +and was removed in subsequent standards. +.Sh BUGS +If the process is able to change its working directory to the target +directory, but another access control check fails (such as a check for +open directories, or a MAC check), it is possible that this system +call may return an error, with the working directory of the process +left changed. +.Sh SECURITY CONSIDERATIONS +The system have many hardcoded paths to files where it may load after +the process starts. +It is generally recommended to drop privileges immediately after a +successful +.Nm +call, +and restrict write access to a limited subtree of the +.Nm +root, +for instance, +setup the sandbox so that the sandboxed user will have no write +access to any well-known system directories. diff --git a/lib/libc/sys/clock_gettime.2 b/lib/libc/sys/clock_gettime.2 new file mode 100644 index 000000000000..e77b1e81dc33 --- /dev/null +++ b/lib/libc/sys/clock_gettime.2 @@ -0,0 +1,166 @@ +.\" $OpenBSD: clock_gettime.2,v 1.4 1997/05/08 20:21:16 kstailey Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 27, 2015 +.Dt CLOCK_GETTIME 2 +.Os +.Sh NAME +.Nm clock_gettime , +.Nm clock_settime , +.Nm clock_getres +.Nd get/set/calibrate date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn clock_gettime "clockid_t clock_id" "struct timespec *tp" +.Ft int +.Fn clock_settime "clockid_t clock_id" "const struct timespec *tp" +.Ft int +.Fn clock_getres "clockid_t clock_id" "struct timespec *tp" +.Sh DESCRIPTION +The +.Fn clock_gettime +and +.Fn clock_settime +system calls allow the calling process to retrieve or set the value +used by a clock which is specified by +.Fa clock_id . +.Pp +The +.Fa clock_id +argument +can be one of the following values: +.Dv CLOCK_REALTIME , +.Dv CLOCK_REALTIME_PRECISE , +.Dv CLOCK_REALTIME_FAST +for time that increments as +a wall clock should; +.Dv CLOCK_MONOTONIC , +.Dv CLOCK_MONOTONIC_PRECISE , +.Dv CLOCK_MONOTONIC_FAST +which increments in SI seconds; +.Dv CLOCK_UPTIME , +.Dv CLOCK_UPTIME_PRECISE , +.Dv CLOCK_UPTIME_FAST +which starts at zero when the kernel boots and increments +monotonically in SI seconds while the machine is running; +.Dv CLOCK_VIRTUAL +for time that increments only when +the CPU is running in user mode on behalf of the calling process; +.Dv CLOCK_PROF +for time that increments when the CPU is running in user or +kernel mode; or +.Dv CLOCK_SECOND +which returns the current second without performing a full time counter +query, using in-kernel cached value of current second. +.Pp +The clock IDs +.Fa CLOCK_REALTIME_FAST , +.Fa CLOCK_MONOTONIC_FAST , +.Fa CLOCK_UPTIME_FAST +are analogs of corresponding IDs without _FAST suffix but do not perform +a full time counter query, so their accuracy is one timer tick. +Similarly, +.Fa CLOCK_REALTIME_PRECISE , +.Fa CLOCK_MONOTONIC_PRECISE , +.Fa CLOCK_UPTIME_PRECISE +are used to get the most exact value as possible, at the expense of +execution time. +.Pp +The structure pointed to by +.Fa tp +is defined in +.In sys/timespec.h +as: +.Bd -literal +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* and nanoseconds */ +}; +.Ed +.Pp +Only the super-user may set the time of day, using only +.Fa CLOCK_REALTIME . +If the system securelevel is greater than 1 (see +.Xr init 8 ) , +the time may only be advanced. +This limitation is imposed to prevent a malicious super-user +from setting arbitrary time stamps on files. +The system time can still be adjusted backwards using the +.Xr adjtime 2 +system call even when the system is secure. +.Pp +The resolution (granularity) of a clock is returned by the +.Fn clock_getres +system call. +This value is placed in a (non-NULL) +.Fa *tp . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa clock_id +or +.Fa timespec +argument +was not a valid value. +.It Bq Er EPERM +A user other than the super-user attempted to set the time. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr adjtime 2 , +.Xr ctime 3 , +.Xr timed 8 +.Sh STANDARDS +The +.Fn clock_gettime , +.Fn clock_settime , +and +.Fn clock_getres +system calls conform to +.St -p1003.1b-93 . +The clock IDs +.Fa CLOCK_REALTIME_FAST , +.Fa CLOCK_REALTIME_PRECISE , +.Fa CLOCK_MONOTONIC_FAST , +.Fa CLOCK_MONOTONIC_PRECISE , +.Fa CLOCK_UPTIME , +.Fa CLOCK_UPTIME_FAST , +.Fa CLOCK_UPTIME_PRECISE , +.Fa CLOCK_SECOND +are FreeBSD extensions to the POSIX interface. diff --git a/lib/libc/sys/clock_gettime.c b/lib/libc/sys/clock_gettime.c new file mode 100644 index 000000000000..e7e701b2e509 --- /dev/null +++ b/lib/libc/sys/clock_gettime.c @@ -0,0 +1,52 @@ +/*- + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/syscall.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include <time.h> +#include "libc_private.h" + +int __clock_gettime(clockid_t, struct timespec *ts); + +__weak_reference(__clock_gettime, clock_gettime); + +int +__clock_gettime(clockid_t clock_id, struct timespec *ts) +{ + int error; + + if (__vdso_clock_gettime != NULL && __vdso_gettc != NULL) + error = __vdso_clock_gettime(clock_id, ts); + else + error = ENOSYS; + if (error == ENOSYS) + error = __sys_clock_gettime(clock_id, ts); + return (error); +} diff --git a/lib/libc/sys/close.2 b/lib/libc/sys/close.2 new file mode 100644 index 000000000000..6df4500643be --- /dev/null +++ b/lib/libc/sys/close.2 @@ -0,0 +1,144 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)close.2 8.2 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd September 11, 2013 +.Dt CLOSE 2 +.Os +.Sh NAME +.Nm close +.Nd delete a descriptor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn close "int fd" +.Sh DESCRIPTION +The +.Fn close +system call deletes a descriptor from the per-process object +reference table. +If this is the last reference to the underlying object, the +object will be deactivated. +For example, on the last close of a file +the current +.Em seek +pointer associated with the file is lost; +on the last close of a +.Xr socket 2 +associated naming information and queued data are discarded; +on the last close of a file holding an advisory lock +the lock is released (see further +.Xr flock 2 ) . +However, the semantics of System V and +.St -p1003.1-88 +dictate that all +.Xr fcntl 2 +advisory record locks associated with a file for a given process +are removed when +.Em any +file descriptor for that file is closed by that process. +.Pp +When a process exits, +all associated file descriptors are freed, but since there is +a limit on active descriptors per processes, the +.Fn close +system call +is useful when a large quantity of file descriptors are being handled. +.Pp +When a process forks (see +.Xr fork 2 ) , +all descriptors for the new child process reference the same +objects as they did in the parent before the fork. +If a new process is then to be run using +.Xr execve 2 , +the process would normally inherit these descriptors. +Most +of the descriptors can be rearranged with +.Xr dup2 2 +or deleted with +.Fn close +before the +.Xr execve 2 +is attempted, but if some of these descriptors will still +be needed if the execve fails, it is necessary to arrange for them +to be closed if the execve succeeds. +For this reason, the call +.Dq Li fcntl(d, F_SETFD, FD_CLOEXEC) +is provided, +which arranges that a descriptor will be closed after a successful +execve; the call +.Dq Li fcntl(d, F_SETFD, 0) +restores the default, +which is to not close the descriptor. +.Sh RETURN VALUES +.Rv -std close +.Sh ERRORS +The +.Fn close +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not an active descriptor. +.It Bq Er EINTR +An interrupt was received. +.It Bq Er ENOSPC +The underlying object did not fit, cached data was lost. +.It Bq Er ECONNRESET +The underlying object was a stream socket that was shut down by the peer +before all pending data was delivered. +.El +.Pp +In case of any error except +.Er EBADF , +the supplied file descriptor is deallocated and therefore is no longer valid. +.Sh SEE ALSO +.Xr accept 2 , +.Xr closefrom 2 , +.Xr execve 2 , +.Xr fcntl 2 , +.Xr flock 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr socket 2 , +.Xr socketpair 2 +.Sh STANDARDS +The +.Fn close +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn close +function appeared in +.At v7 . diff --git a/lib/libc/sys/close.c b/lib/libc/sys/close.c new file mode 100644 index 000000000000..f7b36f85ddd5 --- /dev/null +++ b/lib/libc/sys/close.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/fcntl.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_close, __close); + +#pragma weak close +int +close(int fd) +{ + + return (((int (*)(int))__libc_interposing[INTERPOS_close])(fd)); +} diff --git a/lib/libc/sys/closefrom.2 b/lib/libc/sys/closefrom.2 new file mode 100644 index 000000000000..a0b5fc218666 --- /dev/null +++ b/lib/libc/sys/closefrom.2 @@ -0,0 +1,53 @@ +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin <jhb@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 12, 2009 +.Dt CLOSEFROM 2 +.Os +.Sh NAME +.Nm closefrom +.Nd delete open file descriptors +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn closefrom "int lowfd" +.Sh DESCRIPTION +The +.Fn closefrom +system call deletes all open file descriptors greater than or equal to +.Fa lowfd +from the per-process object reference table. +Any errors encountered while closing file descriptors are ignored. +.Sh SEE ALSO +.Xr close 2 +.Sh HISTORY +The +.Fn closefrom +function first appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/connect.2 b/lib/libc/sys/connect.2 new file mode 100644 index 000000000000..dceec0d40209 --- /dev/null +++ b/lib/libc/sys/connect.2 @@ -0,0 +1,185 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)connect.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd August 18, 2016 +.Dt CONNECT 2 +.Os +.Sh NAME +.Nm connect +.Nd initiate a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen" +.Sh DESCRIPTION +The +.Fa s +argument +is a socket. +If it is of type +.Dv SOCK_DGRAM , +this call specifies the peer with which the socket is to be associated; +this address is that to which datagrams are to be sent, +and the only address from which datagrams are to be received. +If the socket is of type +.Dv SOCK_STREAM , +this call attempts to make a connection to +another socket. +The other socket is specified by +.Fa name , +which is an address in the communications space of the socket. +.Fa namelen +indicates the amount of space pointed to by +.Fa name , +in bytes; the +.Fa sa_len +member of +.Fa name +is ignored. +Each communications space interprets the +.Fa name +argument in its own way. +Generally, stream sockets may successfully +.Fn connect +only once; datagram sockets may use +.Fn connect +multiple times to change their association. +Datagram sockets may dissolve the association +by connecting to an invalid address, such as a null address. +.Sh RETURN VALUES +.Rv -std connect +.Sh ERRORS +The +.Fn connect +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa s +argument +is not a valid descriptor. +.It Bq Er EINVAL +The +.Fa namelen +argument is not a valid length for the address family. +.It Bq Er ENOTSOCK +The +.Fa s +argument +is a descriptor for a file, not a socket. +.It Bq Er EADDRNOTAVAIL +The specified address is not available on this machine. +.It Bq Er EAFNOSUPPORT +Addresses in the specified address family cannot be used with this socket. +.It Bq Er EISCONN +The socket is already connected. +.It Bq Er ETIMEDOUT +Connection establishment timed out without establishing a connection. +.It Bq Er ECONNREFUSED +The attempt to connect was forcefully rejected. +.It Bq Er ECONNRESET +The connection was reset by the remote host. +.It Bq Er ENETUNREACH +The network is not reachable from this host. +.It Bq Er EHOSTUNREACH +The remote host is not reachable from this host. +.It Bq Er EADDRINUSE +The address is already in use. +.It Bq Er EFAULT +The +.Fa name +argument specifies an area outside +the process address space. +.It Bq Er EINPROGRESS +The socket is non-blocking +and the connection cannot +be completed immediately. +It is possible to +.Xr select 2 +for completion by selecting the socket for writing. +.It Bq Er EINTR +The connection attempt was interrupted by the delivery of a signal. +The connection will be established in the background, +as in the case of +.Er EINPROGRESS . +.It Bq Er EALREADY +A previous connection attempt has not yet been completed. +.It Bq Er EACCES +An attempt is made to connect to a broadcast address (obtained through the +.Dv INADDR_BROADCAST +constant or the +.Dv INADDR_NONE +return value) through a socket that does not provide broadcast functionality. +.It Bq Er EAGAIN +An auto-assigned port number was requested but no auto-assigned ports +are available. +Increasing the port range specified by +.Xr sysctl 3 +MIB variables +.Va net.inet.ip.portrange.first +and +.Va net.inet.ip.portrange.last +may alleviate the problem. +.El +.Pp +The following errors are specific to connecting names in the UNIX domain. +These errors may not apply in future versions of the UNIX IPC domain. +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named socket does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write access to the named socket is denied. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +Write access to the named socket is denied. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr sysctl 3 , +.Xr sysctl 8 +.Sh HISTORY +The +.Fn connect +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/connect.c b/lib/libc/sys/connect.c new file mode 100644 index 000000000000..7969142ad072 --- /dev/null +++ b/lib/libc/sys/connect.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_connect, __connect); + +#pragma weak connect +int +connect(int s, const struct sockaddr *addr, socklen_t addrlen) +{ + + return (((int (*)(int, const struct sockaddr *, socklen_t)) + __libc_interposing[INTERPOS_connect])(s, addr, addrlen)); +} diff --git a/lib/libc/sys/connectat.2 b/lib/libc/sys/connectat.2 new file mode 100644 index 000000000000..759b7eac8e2e --- /dev/null +++ b/lib/libc/sys/connectat.2 @@ -0,0 +1,109 @@ +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 13, 2013 +.Dt CONNECTAT 2 +.Os +.Sh NAME +.Nm connectat +.Nd initiate a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Pp +.In fcntl.h +.Ft int +.Fn connectat "int fd" "int s" "const struct sockaddr *name" "socklen_t namelen" +.Sh DESCRIPTION +The +.Fn connectat +system call initiates a connection on a socket. +It works just like the +.Xr connect 2 +system call with two exceptions: +.Pp +.Bl -enum -offset indent -compact +.It +It is limited to sockets in the PF_LOCAL domain. +.Pp +.It +If the file path stored in the +.Fa sun_path +field of the sockaddr_un structure is a relative path, it is located relative +to the directory associated with the file descriptor +.Fa fd . +If +.Fn connectat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is identical +to a call to +.Xr connect 2 . +.El +.Sh RETURN VALUES +.Rv -std connectat +.Sh ERRORS +The +.Fn connectat +system call may fail with the same errors as the +.Xr connect 2 +system call for a UNIX domain socket or with the following errors: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa sun_path +field does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er ENOTDIR +The +.Fa sun_path +field is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr bindat 2 , +.Xr connect 2 , +.Xr socket 2 , +.Xr unix 4 +.Sh AUTHORS +The +.Nm +was developed by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. diff --git a/lib/libc/sys/cpuset.2 b/lib/libc/sys/cpuset.2 new file mode 100644 index 000000000000..d16b3ff37511 --- /dev/null +++ b/lib/libc/sys/cpuset.2 @@ -0,0 +1,230 @@ +.\" Copyright (c) 2008 Christian Brueffer +.\" Copyright (c) 2008 Jeffrey Roberson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 20, 2015 +.Dt CPUSET 2 +.Os +.Sh NAME +.Nm cpuset , +.Nm cpuset_getid , +.Nm cpuset_setid +.Nd manage CPU affinity sets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/cpuset.h +.Ft int +.Fn cpuset "cpusetid_t *setid" +.Ft int +.Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid" +.Ft int +.Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid" +.Sh DESCRIPTION +The +.Nm +family of system calls allow applications to control sets of processors and +assign processes and threads to these sets. +Processor sets contain lists of CPUs that members may run on and exist only +as long as some process is a member of the set. +All processes in the system have an assigned set. +The default set for all processes in the system is the set numbered 1. +Threads belong to the same set as the process which contains them, +however, they may further restrict their set with the anonymous +per-thread mask. +.Pp +Sets are referenced by a number of type +.Ft cpuset_id_t . +Each thread has a root set, an assigned set, and an anonymous mask. +Only the root and assigned sets are numbered. +The root set is the set of all CPUs available in the system or in the +system partition the thread is running in. +The assigned set is a subset of the root set and is administratively +assignable on a per-process basis. +Many processes and threads may be members of a numbered set. +.Pp +The anonymous set is a further thread-specific refinement on the assigned +set. +It is intended that administrators will manipulate numbered sets using +.Xr cpuset 1 +while application developers will manipulate anonymous sets using +.Xr cpuset_setaffinity 2 . +.Pp +To select the correct set a value of type +.Ft cpulevel_t +is used. +The following values for +.Fa level +are supported: +.Bl -column CPU_LEVEL_CPUSET -offset indent +.It Dv CPU_LEVEL_ROOT Ta "Root set" +.It Dv CPU_LEVEL_CPUSET Ta "Assigned set" +.It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument" +.El +.Pp +The +.Fa which +argument determines how the value of +.Fa id +is interpreted and is of type +.Ft cpuwhich_t . +The +.Fa which +argument may have the following values: +.Bl -column CPU_WHICH_CPUSET -offset indent +.It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)" +.It Dv CPU_WHICH_PID Ta "id is pid_t (process id)" +.It Dv CPU_WHICH_JAIL Ta "id is jid (jail id)" +.It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)" +.It Dv CPU_WHICH_IRQ Ta "id is an irq number" +.It Dv CPU_WHICH_DOMAIN Ta "id is a NUMA domain" +.El +.Pp +An +.Fa id +of '-1' may be used with a +.Fa which +of +.Dv CPU_WHICH_TID , +.Dv CPU_WHICH_PID , +or +.Dv CPU_WHICH_CPUSET +to mean the current thread, process, or current thread's +cpuset. +All cpuset syscalls allow this usage. +.Pp +A +.Fa level +argument of +.Dv CPU_LEVEL_WHICH +combined with a +.Fa which +argument other than +.Dv CPU_WHICH_CPUSET +refers to the anonymous mask of the object. +This mask does not have an id and may only be manipulated with +.Xr cpuset_setaffinity 2 . +.Pp +.Fn cpuset +creates a new set containing the same CPUs as the root set of the current +process and stores its id in the space provided by +.Fa setid . +On successful completion the calling process joins the set and is the +only member. +Children inherit this set after a call to +.Xr fork 2 . +.Pp +.Fn cpuset_setid +attempts to set the id of the object specified by the +.Fa which +argument. +Currently +.Dv CPU_WHICH_PID +is the only acceptable value for which as +threads do not have an id distinct from their process and the API does +not permit changing the id of an existing set. +Upon successful completion all of the threads in the target process will +be running on CPUs permitted by the set. +.Pp +.Fn cpuset_getid +retrieves a set id from the object indicated by +.Fa which +and stores it in the space pointed to by +.Fa setid . +The retrieved id may be that of either the root or assigned set +depending on the value of +.Fa level . +.Fa level +should be +.Dv CPU_LEVEL_CPUSET +or +.Dv CPU_LEVEL_ROOT +to get the set id from +the process or thread specified by the +.Fa id +argument. +Specifying +.Dv CPU_LEVEL_WHICH +with a process or thread is unsupported since +this references the unnumbered anonymous mask. +.Pp +The actual contents of the sets may be retrieved or manipulated using +.Xr cpuset_getaffinity 2 +and +.Xr cpuset_setaffinity 2 . +See those manual pages for more detail. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa which +or +.Fa level +argument was not a valid value. +.It Bq Er EDEADLK +The +.Fn cpuset_setid +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The setid pointer passed to +.Fn cpuset_getid +or +.Fn cpuset +was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.It Bq Er ENFILE +There was no free +.Ft cpusetid_t +for allocation. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset_getaffinity 2 , +.Xr cpuset_setaffinity 2 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 7.1 . +.Sh AUTHORS +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org diff --git a/lib/libc/sys/cpuset_getaffinity.2 b/lib/libc/sys/cpuset_getaffinity.2 new file mode 100644 index 000000000000..c379518214b8 --- /dev/null +++ b/lib/libc/sys/cpuset_getaffinity.2 @@ -0,0 +1,166 @@ +.\" Copyright (c) 2008 Christian Brueffer +.\" Copyright (c) 2008 Jeffrey Roberson +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 2, 2016 +.Dt CPUSET_GETAFFINITY 2 +.Os +.Sh NAME +.Nm cpuset_getaffinity , +.Nm cpuset_setaffinity +.Nd manage CPU affinity +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/cpuset.h +.Ft int +.Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask" +.Ft int +.Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask" +.Sh DESCRIPTION +.Fn cpuset_getaffinity +and +.Fn cpuset_setaffinity +allow the manipulation of sets of CPUs available to processes, threads, +interrupts, jails and other resources. +These functions may manipulate sets of CPUs that contain many processes +or per-object anonymous masks that effect only a single object. +.Pp +The valid values for the +.Fa level +and +.Fa which +arguments are documented in +.Xr cpuset 2 . +These arguments specify which object and which set of the object we are +referring to. +Not all possible combinations are valid. +For example, only processes may belong to a numbered set accessed by a +.Fa level +argument of +.Dv CPU_LEVEL_CPUSET . +All resources, however, have a mask which may be manipulated with +.Dv CPU_LEVEL_WHICH . +.Pp +Masks of type +.Ft cpuset_t +are composed using the +.Dv CPU_SET +macros. +The kernel tolerates large sets as long as all CPUs specified +in the set exist. +Sets smaller than the kernel uses generate an error on calls to +.Fn cpuset_getaffinity +even if the result set would fit within the user supplied set. +Calls to +.Fn cpuset_setaffinity +tolerate small sets with no restrictions. +.Pp +The supplied mask should have a size of +.Fa setsize +bytes. +This size is usually provided by calling +.Li sizeof(mask) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn cpuset_getaffinity +retrieves the +mask from the object specified by +.Fa level , +.Fa which +and +.Fa id +and stores it in the space provided by +.Fa mask . +.Pp +.Fn cpuset_setaffinity +attempts to set the mask for the object specified by +.Fa level , +.Fa which +and +.Fa id +to the value in +.Fa mask . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. +.It Bq Er EINVAL +The +.Fa level +or +.Fa which +argument was not a valid value. +.It Bq Er EINVAL +The +.Fa mask +argument specified when calling +.Fn cpuset_setaffinity +was not a valid value. +.It Bq Er EDEADLK +The +.Fn cpuset_setaffinity +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The mask pointer passed was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er ERANGE +The +.Fa cpusetsize +was either preposterously large or smaller than the kernel set size. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setid 2 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 7.1 . +.Sh AUTHORS +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org diff --git a/lib/libc/sys/dup.2 b/lib/libc/sys/dup.2 new file mode 100644 index 000000000000..f21c93b5868b --- /dev/null +++ b/lib/libc/sys/dup.2 @@ -0,0 +1,169 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)dup.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 1, 2013 +.Dt DUP 2 +.Os +.Sh NAME +.Nm dup , +.Nm dup2 +.Nd duplicate an existing file descriptor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn dup "int oldd" +.Ft int +.Fn dup2 "int oldd" "int newd" +.Sh DESCRIPTION +The +.Fn dup +system call +duplicates an existing object descriptor and returns its value to +the calling process +.Fa ( newd += +.Fn dup oldd ) . +The argument +.Fa oldd +is a small non-negative integer index in +the per-process descriptor table. +The new descriptor returned by the call +is the lowest numbered descriptor +currently not in use by the process. +.Pp +The object referenced by the descriptor does not distinguish +between +.Fa oldd +and +.Fa newd +in any way. +Thus if +.Fa newd +and +.Fa oldd +are duplicate references to an open +file, +.Xr read 2 , +.Xr write 2 +and +.Xr lseek 2 +calls all move a single pointer into the file, +and append mode, non-blocking I/O and asynchronous I/O options +are shared between the references. +If a separate pointer into the file is desired, a different +object reference to the file must be obtained by issuing an +additional +.Xr open 2 +system call. +The close-on-exec flag on the new file descriptor is unset. +.Pp +In +.Fn dup2 , +the value of the new descriptor +.Fa newd +is specified. +If this descriptor is already in use and +.Fa oldd +\*(Ne +.Fa newd , +the descriptor is first deallocated as if the +.Xr close 2 +system call had been used. +If +.Fa oldd +is not a valid descriptor, then +.Fa newd +is not closed. +If +.Fa oldd +== +.Fa newd +and +.Fa oldd +is a valid descriptor, then +.Fn dup2 +is successful, and does nothing. +.Sh RETURN VALUES +These calls return the new file descriptor if successful; +otherwise the value -1 is returned and +the external variable +.Va errno +is set to indicate the cause of the error. +.Sh ERRORS +The +.Fn dup +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa oldd +argument +is not a valid active descriptor +.It Bq Er EMFILE +Too many descriptors are active. +.El +.Pp +The +.Fn dup2 +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa oldd +argument is not a valid active descriptor or the +.Fa newd +argument is negative or exceeds the maximum allowable descriptor number +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr close 2 , +.Xr fcntl 2 , +.Xr getdtablesize 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr dup3 3 +.Sh STANDARDS +The +.Fn dup +and +.Fn dup2 +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn dup +and +.Fn dup2 +functions appeared in +.At v7 . diff --git a/lib/libc/sys/execve.2 b/lib/libc/sys/execve.2 new file mode 100644 index 000000000000..991495c3c9d8 --- /dev/null +++ b/lib/libc/sys/execve.2 @@ -0,0 +1,377 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)execve.2 8.5 (Berkeley) 6/1/94 +.\" $FreeBSD$ +.\" +.Dd September 21, 2010 +.Dt EXECVE 2 +.Os +.Sh NAME +.Nm execve , +.Nm fexecve +.Nd execute a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn execve "const char *path" "char *const argv[]" "char *const envp[]" +.Ft int +.Fn fexecve "int fd" "char *const argv[]" "char *const envp[]" +.Sh DESCRIPTION +The +.Fn execve +system call +transforms the calling process into a new process. +The new process is constructed from an ordinary file, +whose name is pointed to by +.Fa path , +called the +.Em new process file . +The +.Fn fexecve +system call is equivalent to +.Fn execve +except that the file to be executed is determined by the file +descriptor +.Fa fd +instead of a +.Fa path . +This file is either an executable object file, +or a file of data for an interpreter. +An executable object file consists of an identifying header, +followed by pages of data representing the initial program (text) +and initialized data pages. +Additional pages may be specified +by the header to be initialized with zero data; see +.Xr elf 5 +and +.Xr a.out 5 . +.Pp +An interpreter file begins with a line of the form: +.Pp +.Bd -ragged -offset indent -compact +.Sy \&#! +.Em interpreter +.Bq Em arg +.Ed +.Pp +When an interpreter file is +.Sy execve Ap d , +the system actually +.Sy execve Ap s +the specified +.Em interpreter . +If the optional +.Em arg +is specified, it becomes the first argument to the +.Em interpreter , +and the name of the originally +.Sy execve Ap d +file becomes the second argument; +otherwise, the name of the originally +.Sy execve Ap d +file becomes the first argument. +The original arguments are shifted over to +become the subsequent arguments. +The zeroth argument is set to the specified +.Em interpreter . +.Pp +The argument +.Fa argv +is a pointer to a null-terminated array of +character pointers to null-terminated character strings. +These strings construct the argument list to be made available to the new +process. +At least one argument must be present in +the array; by custom, the first element should be +the name of the executed program (for example, the last component of +.Fa path ) . +.Pp +The argument +.Fa envp +is also a pointer to a null-terminated array of +character pointers to null-terminated strings. +A pointer to this array is normally stored in the global variable +.Va environ . +These strings pass information to the +new process that is not directly an argument to the command (see +.Xr environ 7 ) . +.Pp +File descriptors open in the calling process image remain open in +the new process image, except for those for which the close-on-exec +flag is set (see +.Xr close 2 +and +.Xr fcntl 2 ) . +Descriptors that remain open are unaffected by +.Fn execve . +If any of the standard descriptors (0, 1, and/or 2) are closed at the +time +.Fn execve +is called, and the process will gain privilege as a result of set-id +semantics, those descriptors will be re-opened automatically. +No programs, whether privileged or not, should assume that these descriptors +will remain closed across a call to +.Fn execve . +.Pp +Signals set to be ignored in the calling process are set to be ignored in +the +new process. +Signals which are set to be caught in the calling process image +are set to default action in the new process image. +Blocked signals remain blocked regardless of changes to the signal action. +The signal stack is reset to be undefined (see +.Xr sigaction 2 +for more information). +.Pp +If the set-user-ID mode bit of the new process image file is set +(see +.Xr chmod 2 ) , +the effective user ID of the new process image is set to the owner ID +of the new process image file. +If the set-group-ID mode bit of the new process image file is set, +the effective group ID of the new process image is set to the group ID +of the new process image file. +(The effective group ID is the first element of the group list.) +The real user ID, real group ID and +other group IDs of the new process image remain the same as the calling +process image. +After any set-user-ID and set-group-ID processing, +the effective user ID is recorded as the saved set-user-ID, +and the effective group ID is recorded as the saved set-group-ID. +These values may be used in changing the effective IDs later (see +.Xr setuid 2 ) . +.Pp +The set-ID bits are not honored if the respective file system has the +.Cm nosuid +option enabled or if the new process file is an interpreter file. +Syscall +tracing is disabled if effective IDs are changed. +.Pp +The new process also inherits the following attributes from +the calling process: +.Pp +.Bl -column parent_process_ID -offset indent -compact +.It process ID Ta see Xr getpid 2 +.It parent process ID Ta see Xr getppid 2 +.It process group ID Ta see Xr getpgrp 2 +.It access groups Ta see Xr getgroups 2 +.It working directory Ta see Xr chdir 2 +.It root directory Ta see Xr chroot 2 +.It control terminal Ta see Xr termios 4 +.It resource usages Ta see Xr getrusage 2 +.It interval timers Ta see Xr getitimer 2 +.It resource limits Ta see Xr getrlimit 2 +.It file mode mask Ta see Xr umask 2 +.It signal mask Ta see Xr sigaction 2 , +.Xr sigprocmask 2 +.El +.Pp +When a program is executed as a result of an +.Fn execve +system call, it is entered as follows: +.Bd -literal -offset indent +main(argc, argv, envp) +int argc; +char **argv, **envp; +.Ed +.Pp +where +.Fa argc +is the number of elements in +.Fa argv +(the ``arg count'') +and +.Fa argv +points to the array of character pointers +to the arguments themselves. +.Pp +The +.Fn fexecve +ignores the file offset of +.Fa fd . +Since execute permission is checked by +.Fn fexecve , +the file descriptor +.Fa fd +need not have been opened with the +.Dv O_EXEC +flag. +However, if the file to be executed denies read permission for the process +preparing to do the exec, the only way to provide the +.Fa fd +to +.Fn fexecve +is to use the +.Dv O_EXEC +flag when opening +.Fa fd . +Note that the file to be executed can not be open for writing. +.Sh RETURN VALUES +As the +.Fn execve +system call overlays the current process image +with a new process image the successful call +has no process to return to. +If +.Fn execve +does return to the calling process an error has occurred; the +return value will be -1 and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn execve +system call +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOEXEC +When invoking an interpreted script, the length of the first line, +inclusive of the +.Sy \&#! +prefix and terminating newline, exceeds +.Dv MAXSHELLCMDLEN +characters. +.It Bq Er ENOENT +The new process file does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The new process file is not an ordinary file. +.It Bq Er EACCES +The new process file mode denies execute permission. +.It Bq Er ENOEXEC +The new process file has the appropriate access +permission, but has an invalid magic number in its header. +.It Bq Er ETXTBSY +The new process file is a pure procedure (shared text) +file that is currently open for writing by some process. +.It Bq Er ENOMEM +The new process requires more virtual memory than +is allowed by the imposed maximum +.Pq Xr getrlimit 2 . +.It Bq Er E2BIG +The number of bytes in the new process' argument list +is larger than the system-imposed limit. +This limit is specified by the +.Xr sysctl 3 +MIB variable +.Dv KERN_ARGMAX . +.It Bq Er EFAULT +The new process file is not as long as indicated by +the size values in its header. +.It Bq Er EFAULT +The +.Fa path , +.Fa argv , +or +.Fa envp +arguments +point +to an illegal address. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.El +.Pp +In addition, the +.Fn fexecve +will fail and return to the calling process if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor open for executing. +.El +.Sh SEE ALSO +.Xr ktrace 1 , +.Xr _exit 2 , +.Xr fork 2 , +.Xr open 2 , +.Xr execl 3 , +.Xr exit 3 , +.Xr sysctl 3 , +.Xr a.out 5 , +.Xr elf 5 , +.Xr fdescfs 5 , +.Xr environ 7 , +.Xr mount 8 +.Sh STANDARDS +The +.Fn execve +system call conforms to +.St -p1003.1-2001 , +with the exception of reopening descriptors 0, 1, and/or 2 in certain +circumstances. +A future update of the Standard is expected to require this behavior, +and it may become the default for non-privileged processes as well. +.\" NB: update this caveat when TC1 is blessed. +The support for executing interpreted programs is an extension. +The +.Fn fexecve +system call conforms to The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn execve +system call appeared in +.Bx 4.2 . +The +.Fn fexecve +system call appeared in +.Fx 8.0 . +.Sh CAVEATS +If a program is +.Em setuid +to a non-super-user, but is executed when +the real +.Em uid +is ``root'', then the program has some of the powers +of a super-user as well. +.Pp +When executing an interpreted program through +.Fn fexecve , +kernel supplies +.Pa /dev/fd/n +as a second argument to the interpreter, +where +.Ar n +is the file descriptor passed in the +.Fa fd +argument to +.Fn fexecve . +For this construction to work correctly, the +.Xr fdescfs 5 +filesystem shall be mounted on +.Pa /dev/fd . diff --git a/lib/libc/sys/extattr_get_file.2 b/lib/libc/sys/extattr_get_file.2 new file mode 100644 index 000000000000..db4ea92fd59f --- /dev/null +++ b/lib/libc/sys/extattr_get_file.2 @@ -0,0 +1,276 @@ +.\" +.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> +.\" Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 29, 2008 +.Dt EXTATTR 2 +.Os +.Sh NAME +.Nm extattr_get_fd , +.Nm extattr_set_fd , +.Nm extattr_delete_fd , +.Nm extattr_list_fd , +.Nm extattr_get_file , +.Nm extattr_set_file , +.Nm extattr_delete_file , +.Nm extattr_list_file , +.Nm extattr_get_link , +.Nm extattr_set_link , +.Nm extattr_delete_link , +.Nm extattr_list_link +.Nd system calls to manipulate VFS extended attributes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/extattr.h +.Ft ssize_t +.Fn extattr_get_fd "int fd" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_set_fd "int fd" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" +.Ft int +.Fn extattr_delete_fd "int fd" "int attrnamespace" "const char *attrname" +.Ft ssize_t +.Fn extattr_list_fd "int fd" "int attrnamespace" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_get_file "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_set_file "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" +.Ft int +.Fn extattr_delete_file "const char *path" "int attrnamespace" "const char *attrname" +.Ft ssize_t +.Fn extattr_list_file "const char *path" "int attrnamespace" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_get_link "const char *path" "int attrnamespace" "const char *attrname" "void *data" "size_t nbytes" +.Ft ssize_t +.Fn extattr_set_link "const char *path" "int attrnamespace" "const char *attrname" "const void *data" "size_t nbytes" +.Ft int +.Fn extattr_delete_link "const char *path" "int attrnamespace" "const char *attrname" +.Ft ssize_t +.Fn extattr_list_link "const char *path" "int attrnamespace" "void *data" "size_t nbytes" +.Sh DESCRIPTION +Named extended attributes are meta-data associated with vnodes +representing files and directories. +They exist as +.Qq Li name=value +pairs within a set of namespaces. +.Pp +The +.Fn extattr_get_file +system call retrieves the value of the specified extended attribute into +a buffer pointed to by +.Fa data +of size +.Fa nbytes . +The +.Fn extattr_set_file +system call sets the value of the specified extended attribute to the data +described by +.Fa data . +The +.Fn extattr_delete_file +system call deletes the extended attribute specified. +The +.Fn extattr_list_file +returns a list of attributes present in the requested namespace. +Each list entry consists of a single byte containing the length +of the attribute name, followed by the attribute name. +The attribute name is not terminated by ASCII 0 (nul). +The +.Fn extattr_get_file , +and +.Fn extattr_list_file +calls consume the +.Fa data +and +.Fa nbytes +arguments in the style of +.Xr read 2 ; +.Fn extattr_set_file +consumes these arguments in the style of +.Xr write 2 . +.Pp +If +.Fa data +is +.Dv NULL +in a call to +.Fn extattr_get_file +and +.Fn extattr_list_file +then the size of defined extended attribute data will be returned, rather +than the quantity read, permitting applications to test the size of the +data without performing a read. +The +.Fn extattr_delete_link , +.Fn extattr_get_link , +and +.Fn extattr_set_link +system calls behave in the same way as their _file counterparts, except that +they do not follow symlinks. +.Pp +The +.Fn extattr_get_fd , +.Fn extattr_set_fd , +.Fn extattr_delete_fd , +and +.Fn extattr_list_fd , +calls are identical to their +.Qq Li _file +counterparts except for the first argument. +The +.Qq Li _fd +functions take a file descriptor, while the +.Qq Li _file +functions take a path. +Both arguments describe a file associated with the extended attribute +that should be manipulated. +.Pp +The following arguments are common to all the system calls described here: +.Bl -tag -width attrnamespace +.It Fa attrnamespace +the namespace in which the extended attribute resides; see +.Xr extattr 9 +.It Fa attrname +the name of the extended attribute +.El +.Pp +Named extended attribute semantics vary by file system implementing the call. +Not all operations may be supported for a particular attribute. +Additionally, the format of the data in +.Fa data +is attribute-specific. +.Pp +For more information on named extended attributes, please see +.Xr extattr 9 . +.Sh CAVEAT +This interface is under active development, and as such is subject to +change as applications are adapted to use it. +Developers are discouraged from relying on its stability. +.Sh RETURN VALUES +If successful, the +.Fn extattr_get_file , +.Fn extattr_set_file , +and +.Fn extattr_list_file +calls return the number of bytes +that were read or written from the +.Fa data , +respectively, or if +.Fa data +was +.Dv NULL , +then +.Fn extattr_get_file +and +.Fn extattr_list_file +return the number of bytes available to read. +If any of the calls are unsuccessful, the value \-1 is returned +and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std extattr_delete_file +.Sh ERRORS +The following errors may be returned by the system calls themselves. +Additionally, the file system implementing the call may return any +other errors it desires. +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa attrnamespace +and +.Fa attrname +arguments, +or the memory range defined by +.Fa data +and +.Fa nbytes +point outside the process's allocated address space. +.It Bq Er ENAMETOOLONG +The attribute name was longer than +.Dv EXTATTR_MAXNAMELEN . +.El +.Pp +The +.Fn extattr_get_fd , +.Fn extattr_set_fd , +.Fn extattr_delete_fd , +and +.Fn extattr_list_fd +system calls may also fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The file descriptor referenced by +.Fa fd +was invalid. +.El +.Pp +Additionally, the +.Fn extattr_get_file , +.Fn extattr_set_file , +and +.Fn extattr_delete_file +calls may also fail due to the following errors: +.Bl -tag -width Er +.It Bq Er ENOATTR +The requested attribute was not defined for this file. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path name that must exist does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.\" XXX are any missing? +.El +.Sh SEE ALSO +.Xr extattr 3 , +.Xr getextattr 8 , +.Xr setextattr 8 , +.Xr extattr 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 +.Sh HISTORY +Extended attribute support was developed as part of the +.Tn TrustedBSD +Project, and introduced in +.Fx 5.0 . +It was developed to support security extensions requiring additional labels +to be associated with each file or directory. +.Sh BUGS +In earlier versions of this API, passing an empty string for the +attribute name to +.Fn extattr_get_fd , +.Fn extattr_get_file , +or +.Fn extattr_get_link +would return the list of attributes defined for the target object. +This interface has been deprecated in preference to using the explicit +list API, and should not be used. diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2 new file mode 100644 index 000000000000..cb91fbad079c --- /dev/null +++ b/lib/libc/sys/fcntl.2 @@ -0,0 +1,679 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94 +.\" $FreeBSD$ +.\" +.Dd July 7, 2016 +.Dt FCNTL 2 +.Os +.Sh NAME +.Nm fcntl +.Nd file control +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn fcntl "int fd" "int cmd" "..." +.Sh DESCRIPTION +The +.Fn fcntl +system call provides for control over descriptors. +The argument +.Fa fd +is a descriptor to be operated on by +.Fa cmd +as described below. +Depending on the value of +.Fa cmd , +.Fn fcntl +can take an additional third argument +.Fa "int arg" . +.Bl -tag -width F_DUP2FD_CLOEXEC +.It Dv F_DUPFD +Return a new descriptor as follows: +.Pp +.Bl -bullet -compact -offset 4n +.It +Lowest numbered available descriptor greater than or equal to +.Fa arg . +.It +Same object references as the original descriptor. +.It +New descriptor shares the same file offset if the object +was a file. +.It +Same access mode (read, write or read/write). +.It +Same file status flags (i.e., both file descriptors +share the same file status flags). +.It +The close-on-exec flag +.Dv FD_CLOEXEC +associated with the new file descriptor is cleared, so the file descriptor is +to remain open across +.Xr execve 2 +system calls. +.El +.It Dv F_DUPFD_CLOEXEC +Like +.Dv F_DUPFD , +but the +.Dv FD_CLOEXEC +flag associated with the new file descriptor is set, so the file descriptor +is closed when +.Xr execve 2 +system call executes. +.It Dv F_DUP2FD +It is functionally equivalent to +.Bd -literal -offset indent +dup2(fd, arg) +.Ed +.It Dv F_DUP2FD_CLOEXEC +Like +.Dv F_DUP2FD , +but the +.Dv FD_CLOEXEC +flag associated with the new file descriptor is set. +.Pp +The +.Dv F_DUP2FD +and +.Dv F_DUP2FD_CLOEXEC +constants are not portable, so they should not be used if +portability is needed. +Use +.Fn dup2 +instead of +.Dv F_DUP2FD . +.It Dv F_GETFD +Get the close-on-exec flag associated with the file descriptor +.Fa fd +as +.Dv FD_CLOEXEC . +If the returned value ANDed with +.Dv FD_CLOEXEC +is 0, +the file will remain open across +.Fn exec , +otherwise the file will be closed upon execution of +.Fn exec +.Fa ( arg +is ignored). +.It Dv F_SETFD +Set the close-on-exec flag associated with +.Fa fd +to +.Fa arg , +where +.Fa arg +is either 0 or +.Dv FD_CLOEXEC , +as described above. +.It Dv F_GETFL +Get descriptor status flags, as described below +.Fa ( arg +is ignored). +.It Dv F_SETFL +Set descriptor status flags to +.Fa arg . +.It Dv F_GETOWN +Get the process ID or process group +currently receiving +.Dv SIGIO +and +.Dv SIGURG +signals; process groups are returned +as negative values +.Fa ( arg +is ignored). +.It Dv F_SETOWN +Set the process or process group +to receive +.Dv SIGIO +and +.Dv SIGURG +signals; +process groups are specified by supplying +.Fa arg +as negative, otherwise +.Fa arg +is interpreted as a process ID. +.It Dv F_READAHEAD +Set or clear the read ahead amount for sequential access to the third +argument, +.Fa arg , +which is rounded up to the nearest block size. +A zero value in +.Fa arg +turns off read ahead, a negative value restores the system default. +.It Dv F_RDAHEAD +Equivalent to Darwin counterpart which sets read ahead amount of 128KB +when the third argument, +.Fa arg +is non-zero. +A zero value in +.Fa arg +turns off read ahead. +.El +.Pp +The flags for the +.Dv F_GETFL +and +.Dv F_SETFL +flags are as follows: +.Bl -tag -width O_NONBLOCKX +.It Dv O_NONBLOCK +Non-blocking I/O; if no data is available to a +.Xr read 2 +system call, or if a +.Xr write 2 +operation would block, +the read or write call returns -1 with the error +.Er EAGAIN . +.It Dv O_APPEND +Force each write to append at the end of file; +corresponds to the +.Dv O_APPEND +flag of +.Xr open 2 . +.It Dv O_DIRECT +Minimize or eliminate the cache effects of reading and writing. +The system +will attempt to avoid caching the data you read or write. +If it cannot +avoid caching the data, it will minimize the impact the data has on the cache. +Use of this flag can drastically reduce performance if not used with care. +.It Dv O_ASYNC +Enable the +.Dv SIGIO +signal to be sent to the process group +when I/O is possible, e.g., +upon availability of data to be read. +.El +.Pp +Several commands are available for doing advisory file locking; +they all operate on the following structure: +.Bd -literal +struct flock { + off_t l_start; /* starting offset */ + off_t l_len; /* len = 0 means until end of file */ + pid_t l_pid; /* lock owner */ + short l_type; /* lock type: read/write, etc. */ + short l_whence; /* type of l_start */ + int l_sysid; /* remote system id or zero for local */ +}; +.Ed +The commands available for advisory record locking are as follows: +.Bl -tag -width F_SETLKWX +.It Dv F_GETLK +Get the first lock that blocks the lock description pointed to by the +third argument, +.Fa arg , +taken as a pointer to a +.Fa "struct flock" +(see above). +The information retrieved overwrites the information passed to +.Fn fcntl +in the +.Fa flock +structure. +If no lock is found that would prevent this lock from being created, +the structure is left unchanged by this system call except for the +lock type which is set to +.Dv F_UNLCK . +.It Dv F_SETLK +Set or clear a file segment lock according to the lock description +pointed to by the third argument, +.Fa arg , +taken as a pointer to a +.Fa "struct flock" +(see above). +.Dv F_SETLK +is used to establish shared (or read) locks +.Pq Dv F_RDLCK +or exclusive (or write) locks, +.Pq Dv F_WRLCK , +as well as remove either type of lock +.Pq Dv F_UNLCK . +If a shared or exclusive lock cannot be set, +.Fn fcntl +returns immediately with +.Er EAGAIN . +.It Dv F_SETLKW +This command is the same as +.Dv F_SETLK +except that if a shared or exclusive lock is blocked by other locks, +the process waits until the request can be satisfied. +If a signal that is to be caught is received while +.Fn fcntl +is waiting for a region, the +.Fn fcntl +will be interrupted if the signal handler has not specified the +.Dv SA_RESTART +(see +.Xr sigaction 2 ) . +.El +.Pp +When a shared lock has been set on a segment of a file, +other processes can set shared locks on that segment +or a portion of it. +A shared lock prevents any other process from setting an exclusive +lock on any portion of the protected area. +A request for a shared lock fails if the file descriptor was not +opened with read access. +.Pp +An exclusive lock prevents any other process from setting a shared lock or +an exclusive lock on any portion of the protected area. +A request for an exclusive lock fails if the file was not +opened with write access. +.Pp +The value of +.Fa l_whence +is +.Dv SEEK_SET , +.Dv SEEK_CUR , +or +.Dv SEEK_END +to indicate that the relative offset, +.Fa l_start +bytes, will be measured from the start of the file, +current position, or end of the file, respectively. +The value of +.Fa l_len +is the number of consecutive bytes to be locked. +If +.Fa l_len +is negative, +.Fa l_start +means end edge of the region. +The +.Fa l_pid +and +.Fa l_sysid +fields are only used with +.Dv F_GETLK +to return the process ID of the process holding a blocking lock and +the system ID of the system that owns that process. +Locks created by the local system will have a system ID of zero. +After a successful +.Dv F_GETLK +request, the value of +.Fa l_whence +is +.Dv SEEK_SET . +.Pp +Locks may start and extend beyond the current end of a file, +but may not start or extend before the beginning of the file. +A lock is set to extend to the largest possible value of the +file offset for that file if +.Fa l_len +is set to zero. +If +.Fa l_whence +and +.Fa l_start +point to the beginning of the file, and +.Fa l_len +is zero, the entire file is locked. +If an application wishes only to do entire file locking, the +.Xr flock 2 +system call is much more efficient. +.Pp +There is at most one type of lock set for each byte in the file. +Before a successful return from an +.Dv F_SETLK +or an +.Dv F_SETLKW +request when the calling process has previously existing locks +on bytes in the region specified by the request, +the previous lock type for each byte in the specified +region is replaced by the new lock type. +As specified above under the descriptions +of shared locks and exclusive locks, an +.Dv F_SETLK +or an +.Dv F_SETLKW +request fails or blocks respectively when another process has existing +locks on bytes in the specified region and the type of any of those +locks conflicts with the type specified in the request. +.Pp +The queuing for +.Dv F_SETLKW +requests on local files is fair; +that is, while the thread is blocked, +subsequent requests conflicting with its requests will not be granted, +even if these requests do not conflict with existing locks. +.Pp +This interface follows the completely stupid semantics of System V and +.St -p1003.1-88 +that require that all locks associated with a file for a given process are +removed when +.Em any +file descriptor for that file is closed by that process. +This semantic means that applications must be aware of any files that +a subroutine library may access. +For example if an application for updating the password file locks the +password file database while making the update, and then calls +.Xr getpwnam 3 +to retrieve a record, +the lock will be lost because +.Xr getpwnam 3 +opens, reads, and closes the password database. +The database close will release all locks that the process has +associated with the database, even if the library routine never +requested a lock on the database. +Another minor semantic problem with this interface is that +locks are not inherited by a child process created using the +.Xr fork 2 +system call. +The +.Xr flock 2 +interface has much more rational last close semantics and +allows locks to be inherited by child processes. +The +.Xr flock 2 +system call is recommended for applications that want to ensure the integrity +of their locks when using library routines or wish to pass locks +to their children. +.Pp +The +.Fn fcntl , +.Xr flock 2 , +and +.Xr lockf 3 +locks are compatible. +Processes using different locking interfaces can cooperate +over the same file safely. +However, only one of such interfaces should be used within +the same process. +If a file is locked by a process through +.Xr flock 2 , +any record within the file will be seen as locked +from the viewpoint of another process using +.Fn fcntl +or +.Xr lockf 3 , +and vice versa. +Note that +.Fn fcntl F_GETLK +returns \-1 in +.Fa l_pid +if the process holding a blocking lock previously locked the +file descriptor by +.Xr flock 2 . +.Pp +All locks associated with a file for a given process are +removed when the process terminates. +.Pp +All locks obtained before a call to +.Xr execve 2 +remain in effect until the new program releases them. +If the new program does not know about the locks, they will not be +released until the program exits. +.Pp +A potential for deadlock occurs if a process controlling a locked region +is put to sleep by attempting to lock the locked region of another process. +This implementation detects that sleeping until a locked region is unlocked +would cause a deadlock and fails with an +.Er EDEADLK +error. +.Sh RETURN VALUES +Upon successful completion, the value returned depends on +.Fa cmd +as follows: +.Bl -tag -width F_GETOWNX -offset indent +.It Dv F_DUPFD +A new file descriptor. +.It Dv F_DUP2FD +A file descriptor equal to +.Fa arg . +.It Dv F_GETFD +Value of flag (only the low-order bit is defined). +.It Dv F_GETFL +Value of flags. +.It Dv F_GETOWN +Value of file descriptor owner. +.It other +Value other than -1. +.El +.Pp +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn fcntl +system call will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The argument +.Fa cmd +is +.Dv F_SETLK , +the type of lock +.Pq Fa l_type +is a shared lock +.Pq Dv F_RDLCK +or exclusive lock +.Pq Dv F_WRLCK , +and the segment of a file to be locked is already +exclusive-locked by another process; +or the type is an exclusive lock and some portion of the +segment of a file to be locked is already shared-locked or +exclusive-locked by another process. +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.Pp +The argument +.Fa cmd +is +.Dv F_DUP2FD , +and +.Fa arg +is not a valid file descriptor. +.Pp +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +the type of lock +.Pq Fa l_type +is a shared lock +.Pq Dv F_RDLCK , +and +.Fa fd +is not a valid file descriptor open for reading. +.Pp +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +the type of lock +.Pq Fa l_type +is an exclusive lock +.Pq Dv F_WRLCK , +and +.Fa fd +is not a valid file descriptor open for writing. +.It Bq Er EDEADLK +The argument +.Fa cmd +is +.Dv F_SETLKW , +and a deadlock condition was detected. +.It Bq Er EINTR +The argument +.Fa cmd +is +.Dv F_SETLKW , +and the system call was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa cmd +argument +is +.Dv F_DUPFD +and +.Fa arg +is negative or greater than the maximum allowable number +(see +.Xr getdtablesize 2 ) . +.Pp +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK +or +.Dv F_SETLKW +and the data to which +.Fa arg +points is not valid. +.It Bq Er EMFILE +The argument +.Fa cmd +is +.Dv F_DUPFD +and the maximum number of file descriptors permitted for the +process are already in use, +or no file descriptors greater than or equal to +.Fa arg +are available. +.It Bq Er ENOLCK +The argument +.Fa cmd +is +.Dv F_SETLK +or +.Dv F_SETLKW , +and satisfying the lock or unlock request would result in the +number of locked regions in the system exceeding a system-imposed limit. +.It Bq Er EOPNOTSUPP +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK +or +.Dv F_SETLKW +and +.Fa fd +refers to a file for which locking is not supported. +.It Bq Er EOVERFLOW +The argument +.Fa cmd +is +.Dv F_GETLK , +.Dv F_SETLK +or +.Dv F_SETLKW +and an +.Fa off_t +calculation overflowed. +.It Bq Er EPERM +The +.Fa cmd +argument +is +.Dv F_SETOWN +and +the process ID or process group given as an argument is in a +different session than the caller. +.It Bq Er ESRCH +The +.Fa cmd +argument +is +.Dv F_SETOWN +and +the process ID given as argument is not in use. +.El +.Pp +In addition, if +.Fa fd +refers to a descriptor open on a terminal device (as opposed to a +descriptor open on a socket), a +.Fa cmd +of +.Dv F_SETOWN +can fail for the same reasons as in +.Xr tcsetpgrp 3 , +and a +.Fa cmd +of +.Dv F_GETOWN +for the reasons as stated in +.Xr tcgetpgrp 3 . +.Sh SEE ALSO +.Xr close 2 , +.Xr dup2 2 , +.Xr execve 2 , +.Xr flock 2 , +.Xr getdtablesize 2 , +.Xr open 2 , +.Xr sigaction 2 , +.Xr lockf 3 , +.Xr tcgetpgrp 3 , +.Xr tcsetpgrp 3 +.Sh STANDARDS +The +.Dv F_DUP2FD +constant is non portable. +It is provided for compatibility with AIX and Solaris. +.Pp +Per +.St -susv4 , +a call with +.Dv F_SETLKW +should fail with +.Bq Er EINTR +after any caught signal +and should continue waiting during thread suspension such as a stop signal. +However, in this implementation a call with +.Dv F_SETLKW +is restarted after catching a signal with a +.Dv SA_RESTART +handler or a thread suspension such as a stop signal. +.Sh HISTORY +The +.Fn fcntl +system call appeared in +.Bx 4.2 . +.Pp +The +.Dv F_DUP2FD +constant first appeared in +.Fx 7.1 . diff --git a/lib/libc/sys/fcntl.c b/lib/libc/sys/fcntl.c new file mode 100644 index 000000000000..e85574a6e0e3 --- /dev/null +++ b/lib/libc/sys/fcntl.c @@ -0,0 +1,56 @@ +/*- + * Copyright (c) 2008 Isilon Inc http://www.isilon.com/ + * Authors: Doug Rabson <dfr@rabson.org> + * Developed with Red Inc: Alfred Perlstein <alfred@freebsd.org> + * + * Copyright (c) 2014-2015 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <fcntl.h> +#include <stdarg.h> +#include <sys/types.h> +#include <sys/syscall.h> +#include "libc_private.h" + +#pragma weak fcntl +int +fcntl(int fd, int cmd, ...) +{ + va_list args; + long arg; + + va_start(args, cmd); + arg = va_arg(args, long); + va_end(args); + + return (((int (*)(int, int, ...)) + __libc_interposing[INTERPOS_fcntl])(fd, cmd, arg)); +} diff --git a/lib/libc/sys/fdatasync.c b/lib/libc/sys/fdatasync.c new file mode 100644 index 000000000000..fed97913d31e --- /dev/null +++ b/lib/libc/sys/fdatasync.c @@ -0,0 +1,46 @@ +/* + * Copyright (c) 2016 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/fcntl.h> +#include <unistd.h> +#include "libc_private.h" + +int +fdatasync(int fd) +{ + + return (((int (*)(int))__libc_interposing[INTERPOS_fdatasync])(fd)); +} diff --git a/lib/libc/sys/ffclock.2 b/lib/libc/sys/ffclock.2 new file mode 100644 index 000000000000..78fed527b148 --- /dev/null +++ b/lib/libc/sys/ffclock.2 @@ -0,0 +1,177 @@ +.\" Copyright (c) 2011 The University of Melbourne +.\" All rights reserved. +.\" +.\" This documentation was written by Julien Ridoux at the University of +.\" Melbourne under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 21, 2011 +.Dt FFCLOCK 2 +.Os +.Sh NAME +.Nm ffclock_getcounter , +.Nm ffclock_getestimate , +.Nm ffclock_setestimate +.Nd Retrieve feed-forward counter, get and set feed-forward clock estimates +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/timeffc.h +.Ft int +.Fn ffclock_getcounter "ffcounter *ffcount" +.Ft int +.Fn ffclock_getestimate "struct ffclock_estimate *cest" +.Ft int +.Fn ffclock_setestimate "struct ffclock_estimate *cest" +.Sh DESCRIPTION +The ffclock is an alternative method to synchronise the system clock. +The ffclock implements a feed-forward paradigm and decouples the timestamping +and timekeeping kernel functions. +This ensures that past clock errors do not affect current timekeeping, an +approach radically different from the feedback alternative implemented by the +ntpd daemon when adjusting the system clock. +The feed-forward approach has demonstrated better performance and higher +robustness than a feedback approach when synchronising over the network. +.Pp +In the feed-forward context, a +.Em timestamp +is a cumulative value of the ticks of the timecounter, which can be converted +into seconds by using the feed-forward +.Em clock estimates . +.Pp +The +.Fn ffclock_getcounter +system call allows the calling process to retrieve the current value of the +feed-forward counter maintained by the kernel. +.Pp +The +.Fn ffclock_getestimate +and +.Fn ffclock_setestimate +system calls allow the caller to get and set the kernel's feed-forward clock +parameter estimates respectively. +The +.Fn ffclock_setestimate +system call should be invoked by a single instance of a feed-forward +synchronisation daemon. +The +.Fn ffclock_getestimate +system call can be called by any process to retrieve the feed-forward clock +estimates. +.Pp +The feed-forward approach does not require that the clock estimates be retrieved +every time a timestamp is to be converted into seconds. +The number of system calls can therefore be greatly reduced if the calling +process retrieves the clock estimates from the clock synchronisation daemon +instead. +The +.Fn ffclock_getestimate +must be used when the feed-forward synchronisation daemon is not running +.Po see +.Sx USAGE +below +.Pc . +.Pp +The clock parameter estimates structure pointed to by +.Fa cest +is defined in +.In sys/timeffc.h +as: +.Bd -literal +struct ffclock_estimate { + struct bintime update_time; /* Time of last estimates update. */ + ffcounter update_ffcount; /* Counter value at last update. */ + ffcounter leapsec_next; /* Counter value of next leap second. */ + uint64_t period; /* Estimate of counter period. */ + uint32_t errb_abs; /* Bound on absolute clock error [ns]. */ + uint32_t errb_rate; /* Bound on counter rate error [ps/s]. */ + uint32_t status; /* Clock status. */ + int16_t leapsec_total; /* All leap seconds seen so far. */ + int8_t leapsec; /* Next leap second (in {-1,0,1}). */ +}; +.Ed +.Pp +Only the super-user may set the feed-forward clock estimates. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa ffcount +or +.Fa cest +pointer referenced invalid memory. +.It Bq Er EPERM +A user other than the super-user attempted to set the feed-forward clock +parameter estimates. +.El +.Sh USAGE +The feed-forward paradigm enables the definition of specialised clock functions. +.Pp +In its simplest form, +.Fn ffclock_getcounter +can be used to establish strict order between events or to measure small time +intervals very accurately with a minimum performance cost. +.Pp +Different methods exist to access absolute time +.Po or +.Qq wall-clock time +.Pc tracked by the ffclock. +The simplest method uses the ffclock sysctl interface +.Va kern.ffclock +to make the system clock return the ffclock time. +The +.Xr clock_gettime 2 +system call can then be used to retrieve the current time seen by the +feed-forward clock. +Note that this setting affects the entire system and that a feed-forward +synchronisation daemon should be running. +.Pp +A less automated method consists of retrieving the feed-forward counter +timestamp from the kernel and using the feed-forward clock parameter estimates +to convert the timestamp into seconds. +The feed-forward clock parameter estimates can be retrieved from the kernel or +from the synchronisation daemon directly (preferred). +This method allows converting timestamps using different clock models as needed +by the application, while collecting meaningful upper bounds on current clock +error. +.Sh SEE ALSO +.Xr date 1 , +.Xr adjtime 2 , +.Xr clock_gettime 2 , +.Xr ctime 3 +.Sh HISTORY +Feed-forward clock support first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +The feed-forward clock support was written by +.An Julien Ridoux Aq Mt jridoux@unimelb.edu.au +in collaboration with +.An Darryl Veitch Aq Mt dveitch@unimelb.edu.au +at the University of Melbourne under sponsorship from the FreeBSD Foundation. diff --git a/lib/libc/sys/fhopen.2 b/lib/libc/sys/fhopen.2 new file mode 100644 index 000000000000..2a609c1c2cd2 --- /dev/null +++ b/lib/libc/sys/fhopen.2 @@ -0,0 +1,147 @@ +.\" $NetBSD: fhopen.2,v 1.1 1999/06/30 01:32:15 wrstuden Exp $ +.\" +.\" Copyright (c) 1999 National Aeronautics & Space Administration +.\" All rights reserved. +.\" +.\" This software was written by William Studenmund of the +.\" Numerical Aerospace Simulation Facility, NASA Ames Research Center. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the National Aeronautics & Space Administration +.\" nor the names of its contributors may be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NATIONAL AERONAUTICS & SPACE ADMINISTRATION +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ADMINISTRATION OR CONTRIB- +.\" UTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, +.\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 29, 1999 +.Dt FHOPEN 2 +.Os +.Sh NAME +.Nm fhopen , +.Nm fhstat , +.Nm fhstatfs +.Nd access file via file handle +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/stat.h +.Ft int +.Fn fhopen "const fhandle_t *fhp" "int flags" +.Ft int +.Fn fhstat "const fhandle_t *fhp" "struct stat *sb" +.Ft int +.Fn fhstatfs "const fhandle_t *fhp" "struct statfs *buf" +.Sh DESCRIPTION +These system calls provide a means to access a file given the file handle +.Fa fhp . +As this method bypasses directory access restrictions, these calls are +restricted to the superuser. +.Pp +The +.Fn fhopen +system call +opens the file referenced by +.Fa fhp +for reading and/or writing as specified by the argument +.Fa flags +and returns the file descriptor to the calling process. +The +.Fa flags +argument +is specified by +.Em or Ns 'ing +together the flags used for the +.Xr open 2 +system call. +All said flags are valid except for +.Dv O_CREAT . +.Pp +The +.Fn fhstat +and +.Fn fhstatfs +system calls +provide the functionality of the +.Xr fstat 2 +and +.Xr fstatfs 2 +calls except that they return information for the file referred to by +.Fa fhp +rather than an open file. +.Sh RETURN VALUES +Upon successful completion, +.Fn fhopen +returns the file descriptor for the opened file; +otherwise the value \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std fhstat fhstatfs +.Sh ERRORS +In addition to the errors returned by +.Xr open 2 , +.Xr fstat 2 , +and +.Xr fstatfs 2 +respectively, +.Fn fhopen , +.Fn fhstat , +and +.Fn fhstatfs +will return +.Bl -tag -width Er +.It Bq Er EINVAL +Calling +.Fn fhopen +with +.Dv O_CREAT +set. +.It Bq Er ESTALE +The file handle +.Fa fhp +is no longer valid. +.El +.Sh SEE ALSO +.Xr fstat 2 , +.Xr fstatfs 2 , +.Xr getfh 2 , +.Xr open 2 +.Sh HISTORY +The +.Fn fhopen , +.Fn fhstat , +and +.Fn fhstatfs +system calls first appeared in +.Nx 1.5 +and were adapted to +.Fx 4.0 +by +.An Alfred Perlstein . +.Sh AUTHORS +This manual page was written by +.An William Studenmund +for +.Nx . diff --git a/lib/libc/sys/flock.2 b/lib/libc/sys/flock.2 new file mode 100644 index 000000000000..6106bf4f5100 --- /dev/null +++ b/lib/libc/sys/flock.2 @@ -0,0 +1,173 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)flock.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd November 9, 2011 +.Dt FLOCK 2 +.Os +.Sh NAME +.Nm flock +.Nd "apply or remove an advisory lock on an open file" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/file.h +.Fd "#define LOCK_SH 0x01 /* shared file lock */" +.Fd "#define LOCK_EX 0x02 /* exclusive file lock */" +.Fd "#define LOCK_NB 0x04 /* do not block when locking */" +.Fd "#define LOCK_UN 0x08 /* unlock file */" +.Ft int +.Fn flock "int fd" "int operation" +.Sh DESCRIPTION +The +.Fn flock +system call applies or removes an +.Em advisory +lock on the file associated with the file descriptor +.Fa fd . +A lock is applied by specifying an +.Fa operation +argument that is one of +.Dv LOCK_SH +or +.Dv LOCK_EX +with the optional addition of +.Dv LOCK_NB . +To unlock +an existing lock +.Dv operation +should be +.Dv LOCK_UN . +.Pp +Advisory locks allow cooperating processes to perform +consistent operations on files, but do not guarantee +consistency (i.e., processes may still access files +without using advisory locks possibly resulting in +inconsistencies). +.Pp +The locking mechanism allows two types of locks: +.Em shared +locks and +.Em exclusive +locks. +At any time multiple shared locks may be applied to a file, +but at no time are multiple exclusive, or both shared and exclusive, +locks allowed simultaneously on a file. +.Pp +A shared lock may be +.Em upgraded +to an exclusive lock, and vice versa, simply by specifying +the appropriate lock type; this results in the previous +lock being released and the new lock applied (possibly +after other processes have gained and released the lock). +.Pp +Requesting a lock on an object that is already locked +normally causes the caller to be blocked until the lock may be +acquired. +If +.Dv LOCK_NB +is included in +.Fa operation , +then this will not happen; instead the call will fail and +the error +.Er EWOULDBLOCK +will be returned. +.Sh NOTES +Locks are on files, not file descriptors. +That is, file descriptors +duplicated through +.Xr dup 2 +or +.Xr fork 2 +do not result in multiple instances of a lock, but rather multiple +references to a single lock. +If a process holding a lock on a file +forks and the child explicitly unlocks the file, the parent will +lose its lock. +.Pp +The +.Fn flock , +.Xr fcntl 2 , +and +.Xr lockf 3 +locks are compatible. +Processes using different locking interfaces can cooperate +over the same file safely. +However, only one of such interfaces should be used within +the same process. +If a file is locked by a process through +.Fn flock , +any record within the file will be seen as locked +from the viewpoint of another process using +.Xr fcntl 2 +or +.Xr lockf 3 , +and vice versa. +.Pp +Processes blocked awaiting a lock may be awakened by signals. +.Sh RETURN VALUES +.Rv -std flock +.Sh ERRORS +The +.Fn flock +system call fails if: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +The file is locked and the +.Dv LOCK_NB +option was specified. +.It Bq Er EBADF +The argument +.Fa fd +is an invalid descriptor. +.It Bq Er EINVAL +The argument +.Fa fd +refers to an object other than a file. +.It Bq Er EOPNOTSUPP +The argument +.Fa fd +refers to an object that does not support file locking. +.It Bq Er ENOLCK +A lock was requested, but no locks are available. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr execve 2 , +.Xr fcntl 2 , +.Xr fork 2 , +.Xr open 2 , +.Xr flopen 3 , +.Xr lockf 3 +.Sh HISTORY +The +.Fn flock +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2 new file mode 100644 index 000000000000..4fda74d605e7 --- /dev/null +++ b/lib/libc/sys/fork.2 @@ -0,0 +1,148 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fork.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd May 1, 2015 +.Dt FORK 2 +.Os +.Sh NAME +.Nm fork +.Nd create a new process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn fork void +.Sh DESCRIPTION +The +.Fn fork +system call causes creation of a new process. +The new process (child process) is an exact copy of the +calling process (parent process) except for the following: +.Bl -bullet -offset indent +.It +The child process has a unique process ID. +.It +The child process has a different parent +process ID (i.e., the process ID of the parent process). +.It +The child process has its own copy of the parent's descriptors, +except for descriptors returned by +.Xr kqueue 2 , +which are not inherited from the parent process. +These descriptors reference the same underlying objects, so that, +for instance, file pointers in file objects are shared between +the child and the parent, so that an +.Xr lseek 2 +on a descriptor in the child process can affect a subsequent +.Xr read 2 +or +.Xr write 2 +by the parent. +This descriptor copying is also used by the shell to +establish standard input and output for newly created processes +as well as to set up pipes. +.It +The child process' resource utilizations +are set to 0; see +.Xr setrlimit 2 . +.It +All interval timers are cleared; see +.Xr setitimer 2 . +.It +The child process has only one thread, +corresponding to the calling thread in the parent process. +If the process has more than one thread, +locks and other resources held by the other threads are not released +and therefore only async-signal-safe functions +(see +.Xr sigaction 2 ) +are guaranteed to work in the child process until a call to +.Xr execve 2 +or a similar function. +.El +.Sh RETURN VALUES +Upon successful completion, +.Fn fork +returns a value +of 0 to the child process and returns the process ID of the child +process to the parent process. +Otherwise, a value of -1 is returned +to the parent process, no child process is created, and the global +variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn fork +system call will fail and no child process will be created if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +(The limit is actually ten less than this +except for the super user). +.It Bq Er EAGAIN +The user is not the super user, and +the system-imposed limit +on the total number of +processes under execution by a single user would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROCPERUID . +.It Bq Er EAGAIN +The user is not the super user, and +the soft resource limit corresponding to the +.Fa resource +argument +.Dv RLIMIT_NPROC +would be exceeded (see +.Xr getrlimit 2 ) . +.It Bq Er ENOMEM +There is insufficient swap space for the new process. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr rfork 2 , +.Xr setitimer 2 , +.Xr setrlimit 2 , +.Xr sigaction 2 , +.Xr vfork 2 , +.Xr wait 2 +.Sh HISTORY +The +.Fn fork +function appeared in +.At v6 . diff --git a/lib/libc/sys/fork.c b/lib/libc/sys/fork.c new file mode 100644 index 000000000000..695540a7264f --- /dev/null +++ b/lib/libc/sys/fork.c @@ -0,0 +1,48 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_fork, __fork); + +#pragma weak fork +pid_t +fork(void) +{ + + return (((pid_t (*)(void))__libc_interposing[INTERPOS_fork])()); +} diff --git a/lib/libc/sys/fsync.2 b/lib/libc/sys/fsync.2 new file mode 100644 index 000000000000..3f83291a0dbb --- /dev/null +++ b/lib/libc/sys/fsync.2 @@ -0,0 +1,130 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" Parts of this documentation were written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)fsync.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd August 17, 2016 +.Dt FSYNC 2 +.Os +.Sh NAME +.Nm fdatasync, fsync +.Nd "synchronise changes to a file" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn fdatasync "int fd" +.Ft int +.Fn fsync "int fd" +.Sh DESCRIPTION +The +.Fn fsync +system call +causes all modified data and attributes of the file referenced by +the file descriptor +.Fa fd +to be moved to a permanent storage device. +This normally results in all in-core modified copies +of buffers for the associated file to be written to a disk. +.Pp +The +.Fn fdatasync +system call causes all modified data of +.Fa fd +to be moved to a permanent storage device. +Unlike +.Fn fsync , +the system call does not guarantee that file attributes or +metadata necessary to access the file are committed to the permanent storage. +.Pp +The +.Fn fsync +system call +should be used by programs that require a file to be +in a known state, for example, in building a simple transaction +facility. +If the file metadata has already been committed, using +.Fn fdatasync +can be more efficient than +.Fn fsync . +.Pp +Both +.Fn fdatasync +and +.Fn fsync +calls are cancellation points. +.Sh RETURN VALUES +.Rv -std fsync +.Sh ERRORS +The +.Fn fsync +and +.Fn fdatasync +calls fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument +refers to a socket, not to a file. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr sync 2 , +.Xr syncer 4 , +.Xr sync 8 +.Sh HISTORY +The +.Fn fsync +system call appeared in +.Bx 4.2 . +The +.Fn fdatasync +system call appeared in +.Fx 12.0 +.Sh BUGS +The +.Fn fdatasync +system call currently does not guarantee that enqueued +.Xr aio 4 +requests for the file referenced by +.Fa fd +are completed before the syscall returns. diff --git a/lib/libc/sys/fsync.c b/lib/libc/sys/fsync.c new file mode 100644 index 000000000000..5f1512932baa --- /dev/null +++ b/lib/libc/sys/fsync.c @@ -0,0 +1,48 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/fcntl.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_fsync, __fsync); + +int +fsync(int fd) +{ + + return (((int (*)(int))__libc_interposing[INTERPOS_fsync])(fd)); +} diff --git a/lib/libc/sys/futimens.c b/lib/libc/sys/futimens.c new file mode 100644 index 000000000000..59fb37f5249a --- /dev/null +++ b/lib/libc/sys/futimens.c @@ -0,0 +1,100 @@ +/*- + * Copyright (c) 2015 Jilles Tjoelker + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include "namespace.h" +#include <sys/stat.h> + +#include <errno.h> +#include <fcntl.h> +#include <time.h> +#include "un-namespace.h" + +#include "libc_private.h" + +int +futimens(int fd, const struct timespec times[2]) +{ + struct timeval now, tv[2], *tvp; + struct stat sb; + int osreldate; + + osreldate = __getosreldate(); + if (osreldate >= 1100056 || + (osreldate >= 1002506 && osreldate < 1100000)) + return (__sys_futimens(fd, times)); + + if (times == NULL || (times[0].tv_nsec == UTIME_NOW && + times[1].tv_nsec == UTIME_NOW)) + tvp = NULL; + else if (times[0].tv_nsec == UTIME_OMIT && + times[1].tv_nsec == UTIME_OMIT) + return (0); + else { + if ((times[0].tv_nsec < 0 || times[0].tv_nsec > 999999999) && + times[0].tv_nsec != UTIME_NOW && + times[0].tv_nsec != UTIME_OMIT) { + errno = EINVAL; + return (-1); + } + if ((times[1].tv_nsec < 0 || times[1].tv_nsec > 999999999) && + times[1].tv_nsec != UTIME_NOW && + times[1].tv_nsec != UTIME_OMIT) { + errno = EINVAL; + return (-1); + } + tv[0].tv_sec = times[0].tv_sec; + tv[0].tv_usec = times[0].tv_nsec / 1000; + tv[1].tv_sec = times[1].tv_sec; + tv[1].tv_usec = times[1].tv_nsec / 1000; + tvp = tv; + if (times[0].tv_nsec == UTIME_OMIT || + times[1].tv_nsec == UTIME_OMIT) { + if (_fstat(fd, &sb) == -1) + return (-1); + if (times[0].tv_nsec == UTIME_OMIT) { + tv[0].tv_sec = sb.st_atim.tv_sec; + tv[0].tv_usec = sb.st_atim.tv_nsec / 1000; + } + if (times[1].tv_nsec == UTIME_OMIT) { + tv[1].tv_sec = sb.st_mtim.tv_sec; + tv[1].tv_usec = sb.st_mtim.tv_nsec / 1000; + } + } + if (times[0].tv_nsec == UTIME_NOW || + times[1].tv_nsec == UTIME_NOW) { + if (gettimeofday(&now, NULL) == -1) + return (-1); + if (times[0].tv_nsec == UTIME_NOW) + tv[0] = now; + if (times[1].tv_nsec == UTIME_NOW) + tv[1] = now; + } + } + return (futimes(fd, tvp)); +} diff --git a/lib/libc/sys/getdirentries.2 b/lib/libc/sys/getdirentries.2 new file mode 100644 index 000000000000..e4f61dbe82da --- /dev/null +++ b/lib/libc/sys/getdirentries.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95 +.\" $FreeBSD$ +.\" +.Dd May 3, 1995 +.Dt GETDIRENTRIES 2 +.Os +.Sh NAME +.Nm getdirentries , +.Nm getdents +.Nd "get directory entries in a file system independent format" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In dirent.h +.Ft int +.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" +.Ft int +.Fn getdents "int fd" "char *buf" "int nbytes" +.Sh DESCRIPTION +The +.Fn getdirentries +and +.Fn getdents +system calls read directory entries from the directory +referenced by the file descriptor +.Fa fd +into the buffer pointed to by +.Fa buf , +in a file system independent format. +Up to +.Fa nbytes +of data will be transferred. +The +.Fa nbytes +argument must be greater than or equal to the +block size associated with the file, +see +.Xr stat 2 . +Some file systems may not support these system calls +with buffers smaller than this size. +.Pp +The data in the buffer is a series of +.Vt dirent +structures each containing the following entries: +.Bd -literal -offset indent +uint32_t d_fileno; +uint16_t d_reclen; +uint8_t d_type; +uint8_t d_namlen; +char d_name[MAXNAMLEN + 1]; /* see below */ +.Ed +.Pp +The +.Fa d_fileno +entry is a number which is unique for each +distinct file in the file system. +Files that are linked by hard links (see +.Xr link 2 ) +have the same +.Fa d_fileno . +The +.Fa d_reclen +entry is the length, in bytes, of the directory record. +The +.Fa d_type +entry is the type of the file pointed to by the directory record. +The file type values are defined in +.Fa <sys/dirent.h> . +The +.Fa d_name +entry contains a null terminated file name. +The +.Fa d_namlen +entry specifies the length of the file name excluding the null byte. +Thus the actual size of +.Fa d_name +may vary from 1 to +.Dv MAXNAMLEN +\&+ 1. +.Pp +Entries may be separated by extra space. +The +.Fa d_reclen +entry may be used as an offset from the start of a +.Fa dirent +structure to the next structure, if any. +.Pp +The actual number of bytes transferred is returned. +The current position pointer associated with +.Fa fd +is set to point to the next block of entries. +The pointer may not advance by the number of bytes returned by +.Fn getdirentries +or +.Fn getdents . +A value of zero is returned when +the end of the directory has been reached. +.Pp +The +.Fn getdirentries +system call writes the position of the block read into the location pointed to by +.Fa basep . +Alternatively, the current position pointer may be set and retrieved by +.Xr lseek 2 . +The current position pointer should only be set to a value returned by +.Xr lseek 2 , +a value returned in the location pointed to by +.Fa basep +.Po Fn getdirentries +only +.Pc +or zero. +.Sh RETURN VALUES +If successful, the number of bytes actually transferred is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn getdirentries +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid file descriptor open for reading. +.It Bq Er EFAULT +Either +.Fa buf +or +.Fa basep +point outside the allocated address space. +.It Bq Er EINVAL +The file referenced by +.Fa fd +is not a directory, or +.Fa nbytes +is too small for returning a directory entry or block of entries, +or the current position pointer is invalid. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr lseek 2 , +.Xr open 2 +.Sh HISTORY +The +.Fn getdirentries +system call first appeared in +.Bx 4.4 . +The +.Fn getdents +system call first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/getdtablesize.2 b/lib/libc/sys/getdtablesize.2 new file mode 100644 index 000000000000..c47189123bd8 --- /dev/null +++ b/lib/libc/sys/getdtablesize.2 @@ -0,0 +1,62 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getdtablesize.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 24, 2013 +.Dt GETDTABLESIZE 2 +.Os +.Sh NAME +.Nm getdtablesize +.Nd get file descriptor limit +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getdtablesize void +.Sh DESCRIPTION +The +.Fn getdtablesize +system call returns the maximum number of file descriptors +that the current process may open. +The maximum file descriptor number that the system may assign +is the return value minus one. +Existing file descriptor numbers may be higher +if the limit was lowered after they were opened. +.Sh SEE ALSO +.Xr close 2 , +.Xr closefrom 2 , +.Xr dup 2 , +.Xr getrlimit 2 , +.Xr sysconf 3 +.Sh HISTORY +The +.Fn getdtablesize +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getfh.2 b/lib/libc/sys/getfh.2 new file mode 100644 index 000000000000..b44d4af001f0 --- /dev/null +++ b/lib/libc/sys/getfh.2 @@ -0,0 +1,115 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getfh.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd April 14, 2011 +.Dt GETFH 2 +.Os +.Sh NAME +.Nm getfh , +.Nm lgetfh +.Nd get file handle +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn getfh "const char *path" "fhandle_t *fhp" +.Ft int +.Fn lgetfh "const char *path" "fhandle_t *fhp" +.Sh DESCRIPTION +The +.Fn getfh +system call +returns a file handle for the specified file or directory +in the file handle pointed to by +.Fa fhp . +The +.Fn lgetfh +system call is like +.Fn getfh +except in the case where the named file is a symbolic link, +in which case +.Fn lgetfh +returns information about the link, +while +.Fn getfh +returns information about the file the link references. +These system calls are restricted to the superuser. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getfh +and +.Fn lgetfh +system calls +fail if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix of +.Fa path +is not a directory. +.It Bq Er ENAMETOOLONG +The length of a component of +.Fa path +exceeds 255 characters, +or the length of +.Fa path +exceeds 1023 characters. +.It Bq Er ENOENT +The file referred to by +.Fa path +does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix of +.Fa path . +.It Bq Er ELOOP +Too many symbolic links were encountered in translating +.Fa path . +.It Bq Er EFAULT +The +.Fa fhp +argument +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr fhopen 2 , +.Xr open 2 , +.Xr stat 2 +.Sh HISTORY +The +.Fn getfh +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/getfsstat.2 b/lib/libc/sys/getfsstat.2 new file mode 100644 index 000000000000..08cdf49d6e39 --- /dev/null +++ b/lib/libc/sys/getfsstat.2 @@ -0,0 +1,130 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getfsstat.2 8.3 (Berkeley) 5/25/95 +.\" $FreeBSD$ +.\" +.Dd December 27, 2016 +.Dt GETFSSTAT 2 +.Os +.Sh NAME +.Nm getfsstat +.Nd get list of all mounted file systems +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.In sys/mount.h +.Ft int +.Fn getfsstat "struct statfs *buf" "long bufsize" "int mode" +.Sh DESCRIPTION +The +.Fn getfsstat +system call +returns information about all mounted file systems. +The +.Fa buf +argument +is a pointer to +.Vt statfs +structures, as described in +.Xr statfs 2 . +.Pp +Fields that are undefined for a particular file system are set to -1. +The buffer is filled with an array of +.Fa statfs +structures, one for each mounted file system +up to the byte count specified by +.Fa bufsize . +Note, the +.Fa bufsize +argument is the number of bytes that +.Fa buf +can hold, not the count of statfs structures it will hold. +.Pp +If +.Fa buf +is given as NULL, +.Fn getfsstat +returns just the number of mounted file systems. +.Pp +Normally +.Fa mode +should be specified as +.Dv MNT_WAIT . +If +.Fa mode +is set to +.Dv MNT_NOWAIT , +.Fn getfsstat +will return the information it has available without requesting +an update from each file system. +Thus, some of the information will be out of date, but +.Fn getfsstat +will not block waiting for information from a file system that is +unable to respond. +It will also skip any file system that is in the process of being +unmounted, even if the unmount would eventually fail. +.Sh RETURN VALUES +Upon successful completion, the number of +.Fa statfs +structures is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn getfsstat +system call +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa buf +argument +points to an invalid address. +.It Bq Er EINVAL +.Fa mode +is set to a value other than +.Dv MNT_WAIT +or +.Dv MNT_NOWAIT . +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr statfs 2 , +.Xr fstab 5 , +.Xr mount 8 +.Sh HISTORY +The +.Fn getfsstat +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/getgid.2 b/lib/libc/sys/getgid.2 new file mode 100644 index 000000000000..5bd2a94b9dc1 --- /dev/null +++ b/lib/libc/sys/getgid.2 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getgid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt GETGID 2 +.Os +.Sh NAME +.Nm getgid , +.Nm getegid +.Nd get group process identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft gid_t +.Fn getgid void +.Ft gid_t +.Fn getegid void +.Sh DESCRIPTION +The +.Fn getgid +system call returns the real group ID of the calling process, +.Fn getegid +returns the effective group ID of the calling process. +.Pp +The real group ID is specified at login time. +.Pp +The real group ID is the group of the user who invoked the program. +As the effective group ID gives the process additional permissions +during the execution of +.Dq Em set-group-ID +mode processes, +.Fn getgid +is used to determine the real-user-id of the calling process. +.Sh ERRORS +The +.Fn getgid +and +.Fn getegid +system calls are always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr setgid 2 , +.Xr setregid 2 +.Sh STANDARDS +The +.Fn getgid +and +.Fn getegid +system calls are expected to conform to +.St -p1003.1-90 . diff --git a/lib/libc/sys/getgroups.2 b/lib/libc/sys/getgroups.2 new file mode 100644 index 000000000000..66238a15ce90 --- /dev/null +++ b/lib/libc/sys/getgroups.2 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getgroups.2 8.2 (Berkeley) 4/16/94 +.\" $FreeBSD$ +.\" +.Dd January 21, 2011 +.Dt GETGROUPS 2 +.Os +.Sh NAME +.Nm getgroups +.Nd get group access list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getgroups "int gidsetlen" "gid_t *gidset" +.Sh DESCRIPTION +The +.Fn getgroups +system call +gets the current group access list of the user process +and stores it in the array +.Fa gidset . +The +.Fa gidsetlen +argument +indicates the number of entries that may be placed in +.Fa gidset . +The +.Fn getgroups +system call +returns the actual number of groups returned in +.Fa gidset . +At least one and as many as {NGROUPS_MAX}+1 values may be returned. +If +.Fa gidsetlen +is zero, +.Fn getgroups +returns the number of supplementary group IDs associated with +the calling process without modifying the array pointed to by +.Fa gidset . +.Pp +The value of +.Dv {NGROUPS_MAX} +should be obtained using +.Xr sysconf 3 +to avoid hard-coding it into the executable. +.Sh RETURN VALUES +A successful call returns the number of groups in the group set. +A value of -1 indicates that an error occurred, and the error +code is stored in the global variable +.Va errno . +.Sh ERRORS +The possible errors for +.Fn getgroups +are: +.Bl -tag -width Er +.It Bq Er EINVAL +The argument +.Fa gidsetlen +is smaller than the number of groups in the group set. +.It Bq Er EFAULT +The argument +.Fa gidset +specifies +an invalid address. +.El +.Sh SEE ALSO +.Xr setgroups 2 , +.Xr initgroups 3 , +.Xr sysconf 3 +.Sh STANDARDS +The +.Fn getgroups +system call conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn getgroups +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getitimer.2 b/lib/libc/sys/getitimer.2 new file mode 100644 index 000000000000..539dea61bec1 --- /dev/null +++ b/lib/libc/sys/getitimer.2 @@ -0,0 +1,180 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getitimer.2 8.3 (Berkeley) 5/16/95 +.\" $FreeBSD$ +.\" +.Dd May 16, 1995 +.Dt GETITIMER 2 +.Os +.Sh NAME +.Nm getitimer , +.Nm setitimer +.Nd get/set value of interval timer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Fd "#define ITIMER_REAL 0" +.Fd "#define ITIMER_VIRTUAL 1" +.Fd "#define ITIMER_PROF 2" +.Ft int +.Fn getitimer "int which" "struct itimerval *value" +.Ft int +.Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue" +.Sh DESCRIPTION +The system provides each process with three interval timers, +defined in +.In sys/time.h . +The +.Fn getitimer +system call returns the current value for the timer specified in +.Fa which +in the structure at +.Fa value . +The +.Fn setitimer +system call sets a timer to the specified +.Fa value +(returning the previous value of the timer if +.Fa ovalue +is not a null pointer). +.Pp +A timer value is defined by the +.Fa itimerval +structure: +.Bd -literal -offset indent +struct itimerval { + struct timeval it_interval; /* timer interval */ + struct timeval it_value; /* current value */ +}; +.Ed +.Pp +If +.Fa it_value +is non-zero, it indicates the time to the next timer expiration. +If +.Fa it_interval +is non-zero, it specifies a value to be used in reloading +.Fa it_value +when the timer expires. +Setting +.Fa it_value +to 0 disables a timer, regardless of the value of +.Fa it_interval . +Setting +.Fa it_interval +to 0 causes a timer to be disabled after its next expiration (assuming +.Fa it_value +is non-zero). +.Pp +Time values smaller than the resolution of the +system clock are rounded up to this resolution +(typically 10 milliseconds). +.Pp +The +.Dv ITIMER_REAL +timer decrements in real time. +A +.Dv SIGALRM +signal is +delivered when this timer expires. +.Pp +The +.Dv ITIMER_VIRTUAL +timer decrements in process virtual time. +It runs only when the process is executing. +A +.Dv SIGVTALRM +signal +is delivered when it expires. +.Pp +The +.Dv ITIMER_PROF +timer decrements both in process virtual time and +when the system is running on behalf of the process. +It is designed +to be used by interpreters in statistically profiling the execution +of interpreted programs. +Each time the +.Dv ITIMER_PROF +timer expires, the +.Dv SIGPROF +signal is +delivered. +Because this signal may interrupt in-progress +system calls, programs using this timer must be prepared to +restart interrupted system calls. +.Pp +The maximum number of seconds allowed for +.Fa it_interval +and +.Fa it_value +in +.Fn setitimer +is 100000000. +.Sh NOTES +Three macros for manipulating time values are defined in +.In sys/time.h . +The +.Fn timerclear +macro +sets a time value to zero, +.Fn timerisset +tests if a time value is non-zero, and +.Fn timercmp +compares two time values. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getitimer +and +.Fn setitimer +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa value +argument specified a bad address. +.It Bq Er EINVAL +The +.Fa value +argument specified a time that was too large +to be handled. +.El +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr select 2 , +.Xr sigaction 2 , +.Xr clocks 7 +.Sh HISTORY +The +.Fn getitimer +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getlogin.2 b/lib/libc/sys/getlogin.2 new file mode 100644 index 000000000000..b7c27df3329a --- /dev/null +++ b/lib/libc/sys/getlogin.2 @@ -0,0 +1,204 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getlogin.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd June 9, 1993 +.Dt GETLOGIN 2 +.Os +.Sh NAME +.Nm getlogin , +.Nm getlogin_r , +.Nm setlogin +.Nd get/set login name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft char * +.Fn getlogin void +.In sys/param.h +.Ft int +.Fn getlogin_r "char *name" "int len" +.Ft int +.Fn setlogin "const char *name" +.Sh DESCRIPTION +The +.Fn getlogin +routine +returns the login name of the user associated with the current session, +as previously set by +.Fn setlogin . +The name is normally associated with a login shell +at the time a session is created, +and is inherited by all processes descended from the login shell. +(This is true even if some of those processes assume another user ID, +for example when +.Xr su 1 +is used). +.Pp +The +.Fn getlogin_r +function +provides the same service as +.Fn getlogin +except the caller must provide the buffer +.Fa name +with length +.Fa len +bytes +to hold the result. +The buffer should be at least +.Dv MAXLOGNAME +bytes in length. +.Pp +The +.Fn setlogin +system call +sets the login name of the user associated with the current session to +.Fa name . +This system call is restricted to the super-user, and +is normally used only when a new session is being created on behalf +of the named user +(for example, at login time, or when a remote shell is invoked). +.Pp +.Em NOTE : +There is only one login name per session. +.Pp +It is +.Em CRITICALLY +important to ensure that +.Fn setlogin +is only ever called after the process has taken adequate steps to ensure +that it is detached from its parent's session. +Making a +.Fn setsid +system call is the +.Em ONLY +way to do this. +The +.Xr daemon 3 +function calls +.Fn setsid +which is an ideal way of detaching from a controlling terminal and +forking into the background. +.Pp +In particular, doing a +.Fn ioctl ttyfd TIOCNOTTY ...\& +or +.Fn setpgrp ...\& +is +.Em NOT +sufficient. +.Pp +Once a parent process does a +.Fn setsid +system call, it is acceptable for some child of that process to then do a +.Fn setlogin +even though it is not the session leader, but beware that ALL processes +in the session will change their login name at the same time, even the +parent. +.Pp +This is not the same as the traditional UNIX behavior of inheriting privilege. +.Pp +Since the +.Fn setlogin +system call is restricted to the super-user, it is assumed that (like +all other privileged programs) the programmer has taken adequate +precautions to prevent security violations. +.Sh RETURN VALUES +If a call to +.Fn getlogin +succeeds, it returns a pointer to a null-terminated string in a static buffer, +or +.Dv NULL +if the name has not been set. +The +.Fn getlogin_r +function +returns zero if successful, or the error number upon failure. +.Pp +.Rv -std setlogin +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +argument gave an +invalid address. +.It Bq Er EINVAL +The +.Fa name +argument +pointed to a string that was too long. +Login names are limited to +.Dv MAXLOGNAME +(from +.In sys/param.h ) +characters, currently 17 including null. +.It Bq Er EPERM +The caller tried to set the login name and was not the super-user. +.It Bq Er ERANGE +The size of the buffer is smaller than the result to be returned. +.El +.Sh SEE ALSO +.Xr setsid 2 , +.Xr daemon 3 +.Sh STANDARDS +The +.Fn getlogin +system call +and +the +.Fn getlogin_r +function +conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn getlogin +system call first appeared in +.Bx 4.4 . +The return value of +.Fn getlogin_r +was changed from earlier versions of +.Fx +to be conformant with +.St -p1003.1-96 . +.Sh BUGS +In earlier versions of the system, +.Fn getlogin +failed unless the process was associated with a login terminal. +The current implementation (using +.Fn setlogin ) +allows getlogin to succeed even when the process has no controlling terminal. +In earlier versions of the system, the value returned by +.Fn getlogin +could not be trusted without checking the user ID. +Portable programs should probably still make this check. diff --git a/lib/libc/sys/getloginclass.2 b/lib/libc/sys/getloginclass.2 new file mode 100644 index 000000000000..6249d830c82e --- /dev/null +++ b/lib/libc/sys/getloginclass.2 @@ -0,0 +1,100 @@ +.\"- +.\" Copyright (c) 2011 Edward Tomasz Napierala +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 12, 2016 +.Dt GETLOGINCLASS 2 +.Os +.Sh NAME +.Nm getloginclass , +.Nm setloginclass +.Nd get/set login class +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getloginclass "char *name" "size_t len" +.Ft int +.Fn setloginclass "const char *name" +.Sh DESCRIPTION +The +.Fn getloginclass +routine returns the login class name associated with the calling process, +as previously set by +.Fn setloginclass . +The caller must provide the buffer +.Fa name +with length +.Fa len +bytes to hold the result. +The buffer should be at least +.Dv MAXLOGNAME +bytes in length. +.Pp +The +.Fn setloginclass +system call sets the login class of the calling process to +.Fa name . +This system call is restricted to the super-user, and is normally used +only when a new session is being created on behalf of the named user +(for example, at login time, or when a remote shell is invoked). +Processes inherit login class from their parents. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following errors may be returned by these calls: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa name +argument gave an invalid address. +.It Bq Er EINVAL +The +.Fa name +argument pointed to a string that was too long. +Login class names are limited to +.Dv MAXLOGNAME +(from +.In sys/param.h ) +characters, currently 17 including null. +.It Bq Er EPERM +The caller tried to set the login class and was not the super-user. +.It Bq Er ENAMETOOLONG +The size of the buffer is smaller than the result to be returned. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr setusercontext 3 , +.Xr login.conf 5 , +.Xr rctl 8 +.Sh HISTORY +The +.Fn getloginclass +and +.Fn setloginclass +system calls first appeared in +.Fx 9.0 . diff --git a/lib/libc/sys/getpeername.2 b/lib/libc/sys/getpeername.2 new file mode 100644 index 000000000000..255c7a01bb88 --- /dev/null +++ b/lib/libc/sys/getpeername.2 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpeername.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt GETPEERNAME 2 +.Os +.Sh NAME +.Nm getpeername +.Nd get name of connected peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getpeername "int s" "struct sockaddr * restrict name" "socklen_t * restrict namelen" +.Sh DESCRIPTION +The +.Fn getpeername +system call +returns the name of the peer connected to +socket +.Fa s . +The +.Fa namelen +argument should be initialized to indicate +the amount of space pointed to by +.Fa name . +On return it contains the actual size of the name +returned (in bytes). +The name is truncated if the buffer provided is too small. +.Sh RETURN VALUES +.Rv -std getpeername +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ECONNRESET +The connection has been reset by the peer. +.It Bq Er EINVAL +The value of the +.Fa namelen +argument is not valid. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOTCONN +The socket is not connected. +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.It Bq Er EFAULT +The +.Fa name +argument points to memory not in a valid part of the +process address space. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr getsockname 2 , +.Xr socket 2 +.Sh HISTORY +The +.Fn getpeername +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getpgrp.2 b/lib/libc/sys/getpgrp.2 new file mode 100644 index 000000000000..f5e81a8a81e5 --- /dev/null +++ b/lib/libc/sys/getpgrp.2 @@ -0,0 +1,142 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpgrp.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt GETPGRP 2 +.Os +.Sh NAME +.Nm getpgrp +.Nd get process group +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn getpgrp void +.Ft pid_t +.Fn getpgid "pid_t pid" +.Sh DESCRIPTION +The process group of the current process is returned by +.Fn getpgrp . +The process group of the process identified by +.Fa pid +is returned by +.Fn getpgid . +If +.Fa pid +is zero, +.Fn getpgid +returns the process group of the current process. +.Pp +Process groups are used for distribution of signals, and +by terminals to arbitrate requests for their input: processes +that have the same process group as the terminal are foreground +and may read, while others will block with a signal if they attempt +to read. +.Pp +This system call is thus used by programs such as +.Xr csh 1 +to create +process groups +in implementing job control. +The +.Fn tcgetpgrp +and +.Fn tcsetpgrp +calls +are used to get/set the process group of the control terminal. +.Sh RETURN VALUES +The +.Fn getpgrp +system call always succeeds. +Upon successful completion, the +.Fn getpgid +system call returns the process group of the specified process; +otherwise, it returns a value of \-1 and sets +.Va errno +to indicate the error. +.Sh COMPATIBILITY +This version of +.Fn getpgrp +differs from past Berkeley versions by not taking a +.Fa "pid_t pid" +argument. +This incompatibility is required by +.St -p1003.1-90 . +.Pp +From the +.St -p1003.1-90 +Rationale: +.Pp +.Bx 4.3 +provides a +.Fn getpgrp +system call that returns the process group ID for a specified process. +Although this function is used to support job control, all known +job-control shells always specify the calling process with this +function. +Thus, the simpler +.At V +.Fn getpgrp +suffices, and the added complexity of the +.Bx 4.3 +.Fn getpgrp +has been omitted from POSIX.1. +The old functionality is available from the +.Fn getpgid +system call. +.Sh ERRORS +The +.Fn getpgid +system call +will succeed unless: +.Bl -tag -width Er +.It Bq Er ESRCH +there is no process whose process ID equals +.Fa pid +.El +.Sh SEE ALSO +.Xr getsid 2 , +.Xr setpgid 2 , +.Xr termios 4 +.Sh STANDARDS +The +.Fn getpgrp +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getpgrp +system call appeared in +.Bx 4.0 . +The +.Fn getpgid +system call is derived from its usage in +.At V.4 . diff --git a/lib/libc/sys/getpid.2 b/lib/libc/sys/getpid.2 new file mode 100644 index 000000000000..ab69f7117aeb --- /dev/null +++ b/lib/libc/sys/getpid.2 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt GETPID 2 +.Os +.Sh NAME +.Nm getpid , +.Nm getppid +.Nd get parent or calling process identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn getpid void +.Ft pid_t +.Fn getppid void +.Sh DESCRIPTION +The +.Fn getpid +system call +returns +the process ID of +the calling process. +Though the ID is guaranteed to be unique, it should +.Em NOT +be used for constructing temporary file names, for +security reasons; see +.Xr mkstemp 3 +instead. +.Pp +The +.Fn getppid +system call +returns the process ID of the parent +of the calling process. +.Sh ERRORS +The +.Fn getpid +and +.Fn getppid +system calls are always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr fork 2 , +.Xr getpgrp 2 , +.Xr kill 2 , +.Xr setpgid 2 , +.Xr setsid 2 , +.Xr exec 3 +.Sh STANDARDS +The +.Fn getpid +and +.Fn getppid +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getpid +function appeared in +.At v7 . diff --git a/lib/libc/sys/getpriority.2 b/lib/libc/sys/getpriority.2 new file mode 100644 index 000000000000..ae70f5f441d5 --- /dev/null +++ b/lib/libc/sys/getpriority.2 @@ -0,0 +1,150 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getpriority.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt GETPRIORITY 2 +.Os +.Sh NAME +.Nm getpriority , +.Nm setpriority +.Nd get/set program scheduling priority +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.In sys/resource.h +.Ft int +.Fn getpriority "int which" "int who" +.Ft int +.Fn setpriority "int which" "int who" "int prio" +.Sh DESCRIPTION +The scheduling +priority of the process, process group, or user, as indicated by +.Fa which +and +.Fa who +is obtained with the +.Fn getpriority +system call and set with the +.Fn setpriority +system call. +The +.Fa which +argument +is one of +.Dv PRIO_PROCESS , +.Dv PRIO_PGRP , +or +.Dv PRIO_USER , +and +.Fa who +is interpreted relative to +.Fa which +(a process identifier for +.Dv PRIO_PROCESS , +process group +identifier for +.Dv PRIO_PGRP , +and a user ID for +.Dv PRIO_USER ) . +A zero value of +.Fa who +denotes the current process, process group, or user. +The +.Fa prio +argument +is a value in the range -20 to 20. +The default priority is 0; +lower priorities cause more favorable scheduling. +.Pp +The +.Fn getpriority +system call returns the highest priority (lowest numerical value) +enjoyed by any of the specified processes. +The +.Fn setpriority +system call sets the priorities of all of the specified processes +to the specified value. +Only the super-user may lower priorities. +.Sh RETURN VALUES +Since +.Fn getpriority +can legitimately return the value -1, it is necessary +to clear the external variable +.Va errno +prior to the +call, then check it afterward to determine +if a -1 is an error or a legitimate value. +.Pp +.Rv -std setpriority +.Sh ERRORS +The +.Fn getpriority +and +.Fn setpriority +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +No process was located using the +.Fa which +and +.Fa who +values specified. +.It Bq Er EINVAL +The +.Fa which +argument +was not one of +.Dv PRIO_PROCESS , +.Dv PRIO_PGRP , +or +.Dv PRIO_USER . +.El +.Pp +In addition to the errors indicated above, +.Fn setpriority +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +A process was located, but neither its effective nor real user +ID matched the effective user ID of the caller. +.It Bq Er EACCES +A non super-user attempted to lower a process priority. +.El +.Sh SEE ALSO +.Xr nice 1 , +.Xr fork 2 , +.Xr renice 8 +.Sh HISTORY +The +.Fn getpriority +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getrlimit.2 b/lib/libc/sys/getrlimit.2 new file mode 100644 index 000000000000..1ac01d396ee9 --- /dev/null +++ b/lib/libc/sys/getrlimit.2 @@ -0,0 +1,238 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getrlimit.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd September 30, 2016 +.Dt GETRLIMIT 2 +.Os +.Sh NAME +.Nm getrlimit , +.Nm setrlimit +.Nd control maximum system resource consumption +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/resource.h +.Ft int +.Fn getrlimit "int resource" "struct rlimit *rlp" +.Ft int +.Fn setrlimit "int resource" "const struct rlimit *rlp" +.Sh DESCRIPTION +Limits on the consumption of system resources by the current process +and each process it creates may be obtained with the +.Fn getrlimit +system call, and set with the +.Fn setrlimit +system call. +.Pp +The +.Fa resource +argument is one of the following: +.Bl -tag -width RLIMIT_FSIZEAA +.It Dv RLIMIT_AS +The maximum amount (in bytes) of virtual memory the process is +allowed to map. +.It Dv RLIMIT_CORE +The largest size (in bytes) +.Xr core 5 +file that may be created. +.It Dv RLIMIT_CPU +The maximum amount of cpu time (in seconds) to be used by +each process. +.It Dv RLIMIT_DATA +The maximum size (in bytes) of the data segment for a process; +this defines how far a program may extend its break with the +.Xr sbrk 2 +function. +.It Dv RLIMIT_FSIZE +The largest size (in bytes) file that may be created. +.It Dv RLIMIT_KQUEUES +The maximum number of kqueues this user id is allowed to create. +.It Dv RLIMIT_MEMLOCK +The maximum size (in bytes) which a process may lock into memory +using the +.Xr mlock 2 +system call. +.It Dv RLIMIT_NOFILE +The maximum number of open files for this process. +.It Dv RLIMIT_NPROC +The maximum number of simultaneous processes for this user id. +.It Dv RLIMIT_NPTS +The maximum number of pseudo-terminals this user id is allowed to create. +.It Dv RLIMIT_RSS +When there is memory pressure and swap is available, prioritize eviction of +a process' resident pages beyond this amount (in bytes). +When memory is not under pressure, this rlimit is effectively ignored. +Even when there is memory pressure, the amount of available swap space and some +sysctl settings like +.Xr vm.swap_enabled +and +.Xr vm.swap_idle_enabled +can affect what happens to processes that have exceeded this size. +.Pp +Processes that exceed their set +.Dv RLIMIT_RSS +are not signalled or halted. +The limit is merely a hint to the VM daemon to prefer to deactivate pages from +processes that have exceeded their set +.Dv RLIMIT_RSS . +.It Dv RLIMIT_SBSIZE +The maximum size (in bytes) of socket buffer usage for this user. +This limits the amount of network memory, and hence the amount of +mbufs, that this user may hold at any time. +.It Dv RLIMIT_STACK +The maximum size (in bytes) of the stack segment for a process; +this defines how far a program's stack segment may be extended. +Stack extension is performed automatically by the system. +.It Dv RLIMIT_SWAP +The maximum size (in bytes) of the swap space that may be reserved or +used by all of this user id's processes. +This limit is enforced only if bit 1 of the +.Va vm.overcommit +sysctl is set. +Please see +.Xr tuning 7 +for a complete description of this sysctl. +.It Dv RLIMIT_VMEM +An alias for +.Dv RLIMIT_AS . +.El +.Pp +A resource limit is specified as a soft limit and a hard limit. +When a soft limit is exceeded, a process might or might not receive a signal. +For example, signals are generated when the cpu time or file size is exceeded, +but not if the address space or RSS limit is exceeded. +A program that exceeds the soft limit is allowed to continue execution until it +reaches the hard limit, or modifies its own resource limit. +Even reaching the hard limit does not necessarily halt a process. +For example, if the RSS hard limit is exceeded, nothing happens. +.Pp +The +.Vt rlimit +structure is used to specify the hard and soft limits on a resource. +.Bd -literal -offset indent +struct rlimit { + rlim_t rlim_cur; /* current (soft) limit */ + rlim_t rlim_max; /* maximum value for rlim_cur */ +}; +.Ed +.Pp +Only the super-user may raise the maximum limits. +Other users +may only alter +.Fa rlim_cur +within the range from 0 to +.Fa rlim_max +or (irreversibly) lower +.Fa rlim_max . +.Pp +An +.Dq infinite +value for a limit is defined as +.Dv RLIM_INFINITY . +.Pp +Because this information is stored in the per-process information, +this system call must be executed directly by the shell if it +is to affect all future processes created by the shell; +.Ic limit +is thus a built-in command to +.Xr csh 1 . +.Pp +The system refuses to extend the data or stack space when the limits +would be exceeded in the normal way: a +.Xr brk 2 +function fails if the data space limit is reached. +When the stack limit is reached, the process receives +a segmentation fault +.Pq Dv SIGSEGV ; +if this signal is not +caught by a handler using the signal stack, this signal +will kill the process. +.Pp +A file I/O operation that would create a file larger that the process' +soft limit will cause the write to fail and a signal +.Dv SIGXFSZ +to be +generated; this normally terminates the process, but may be caught. +When +the soft cpu time limit is exceeded, a +.Dv SIGXCPU +signal is sent to the +offending process. +.Pp +When most operations would allocate more virtual memory than allowed by the +soft limit of +.Dv RLIMIT_AS , +the operation fails with +.Dv ENOMEM +and no signal is raised. +A notable exception is stack extension, described above. +If stack extension would allocate more virtual memory than allowed by the soft +limit of +.Dv RLIMIT_AS , +a +.Dv SIGSEGV +signal will be delivered. +The caller is free to raise the soft address space limit up to the hard limit +and retry the allocation. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn getrlimit +and +.Fn setrlimit +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The address specified for +.Fa rlp +is invalid. +.It Bq Er EPERM +The limit specified to +.Fn setrlimit +would have +raised the maximum limit value, and the caller is not the super-user. +.El +.Sh SEE ALSO +.Xr csh 1 , +.Xr quota 1 , +.Xr quotactl 2 , +.Xr sigaction 2 , +.Xr sigaltstack 2 , +.Xr sysctl 3 , +.Xr ulimit 3 +.Sh HISTORY +The +.Fn getrlimit +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/getrusage.2 b/lib/libc/sys/getrusage.2 new file mode 100644 index 000000000000..45ded184932a --- /dev/null +++ b/lib/libc/sys/getrusage.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getrusage.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd May 1, 2010 +.Dt GETRUSAGE 2 +.Os +.Sh NAME +.Nm getrusage +.Nd get information about resource utilization +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/resource.h +.Fd "#define RUSAGE_SELF 0" +.Fd "#define RUSAGE_CHILDREN -1" +.Fd "#define RUSAGE_THREAD 1" +.Ft int +.Fn getrusage "int who" "struct rusage *rusage" +.Sh DESCRIPTION +The +.Fn getrusage +system call +returns information describing the resources utilized by the current +thread, the current process, or all its terminated child processes. +The +.Fa who +argument is either +.Dv RUSAGE_THREAD , +.Dv RUSAGE_SELF , +or +.Dv RUSAGE_CHILDREN . +The buffer to which +.Fa rusage +points will be filled in with +the following structure: +.Bd -literal +struct rusage { + struct timeval ru_utime; /* user time used */ + struct timeval ru_stime; /* system time used */ + long ru_maxrss; /* max resident set size */ + long ru_ixrss; /* integral shared text memory size */ + long ru_idrss; /* integral unshared data size */ + long ru_isrss; /* integral unshared stack size */ + long ru_minflt; /* page reclaims */ + long ru_majflt; /* page faults */ + long ru_nswap; /* swaps */ + long ru_inblock; /* block input operations */ + long ru_oublock; /* block output operations */ + long ru_msgsnd; /* messages sent */ + long ru_msgrcv; /* messages received */ + long ru_nsignals; /* signals received */ + long ru_nvcsw; /* voluntary context switches */ + long ru_nivcsw; /* involuntary context switches */ +}; +.Ed +.Pp +The fields are interpreted as follows: +.Bl -tag -width ru_minfltaa +.It Fa ru_utime +the total amount of time spent executing in user mode. +.It Fa ru_stime +the total amount of time spent in the system executing on behalf +of the process(es). +.It Fa ru_maxrss +the maximum resident set size utilized (in kilobytes). +.It Fa ru_ixrss +an +.Dq integral +value indicating the amount of memory used +by the text segment +that was also shared among other processes. +This value is expressed +in units of kilobytes * ticks-of-execution. +Ticks are statistics clock ticks. +The statistics clock has a frequency of +.Fn sysconf _SC_CLK_TCK +ticks per second. +.It Fa ru_idrss +an integral value of the amount of unshared memory residing in the +data segment of a process (expressed in units of +kilobytes * ticks-of-execution). +.It Fa ru_isrss +an integral value of the amount of unshared memory residing in the +stack segment of a process (expressed in units of +kilobytes * ticks-of-execution). +.It Fa ru_minflt +the number of page faults serviced without any I/O activity; here +I/O activity is avoided by +.Dq reclaiming +a page frame from +the list of pages awaiting reallocation. +.It Fa ru_majflt +the number of page faults serviced that required I/O activity. +.It Fa ru_nswap +the number of times a process was +.Dq swapped +out of main +memory. +.It Fa ru_inblock +the number of times the file system had to perform input. +.It Fa ru_oublock +the number of times the file system had to perform output. +.It Fa ru_msgsnd +the number of IPC messages sent. +.It Fa ru_msgrcv +the number of IPC messages received. +.It Fa ru_nsignals +the number of signals delivered. +.It Fa ru_nvcsw +the number of times a context switch resulted due to a process +voluntarily giving up the processor before its time slice was +completed (usually to await availability of a resource). +.It Fa ru_nivcsw +the number of times a context switch resulted due to a higher +priority process becoming runnable or because the current process +exceeded its time slice. +.El +.Sh NOTES +The numbers +.Fa ru_inblock +and +.Fa ru_oublock +account only for real +I/O; data supplied by the caching mechanism is charged only +to the first process to read or write the data. +.Sh RETURN VALUES +.Rv -std getrusage +.Sh ERRORS +The +.Fn getrusage +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa who +argument is not a valid value. +.It Bq Er EFAULT +The address specified by the +.Fa rusage +argument is not in a valid part of the process address space. +.El +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr wait 2 , +.Xr clocks 7 +.Sh HISTORY +The +.Fn getrusage +system call appeared in +.Bx 4.2 . +The +.Dv RUSAGE_THREAD +facility first appeared in +.Fx 8.1 . +.Sh BUGS +There is no way to obtain information about a child process +that has not yet terminated. diff --git a/lib/libc/sys/getsid.2 b/lib/libc/sys/getsid.2 new file mode 100644 index 000000000000..8d3107439601 --- /dev/null +++ b/lib/libc/sys/getsid.2 @@ -0,0 +1,82 @@ +.\" Copyright (c) 1997 Peter Wemm <peter@FreeBSD.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 19, 1997 +.Dt GETSID 2 +.Os +.Sh NAME +.Nm getsid +.Nd get process session +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn getsid "pid_t pid" +.Sh DESCRIPTION +The session ID of the process identified by +.Fa pid +is returned by +.Fn getsid . +If +.Fa pid +is zero, +.Fn getsid +returns the session ID of the current process. +.Sh RETURN VALUES +Upon successful completion, the +.Fn getsid +system call +returns the session ID of +the specified process; otherwise, it returns a value of -1 and +sets errno to indicate an error. +.Sh ERRORS +The +.Fn getsid +system call +will succeed unless: +.Bl -tag -width Er +.It Bq Er ESRCH +if there is no process with a process ID equal to +.Fa pid . +.El +.Pp +Note that an implementation may restrict this system call to +processes within the same session ID as the calling process. +.Sh SEE ALSO +.Xr getpgid 2 , +.Xr getpgrp 2 , +.Xr setpgid 2 , +.Xr setsid 2 , +.Xr termios 4 +.Sh HISTORY +The +.Fn getsid +system call appeared in +.Fx 3.0 . +The +.Fn getsid +system call is derived from its usage in +.At V . diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2 new file mode 100644 index 000000000000..1de025768358 --- /dev/null +++ b/lib/libc/sys/getsockname.2 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getsockname.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt GETSOCKNAME 2 +.Os +.Sh NAME +.Nm getsockname +.Nd get socket name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getsockname "int s" "struct sockaddr * restrict name" "socklen_t * restrict namelen" +.Sh DESCRIPTION +The +.Fn getsockname +system call +returns the current +.Fa name +for the specified socket. +The +.Fa namelen +argument should be initialized to indicate +the amount of space pointed to by +.Fa name . +On return it contains the actual size of the name +returned (in bytes). +.Sh RETURN VALUES +.Rv -std getsockname +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ECONNRESET +The connection has been reset by the peer. +.It Bq Er EINVAL +The value of the +.Fa namelen +argument is not valid. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOBUFS +Insufficient resources were available in the system +to perform the operation. +.It Bq Er EFAULT +The +.Fa name +argument points to memory not in a valid part of the +process address space. +.El +.Sh SEE ALSO +.Xr bind 2 , +.Xr getpeername 2 , +.Xr socket 2 +.Sh HISTORY +The +.Fn getsockname +system call appeared in +.Bx 4.2 . +.Sh BUGS +Names bound to sockets in the UNIX domain are inaccessible; +.Fn getsockname +returns a zero length name. diff --git a/lib/libc/sys/getsockopt.2 b/lib/libc/sys/getsockopt.2 new file mode 100644 index 000000000000..1f742ee7c334 --- /dev/null +++ b/lib/libc/sys/getsockopt.2 @@ -0,0 +1,576 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getsockopt.2 8.4 (Berkeley) 5/2/95 +.\" $FreeBSD$ +.\" +.Dd January 18, 2017 +.Dt GETSOCKOPT 2 +.Os +.Sh NAME +.Nm getsockopt , +.Nm setsockopt +.Nd get and set options on sockets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn getsockopt "int s" "int level" "int optname" "void * restrict optval" "socklen_t * restrict optlen" +.Ft int +.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen" +.Sh DESCRIPTION +The +.Fn getsockopt +and +.Fn setsockopt +system calls +manipulate the +.Em options +associated with a socket. +Options may exist at multiple +protocol levels; they are always present at the uppermost +.Dq socket +level. +.Pp +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 socket level, +.Fa level +is specified as +.Dv SOL_SOCKET . +To manipulate options at any +other level the protocol number of the appropriate protocol +controlling the option is supplied. +For example, +to indicate that an option is to be interpreted by the +.Tn TCP +protocol, +.Fa level +should be set to the protocol number of +.Tn TCP ; +see +.Xr getprotoent 3 . +.Pp +The +.Fa optval +and +.Fa optlen +arguments +are used to access option values for +.Fn setsockopt . +For +.Fn getsockopt +they identify a buffer in which the value for the +requested option(s) are to be returned. +For +.Fn getsockopt , +.Fa optlen +is a value-result argument, initially containing the +size of the buffer pointed to by +.Fa optval , +and modified on return to indicate the actual size of +the value returned. +If no option value is +to be supplied or returned, +.Fa optval +may be NULL. +.Pp +The +.Fa optname +argument +and any specified options are passed uninterpreted to the appropriate +protocol module for interpretation. +The include file +.In sys/socket.h +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 +Most socket-level options utilize an +.Vt int +argument for +.Fa optval . +For +.Fn setsockopt , +the argument should be non-zero to enable a boolean option, +or zero if the option is to be disabled. +.Dv SO_LINGER +uses a +.Vt "struct linger" +argument, defined in +.In sys/socket.h , +which specifies the desired state of the option and the +linger interval (see below). +.Dv SO_SNDTIMEO +and +.Dv SO_RCVTIMEO +use a +.Vt "struct timeval" +argument, defined in +.In sys/time.h . +.Pp +The following options are recognized at the socket level. +For protocol-specific options, see protocol manual pages, +e.g. +.Xr ip 4 +or +.Xr tcp 4 . +Except as noted, each may be examined with +.Fn getsockopt +and set with +.Fn setsockopt . +.Bl -column SO_ACCEPTFILTER -offset indent +.It Dv SO_DEBUG Ta "enables recording of debugging information" +.It Dv SO_REUSEADDR Ta "enables local address reuse" +.It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings" +.It Dv SO_KEEPALIVE Ta "enables keep connections alive" +.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" +.It Dv SO_LINGER Ta "linger on close if data present" +.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" +.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" +.It Dv SO_SNDBUF Ta "set buffer size for output" +.It Dv SO_RCVBUF Ta "set buffer size for input" +.It Dv SO_SNDLOWAT Ta "set minimum count for output" +.It Dv SO_RCVLOWAT Ta "set minimum count for input" +.It Dv SO_SNDTIMEO Ta "set timeout value for output" +.It Dv SO_RCVTIMEO Ta "set timeout value for input" +.It Dv SO_ACCEPTFILTER Ta "set accept filter on listening socket" +.It Dv SO_NOSIGPIPE Ta +controls generation of +.Dv SIGPIPE +for the socket +.It Dv SO_TIMESTAMP Ta "enables reception of a timestamp with datagrams" +.It Dv SO_BINTIME Ta "enables reception of a timestamp with datagrams" +.It Dv SO_ACCEPTCONN Ta "get listening status of the socket (get only)" +.It Dv SO_TYPE Ta "get the type of the socket (get only)" +.It Dv SO_PROTOCOL Ta "get the protocol number for the socket (get only)" +.It Dv SO_PROTOTYPE Ta "SunOS alias for the Linux SO_PROTOCOL (get only)" +.It Dv SO_ERROR Ta "get and clear error on the socket (get only)" +.It Dv SO_SETFIB Ta "set the associated FIB (routing table) for the socket (set only)" +.El +.Pp +The following options are recognized in +.Fx : +.Bl -column SO_LISTENINCQLEN -offset indent +.It Dv SO_LABEL Ta "get MAC label of the socket (get only)" +.It Dv SO_PEERLABEL Ta "get socket's peer's MAC label (get only)" +.It Dv SO_LISTENQLIMIT Ta "get backlog limit of the socket (get only)" +.It Dv SO_LISTENQLEN Ta "get complete queue length of the socket (get only)" +.It Dv SO_LISTENINCQLEN Ta "get incomplete queue length of the socket (get only)" +.It Dv SO_USER_COOKIE Ta "set the 'so_user_cookie' value for the socket (uint32_t, set only)" +.It Dv SO_TS_CLOCK Ta "set specific format of timestamp returned by SO_TIMESTAMP" +.It Dv SO_MAX_PACING_RATE "set the maximum transmit rate in bytes per second for the socket" +.El +.Pp +.Dv SO_DEBUG +enables debugging in the underlying protocol modules. +.Pp +.Dv SO_REUSEADDR +indicates that the rules used in validating addresses supplied +in a +.Xr bind 2 +system call should allow reuse of local addresses. +.Pp +.Dv SO_REUSEPORT +allows completely duplicate bindings by multiple processes +if they all set +.Dv SO_REUSEPORT +before binding the port. +This option permits multiple instances of a program to each +receive UDP/IP multicast or broadcast datagrams destined for the bound port. +.Pp +.Dv SO_KEEPALIVE +enables the +periodic transmission of messages on a connected socket. +Should the +connected party fail to respond to these messages, the connection is +considered broken and processes using the socket are notified via a +.Dv SIGPIPE +signal when attempting to send data. +.Pp +.Dv SO_DONTROUTE +indicates that outgoing messages should +bypass the standard routing facilities. +Instead, messages are directed +to the appropriate network interface according to the network portion +of the destination address. +.Pp +.Dv SO_LINGER +controls the action taken when unsent messages +are queued on socket and a +.Xr close 2 +is performed. +If the socket promises reliable delivery of data and +.Dv SO_LINGER +is set, +the system will block the process on the +.Xr close 2 +attempt until it is able to transmit the data or until it decides it +is unable to deliver the information (a timeout period, termed the +linger interval, is specified in seconds in the +.Fn setsockopt +system call when +.Dv SO_LINGER +is requested). +If +.Dv SO_LINGER +is disabled and a +.Xr close 2 +is issued, the system will process the close in a manner that allows +the process to continue as quickly as possible. +.Pp +The option +.Dv SO_BROADCAST +requests permission to send broadcast datagrams +on the socket. +Broadcast was a privileged operation in earlier versions of the system. +.Pp +With protocols that support out-of-band data, the +.Dv SO_OOBINLINE +option +requests that out-of-band data be placed in the normal data input queue +as received; it will then be accessible with +.Xr recv 2 +or +.Xr read 2 +calls without the +.Dv MSG_OOB +flag. +Some protocols always behave as if this option is set. +.Pp +.Dv SO_SNDBUF +and +.Dv SO_RCVBUF +are options to adjust the normal +buffer sizes allocated for output and input buffers, respectively. +The buffer size may be increased for high-volume connections, +or may be decreased to limit the possible backlog of incoming data. +The system places an absolute maximum on these values, which is accessible +through the +.Xr sysctl 3 +MIB variable +.Dq Li kern.ipc.maxsockbuf . +.Pp +.Dv SO_SNDLOWAT +is an option to set the minimum count for output operations. +Most output operations process all of the data supplied +by the call, delivering data to the protocol for transmission +and blocking as necessary for flow control. +Nonblocking output operations will process as much data as permitted +subject to flow control without blocking, but will process no data +if flow control does not allow the smaller of the low water mark value +or the entire request to be processed. +A +.Xr select 2 +operation testing the ability to write to a socket will return true +only if the low water mark amount could be processed. +The default value for +.Dv SO_SNDLOWAT +is set to a convenient size for network efficiency, often 1024. +.Pp +.Dv SO_RCVLOWAT +is an option to set the minimum count for input operations. +In general, receive calls will block until any (non-zero) amount of data +is received, then return with the smaller of the amount available or the amount +requested. +The default value for +.Dv SO_RCVLOWAT +is 1. +If +.Dv SO_RCVLOWAT +is set to a larger value, blocking receive calls normally +wait until they have received the smaller of the low water mark value +or the requested amount. +Receive calls may still return less than the low water mark if an error +occurs, a signal is caught, or the type of data next in the receive queue +is different from that which was returned. +.Pp +.Dv SO_SNDTIMEO +is an option to set a timeout value for output operations. +It accepts a +.Vt "struct timeval" +argument with the number of seconds and microseconds +used to limit waits for output operations to complete. +If a send operation has blocked for this much time, +it returns with a partial count +or with the error +.Er EWOULDBLOCK +if no data were sent. +In the current implementation, this timer is restarted each time additional +data are delivered to the protocol, +implying that the limit applies to output portions ranging in size +from the low water mark to the high water mark for output. +.Pp +.Dv SO_RCVTIMEO +is an option to set a timeout value for input operations. +It accepts a +.Vt "struct timeval" +argument with the number of seconds and microseconds +used to limit waits for input operations to complete. +In the current implementation, this timer is restarted each time additional +data are received by the protocol, +and thus the limit is in effect an inactivity timer. +If a receive operation has been blocked for this much time without +receiving additional data, it returns with a short count +or with the error +.Er EWOULDBLOCK +if no data were received. +.Pp +.Dv SO_SETFIB +can be used to over-ride the default FIB (routing table) for the given socket. +The value must be from 0 to one less than the number returned from +the sysctl +.Em net.fibs . +.Pp +.Dv SO_USER_COOKIE +can be used to set the uint32_t so_user_cookie field in the socket. +The value is an uint32_t, and can be used in the kernel code that +manipulates traffic related to the socket. +The default value for the field is 0. +As an example, the value can be used as the skipto target or +pipe number in +.Nm ipfw/dummynet . +.Pp +.Dv SO_ACCEPTFILTER +places an +.Xr accept_filter 9 +on the socket, +which will filter incoming connections +on a listening stream socket before being presented for +.Xr accept 2 . +Once more, +.Xr listen 2 +must be called on the socket before +trying to install the filter on it, +or else the +.Fn setsockopt +system call will fail. +.Bd -literal +struct accept_filter_arg { + char af_name[16]; + char af_arg[256-16]; +}; +.Ed +.Pp +The +.Fa optval +argument +should point to a +.Fa struct accept_filter_arg +that will select and configure the +.Xr accept_filter 9 . +The +.Fa af_name +argument +should be filled with the name of the accept filter +that the application wishes to place on the listening socket. +The optional argument +.Fa af_arg +can be passed to the accept +filter specified by +.Fa af_name +to provide additional configuration options at attach time. +Passing in an +.Fa optval +of NULL will remove the filter. +.Pp +The +.Dv SO_NOSIGPIPE +option controls generation of the +.Dv SIGPIPE +signal normally sent +when writing to a connected socket where the other end has been +closed returns with the error +.Er EPIPE . +.Pp +If the +.Dv SO_TIMESTAMP +or +.Dv SO_BINTIME +option is enabled on a +.Dv SOCK_DGRAM +socket, the +.Xr recvmsg 2 +call will return a timestamp corresponding to when the datagram was received. +The +.Va msg_control +field in the +.Vt msghdr +structure points to a buffer that contains a +.Vt cmsghdr +structure followed by a +.Vt "struct timeval" +for +.Dv SO_TIMESTAMP +and +.Vt "struct bintime" +for +.Dv SO_BINTIME . +The +.Vt cmsghdr +fields have the following values for TIMESTAMP by default: +.Bd -literal + cmsg_len = CMSG_LEN(sizeof(struct timeval)); + cmsg_level = SOL_SOCKET; + cmsg_type = SCM_TIMESTAMP; +.Ed +.Pp +and for +.Dv SO_BINTIME : +.Bd -literal + cmsg_len = CMSG_LEN(sizeof(struct bintime)); + cmsg_level = SOL_SOCKET; + cmsg_type = SCM_BINTIME; +.Ed +.Pp +Additional timestamp types are available by following +.Dv SO_TIMESTAMP +with +.Dv SO_TS_CLOCK , +which requests a specific timestamp format to be returned instead of +.Dv SCM_TIMESTAMP when +.Dv SO_TIMESTAMP is enabled. +These +.Dv SO_TS_CLOCK +values are recognized in +.Fx : +.Bl -column SO_TS_CLOCK -offset indent +.It Dv SO_TS_REALTIME_MICRO Ta "realtime (SCM_TIMESTAMP, struct timeval), default" +.It Dv SO_TS_BINTIME Ta "realtime (SCM_BINTIME, struct bintime)" +.It Dv SO_TS_REALTIME Ta "realtime (SCM_REALTIME, struct timespec)" +.It Dv SO_TS_MONOTONIC Ta "monotonic time (SCM_MONOTONIC, struct timespec)" +.El +.Pp +.Dv SO_ACCEPTCONN , +.Dv SO_TYPE , +.Dv SO_PROTOCOL +(and its alias +.Dv SO_PROTOTYPE ) +and +.Dv SO_ERROR +are options used only with +.Fn getsockopt . +.Dv SO_ACCEPTCONN +returns whether the socket is currently accepting connections, +that is, whether or not the +.Xr listen 2 +system call was invoked on the socket. +.Dv SO_TYPE +returns the type of the socket, such as +.Dv SOCK_STREAM ; +it is useful for servers that inherit sockets on startup. +.Dv SO_PROTOCOL +returns the protocol number for the socket, for +.Dv AF_INET +and +.Dv AF_INET6 +address families. +.Dv SO_ERROR +returns any pending error on the socket and clears +the error status. +It may be used to check for asynchronous errors on connected +datagram sockets or for other asynchronous errors. +.Pp +Finally, +.Dv SO_LABEL +returns the MAC label of the socket. +.Dv SO_PEERLABEL +returns the MAC label of the socket's peer. +Note that your kernel must be compiled with MAC support. +See +.Xr mac 3 +for more information. +.Dv SO_LISTENQLIMIT +returns the maximal number of queued connections, as set by +.Xr listen 2 . +.Dv SO_LISTENQLEN +returns the number of unaccepted complete connections. +.Dv SO_LISTENINCQLEN +returns the number of unaccepted incomplete connections. +.Pp +.Dv SO_MAX_PACING_RATE +instruct the socket and underlying network adapter layers to limit the +transfer rate to the given unsigned 32-bit value in bytes per second. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is a file, not a socket. +.It Bq Er ENOPROTOOPT +The option is unknown at the level indicated. +.It Bq Er EFAULT +The address pointed to by +.Fa optval +is not in a valid part of the process address space. +For +.Fn getsockopt , +this error may also be returned if +.Fa optlen +is not in a valid part of the process address space. +.It Bq Er EINVAL +Installing an +.Xr accept_filter 9 +on a non-listening socket was attempted. +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr listen 2 , +.Xr recvmsg 2 , +.Xr socket 2 , +.Xr getprotoent 3 , +.Xr mac 3 , +.Xr sysctl 3 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr sctp 4 , +.Xr tcp 4 , +.Xr protocols 5 , +.Xr sysctl 8 , +.Xr accept_filter 9 , +.Xr bintime 9 +.Sh HISTORY +The +.Fn getsockopt +and +.Fn setsockopt +system calls appeared in +.Bx 4.2 . +.Sh BUGS +Several of the socket options should be handled at lower levels of the system. diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2 new file mode 100644 index 000000000000..86b6b1aa1937 --- /dev/null +++ b/lib/libc/sys/gettimeofday.2 @@ -0,0 +1,132 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)gettimeofday.2 8.2 (Berkeley) 5/26/95 +.\" $FreeBSD$ +.\" +.Dd December 27, 2015 +.Dt GETTIMEOFDAY 2 +.Os +.Sh NAME +.Nm gettimeofday , +.Nm settimeofday +.Nd get/set date and time +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn gettimeofday "struct timeval *tp" "struct timezone *tzp" +.Ft int +.Fn settimeofday "const struct timeval *tp" "const struct timezone *tzp" +.Sh DESCRIPTION +.Bf -symbolic +Note: timezone is no longer used; this information is kept outside +the kernel. +.Ef +.Pp +The system's notion of the current Greenwich time and the current time +zone is obtained with the +.Fn gettimeofday +system call, and set with the +.Fn settimeofday +system call. +The time is expressed in seconds and microseconds +since midnight (0 hour), January 1, 1970. +The resolution of the system +clock is hardware dependent, and the time may be updated continuously or +in +.Dq ticks . +If +.Fa tp +or +.Fa tzp +is NULL, the associated time +information will not be returned or set. +.Pp +The structures pointed to by +.Fa tp +and +.Fa tzp +are defined in +.In sys/time.h +as: +.Bd -literal +struct timeval { + time_t tv_sec; /* seconds */ + suseconds_t tv_usec; /* and microseconds */ +}; + +struct timezone { + int tz_minuteswest; /* minutes west of Greenwich */ + int tz_dsttime; /* type of dst correction */ +}; +.Ed +.Pp +The +.Vt timezone +structure indicates the local time zone +(measured in minutes of time westward from Greenwich), +and a flag that, if nonzero, indicates that +Daylight Saving time applies locally during +the appropriate part of the year. +.Pp +Only the super-user may set the time of day or time zone. +If the system is running at securelevel >= 2 (see +.Xr init 8 ) , +the time may only be advanced or retarded by a maximum of one second. +This limitation is imposed to prevent a malicious super-user +from setting arbitrary time stamps on files. +The system time can be adjusted backwards without restriction using the +.Xr adjtime 2 +system call even when the system is secure. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The following error codes may be set in +.Va errno : +.Bl -tag -width Er +.It Bq Er EINVAL +The supplied +.Fa timeval +value is invalid. +.It Bq Er EPERM +A user other than the super-user attempted to set the time. +.El +.Sh SEE ALSO +.Xr date 1 , +.Xr adjtime 2 , +.Xr clock_gettime 2 , +.Xr ctime 3 , +.Xr timeradd 3 , +.Xr clocks 7 , +.Xr timed 8 +.Sh HISTORY +The +.Fn gettimeofday +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/gettimeofday.c b/lib/libc/sys/gettimeofday.c new file mode 100644 index 000000000000..5b1252314c39 --- /dev/null +++ b/lib/libc/sys/gettimeofday.c @@ -0,0 +1,48 @@ +/*- + * Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/syscall.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> +#include "libc_private.h" + +int __gettimeofday(struct timeval *tv, struct timezone *tz); + +__weak_reference(__gettimeofday, gettimeofday); + +int +__gettimeofday(struct timeval *tv, struct timezone *tz) +{ + int error; + + error = __vdso_gettimeofday(tv, tz); + if (error == ENOSYS) + error = __sys_gettimeofday(tv, tz); + return (error); +} diff --git a/lib/libc/sys/getuid.2 b/lib/libc/sys/getuid.2 new file mode 100644 index 000000000000..414535698f89 --- /dev/null +++ b/lib/libc/sys/getuid.2 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)getuid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt GETUID 2 +.Os +.Sh NAME +.Nm getuid , +.Nm geteuid +.Nd get user identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft uid_t +.Fn getuid void +.Ft uid_t +.Fn geteuid void +.Sh DESCRIPTION +The +.Fn getuid +system call returns the real user ID of the calling process. +The +.Fn geteuid +system call +returns the effective user ID of the calling process. +.Pp +The real user ID is that of the user who has invoked the program. +As the effective user ID +gives the process additional permissions during +execution of +.Dq Em set-user-ID +mode processes, +.Fn getuid +is used to determine the real-user-id of the calling process. +.Sh ERRORS +The +.Fn getuid +and +.Fn geteuid +system calls are always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr getgid 2 , +.Xr issetugid 2 , +.Xr setgid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh STANDARDS +The +.Fn geteuid +and +.Fn getuid +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn getuid +and +.Fn geteuid +functions appeared in +.At v7 . diff --git a/lib/libc/sys/interposing_table.c b/lib/libc/sys/interposing_table.c new file mode 100644 index 000000000000..1447e42ef238 --- /dev/null +++ b/lib/libc/sys/interposing_table.c @@ -0,0 +1,91 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include "libc_private.h" + +#define SLOT(a, b) \ + [INTERPOS_##a] = (interpos_func_t)b +interpos_func_t __libc_interposing[INTERPOS_MAX] = { + SLOT(accept, __sys_accept), + SLOT(accept4, __sys_accept4), + SLOT(aio_suspend, __sys_aio_suspend), + SLOT(close, __sys_close), + SLOT(connect, __sys_connect), + SLOT(fcntl, __sys_fcntl), + SLOT(fsync, __sys_fsync), + SLOT(fork, __sys_fork), + SLOT(msync, __sys_msync), + SLOT(nanosleep, __sys_nanosleep), + SLOT(openat, __sys_openat), + SLOT(poll, __sys_poll), + SLOT(pselect, __sys_pselect), + SLOT(read, __sys_read), + SLOT(readv, __sys_readv), + SLOT(recvfrom, __sys_recvfrom), + SLOT(recvmsg, __sys_recvmsg), + SLOT(select, __sys_select), + SLOT(sendmsg, __sys_sendmsg), + SLOT(sendto, __sys_sendto), + SLOT(setcontext, __sys_setcontext), + SLOT(sigaction, __sys_sigaction), + SLOT(sigprocmask, __sys_sigprocmask), + SLOT(sigsuspend, __sys_sigsuspend), + SLOT(sigwait, __libc_sigwait), + SLOT(sigtimedwait, __sys_sigtimedwait), + SLOT(sigwaitinfo, __sys_sigwaitinfo), + SLOT(swapcontext, __sys_swapcontext), + SLOT(system, __libc_system), + SLOT(tcdrain, __libc_tcdrain), + SLOT(wait4, __sys_wait4), + SLOT(write, __sys_write), + SLOT(writev, __sys_writev), + SLOT(_pthread_mutex_init_calloc_cb, _pthread_mutex_init_calloc_cb_stub), + SLOT(spinlock, __libc_spinlock_stub), + SLOT(spinunlock, __libc_spinunlock_stub), + SLOT(kevent, __sys_kevent), + SLOT(wait6, __sys_wait6), + SLOT(ppoll, __sys_ppoll), + SLOT(map_stacks_exec, __libc_map_stacks_exec), + SLOT(fdatasync, __sys_fdatasync), +}; +#undef SLOT + +interpos_func_t * +__libc_interposing_slot(int interposno) +{ + + return (&__libc_interposing[interposno]); +} diff --git a/lib/libc/sys/intro.2 b/lib/libc/sys/intro.2 new file mode 100644 index 000000000000..5a3e17e901f9 --- /dev/null +++ b/lib/libc/sys/intro.2 @@ -0,0 +1,754 @@ +.\" Copyright (c) 1980, 1983, 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)intro.2 8.5 (Berkeley) 2/27/95 +.\" $FreeBSD$ +.\" +.Dd September 8, 2016 +.Dt INTRO 2 +.Os +.Sh NAME +.Nm intro +.Nd introduction to system calls and error numbers +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In errno.h +.Sh DESCRIPTION +This section provides an overview of the system calls, +their error returns, and other common definitions and concepts. +.\".Pp +.\".Sy System call restart +.\".Pp +.\"(more later...) +.Sh RETURN VALUES +Nearly all of the system calls provide an error number referenced via +the external identifier errno. +This identifier is defined in +.In sys/errno.h +as +.Pp +.Dl extern int * __error(); +.Dl #define errno (* __error()) +.Pp +The +.Va __error() +function returns a pointer to a field in the thread specific structure for +threads other than the initial thread. +For the initial thread and +non-threaded processes, +.Va __error() +returns a pointer to a global +.Va errno +variable that is compatible with the previous definition. +.Pp +When a system call detects an error, +it returns an integer value +indicating failure (usually -1) +and sets the variable +.Va errno +accordingly. +(This allows interpretation of the failure on receiving +a -1 and to take action accordingly.) +Successful calls never set +.Va errno ; +once set, it remains until another error occurs. +It should only be examined after an error. +Note that a number of system calls overload the meanings of these +error numbers, and that the meanings must be interpreted according +to the type and circumstances of the call. +.Pp +The following is a complete list of the errors and their +names as given in +.In sys/errno.h . +.Bl -hang -width Ds +.It Er 0 Em "Undefined error: 0" . +Not used. +.It Er 1 EPERM Em "Operation not permitted" . +An attempt was made to perform an operation limited to processes +with appropriate privileges or to the owner of a file or other +resources. +.It Er 2 ENOENT Em "No such file or directory" . +A component of a specified pathname did not exist, or the +pathname was an empty string. +.It Er 3 ESRCH Em "No such process" . +No process could be found corresponding to that specified by the given +process ID. +.It Er 4 EINTR Em "Interrupted system call" . +An asynchronous signal (such as +.Dv SIGINT +or +.Dv SIGQUIT ) +was caught by the process during the execution of an interruptible +function. +If the signal handler performs a normal return, the +interrupted system call will seem to have returned the error condition. +.It Er 5 EIO Em "Input/output error" . +Some physical input or output error occurred. +This error will not be reported until a subsequent operation on the same file +descriptor and may be lost (over written) by any subsequent errors. +.It Er 6 ENXIO Em "Device not configured" . +Input or output on a special file referred to a device that did not +exist, or +made a request beyond the limits of the device. +This error may also occur when, for example, +a tape drive is not online or no disk pack is +loaded on a drive. +.It Er 7 E2BIG Em "Argument list too long" . +The number of bytes used for the argument and environment +list of the new process exceeded the current limit +.Dv ( NCARGS +in +.In sys/param.h ) . +.It Er 8 ENOEXEC Em "Exec format error" . +A request was made to execute a file +that, although it has the appropriate permissions, +was not in the format required for an +executable file. +.It Er 9 EBADF Em "Bad file descriptor" . +A file descriptor argument was out of range, referred to no open file, +or a read (write) request was made to a file that was only open for +writing (reading). +.It Er 10 ECHILD Em "\&No child processes" . +A +.Xr wait 2 +or +.Xr waitpid 2 +function was executed by a process that had no existing or unwaited-for +child processes. +.It Er 11 EDEADLK Em "Resource deadlock avoided" . +An attempt was made to lock a system resource that +would have resulted in a deadlock situation. +.It Er 12 ENOMEM Em "Cannot allocate memory" . +The new process image required more memory than was allowed by the hardware +or by system-imposed memory management constraints. +A lack of swap space is normally temporary; however, +a lack of core is not. +Soft limits may be increased to their corresponding hard limits. +.It Er 13 EACCES Em "Permission denied" . +An attempt was made to access a file in a way forbidden +by its file access permissions. +.It Er 14 EFAULT Em "Bad address" . +The system detected an invalid address in attempting to +use an argument of a call. +.It Er 15 ENOTBLK Em "Block device required" . +A block device operation was attempted on a non-block device or file. +.It Er 16 EBUSY Em "Device busy" . +An attempt to use a system resource which was in use at the time +in a manner which would have conflicted with the request. +.It Er 17 EEXIST Em "File exists" . +An existing file was mentioned in an inappropriate context, +for instance, as the new link name in a +.Xr link 2 +system call. +.It Er 18 EXDEV Em "Cross-device link" . +A hard link to a file on another file system +was attempted. +.It Er 19 ENODEV Em "Operation not supported by device" . +An attempt was made to apply an inappropriate +function to a device, +for example, +trying to read a write-only device such as a printer. +.It Er 20 ENOTDIR Em "Not a directory" . +A component of the specified pathname existed, but it was +not a directory, when a directory was expected. +.It Er 21 EISDIR Em "Is a directory" . +An attempt was made to open a directory with write mode specified. +.It Er 22 EINVAL Em "Invalid argument" . +Some invalid argument was supplied. +(For example, +specifying an undefined signal to a +.Xr signal 3 +function +or a +.Xr kill 2 +system call). +.It Er 23 ENFILE Em "Too many open files in system" . +Maximum number of open files allowable on the system +has been reached and requests for an open cannot be satisfied +until at least one has been closed. +.It Er 24 EMFILE Em "Too many open files" . +Maximum number of file descriptors allowable in the process +has been reached and requests for an open cannot be satisfied +until at least one has been closed. +The +.Xr getdtablesize 2 +system call will obtain the current limit. +.It Er 25 ENOTTY Em "Inappropriate ioctl for device" . +A control function (see +.Xr ioctl 2 ) +was attempted for a file or +special device for which the operation was inappropriate. +.It Er 26 ETXTBSY Em "Text file busy" . +The new process was a pure procedure (shared text) file +which was open for writing by another process, or +while the pure procedure file was being executed an +.Xr open 2 +call requested write access. +.It Er 27 EFBIG Em "File too large" . +The size of a file exceeded the maximum. +.It Er 28 ENOSPC Em "No space left on device" . +A +.Xr write 2 +to an ordinary file, the creation of a +directory or symbolic link, or the creation of a directory +entry failed because no more disk blocks were available +on the file system, or the allocation of an inode for a newly +created file failed because no more inodes were available +on the file system. +.It Er 29 ESPIPE Em "Illegal seek" . +An +.Xr lseek 2 +system call was issued on a socket, pipe or +.Tn FIFO . +.It Er 30 EROFS Em "Read-only file system" . +An attempt was made to modify a file or directory +on a file system that was read-only at the time. +.It Er 31 EMLINK Em "Too many links" . +Maximum allowable hard links to a single file has been exceeded (limit +of 32767 hard links per file). +.It Er 32 EPIPE Em "Broken pipe" . +A write on a pipe, socket or +.Tn FIFO +for which there is no process +to read the data. +.It Er 33 EDOM Em "Numerical argument out of domain" . +A numerical input argument was outside the defined domain of the mathematical +function. +.It Er 34 ERANGE Em "Result too large" . +A numerical result of the function was too large to fit in the +available space (perhaps exceeded precision). +.It Er 35 EAGAIN Em "Resource temporarily unavailable" . +This is a temporary condition and later calls to the +same routine may complete normally. +.It Er 36 EINPROGRESS Em "Operation now in progress" . +An operation that takes a long time to complete (such as +a +.Xr connect 2 ) +was attempted on a non-blocking object (see +.Xr fcntl 2 ) . +.It Er 37 EALREADY Em "Operation already in progress" . +An operation was attempted on a non-blocking object that already +had an operation in progress. +.It Er 38 ENOTSOCK Em "Socket operation on non-socket" . +Self-explanatory. +.It Er 39 EDESTADDRREQ Em "Destination address required" . +A required address was omitted from an operation on a socket. +.It Er 40 EMSGSIZE Em "Message too long" . +A message sent on a socket was larger than the internal message buffer +or some other network limit. +.It Er 41 EPROTOTYPE Em "Protocol wrong type for socket" . +A protocol was specified that does not support the semantics of the +socket type requested. +For example, you cannot use the +.Tn ARPA +Internet +.Tn UDP +protocol with type +.Dv SOCK_STREAM . +.It Er 42 ENOPROTOOPT Em "Protocol not available" . +A bad option or level was specified in a +.Xr getsockopt 2 +or +.Xr setsockopt 2 +call. +.It Er 43 EPROTONOSUPPORT Em "Protocol not supported" . +The protocol has not been configured into the +system or no implementation for it exists. +.It Er 44 ESOCKTNOSUPPORT Em "Socket type not supported" . +The support for the socket type has not been configured into the +system or no implementation for it exists. +.It Er 45 EOPNOTSUPP Em "Operation not supported" . +The attempted operation is not supported for the type of object referenced. +Usually this occurs when a file descriptor refers to a file or socket +that cannot support this operation, +for example, trying to +.Em accept +a connection on a datagram socket. +.It Er 46 EPFNOSUPPORT Em "Protocol family not supported" . +The protocol family has not been configured into the +system or no implementation for it exists. +.It Er 47 EAFNOSUPPORT Em "Address family not supported by protocol family" . +An address incompatible with the requested protocol was used. +For example, you should not necessarily expect to be able to use +.Tn NS +addresses with +.Tn ARPA +Internet protocols. +.It Er 48 EADDRINUSE Em "Address already in use" . +Only one usage of each address is normally permitted. +.It Er 49 EADDRNOTAVAIL Em "Can't assign requested address" . +Normally results from an attempt to create a socket with an +address not on this machine. +.It Er 50 ENETDOWN Em "Network is down" . +A socket operation encountered a dead network. +.It Er 51 ENETUNREACH Em "Network is unreachable" . +A socket operation was attempted to an unreachable network. +.It Er 52 ENETRESET Em "Network dropped connection on reset" . +The host you were connected to crashed and rebooted. +.It Er 53 ECONNABORTED Em "Software caused connection abort" . +A connection abort was caused internal to your host machine. +.It Er 54 ECONNRESET Em "Connection reset by peer" . +A connection was forcibly closed by a peer. +This normally +results from a loss of the connection on the remote socket +due to a timeout or a reboot. +.It Er 55 ENOBUFS Em "\&No buffer space available" . +An operation on a socket or pipe was not performed because +the system lacked sufficient buffer space or because a queue was full. +.It Er 56 EISCONN Em "Socket is already connected" . +A +.Xr connect 2 +request was made on an already connected socket; or, +a +.Xr sendto 2 +or +.Xr sendmsg 2 +request on a connected socket specified a destination +when already connected. +.It Er 57 ENOTCONN Em "Socket is not connected" . +An request to send or receive data was disallowed because +the socket was not connected and (when sending on a datagram socket) +no address was supplied. +.It Er 58 ESHUTDOWN Em "Can't send after socket shutdown" . +A request to send data was disallowed because the socket +had already been shut down with a previous +.Xr shutdown 2 +call. +.It Er 60 ETIMEDOUT Em "Operation timed out" . +A +.Xr connect 2 +or +.Xr send 2 +request failed because the connected party did not +properly respond after a period of time. +(The timeout +period is dependent on the communication protocol.) +.It Er 61 ECONNREFUSED Em "Connection refused" . +No connection could be made because the target machine actively +refused it. +This usually results from trying to connect +to a service that is inactive on the foreign host. +.It Er 62 ELOOP Em "Too many levels of symbolic links" . +A path name lookup involved more than 32 +.Pq Dv MAXSYMLINKS +symbolic links. +.It Er 63 ENAMETOOLONG Em "File name too long" . +A component of a path name exceeded +.Brq Dv NAME_MAX +characters, or an entire +path name exceeded +.Brq Dv PATH_MAX +characters. +(See also the description of +.Dv _PC_NO_TRUNC +in +.Xr pathconf 2 . ) +.It Er 64 EHOSTDOWN Em "Host is down" . +A socket operation failed because the destination host was down. +.It Er 65 EHOSTUNREACH Em "No route to host" . +A socket operation was attempted to an unreachable host. +.It Er 66 ENOTEMPTY Em "Directory not empty" . +A directory with entries other than +.Ql .\& +and +.Ql ..\& +was supplied to a remove directory or rename call. +.It Er 67 EPROCLIM Em "Too many processes" . +.It Er 68 EUSERS Em "Too many users" . +The quota system ran out of table entries. +.It Er 69 EDQUOT Em "Disc quota exceeded" . +A +.Xr write 2 +to an ordinary file, the creation of a +directory or symbolic link, or the creation of a directory +entry failed because the user's quota of disk blocks was +exhausted, or the allocation of an inode for a newly +created file failed because the user's quota of inodes +was exhausted. +.It Er 70 ESTALE Em "Stale NFS file handle" . +An attempt was made to access an open file (on an +.Tn NFS +file system) +which is now unavailable as referenced by the file descriptor. +This may indicate the file was deleted on the +.Tn NFS +server or some +other catastrophic event occurred. +.It Er 72 EBADRPC Em "RPC struct is bad" . +Exchange of +.Tn RPC +information was unsuccessful. +.It Er 73 ERPCMISMATCH Em "RPC version wrong" . +The version of +.Tn RPC +on the remote peer is not compatible with +the local version. +.It Er 74 EPROGUNAVAIL Em "RPC prog. not avail" . +The requested program is not registered on the remote host. +.It Er 75 EPROGMISMATCH Em "Program version wrong" . +The requested version of the program is not available +on the remote host +.Pq Tn RPC . +.It Er 76 EPROCUNAVAIL Em "Bad procedure for program" . +An +.Tn RPC +call was attempted for a procedure which does not exist +in the remote program. +.It Er 77 ENOLCK Em "No locks available" . +A system-imposed limit on the number of simultaneous file +locks was reached. +.It Er 78 ENOSYS Em "Function not implemented" . +Attempted a system call that is not available on this +system. +.It Er 79 EFTYPE Em "Inappropriate file type or format" . +The file was the wrong type for the operation, or a data file had +the wrong format. +.It Er 80 EAUTH Em "Authentication error" . +Attempted to use an invalid authentication ticket to mount a +.Tn NFS +file system. +.It Er 81 ENEEDAUTH Em "Need authenticator" . +An authentication ticket must be obtained before the given +.Tn NFS +file system may be mounted. +.It Er 82 EIDRM Em "Identifier removed" . +An IPC identifier was removed while the current process was waiting on it. +.It Er 83 ENOMSG Em "No message of desired type" . +An IPC message queue does not contain a message of the desired type, or a +message catalog does not contain the requested message. +.It Er 84 EOVERFLOW Em "Value too large to be stored in data type" . +A numerical result of the function was too large to be stored in the caller +provided space. +.It Er 85 ECANCELED Em "Operation canceled" . +The scheduled operation was canceled. +.It Er 86 EILSEQ Em "Illegal byte sequence" . +While decoding a multibyte character the function came along an +invalid or an incomplete sequence of bytes or the given wide +character is invalid. +.It Er 87 ENOATTR Em "Attribute not found" . +The specified extended attribute does not exist. +.It Er 88 EDOOFUS Em "Programming error" . +A function or API is being abused in a way which could only be detected +at run-time. +.It Er 89 EBADMSG Em "Bad message" . +A corrupted message was detected. +.It Er 90 EMULTIHOP Em "Multihop attempted" . +This error code is unused, but present for compatibility with other systems. +.It Er 91 ENOLINK Em "Link has been severed" . +This error code is unused, but present for compatibility with other systems. +.It Er 92 EPROTO Em "Protocol error" . +A device or socket encountered an unrecoverable protocol error. +.It Er 93 ENOTCAPABLE Em "Capabilities insufficient" . +An operation on a capability file descriptor requires greater privilege than +the capability allows. +.It Er 94 ECAPMODE Em "Not permitted in capability mode" . +The system call or operation is not permitted for capability mode processes. +.It Er 95 ENOTRECOVERABLE Em "State not recoverable" . +The state protected by a robust mutex is not recoverable. +.It Er 96 EOWNERDEAD Em "Previous owner died" . +The owner of a robust mutex terminated while holding the mutex lock. +.El +.Sh DEFINITIONS +.Bl -tag -width Ds +.It Process ID . +Each active process in the system is uniquely identified by a non-negative +integer called a process ID. +The range of this ID is from 0 to 99999. +.It Parent process ID +A new process is created by a currently active process (see +.Xr fork 2 ) . +The parent process ID of a process is initially the process ID of its creator. +If the creating process exits, +the parent process ID of each child is set to the ID of the calling process's +reaper (see +.Xr procctl 2 ) , +normally +.Xr init 8 . +.It Process Group +Each active process is a member of a process group that is identified by +a non-negative integer called the process group ID. +This is the process +ID of the group leader. +This grouping permits the signaling of related +processes (see +.Xr termios 4 ) +and the job control mechanisms of +.Xr csh 1 . +.It Session +A session is a set of one or more process groups. +A session is created by a successful call to +.Xr setsid 2 , +which causes the caller to become the only member of the only process +group in the new session. +.It Session leader +A process that has created a new session by a successful call to +.Xr setsid 2 , +is known as a session leader. +Only a session leader may acquire a terminal as its controlling terminal (see +.Xr termios 4 ) . +.It Controlling process +A session leader with a controlling terminal is a controlling process. +.It Controlling terminal +A terminal that is associated with a session is known as the controlling +terminal for that session and its members. +.It "Terminal Process Group ID" +A terminal may be acquired by a session leader as its controlling terminal. +Once a terminal is associated with a session, any of the process groups +within the session may be placed into the foreground by setting +the terminal process group ID to the ID of the process group. +This facility is used +to arbitrate between multiple jobs contending for the same terminal; +(see +.Xr csh 1 +and +.Xr tty 4 ) . +.It "Orphaned Process Group" +A process group is considered to be +.Em orphaned +if it is not under the control of a job control shell. +More precisely, a process group is orphaned +when none of its members has a parent process that is in the same session +as the group, +but is in a different process group. +Note that when a process exits, the parent process for its children +is normally changed to be +.Xr init 8 , +which is in a separate session. +Not all members of an orphaned process group are necessarily orphaned +processes (those whose creating process has exited). +The process group of a session leader is orphaned by definition. +.It "Real User ID and Real Group ID" +Each user on the system is identified by a positive integer +termed the real user ID. +.Pp +Each user is also a member of one or more groups. +One of these groups is distinguished from others and +used in implementing accounting facilities. +The positive +integer corresponding to this distinguished group is termed +the real group ID. +.Pp +All processes have a real user ID and real group ID. +These are initialized from the equivalent attributes +of the process that created it. +.It "Effective User Id, Effective Group Id, and Group Access List" +Access to system resources is governed by two values: +the effective user ID, and the group access list. +The first member of the group access list is also known as the +effective group ID. +(In POSIX.1, the group access list is known as the set of supplementary +group IDs, and it is unspecified whether the effective group ID is +a member of the list.) +.Pp +The effective user ID and effective group ID are initially the +process's real user ID and real group ID respectively. +Either +may be modified through execution of a set-user-ID or set-group-ID +file (possibly by one its ancestors) (see +.Xr execve 2 ) . +By convention, the effective group ID (the first member of the group access +list) is duplicated, so that the execution of a set-group-ID program +does not result in the loss of the original (real) group ID. +.Pp +The group access list is a set of group IDs +used only in determining resource accessibility. +Access checks +are performed as described below in ``File Access Permissions''. +.It "Saved Set User ID and Saved Set Group ID" +When a process executes a new file, the effective user ID is set +to the owner of the file if the file is set-user-ID, and the effective +group ID (first element of the group access list) is set to the group +of the file if the file is set-group-ID. +The effective user ID of the process is then recorded as the saved set-user-ID, +and the effective group ID of the process is recorded as the saved set-group-ID. +These values may be used to regain those values as the effective user +or group ID after reverting to the real ID (see +.Xr setuid 2 ) . +(In POSIX.1, the saved set-user-ID and saved set-group-ID are optional, +and are used in setuid and setgid, but this does not work as desired +for the super-user.) +.It Super-user +A process is recognized as a +.Em super-user +process and is granted special privileges if its effective user ID is 0. +.It Descriptor +An integer assigned by the system when a file is referenced +by +.Xr open 2 +or +.Xr dup 2 , +or when a socket is created by +.Xr pipe 2 , +.Xr socket 2 +or +.Xr socketpair 2 , +which uniquely identifies an access path to that file or socket from +a given process or any of its children. +.It File Name +Names consisting of up to +.Brq Dv NAME_MAX +characters may be used to name +an ordinary file, special file, or directory. +.Pp +These characters may be arbitrary eight-bit values, +excluding +.Dv NUL +.Tn ( ASCII +0) and the +.Ql \&/ +character (slash, +.Tn ASCII +47). +.Pp +Note that it is generally unwise to use +.Ql \&* , +.Ql \&? , +.Ql \&[ +or +.Ql \&] +as part of +file names because of the special meaning attached to these characters +by the shell. +.It Path Name +A path name is a +.Dv NUL Ns -terminated +character string starting with an +optional slash +.Ql \&/ , +followed by zero or more directory names separated +by slashes, optionally followed by a file name. +The total length of a path name must be less than +.Brq Dv PATH_MAX +characters. +(On some systems, this limit may be infinite.) +.Pp +If a path name begins with a slash, the path search begins at the +.Em root +directory. +Otherwise, the search begins from the current working directory. +A slash by itself names the root directory. +An empty +pathname refers to the current directory. +.It Directory +A directory is a special type of file that contains entries +that are references to other files. +Directory entries are called links. +By convention, a directory +contains at least two links, +.Ql .\& +and +.Ql \&.. , +referred to as +.Em dot +and +.Em dot-dot +respectively. +Dot refers to the directory itself and +dot-dot refers to its parent directory. +.It "Root Directory and Current Working Directory" +Each process has associated with it a concept of a root directory +and a current working directory for the purpose of resolving path +name searches. +A process's root directory need not be the root +directory of the root file system. +.It File Access Permissions +Every file in the file system has a set of access permissions. +These permissions are used in determining whether a process +may perform a requested operation on the file (such as opening +a file for writing). +Access permissions are established at the +time a file is created. +They may be changed at some later time +through the +.Xr chmod 2 +call. +.Pp +File access is broken down according to whether a file may be: read, +written, or executed. +Directory files use the execute +permission to control if the directory may be searched. +.Pp +File access permissions are interpreted by the system as +they apply to three different classes of users: the owner +of the file, those users in the file's group, anyone else. +Every file has an independent set of access permissions for +each of these classes. +When an access check is made, the system +decides if permission should be granted by checking the access +information applicable to the caller. +.Pp +Read, write, and execute/search permissions on +a file are granted to a process if: +.Pp +The process's effective user ID is that of the super-user. +(Note: +even the super-user cannot execute a non-executable file.) +.Pp +The process's effective user ID matches the user ID of the owner +of the file and the owner permissions allow the access. +.Pp +The process's effective user ID does not match the user ID of the +owner of the file, and either the process's effective +group ID matches the group ID +of the file, or the group ID of the file is in +the process's group access list, +and the group permissions allow the access. +.Pp +Neither the effective user ID nor effective group ID +and group access list of the process +match the corresponding user ID and group ID of the file, +but the permissions for ``other users'' allow access. +.Pp +Otherwise, permission is denied. +.It Sockets and Address Families +A socket is an endpoint for communication between processes. +Each socket has queues for sending and receiving data. +.Pp +Sockets are typed according to their communications properties. +These properties include whether messages sent and received +at a socket require the name of the partner, whether communication +is reliable, the format used in naming message recipients, etc. +.Pp +Each instance of the system supports some +collection of socket types; consult +.Xr socket 2 +for more information about the types available and +their properties. +.Pp +Each instance of the system supports some number of sets of +communications protocols. +Each protocol set supports addresses +of a certain format. +An Address Family is the set of addresses +for a specific group of protocols. +Each socket has an address +chosen from the address family in which the socket was created. +.El +.Sh SEE ALSO +.Xr intro 3 , +.Xr perror 3 diff --git a/lib/libc/sys/ioctl.2 b/lib/libc/sys/ioctl.2 new file mode 100644 index 000000000000..81500a938ac9 --- /dev/null +++ b/lib/libc/sys/ioctl.2 @@ -0,0 +1,155 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ioctl.2 8.2 (Berkeley) 12/11/93 +.\" +.\" $FreeBSD$ +.\" +.Dd September 11, 2013 +.Dt IOCTL 2 +.Os +.Sh NAME +.Nm ioctl +.Nd control device +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/ioctl.h +.Ft int +.Fn ioctl "int fd" "unsigned long request" ... +.Sh DESCRIPTION +The +.Fn ioctl +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 +.Fn ioctl +requests. +The argument +.Fa fd +must be an open file descriptor. +.Pp +The third argument to +.Fn ioctl +is traditionally named +.Va "char *argp" . +Most uses of +.Fn ioctl , +however, require the third argument to be a +.Vt caddr_t +or an +.Vt int . +.Pp +An +.Fn ioctl +.Fa request +has encoded in it whether the argument is an +.Dq in +argument +or +.Dq out +argument, and the size of the argument +.Fa argp +in bytes. +Macros and defines used in specifying an ioctl +.Fa request +are located in the file +.In sys/ioctl.h . +.Sh GENERIC IOCTLS +Some generic ioctls are not implemented for all types of file +descriptors. +These include: +.Bl -tag -width "xxxxxx" +.It Dv FIONREAD int +Get the number of bytes that are immediately available for reading. +.It Dv FIONWRITE int +Get the number of bytes in the descriptor's send queue. +These bytes are data which has been written to the descriptor but +which are being held by the kernel for further processing. +The nature of the required processing depends on the underlying device. +For TCP sockets, these bytes have not yet been acknowledged by the +other side of the connection. +.It Dv FIONSPACE int +Get the free space in the descriptor's send queue. +This value is the size of the send queue minus the number of bytes +being held in the queue. +Note: while this value represents the number of bytes that may be +added to the queue, other resource limitations may cause a write +not larger than the send queue's space to be blocked. +One such limitation would be a lack of network buffers for a write +to a network connection. +.El +.Sh RETURN VALUES +If an error has occurred, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn ioctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor. +.It Bq Er ENOTTY +The +.Fa fd +argument +is not associated with a character +special device. +.It Bq Er ENOTTY +The specified request does not apply to the kind +of object that the descriptor +.Fa fd +references. +.It Bq Er EINVAL +The +.Fa request +or +.Fa argp +argument +is not valid. +.It Bq Er EFAULT +The +.Fa argp +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr fcntl 2 , +.Xr intro 4 , +.Xr tty 4 +.Sh HISTORY +The +.Fn ioctl +function appeared in +.At v7 . diff --git a/lib/libc/sys/issetugid.2 b/lib/libc/sys/issetugid.2 new file mode 100644 index 000000000000..aed5062a10ad --- /dev/null +++ b/lib/libc/sys/issetugid.2 @@ -0,0 +1,98 @@ +.\" $OpenBSD: issetugid.2,v 1.7 1997/02/18 00:16:09 deraadt Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 25, 1996 +.Dt ISSETUGID 2 +.Os +.Sh NAME +.Nm issetugid +.Nd is current process tainted by uid or gid changes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn issetugid void +.Sh DESCRIPTION +The +.Fn issetugid +system call returns 1 if the process environment or memory address space +is considered +.Dq tainted , +and returns 0 otherwise. +.Pp +A process is tainted if it was created as a result of an +.Xr execve 2 +system call which had either of the setuid or setgid bits set (and extra +privileges were given as a result) or if it has changed any of its real, +effective or saved user or group ID's since it began execution. +.Pp +This system call exists so that library routines (eg: libc, libtermcap) +can reliably determine if it is safe to use information +that was obtained from the user, in particular the results from +.Xr getenv 3 +should be viewed with suspicion if it is used to control operation. +.Pp +A +.Dq tainted +status is inherited by child processes as a result of the +.Xr fork 2 +system call (or other library code that calls fork, such as +.Xr popen 3 ) . +.Pp +It is assumed that a program that clears all privileges as it prepares +to execute another will also reset the environment, hence the +.Dq tainted +status will not be passed on. +This is important for programs such as +.Xr su 1 +which begin setuid but need to be able to create an untainted process. +.Sh ERRORS +The +.Fn issetugid +system call is always successful, and no return value is reserved to +indicate an error. +.Sh SEE ALSO +.Xr execve 2 , +.Xr fork 2 , +.Xr setegid 2 , +.Xr seteuid 2 , +.Xr setgid 2 , +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn issetugid +system call first appeared in +.Ox 2.0 +and was also implemented in +.Fx 3.0 . diff --git a/lib/libc/sys/jail.2 b/lib/libc/sys/jail.2 new file mode 100644 index 000000000000..2e13a6c3a381 --- /dev/null +++ b/lib/libc/sys/jail.2 @@ -0,0 +1,411 @@ +.\" Copyright (c) 1999 Poul-Henning Kamp. +.\" Copyright (c) 2009 James Gritton. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 8, 2012 +.Dt JAIL 2 +.Os +.Sh NAME +.Nm jail , +.Nm jail_get , +.Nm jail_set , +.Nm jail_remove , +.Nm jail_attach +.Nd create and manage system jails +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/jail.h +.Ft int +.Fn jail "struct jail *jail" +.Ft int +.Fn jail_attach "int jid" +.Ft int +.Fn jail_remove "int jid" +.In sys/uio.h +.Ft int +.Fn jail_get "struct iovec *iov" "u_int niov" "int flags" +.Ft int +.Fn jail_set "struct iovec *iov" "u_int niov" "int flags" +.Sh DESCRIPTION +The +.Fn jail +system call sets up a jail and locks the current process in it. +.Pp +The argument is a pointer to a structure describing the prison: +.Bd -literal -offset indent +struct jail { + uint32_t version; + char *path; + char *hostname; + char *jailname; + unsigned int ip4s; + unsigned int ip6s; + struct in_addr *ip4; + struct in6_addr *ip6; +}; +.Ed +.Pp +.Dq Li version +defines the version of the API in use. +.Dv JAIL_API_VERSION +is defined for the current version. +.Pp +The +.Dq Li path +pointer should be set to the directory which is to be the root of the +prison. +.Pp +The +.Dq Li hostname +pointer can be set to the hostname of the prison. +This can be changed +from the inside of the prison. +.Pp +The +.Dq Li jailname +pointer is an optional name that can be assigned to the jail +for example for management purposes. +.Pp +The +.Dq Li ip4s +and +.Dq Li ip6s +give the numbers of IPv4 and IPv6 addresses that will be passed +via their respective pointers. +.Pp +The +.Dq Li ip4 +and +.Dq Li ip6 +pointers can be set to an arrays of IPv4 and IPv6 addresses to be assigned to +the prison, or NULL if none. +IPv4 addresses must be in network byte order. +.Pp +This is equivalent to, and deprecated in favor of, the +.Fn jail_set +system call (see below), with the parameters +.Va path , +.Va host.hostname , +.Va name , +.Va ip4.addr , +and +.Va ip6.addr , +and with the +.Dv JAIL_ATTACH +flag. +.Pp +The +.Fn jail_set +system call creates a new jail, or modifies an existing one, and optionally +locks the current process in it. +Jail parameters are passed as an array of name-value pairs in the array +.Fa iov , +containing +.Fa niov +elements. +Parameter names are a null-terminated string, and values may be strings, +integers, or other arbitrary data. +Some parameters are boolean, and do not have a value (their length is zero) +but are set by the name alone with or without a +.Dq no +prefix, e.g. +.Va persist +or +.Va nopersist . +Any parameters not set will be given default values, generally based on +the current environment. +.Pp +Jails have a set of core parameters, and modules can add their own jail +parameters. +The current set of available parameters, and their formats, can be +retrieved via the +.Va security.jail.param +sysctl MIB entry. +Notable parameters include those mentioned in the +.Fn jail +description above, as well as +.Va jid +and +.Va name , +which identify the jail being created or modified. +See +.Xr jail 8 +for more information on the core jail parameters. +.Pp +The +.Fa flags +arguments consists of one or more of the following flags: +.Bl -tag -width indent +.It Dv JAIL_CREATE +Create a new jail. +If a +.Va jid +or +.Va name +parameters exists, they must not refer to an existing jail. +.It Dv JAIL_UPDATE +Modify an existing jail. +One of the +.Va jid +or +.Va name +parameters must exist, and must refer to an existing jail. +If both +.Dv JAIL_CREATE +and +.Dv JAIL_UPDATE +are set, a jail will be created if it does not yet exist, and modified if it +does exist. +.It Dv JAIL_ATTACH +In addition to creating or modifying the jail, attach the current process to +it, as with the +.Fn jail_attach +system call. +.It Dv JAIL_DYING +Allow setting a jail that is in the process of being removed. +.El +.Pp +The +.Fn jail_get +system call retrieves jail parameters, using the same name-value list as +.Fn jail_set +in the +.Fa iov +and +.Fa niov +arguments. +The jail to read can be specified by either +.Va jid +or +.Va name +by including those parameters in the list. +If they are included but are not intended to be the search key, they +should be cleared (zero and the empty string respectively). +.Pp +The special parameter +.Va lastjid +can be used to retrieve a list of all jails. +It will fetch the jail with the jid above and closest to the passed value. +The first jail (usually but not always jid 1) can be found by passing a +.Va lastjid +of zero. +.Pp +The +.Fa flags +arguments consists of one or more following flags: +.Bl -tag -width indent +.It Dv JAIL_DYING +Allow getting a jail that is in the process of being removed. +.El +.Pp +The +.Fn jail_attach +system call attaches the current process to an existing jail, +identified by +.Fa jid . +.Pp +The +.Fn jail_remove +system call removes the jail identified by +.Fa jid . +It will kill all processes belonging to the jail, and remove any children +of that jail. +.Sh RETURN VALUES +If successful, +.Fn jail , +.Fn jail_set , +and +.Fn jail_get +return a non-negative integer, termed the jail identifier (JID). +They return \-1 on failure, and set +.Va errno +to indicate the error. +.Pp +.Rv -std jail_attach jail_remove +.Sh ERRORS +The +.Fn jail +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +This process is not allowed to create a jail, either because it is not +the super-user, or because it would exceed the jail's +.Va children.max +limit. +.It Bq Er EFAULT +.Fa jail +points to an address outside the allocated address space of the process. +.It Bq Er EINVAL +The version number of the argument is not correct. +.It Bq Er EAGAIN +No free JID could be found. +.El +.Pp +The +.Fn jail_set +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +This process is not allowed to create a jail, either because it is not +the super-user, or because it would exceed the jail's +.Va children.max +limit. +.It Bq Er EPERM +A jail parameter was set to a less restrictive value then the current +environment. +.It Bq Er EFAULT +.Fa Iov , +or one of the addresses contained within it, +points to an address outside the allocated address space of the process. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +or +.Va name +parameter does not exist, and the +.Dv JAIL_CREATE +flag is not set. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +is not accessible by the process, because the process is in a different +jail. +.It Bq Er EEXIST +The jail referred to by a +.Va jid +or +.Va name +parameter exists, and the +.Dv JAIL_UPDATE +flag is not set. +.It Bq Er EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter is out of range. +.It Bq Er EINVAL +A supplied string parameter is not null-terminated. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.It Bq Er EINVAL +One of the +.Dv JAIL_CREATE +or +.Dv JAIL_UPDATE +flags is not set. +.It Bq Er ENAMETOOLONG +A supplied string parameter is longer than allowed. +.It Bq Er EAGAIN +There are no jail IDs left. +.El +.Pp +The +.Fn jail_get +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa Iov , +or one of the addresses contained within it, +points to an address outside the allocated address space of the process. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +or +.Va name +parameter does not exist. +.It Bq Er ENOENT +The jail referred to by a +.Va jid +is not accessible by the process, because the process is in a different +jail. +.It Bq Er ENOENT +The +.Va lastjid +parameter is greater than the highest current jail ID. +.It Bq Er EINVAL +A supplied parameter is the wrong size. +.It Bq Er EINVAL +A supplied parameter name does not match any known parameters. +.El +.Pp +The +.Fn jail_attach +and +.Fn jail_remove +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +A user other than the super-user attempted to attach to or remove a jail. +.It Bq Er EINVAL +The jail specified by +.Fa jid +does not exist. +.El +.Pp +Further +.Fn jail , +.Fn jail_set , +and +.Fn jail_attach +call +.Xr chroot 2 +internally, so they can fail for all the same reasons. +Please consult the +.Xr chroot 2 +manual page for details. +.Sh SEE ALSO +.Xr chdir 2 , +.Xr chroot 2 , +.Xr jail 8 +.Sh HISTORY +The +.Fn jail +system call appeared in +.Fx 4.0 . +The +.Fn jail_attach +system call appeared in +.Fx 5.1 . +The +.Fn jail_set , +.Fn jail_get , +and +.Fn jail_remove +system calls appeared in +.Fx 8.0 . +.Sh AUTHORS +The jail feature was written by +.An Poul-Henning Kamp +for R&D Associates +who contributed it to +.Fx . +.An James Gritton +added the extensible jail parameters and hierarchical jails. diff --git a/lib/libc/sys/kenv.2 b/lib/libc/sys/kenv.2 new file mode 100644 index 000000000000..dc17388f08ba --- /dev/null +++ b/lib/libc/sys/kenv.2 @@ -0,0 +1,179 @@ +.\" +.\" Copyright (C) 2002 Chad David <davidc@FreeBSD.org>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY +.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +.\" DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 17, 2002 +.Dt KENV 2 +.Os +.Sh NAME +.Nm kenv +.Nd kernel environment +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In kenv.h +.Ft int +.Fn kenv "int action" "const char *name" "char *value" "int len" +.Sh DESCRIPTION +The +.Fn kenv +system call manipulates kernel environment variables. +It supports the well known userland actions of getting, setting and unsetting +environment variables, as well as the ability to dump all of the entries in +the kernel environment. +.Pp +The +.Fa action +argument can be one of the following: +.Bl -tag -width ".Dv KENV_UNSET" +.It Dv KENV_GET +Returns the value associated with the named kernel environment variable. +If the variable is not found, \-1 is returned and +the global variable +.Va errno +is set to +.Er ENOENT . +Only the number of bytes available in +.Fa value +are copied out. +.It Dv KENV_SET +Sets or adds a new kernel environment variable. +This option is only available to the superuser. +.It Dv KENV_UNSET +Unsets the kernel environment variable +.Fa name . +If the variable does not exist, \-1 is returned and +the global variable +.Va errno +is set to +.Er EINVAL . +This option is only available to the superuser. +.It Dv KENV_DUMP +Dumps as much of the kernel environment as will fit in +.Fa value . +If +.Fa value +is +.Dv NULL , +.Fn kenv +will return the number of bytes required to copy out the entire environment. +.El +.Pp +The +.Fa name +argument is the name of the environment variable to be affected. +In the case of +.Dv KENV_DUMP +it is ignored. +.Pp +The +.Fa value +argument contains either the value to set the environment variable +.Fa name +to in the case of +.Dv KENV_SET , +or it points to the location where +.Fn kenv +should copy return data to in the case of +.Dv KENV_DUMP +and +.Dv KENV_GET . +If +.Fa value +is +.Dv NULL +in the case of +.Dv KENV_DUMP , +.Fn kenv +will return the number of bytes required to copy out the entire environment. +.Pp +The +.Fa len +argument indicates how many bytes of storage +.Fa value +points to. +.Sh RETURN VALUES +The +.Fn kenv +system call returns 0 if successful in the case of +.Dv KENV_SET +and +.Dv KENV_UNSET , +and the number of bytes copied into +.Fa value +in the case of +.Dv KENV_DUMP +and +.Dv KENV_GET . +If an error occurs, a value of \-1 is returned and +the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn kenv +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa action +argument +is not a valid option, or the length of the +.Fa value +is less than 1 for a +.Dv KENV_SET . +.It Bq Er ENOENT +no value could be found for +.Fa name +for a +.Dv KENV_SET +or +.Dv KENV_UNSET . +.It Bq Er EPERM +a user other than the superuser attempted to set or unset a kernel +environment variable. +.It Bq Er EFAULT +bad address was encountered while attempting to copy in user arguments, +or copy out value(s). +.It Bq Er ENAMETOOLONG +the name of a variable supplied by the user is longer than +.Dv KENV_MNAMELEN +or the value of a variable is longer than +.Dv KENV_MVALLEN . +.El +.Sh SEE ALSO +.Xr kenv 1 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org . +.Pp +The +.Fn kenv +system call was written by +.An Maxime Henrion Aq Mt mux@FreeBSD.org . diff --git a/lib/libc/sys/kevent.c b/lib/libc/sys/kevent.c new file mode 100644 index 000000000000..5f84ef8b10a6 --- /dev/null +++ b/lib/libc/sys/kevent.c @@ -0,0 +1,53 @@ +/* + * Copyright (c) 2015 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/event.h> +#include <sys/time.h> +#include "libc_private.h" + +__weak_reference(__sys_kevent, __kevent); + +#pragma weak kevent +int +kevent(int kq, const struct kevent *changelist, int nchanges, + struct kevent *eventlist, int nevents, const struct timespec *timeout) +{ + + return (((int (*)(int, const struct kevent *, int, + struct kevent *, int, const struct timespec *)) + __libc_interposing[INTERPOS_kevent])(kq, changelist, nchanges, + eventlist, nevents, timeout)); +} diff --git a/lib/libc/sys/kill.2 b/lib/libc/sys/kill.2 new file mode 100644 index 000000000000..98c305086404 --- /dev/null +++ b/lib/libc/sys/kill.2 @@ -0,0 +1,156 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)kill.2 8.3 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd March 15, 2012 +.Dt KILL 2 +.Os +.Sh NAME +.Nm kill +.Nd send signal to a process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In signal.h +.Ft int +.Fn kill "pid_t pid" "int sig" +.Sh DESCRIPTION +The +.Fn kill +system call sends the signal given by +.Fa sig +to +.Fa pid , +a +process or a group of processes. +The +.Fa sig +argument +may be one of the signals specified in +.Xr sigaction 2 +or it may be 0, in which case +error checking is performed but no +signal is actually sent. +This can be used to check the validity of +.Fa pid . +.Pp +For a process to have permission to send a signal to a process designated +by +.Fa pid , +the user must be the super-user, or +the real or saved user ID of the receiving process must match +the real or effective user ID of the sending process. +A single exception is the signal SIGCONT, which may always be sent +to any process with the same session ID as the sender. +In addition, if the +.Va security.bsd.conservative_signals +.Xr sysctl +is set to 1, the user is not a super-user, and +the receiver is set-uid, then +only job control and terminal control signals may +be sent (in particular, only SIGKILL, SIGINT, SIGTERM, SIGALRM, +SIGSTOP, SIGTTIN, SIGTTOU, SIGTSTP, SIGHUP, SIGUSR1, SIGUSR2). +.Bl -tag -width Ds +.It \&If Fa pid No \&is greater than zero : +The +.Fa sig +signal +is sent to the process whose ID is equal to +.Fa pid . +.It \&If Fa pid No \&is zero : +The +.Fa sig +signal +is sent to all processes whose group ID is equal +to the process group ID of the sender, and for which the +process has permission; +this is a variant of +.Xr killpg 2 . +.It \&If Fa pid No \&is -1 : +If the user has super-user privileges, +the signal is sent to all processes excluding +system processes +(with +.Dv P_SYSTEM +flag set), +process with ID 1 +(usually +.Xr init 8 ) , +and the process sending the signal. +If the user is not the super user, the signal is sent to all processes +with the same uid as the user excluding the process sending the signal. +No error is returned if any process could be signaled. +.El +.Pp +For compatibility with System V, +if the process number is negative but not -1, +the signal is sent to all processes whose process group ID +is equal to the absolute value of the process number. +This is a variant of +.Xr killpg 2 . +.Sh RETURN VALUES +.Rv -std kill +.Sh ERRORS +The +.Fn kill +system call +will fail and no signal will be sent if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sig +argument +is not a valid signal number. +.It Bq Er ESRCH +No process or process group can be found corresponding to that specified by +.Fa pid . +.It Bq Er EPERM +The sending process does not have permission to send +.Va sig +to the receiving process. +.El +.Sh SEE ALSO +.Xr getpgrp 2 , +.Xr getpid 2 , +.Xr killpg 2 , +.Xr sigaction 2 , +.Xr sigqueue 2 , +.Xr raise 3 , +.Xr init 8 +.Sh STANDARDS +The +.Fn kill +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn kill +function appeared in +.At v7 . diff --git a/lib/libc/sys/kldfind.2 b/lib/libc/sys/kldfind.2 new file mode 100644 index 000000000000..a8892ed00650 --- /dev/null +++ b/lib/libc/sys/kldfind.2 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 3, 1999 +.Dt KLDFIND 2 +.Os +.Sh NAME +.Nm kldfind +.Nd returns the fileid of a kld file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldfind "const char *file" +.Sh DESCRIPTION +The +.Fn kldfind +system call +returns the fileid of the kld file referenced by +.Fa file . +.Sh RETURN VALUES +The +.Fn kldfind +system call +returns the fileid of the kld file referenced by +.Fa file . +Upon error, +.Fn kldfind +returns -1 and sets +.Va errno +to indicate the error. +.Sh ERRORS +.Va errno +is set to the following if +.Fn kldfind +fails: +.Bl -tag -width Er +.It Bq Er EFAULT +The data required for this operation could not be read from the kernel space. +.It Bq Er ENOENT +The file specified is not loaded in the kernel. +.El +.Sh SEE ALSO +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/kldfirstmod.2 b/lib/libc/sys/kldfirstmod.2 new file mode 100644 index 000000000000..d9967ccd779c --- /dev/null +++ b/lib/libc/sys/kldfirstmod.2 @@ -0,0 +1,76 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 3, 1999 +.Dt KLDFIRSTMOD 2 +.Os +.Sh NAME +.Nm kldfirstmod +.Nd "return first module id from the kld file specified" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldfirstmod "int fileid" +.Sh DESCRIPTION +The +.Fn kldfirstmod +system call returns the module id pertaining to the first module referenced by +.Fa fileid . +.Sh RETURN VALUES +The +.Fn kldfirstmod +will return the id of the first module referenced by +.Fa fileid +or 0 if there are no references. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOENT +The kld file referenced by +.Fa fileid +was not found. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/kldload.2 b/lib/libc/sys/kldload.2 new file mode 100644 index 000000000000..d31cc086e2f9 --- /dev/null +++ b/lib/libc/sys/kldload.2 @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 3, 1999 +.Dt KLDLOAD 2 +.Os +.Sh NAME +.Nm kldload +.Nd load KLD files into the kernel +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldload "const char *file" +.Sh DESCRIPTION +The +.Fn kldload +system call +loads a kld file into the kernel using the kernel linker. +.Sh RETURN VALUES +The +.Fn kldload +system call +returns the fileid of the kld file which was loaded into the kernel. +If an error occurs, +.Fn kldload +will return -1 and set +.Va errno +to indicate the error. +.Sh ERRORS +The named file is loaded unless: +.Bl -tag -width Er +.It Bq Er EPERM +You do not have access to read the file or link it with the kernel. +You should be the root user to be able to use the +.Nm kld +system calls. +.It Bq Er EFAULT +Bad address encountered when adding kld info into the kernel space. +.It Bq Er ENOMEM +There is no memory to load the file into the kernel. +.It Bq Er ENOENT +The file was not found. +.It Bq Er ENOEXEC +The file format of +.Fa file +was unrecognized. +.It Bq Er EEXIST +The supplied +.Fa file +has already been loaded. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldload 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/kldnext.2 b/lib/libc/sys/kldnext.2 new file mode 100644 index 000000000000..c856a2e671f8 --- /dev/null +++ b/lib/libc/sys/kldnext.2 @@ -0,0 +1,89 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 22, 2006 +.Dt KLDNEXT 2 +.Os +.Sh NAME +.Nm kldnext +.Nd return the fileid of the next kld file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldnext "int fileid" +.Sh DESCRIPTION +The +.Fn kldnext +system call +returns the fileid of the next kld file (that is, the one after +.Fa fileid ) +or 0 if +.Fa fileid +is the last file loaded. +To get the fileid of the first kld file, pass +.Fa fileid +of 0 to +.Fn kldnext . +.Sh RETURN VALUES +The +.Fn kldnext +system call +returns the fileid of the next kld file or 0 if successful. +Otherwise +.Fn kldnext +returns the value \-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The only error set by +.Fn kldnext +is +.Er ENOENT , +which is set when +.Fa fileid +refers to a kld file that does not exist (is not loaded). +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/kldstat.2 b/lib/libc/sys/kldstat.2 new file mode 100644 index 000000000000..8b4e5320dd75 --- /dev/null +++ b/lib/libc/sys/kldstat.2 @@ -0,0 +1,133 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 28, 2012 +.Dt KLDSTAT 2 +.Os +.Sh NAME +.Nm kldstat +.Nd get status of kld file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldstat "int fileid" "struct kld_file_stat *stat" +.Sh DESCRIPTION +The +.Fn kldstat +system call writes the info for the file referred to by +.Fa fileid +into +.Fa stat . +.Bd -literal +struct kld_file_stat { + int version; /* set to sizeof(struct kld_file_stat) */ + char name[MAXPATHLEN]; + int refs; + int id; + caddr_t address; + size_t size; + char pathname[MAXPATHLEN]; +}; +.Ed +.Bl -tag -width XXXaddress +.It version +This field is set to the size of the structure mentioned above by the code +calling +.Fn kldstat , +and not +.Fn kldstat +itself. +.It name +The name of the file referred to by +.Fa fileid . +.It refs +The number of modules referenced by +.Fa fileid . +.It id +The id of the file specified in +.Fa fileid . +.It address +The load address of the kld file. +.It size +The amount of memory in bytes allocated by the file. +.It pathname +The full name of the file referred to by +.Fa fileid , +including the path. +.El +.Sh RETURN VALUES +.Rv -std kldstat +.Sh ERRORS +The information for the file referred to by +.Fa fileid +is filled into the structure pointed to by +.Fa stat +unless: +.Bl -tag -width Er +.It Bq Er ENOENT +The file was not found (probably not loaded). +.It Bq Er EINVAL +The version specified in the +.Fa version +field of stat is not the proper version. +You would need to rebuild world, the +kernel, or your application, if this error occurs, given that you did properly +fill in the +.Fa version +field. +.It Bq Er EFAULT +There was a problem copying one, some, or all of the fields into +.Fa stat +in the +.Xr copyout 9 +function. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . +.Sh BUGS +The pathname may not be accurate if the file system mounts have +changed since the module was loaded, or if this function is called +within a chrooted environment. diff --git a/lib/libc/sys/kldsym.2 b/lib/libc/sys/kldsym.2 new file mode 100644 index 000000000000..422feaa268fd --- /dev/null +++ b/lib/libc/sys/kldsym.2 @@ -0,0 +1,121 @@ +.\" Copyright (c) 2001 Chris Costello <chris@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 17, 2016 +.Dt KLDSYM 2 +.Os +.Sh NAME +.Nm kldsym +.Nd look up address by symbol name in a KLD +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldsym "int fileid" "int cmd" "void *data" +.Sh DESCRIPTION +The +.Fn kldsym +system call returns the address of the symbol specified in +.Fa data +in the module specified by +.Fa fileid . +If +.Fa fileid +is 0, all loaded modules are searched. +Currently, the only +.Fa cmd +implemented is +.Dv KLDSYM_LOOKUP . +.Pp +The +.Fa data +argument is of the following structure: +.Bd -literal -offset indent +struct kld_sym_lookup { + int version; /* sizeof(struct kld_sym_lookup) */ + char *symname; /* Symbol name we are looking up */ + u_long symvalue; + size_t symsize; +}; +.Ed +.Pp +The +.Va version +member is to be set +by the code calling +.Fn kldsym +to +.Fn sizeof "struct kld_sym_lookup" . +The next two members, +.Va version +and +.Va symname , +are specified by the user. +The last two, +.Va symvalue +and +.Va symsize , +are filled in by +.Fn kldsym +and contain the address associated with +.Va symname +and the size of the data it points to, respectively. +.Sh RETURN VALUES +.Rv -std kldsym +.Sh ERRORS +The +.Fn kldsym +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value in +.Fa data->version +or +.Fa cmd . +.It Bq Er ENOENT +The +.Fa fileid +argument +is invalid, +or the specified symbol could not be found. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 +.Sh HISTORY +The +.Fn kldsym +system call first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/kldunload.2 b/lib/libc/sys/kldunload.2 new file mode 100644 index 000000000000..d1c259b51461 --- /dev/null +++ b/lib/libc/sys/kldunload.2 @@ -0,0 +1,94 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 25, 2008 +.Dt KLDUNLOAD 2 +.Os +.Sh NAME +.Nm kldunload , kldunloadf +.Nd unload kld files +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldunload "int fileid" +.Ft int +.Fn kldunloadf "int fileid" "int flags" +.Sh DESCRIPTION +The +.Fn kldunload +system call +unloads a kld file from the kernel that was previously linked via +.Xr kldload 2 . +.Pp +The +.Fn kldunloadf +system call accepts an additional flags argument, which may be one of +.Dv LINKER_UNLOAD_NORMAL , +giving the same behavior as +.Fn kldunload , +or +.Dv LINKER_UNLOAD_FORCE , +which causes the unload to ignore a failure to quiesce the module. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The file referred to by +.Fa fileid +is unloaded unless: +.Bl -tag -width Er +.It Bq Er EPERM +You do not have access to unlink the file from the kernel. +.It Bq Er ENOENT +The file was not found. +.It Bq Er EBUSY +You attempted to unload a file linked by the kernel. +.It Bq Er EINVAL +The +.Fn kldunloadf +system call was passed invalid flags. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldunload 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2 new file mode 100644 index 000000000000..adaee1ec37e6 --- /dev/null +++ b/lib/libc/sys/kqueue.2 @@ -0,0 +1,771 @@ +.\" Copyright (c) 2000 Jonathan Lemon +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 3, 2016 +.Dt KQUEUE 2 +.Os +.Sh NAME +.Nm kqueue , +.Nm kevent +.Nd kernel event notification mechanism +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/event.h +.In sys/time.h +.Ft int +.Fn kqueue "void" +.Ft int +.Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout" +.Fn EV_SET "kev" ident filter flags fflags data udata +.Sh DESCRIPTION +The +.Fn kqueue +system call +provides a generic method of notifying the user when an event +happens or a condition holds, based on the results of small +pieces of kernel code termed filters. +A kevent is identified by the (ident, filter) pair; there may only +be one unique kevent per kqueue. +.Pp +The filter is executed upon the initial registration of a kevent +in order to detect whether a preexisting condition is present, and is also +executed whenever an event is passed to the filter for evaluation. +If the filter determines that the condition should be reported, +then the kevent is placed on the kqueue for the user to retrieve. +.Pp +The filter is also run when the user attempts to retrieve the kevent +from the kqueue. +If the filter indicates that the condition that triggered +the event no longer holds, the kevent is removed from the kqueue and +is not returned. +.Pp +Multiple events which trigger the filter do not result in multiple +kevents being placed on the kqueue; instead, the filter will aggregate +the events into a single struct kevent. +Calling +.Fn close +on a file descriptor will remove any kevents that reference the descriptor. +.Pp +The +.Fn kqueue +system call +creates a new kernel event queue and returns a descriptor. +The queue is not inherited by a child created with +.Xr fork 2 . +However, if +.Xr rfork 2 +is called without the +.Dv RFFDG +flag, then the descriptor table is shared, +which will allow sharing of the kqueue between two processes. +.Pp +The +.Fn kevent +system call +is used to register events with the queue, and return any pending +events to the user. +The +.Fa changelist +argument +is a pointer to an array of +.Va kevent +structures, as defined in +.In sys/event.h . +All changes contained in the +.Fa changelist +are applied before any pending events are read from the queue. +The +.Fa nchanges +argument +gives the size of +.Fa changelist . +The +.Fa eventlist +argument +is a pointer to an array of kevent structures. +The +.Fa nevents +argument +determines the size of +.Fa eventlist . +When +.Fa nevents +is zero, +.Fn kevent +will return immediately even if there is a +.Fa timeout +specified unlike +.Xr select 2 . +If +.Fa timeout +is a non-NULL pointer, it specifies a maximum interval to wait +for an event, which will be interpreted as a struct timespec. +If +.Fa timeout +is a NULL pointer, +.Fn kevent +waits indefinitely. +To effect a poll, the +.Fa timeout +argument should be non-NULL, pointing to a zero-valued +.Va timespec +structure. +The same array may be used for the +.Fa changelist +and +.Fa eventlist . +.Pp +The +.Fn EV_SET +macro is provided for ease of initializing a +kevent structure. +.Pp +The +.Va kevent +structure is defined as: +.Bd -literal +struct kevent { + uintptr_t ident; /* identifier for this event */ + short filter; /* filter for event */ + u_short flags; /* action flags for kqueue */ + u_int fflags; /* filter flag value */ + intptr_t data; /* filter data value */ + void *udata; /* opaque user data identifier */ +}; +.Ed +.Pp +The fields of +.Fa struct kevent +are: +.Bl -tag -width "Fa filter" +.It Fa ident +Value used to identify this event. +The exact interpretation is determined by the attached filter, +but often is a file descriptor. +.It Fa filter +Identifies the kernel filter used to process this event. +The pre-defined +system filters are described below. +.It Fa flags +Actions to perform on the event. +.It Fa fflags +Filter-specific flags. +.It Fa data +Filter-specific data value. +.It Fa udata +Opaque user-defined value passed through the kernel unchanged. +.El +.Pp +The +.Va flags +field can contain the following values: +.Bl -tag -width EV_DISPATCH +.It Dv EV_ADD +Adds the event to the kqueue. +Re-adding an existing event +will modify the parameters of the original event, and not result +in a duplicate entry. +Adding an event automatically enables it, +unless overridden by the EV_DISABLE flag. +.It Dv EV_ENABLE +Permit +.Fn kevent +to return the event if it is triggered. +.It Dv EV_DISABLE +Disable the event so +.Fn kevent +will not return it. +The filter itself is not disabled. +.It Dv EV_DISPATCH +Disable the event source immediately after delivery of an event. +See +.Dv EV_DISABLE +above. +.It Dv EV_DELETE +Removes the event from the kqueue. +Events which are attached to +file descriptors are automatically deleted on the last close of +the descriptor. +.It Dv EV_RECEIPT +This flag is useful for making bulk changes to a kqueue without draining +any pending events. +When passed as input, it forces +.Dv EV_ERROR +to always be returned. +When a filter is successfully added the +.Va data +field will be zero. +.It Dv EV_ONESHOT +Causes the event to return only the first occurrence of the filter +being triggered. +After the user retrieves the event from the kqueue, +it is deleted. +.It Dv EV_CLEAR +After the event is retrieved by the user, its state is reset. +This is useful for filters which report state transitions +instead of the current state. +Note that some filters may automatically +set this flag internally. +.It Dv EV_EOF +Filters may set this flag to indicate filter-specific EOF condition. +.It Dv EV_ERROR +See +.Sx RETURN VALUES +below. +.El +.Pp +The predefined system filters are listed below. +Arguments may be passed to and from the filter via the +.Va fflags +and +.Va data +fields in the kevent structure. +.Bl -tag -width "Dv EVFILT_PROCDESC" +.It Dv EVFILT_READ +Takes a descriptor as the identifier, and returns whenever +there is data available to read. +The behavior of the filter is slightly different depending +on the descriptor type. +.Bl -tag -width 2n +.It Sockets +Sockets which have previously been passed to +.Fn listen +return when there is an incoming connection pending. +.Va data +contains the size of the listen backlog. +.Pp +Other socket descriptors return when there is data to be read, +subject to the +.Dv SO_RCVLOWAT +value of the socket buffer. +This may be overridden with a per-filter low water mark at the +time the filter is added by setting the +.Dv NOTE_LOWAT +flag in +.Va fflags , +and specifying the new low water mark in +.Va data . +On return, +.Va data +contains the number of bytes of protocol data available to read. +.Pp +If the read direction of the socket has shutdown, then the filter +also sets +.Dv EV_EOF +in +.Va flags , +and returns the socket error (if any) in +.Va fflags . +It is possible for EOF to be returned (indicating the connection is gone) +while there is still data pending in the socket buffer. +.It Vnodes +Returns when the file pointer is not at the end of file. +.Va data +contains the offset from current position to end of file, +and may be negative. +.Pp +This behavior is different from +.Xr poll 2 , +where read events are triggered for regular files unconditionally. +This event can be triggered unconditionally by setting the +.Dv NOTE_FILE_POLL +flag in +.Va fflags . +.It "Fifos, Pipes" +Returns when the there is data to read; +.Va data +contains the number of bytes available. +.Pp +When the last writer disconnects, the filter will set +.Dv EV_EOF +in +.Va flags . +This may be cleared by passing in +.Dv EV_CLEAR , +at which point the +filter will resume waiting for data to become available before +returning. +.It "BPF devices" +Returns when the BPF buffer is full, the BPF timeout has expired, or +when the BPF has +.Dq immediate mode +enabled and there is any data to read; +.Va data +contains the number of bytes available. +.El +.It Dv EVFILT_WRITE +Takes a descriptor as the identifier, and returns whenever +it is possible to write to the descriptor. +For sockets, pipes +and fifos, +.Va data +will contain the amount of space remaining in the write buffer. +The filter will set EV_EOF when the reader disconnects, and for +the fifo case, this may be cleared by use of +.Dv EV_CLEAR . +Note that this filter is not supported for vnodes or BPF devices. +.Pp +For sockets, the low water mark and socket error handling is +identical to the +.Dv EVFILT_READ +case. +.It Dv EVFILT_AIO +The sigevent portion of the AIO request is filled in, with +.Va sigev_notify_kqueue +containing the descriptor of the kqueue that the event should +be attached to, +.Va sigev_notify_kevent_flags +containing the kevent flags which should be +.Dv EV_ONESHOT , +.Dv EV_CLEAR +or +.Dv EV_DISPATCH , +.Va sigev_value +containing the udata value, and +.Va sigev_notify +set to +.Dv SIGEV_KEVENT . +When the +.Fn aio_* +system call is made, the event will be registered +with the specified kqueue, and the +.Va ident +argument set to the +.Fa struct aiocb +returned by the +.Fn aio_* +system call. +The filter returns under the same conditions as +.Fn aio_error . +.It Dv EVFILT_VNODE +Takes a file descriptor as the identifier and the events to watch for in +.Va fflags , +and returns when one or more of the requested events occurs on the descriptor. +The events to monitor are: +.Bl -tag -width "Dv NOTE_CLOSE_WRITE" +.It Dv NOTE_ATTRIB +The file referenced by the descriptor had its attributes changed. +.It Dv NOTE_CLOSE +A file descriptor referencing the monitored file, was closed. +The closed file descriptor did not have write access. +.It Dv NOTE_CLOSE_WRITE +A file descriptor referencing the monitored file, was closed. +The closed file descriptor had write access. +.Pp +This note, as well as +.Dv NOTE_CLOSE , +are not activated when files are closed forcibly by +.Xr unmount 2 or +.Xr revoke 2 . +Instead, +.Dv NOTE_REVOKE +is sent for such events. +.It Dv NOTE_DELETE +The +.Fn unlink +system call was called on the file referenced by the descriptor. +.It Dv NOTE_EXTEND +For regular file, the file referenced by the descriptor was extended. +.Pp +For directory, reports that a directory entry was added or removed, +as the result of rename operation. +The +.Dv NOTE_EXTEND +event is not reported when a name is changed inside the directory. +.It Dv NOTE_LINK +The link count on the file changed. +In particular, the +.Dv NOTE_LINK +event is reported if a subdirectory was created or deleted inside +the directory referenced by the descriptor. +.It Dv NOTE_OPEN +The file referenced by the descriptor was opened. +.It Dv NOTE_READ +A read occurred on the file referenced by the descriptor. +.It Dv NOTE_RENAME +The file referenced by the descriptor was renamed. +.It Dv NOTE_REVOKE +Access to the file was revoked via +.Xr revoke 2 +or the underlying file system was unmounted. +.It Dv NOTE_WRITE +A write occurred on the file referenced by the descriptor. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_PROC +Takes the process ID to monitor as the identifier and the events to watch for +in +.Va fflags , +and returns when the process performs one or more of the requested events. +If a process can normally see another process, it can attach an event to it. +The events to monitor are: +.Bl -tag -width "Dv NOTE_TRACKERR" +.It Dv NOTE_EXIT +The process has exited. +The exit status will be stored in +.Va data . +.It Dv NOTE_FORK +The process has called +.Fn fork . +.It Dv NOTE_EXEC +The process has executed a new process via +.Xr execve 2 +or a similar call. +.It Dv NOTE_TRACK +Follow a process across +.Fn fork +calls. +The parent process registers a new kevent to monitor the child process +using the same +.Va fflags +as the original event. +The child process will signal an event with +.Dv NOTE_CHILD +set in +.Va fflags +and the parent PID in +.Va data . +.Pp +If the parent process fails to register a new kevent +.Pq usually due to resource limitations , +it will signal an event with +.Dv NOTE_TRACKERR +set in +.Va fflags , +and the child process will not signal a +.Dv NOTE_CHILD +event. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_PROCDESC +Takes the process descriptor created by +.Xr pdfork 2 +to monitor as the identifier and the events to watch for in +.Va fflags , +and returns when the associated process performs one or more of the +requested events. +The events to monitor are: +.Bl -tag -width "Dv NOTE_EXIT" +.It Dv NOTE_EXIT +The process has exited. +The exit status will be stored in +.Va data . +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_SIGNAL +Takes the signal number to monitor as the identifier and returns +when the given signal is delivered to the process. +This coexists with the +.Fn signal +and +.Fn sigaction +facilities, and has a lower precedence. +The filter will record +all attempts to deliver a signal to a process, even if the signal has +been marked as +.Dv SIG_IGN , +except for the +.Dv SIGCHLD +signal, which, if ignored, won't be recorded by the filter. +Event notification happens after normal +signal delivery processing. +.Va data +returns the number of times the signal has occurred since the last call to +.Fn kevent . +This filter automatically sets the +.Dv EV_CLEAR +flag internally. +.It Dv EVFILT_TIMER +Establishes an arbitrary timer identified by +.Va ident . +When adding a timer, +.Va data +specifies the timeout period. +The timer will be periodic unless +.Dv EV_ONESHOT +is specified. +On return, +.Va data +contains the number of times the timeout has expired since the last call to +.Fn kevent . +This filter automatically sets the EV_CLEAR flag internally. +There is a system wide limit on the number of timers +which is controlled by the +.Va kern.kq_calloutmax +sysctl. +.Bl -tag -width "Dv NOTE_USECONDS" +.It Dv NOTE_SECONDS +.Va data +is in seconds. +.It Dv NOTE_MSECONDS +.Va data +is in milliseconds. +.It Dv NOTE_USECONDS +.Va data +is in microseconds. +.It Dv NOTE_NSECONDS +.Va data +is in nanoseconds. +.El +.Pp +If +.Va fflags +is not set, the default is milliseconds. On return, +.Va fflags +contains the events which triggered the filter. +.It Dv EVFILT_USER +Establishes a user event identified by +.Va ident +which is not associated with any kernel mechanism but is triggered by +user level code. +The lower 24 bits of the +.Va fflags +may be used for user defined flags and manipulated using the following: +.Bl -tag -width "Dv NOTE_FFLAGSMASK" +.It Dv NOTE_FFNOP +Ignore the input +.Va fflags . +.It Dv NOTE_FFAND +Bitwise AND +.Va fflags . +.It Dv NOTE_FFOR +Bitwise OR +.Va fflags . +.It Dv NOTE_FFCOPY +Copy +.Va fflags . +.It Dv NOTE_FFCTRLMASK +Control mask for +.Va fflags . +.It Dv NOTE_FFLAGSMASK +User defined flag mask for +.Va fflags . +.El +.Pp +A user event is triggered for output with the following: +.Bl -tag -width "Dv NOTE_FFLAGSMASK" +.It Dv NOTE_TRIGGER +Cause the event to be triggered. +.El +.Pp +On return, +.Va fflags +contains the users defined flags in the lower 24 bits. +.El +.Sh CANCELLATION BEHAVIOUR +If +.Fa nevents +is non-zero, i.e. the function is potentially blocking, the call +is a cancellation point. +Otherwise, i.e. if +.Fa nevents +is zero, the call is not cancellable. +Cancellation can only occur before any changes are made to the kqueue, +or when the call was blocked and no changes to the queue were requested. +.Sh RETURN VALUES +The +.Fn kqueue +system call +creates a new kernel event queue and returns a file descriptor. +If there was an error creating the kernel event queue, a value of -1 is +returned and errno set. +.Pp +The +.Fn kevent +system call +returns the number of events placed in the +.Fa eventlist , +up to the value given by +.Fa nevents . +If an error occurs while processing an element of the +.Fa changelist +and there is enough room in the +.Fa eventlist , +then the event will be placed in the +.Fa eventlist +with +.Dv EV_ERROR +set in +.Va flags +and the system error in +.Va data . +Otherwise, +.Dv -1 +will be returned, and +.Dv errno +will be set to indicate the error condition. +If the time limit expires, then +.Fn kevent +returns 0. +.Sh EXAMPLES +.Bd -literal -compact +#include <sys/types.h> +#include <sys/event.h> +#include <sys/time.h> +#include <err.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <unistd.h> + +int +main(int argc, char **argv) +{ + struct kevent event; /* Event we want to monitor */ + struct kevent tevent; /* Event triggered */ + int kq, fd, ret; + + if (argc != 2) + err(EXIT_FAILURE, "Usage: %s path\en", argv[0]); + fd = open(argv[1], O_RDONLY); + if (fd == -1) + err(EXIT_FAILURE, "Failed to open '%s'", argv[1]); + + /* Create kqueue. */ + kq = kqueue(); + if (kq == -1) + err(EXIT_FAILURE, "kqueue() failed"); + + /* Initialize kevent structure. */ + EV_SET(&event, fd, EVFILT_VNODE, EV_ADD | EV_CLEAR, NOTE_WRITE, + 0, NULL); + /* Attach event to the kqueue. */ + ret = kevent(kq, &event, 1, NULL, 0, NULL); + if (ret == -1) + err(EXIT_FAILURE, "kevent register"); + if (event.flags & EV_ERROR) + errx(EXIT_FAILURE, "Event error: %s", strerror(event.data)); + + for (;;) { + /* Sleep until something happens. */ + ret = kevent(kq, NULL, 0, &tevent, 1, NULL); + if (ret == -1) { + err(EXIT_FAILURE, "kevent wait"); + } else if (ret > 0) { + printf("Something was written in '%s'\en", argv[1]); + } + } +} +.Ed +.Sh ERRORS +The +.Fn kqueue +system call fails if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The kernel failed to allocate enough memory for the kernel queue. +.It Bq Er ENOMEM +The +.Dv RLIMIT_KQUEUES +rlimit +(see +.Xr getrlimit 2 ) +for the current user would be exceeded. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.El +.Pp +The +.Fn kevent +system call fails if: +.Bl -tag -width Er +.It Bq Er EACCES +The process does not have permission to register a filter. +.It Bq Er EFAULT +There was an error reading or writing the +.Va kevent +structure. +.It Bq Er EBADF +The specified descriptor is invalid. +.It Bq Er EINTR +A signal was delivered before the timeout expired and before any +events were placed on the kqueue for return. +.It Bq Er EINTR +A cancellation request was delivered to the thread, but not yet handled. +.It Bq Er EINVAL +The specified time limit or filter is invalid. +.It Bq Er ENOENT +The event could not be found to be modified or deleted. +.It Bq Er ENOMEM +No memory was available to register the event +or, in the special case of a timer, the maximum number of +timers has been exceeded. +This maximum is configurable via the +.Va kern.kq_calloutmax +sysctl. +.It Bq Er ESRCH +The specified process to attach to does not exist. +.El +.Pp +When +.Fn kevent +call fails with +.Er EINTR +error, all changes in the +.Fa changelist +have been applied. +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_return 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr select 2 , +.Xr sigaction 2 , +.Xr write 2 , +.Xr pthread_setcancelstate 3 , +.Xr signal 3 +.Sh HISTORY +The +.Fn kqueue +and +.Fn kevent +system calls first appeared in +.Fx 4.1 . +.Sh AUTHORS +The +.Fn kqueue +system and this manual page were written by +.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . +.Sh BUGS +The +.Fa timeout +value is limited to 24 hours; longer timeouts will be silently +reinterpreted as 24 hours. diff --git a/lib/libc/sys/ktrace.2 b/lib/libc/sys/ktrace.2 new file mode 100644 index 000000000000..b02a6724bc3a --- /dev/null +++ b/lib/libc/sys/ktrace.2 @@ -0,0 +1,204 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ktrace.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd March 31, 2016 +.Dt KTRACE 2 +.Os +.Sh NAME +.Nm ktrace +.Nd process tracing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/uio.h +.In sys/ktrace.h +.Ft int +.Fn ktrace "const char *tracefile" "int ops" "int trpoints" "int pid" +.Sh DESCRIPTION +The +.Fn ktrace +system call enables or disables tracing of one or more processes. +Users may only trace their own processes. +Only the super-user can trace setuid or setgid programs. +.Pp +The +.Fa tracefile +argument +gives the pathname of the file to be used for tracing. +The file must exist and be a regular file writable by the calling process. +All trace records are always appended to the file, +so the file must be truncated to zero length to discard +previous trace data. +If tracing points are being disabled (see KTROP_CLEAR below), +.Fa tracefile +may be NULL. +.Pp +The +.Fa ops +argument specifies the requested ktrace operation. +The defined operations are: +.Bl -column KTRFLAG_DESCENDXXX -offset indent +.It KTROP_SET Ta "Enable trace points specified in" +.Fa trpoints . +.It KTROP_CLEAR Ta "Disable trace points specified in" +.Fa trpoints . +.It KTROP_CLEARFILE Ta "Stop all tracing." +.It KTRFLAG_DESCEND Ta "The tracing change should apply to the" +specified process and all its current children. +.El +.Pp +The +.Fa trpoints +argument specifies the trace points of interest. +The defined trace points are: +.Bl -column KTRFAC_PROCCTORXXX -offset indent +.It KTRFAC_SYSCALL Ta "Trace system calls." +.It KTRFAC_SYSRET Ta "Trace return values from system calls." +.It KTRFAC_NAMEI Ta "Trace name lookup operations." +.It KTRFAC_GENIO Ta "Trace all I/O (note that this option can" +generate much output). +.It KTRFAC_PSIG Ta "Trace posted signals." +.It KTRFAC_CSW Ta "Trace context switch points." +.It KTRFAC_USER Ta "Trace application-specific events." +.It KTRFAC_STRUCT Ta "Trace certain data structures." +.It KTRFAC_SYSCTL Ta "Trace sysctls." +.It KTRFAC_PROCCTOR Ta "Trace process construction." +.It KTRFAC_PROCDTOR Ta "Trace process destruction." +.It KTRFAC_CAPFAIL Ta "Trace capability failures." +.It KTRFAC_FAULT Ta "Trace page faults." +.It KTRFAC_FAULTEND Ta "Trace the end of page faults." +.It KTRFAC_INHERIT Ta "Inherit tracing to future children." +.El +.Pp +Each tracing event outputs a record composed of a generic header +followed by a trace point specific structure. +The generic header is: +.Bd -literal +struct ktr_header { + int ktr_len; /* length of buf */ + short ktr_type; /* trace record type */ + pid_t ktr_pid; /* process id */ + char ktr_comm[MAXCOMLEN+1]; /* command name */ + struct timeval ktr_time; /* timestamp */ + intptr_t ktr_tid; /* was ktr_buffer */ +}; +.Ed +.Pp +The +.Va ktr_len +field specifies the length of the +.Va ktr_type +data that follows this header. +The +.Va ktr_pid +and +.Va ktr_comm +fields specify the process and command generating the record. +The +.Va ktr_time +field gives the time (with microsecond resolution) +that the record was generated. +The +.Va ktr_tid +field holds a thread id. +.Pp +The generic header is followed by +.Va ktr_len +bytes of a +.Va ktr_type +record. +The type specific records are defined in the +.In sys/ktrace.h +include file. +.Sh SYSCTL TUNABLES +The following +.Xr sysctl 8 +tunables influence the behaviour of +.Fn ktrace : +.Bl -tag -width indent +.It Va kern.ktrace.geniosize +bounds the amount of data a traced I/O request will log +to the trace file. +.It Va kern.ktrace.request_pool +bounds the number of trace events being logged at a time. +.El +.Pp +Sysctl tunables that control process debuggability (as determined by +.Xr p_candebug 9 ) +also affect the operation of +.Fn ktrace . +.Sh RETURN VALUES +.Rv -std ktrace +.Sh ERRORS +The +.Fn ktrace +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named tracefile does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er ENOSYS +The kernel was not compiled with +.Nm +support. +.El +.Pp +A thread may be unable to log one or more tracing events due to a +temporary shortage of resources. +This condition is remembered by the kernel, and the next tracing request +that succeeds will have the flag +.Li KTR_DROP +set in its +.Va ktr_type +field. +.Sh SEE ALSO +.Xr kdump 1 , +.Xr ktrace 1 , +.Xr utrace 2 , +.Xr sysctl 8 , +.Xr p_candebug 9 +.Sh HISTORY +The +.Fn ktrace +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/link.2 b/lib/libc/sys/link.2 new file mode 100644 index 000000000000..e1fc3178fb59 --- /dev/null +++ b/lib/libc/sys/link.2 @@ -0,0 +1,288 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)link.2 8.3 (Berkeley) 1/12/94 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt LINK 2 +.Os +.Sh NAME +.Nm link , +.Nm linkat +.Nd make a hard file link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn link "const char *name1" "const char *name2" +.Ft int +.Fo linkat +.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" +.Fc +.Sh DESCRIPTION +The +.Fn link +system call +atomically creates the specified directory entry (hard link) +.Fa name2 +with the attributes of the underlying object pointed at by +.Fa name1 . +If the link is successful: the link count of the underlying object +is incremented; +.Fa name1 +and +.Fa name2 +share equal access and rights +to the +underlying object. +.Pp +If +.Fa name1 +is removed, the file +.Fa name2 +is not deleted and the link count of the +underlying object is +decremented. +.Pp +The object pointed at by the +.Fa name1 +argument +must exist for the hard link to +succeed and +both +.Fa name1 +and +.Fa name2 +must be in the same file system. +The +.Fa name1 +argument +may not be a directory. +.Pp +The +.Fn linkat +system call is equivalent to +.Fa link +except in the case where either +.Fa name1 +or +.Fa name2 +or both are relative paths. +In this case a relative path +.Fa name1 +is interpreted relative to +the directory associated with the file descriptor +.Fa fd1 +instead of the current working directory and similarly for +.Fa name2 +and the file descriptor +.Fa fd2 . +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_FOLLOW +If +.Fa name1 +names a symbolic link, a new link for the target of the symbolic link is +created. +.El +.Pp +If +.Fn linkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd1 +or +.Fa fd2 +parameter, the current working directory is used for the respective +.Fa name +argument. +If both +.Fa fd1 +and +.Fa fd2 +have value +.Dv AT_FDCWD , +the behavior is identical to a call to +.Fn link . +Unless +.Fa flag +contains the +.Dv AT_SYMLINK_FOLLOW +flag, if +.Fa name1 +names a symbolic link, a new link is created for the symbolic link +.Fa name1 +and not its target. +.Sh RETURN VALUES +.Rv -std link +.Sh ERRORS +The +.Fn link +system call +will fail and no link will be created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of either path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of either path prefix does not exist. +.It Bq Er EOPNOTSUPP +The file system containing the file named by +.Fa name1 +does not support links. +.It Bq Er EMLINK +The link count of the file named by +.Fa name1 +would exceed 32767. +.It Bq Er EACCES +A component of either path prefix denies search permission. +.It Bq Er EACCES +The requested link requires writing in a directory with a mode +that denies write permission. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating one of the pathnames. +.It Bq Er ENOENT +The file named by +.Fa name1 +does not exist. +.It Bq Er EEXIST +The link named by +.Fa name2 +does exist. +.It Bq Er EPERM +The file named by +.Fa name1 +is a directory. +.It Bq Er EPERM +The file named by +.Fa name1 +has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the file named by +.Fa name2 +has its immutable flag set. +.It Bq Er EXDEV +The link named by +.Fa name2 +and the file named by +.Fa name1 +are on different file systems. +.It Bq Er ENOSPC +The directory in which the entry for the new link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er EDQUOT +The directory in which the entry for the new link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EIO +An I/O error occurred while reading from or writing to +the file system to make the directory entry. +.It Bq Er EROFS +The requested link requires writing in a directory on a read-only file +system. +.It Bq Er EFAULT +One of the pathnames specified +is outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn link , +the +.Fn linkat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name1 +or +.Fa name2 +argument does not specify an absolute path and the +.Fa fd1 +or +.Fa fd2 +argument, respectively, is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa name1 +or +.Fa name2 +argument is not an absolute path and +.Fa fd1 +or +.Fa fd2 , +respectively, is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr readlink 2 , +.Xr symlink 2 , +.Xr unlink 2 +.Sh STANDARDS +The +.Fn link +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn linkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn link +function appeared in +.At v7 . +The +.Fn linkat +system call appeared in +.Fx 8.0 . +.Pp +The +.Fn link +system call traditionally allows the super-user to link directories which +corrupts the file system coherency. +This implementation no longer permits it. diff --git a/lib/libc/sys/lio_listio.2 b/lib/libc/sys/lio_listio.2 new file mode 100644 index 000000000000..ae228f7e2d8f --- /dev/null +++ b/lib/libc/sys/lio_listio.2 @@ -0,0 +1,218 @@ +.\" Copyright (c) 2003 Tim J. Robbins +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 15, 2016 +.Dt LIO_LISTIO 2 +.Os +.Sh NAME +.Nm lio_listio +.Nd "list directed I/O (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fo lio_listio +.Fa "int mode" +.Fa "struct aiocb * const list[]" +.Fa "int nent" +.Fa "struct sigevent *sig" +.Fc +.Sh DESCRIPTION +The +.Fn lio_listio +function initiates a list of I/O requests with a single function call. +The +.Fa list +argument is an array of pointers to +.Vt aiocb +structures describing each operation to perform, +with +.Fa nent +elements. +.Dv NULL +elements are ignored. +.Pp +The +.Va aio_lio_opcode +field of each +.Vt aiocb +specifies the operation to be performed. +The following operations are supported: +.Bl -tag -width ".Dv LIO_WRITE" +.It Dv LIO_READ +Read data as if by a call to +.Xr aio_read 2 . +.It Dv LIO_NOP +No operation. +.It Dv LIO_WRITE +Write data as if by a call to +.Xr aio_write 2 . +.El +.Pp +If the +.Fa mode +argument is +.Dv LIO_WAIT , +.Fn lio_listio +does not return until all the requested operations have been completed. +If +.Fa mode +is +.Dv LIO_NOWAIT , +.Fa sig +can be used to request asynchronous notification when all operations have +completed. +If +.Fa sig +is +.Dv NULL , +no notification is sent. +.Pp +For +.Dv SIGEV_KEVENT +notifications, +the posted kevent will contain: +.Bl -column ".Va filter" +.It Sy Member Ta Sy Value +.It Va ident Ta Fa list +.It Va filter Ta Dv EVFILT_LIO +.It Va udata Ta +value stored in +.Fa sig->sigev_value +.El +.Pp +For +.Dv SIGEV_SIGNO +and +.Dv SIGEV_THREAD_ID +notifications, +the information for the queued signal will include +.Dv SI_ASYNCIO +in the +.Va si_code +field and the value stored in +.Fa sig->sigev_value +in the +.Va si_value +field. +.Pp +For +.Dv SIGEV_THREAD +notifications, +the value stored in +.Fa sig->sigev_value +is passed to the +.Fa sig->sigev_notify_function +as described in +.Xr sigevent 3 . +.Pp +The order in which the requests are carried out is not specified; +in particular, there is no guarantee that they will be executed in +the order 0, 1, ..., +.Fa nent Ns \-1 . +.Sh RETURN VALUES +If +.Fa mode +is +.Dv LIO_WAIT , +the +.Fn lio_listio +function returns 0 if the operations completed successfully, +otherwise \-1. +.Pp +If +.Fa mode +is +.Dv LIO_NOWAIT , +the +.Fn lio_listio +function returns 0 if the operations are successfully queued, +otherwise \-1. +.Sh ERRORS +The +.Fn lio_listio +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +There are not enough resources to enqueue the requests. +.It Bq Er EAGAIN +The request would cause the system-wide limit +.Dv AIO_MAX +to be exceeded. +.It Bq Er EINVAL +The +.Fa mode +argument is neither +.Dv LIO_WAIT +nor +.Dv LIO_NOWAIT , +or +.Fa nent +is greater than +.Dv AIO_LISTIO_MAX . +.It Bq Er EINVAL +The asynchronous notification method in +.Fa sig->sigev_notify +is invalid or not supported. +.It Bq Er EINTR +A signal interrupted the system call before it could be completed. +.It Bq Er EIO +One or more requests failed. +.El +.Pp +In addition, the +.Fn lio_listio +function may fail for any of the reasons listed for +.Xr aio_read 2 +and +.Xr aio_write 2 . +.Pp +If +.Fn lio_listio +succeeds, or fails with an error code of +.Er EAGAIN , EINTR , +or +.Er EIO , +some of the requests may have been initiated. +The caller should check the error status of each +.Vt aiocb +structure individually by calling +.Xr aio_error 2 . +.Sh SEE ALSO +.Xr aio_error 2 , +.Xr aio_read 2 , +.Xr aio_write 2 , +.Xr read 2 , +.Xr write 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn lio_listio +function is expected to conform to +.St -p1003.1-2001 . diff --git a/lib/libc/sys/listen.2 b/lib/libc/sys/listen.2 new file mode 100644 index 000000000000..2bf5a3dd6a49 --- /dev/null +++ b/lib/libc/sys/listen.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)listen.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd August 18, 2016 +.Dt LISTEN 2 +.Os +.Sh NAME +.Nm listen +.Nd listen for connections on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn listen "int s" "int backlog" +.Sh DESCRIPTION +To accept connections, a socket +is first created with +.Xr socket 2 , +a willingness to accept incoming connections and +a queue limit for incoming connections are specified with +.Fn listen , +and then the connections are +accepted with +.Xr accept 2 . +The +.Fn listen +system call applies only to sockets of type +.Dv SOCK_STREAM +or +.Dv SOCK_SEQPACKET . +.Pp +The +.Fa backlog +argument defines the maximum length the queue of +pending connections may grow to. +The real maximum queue length will be 1.5 times more than the value +specified in the +.Fa backlog +argument. +A subsequent +.Fn listen +system call on the listening socket allows the caller to change the maximum +queue length using a new +.Fa backlog +argument. +If a connection +request arrives with the queue full the client may +receive an error with an indication of +.Er ECONNREFUSED , +or, in the case of TCP, the connection will be +silently dropped. +.Pp +Current queue lengths of listening sockets can be queried using +.Xr netstat 1 +command. +.Pp +Note that before +.Fx 4.5 +and the introduction of the syncache, +the +.Fa backlog +argument also determined the length of the incomplete +connection queue, which held TCP sockets in the process +of completing TCP's 3-way handshake. +These incomplete connections +are now held entirely in the syncache, which is unaffected by +queue lengths. +Inflated +.Fa backlog +values to help handle denial +of service attacks are no longer necessary. +.Pp +The +.Xr sysctl 3 +MIB variable +.Va kern.ipc.soacceptqueue +specifies a hard limit on +.Fa backlog ; +if a value greater than +.Va kern.ipc.soacceptqueue +or less than zero is specified, +.Fa backlog +is silently forced to +.Va kern.ipc.soacceptqueue . +.Sh INTERACTION WITH ACCEPT FILTERS +When accept filtering is used on a socket, a second queue will +be used to hold sockets that have connected, but have not yet +met their accept filtering criteria. +Once the criteria has been +met, these sockets will be moved over into the completed connection +queue to be +.Xr accept 2 Ns ed . +If this secondary queue is full and a +new connection comes in, the oldest socket which has not yet met +its accept filter criteria will be terminated. +.Pp +This secondary queue, like the primary listen queue, is sized +according to the +.Fa backlog +argument. +.Sh RETURN VALUES +.Rv -std listen +.Sh ERRORS +The +.Fn listen +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er EDESTADDRREQ +The socket is not bound to a local address, and the protocol does not +support listening on an unbound socket. +.It Bq Er EINVAL +The socket is already connected, or in the process of being connected. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EOPNOTSUPP +The socket is not of a type that supports the operation +.Fn listen . +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr accept 2 , +.Xr connect 2 , +.Xr socket 2 , +.Xr sysctl 3 , +.Xr sysctl 8 , +.Xr accept_filter 9 +.Sh HISTORY +The +.Fn listen +system call appeared in +.Bx 4.2 . +The ability to configure the maximum +.Fa backlog +at run-time, and to use a negative +.Fa backlog +to request the maximum allowable value, was introduced in +.Fx 2.2 . +The +.Va kern.ipc.somaxconn +.Xr sysctl 3 +has been replaced with +.Va kern.ipc.soacceptqueue +in +.Fx 10.0 +to prevent confusion about its actual functionality. +The original +.Xr sysctl 3 +.Va kern.ipc.somaxconn +is still available but hidden from a +.Xr sysctl 3 +-a output so that existing applications and scripts continue to work. diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 new file mode 100644 index 000000000000..017dc54227eb --- /dev/null +++ b/lib/libc/sys/lseek.2 @@ -0,0 +1,217 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)lseek.2 8.3 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd February 18, 2016 +.Dt LSEEK 2 +.Os +.Sh NAME +.Nm lseek +.Nd reposition read/write file offset +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft off_t +.Fn lseek "int fildes" "off_t offset" "int whence" +.Sh DESCRIPTION +The +.Fn lseek +system call repositions the offset of the file descriptor +.Fa fildes +to the +argument +.Fa offset +according to the directive +.Fa whence . +The argument +.Fa fildes +must be an open +file descriptor. +The +.Fn lseek +system call +repositions the file position pointer associated with the file +descriptor +.Fa fildes +as follows: +.Bl -item -offset indent +.It +If +.Fa whence +is +.Dv SEEK_SET , +the offset is set to +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_CUR , +the offset is set to its current location plus +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_END , +the offset is set to the size of the +file plus +.Fa offset +bytes. +.It +If +.Fa whence +is +.Dv SEEK_HOLE , +the offset is set to the start of the next hole greater than or equal +to the supplied +.Fa offset . +The definition of a hole is provided below. +.It +If +.Fa whence +is +.Dv SEEK_DATA , +the offset is set to the start of the next non-hole file region greater +than or equal to the supplied +.Fa offset . +.El +.Pp +The +.Fn lseek +system call allows the file offset to be set beyond the end +of the existing end-of-file of the file. +If data is later written +at this point, subsequent reads of the data in the gap return +bytes of zeros (until data is actually written into the gap). +.Pp +Some devices are incapable of seeking. +The value of the pointer +associated with such a device is undefined. +.Pp +A +.Qq hole +is defined as a contiguous range of bytes in a file, all having the value of +zero, but not all zeros in a file are guaranteed to be represented as holes +returned with +.Dv SEEK_HOLE . +File systems are allowed to expose ranges of zeros with +.Dv SEEK_HOLE , +but not required to. +Applications can use +.Dv SEEK_HOLE +to optimise their behavior for ranges of zeros, but must not depend on it to +find all such ranges in a file. +Each file is presented as having a zero-size virtual hole at the very +end of the file. +The existence of a hole at the end of every data region allows for easy +programming and also provides compatibility to the original implementation +in Solaris. +It also causes the current file size (i.e., end-of-file offset) to be returned +to indicate that there are no more holes past the supplied +.Fa offset . +Applications should use +.Fn fpathconf _PC_MIN_HOLE_SIZE +or +.Fn pathconf _PC_MIN_HOLE_SIZE +to determine if a file system supports +.Dv SEEK_HOLE . +See +.Xr pathconf 2 . +.Pp +For file systems that do not supply information about holes, the file will be +represented as one entire data region. +.Sh RETURN VALUES +Upon successful completion, +.Fn lseek +returns the resulting offset location as measured in bytes from the +beginning of the file. +Otherwise, +a value of -1 is returned and +.Va errno +is set to indicate +the error. +.Sh ERRORS +The +.Fn lseek +system call +will fail and the file position pointer will remain unchanged if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fildes +argument +is not an open file descriptor. +.It Bq Er EINVAL +The +.Fa whence +argument +is not a proper value +or the resulting file offset would +be negative for a non-character special file. +.It Bq Er ENXIO +For +.Dv SEEK_DATA , +there are no more data regions past the supplied offset. +Due to existence of the hole at the end of the file, for +.Dv SEEK_HOLE +this error is only returned when the +.Fa offset +already points to the end-of-file position. +.It Bq Er EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type +.Fa off_t . +.It Bq Er ESPIPE +The +.Fa fildes +argument +is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr dup 2 , +.Xr open 2 , +.Xr pathconf 2 +.Sh STANDARDS +The +.Fn lseek +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn lseek +function appeared in +.At v7 . +.Sh BUGS +This document's use of +.Fa whence +is incorrect English, but is maintained for historical reasons. diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2 new file mode 100644 index 000000000000..499bf67b8a91 --- /dev/null +++ b/lib/libc/sys/madvise.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)madvise.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd July 12, 2015 +.Dt MADVISE 2 +.Os +.Sh NAME +.Nm madvise , posix_madvise +.Nd give advice about use of memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn madvise "void *addr" "size_t len" "int behav" +.Ft int +.Fn posix_madvise "void *addr" "size_t len" "int behav" +.Sh DESCRIPTION +The +.Fn madvise +system call +allows a process that has knowledge of its memory behavior +to describe it to the system. +The +.Fn posix_madvise +interface is identical, except it returns an error number on error and does +not modify +.Va errno , +and is provided for standards conformance. +.Pp +The known behaviors are: +.Bl -tag -width MADV_SEQUENTIAL +.It Dv MADV_NORMAL +Tells the system to revert to the default paging +behavior. +.It Dv MADV_RANDOM +Is a hint that pages will be accessed randomly, and prefetching +is likely not advantageous. +.It Dv MADV_SEQUENTIAL +Causes the VM system to depress the priority of +pages immediately preceding a given page when it is faulted in. +.It Dv MADV_WILLNEED +Causes pages that are in a given virtual address range +to temporarily have higher priority, and if they are in +memory, decrease the likelihood of them being freed. +Additionally, +the pages that are already in memory will be immediately mapped into +the process, thereby eliminating unnecessary overhead of going through +the entire process of faulting the pages in. +This WILL NOT fault +pages in from backing store, but quickly map the pages already in memory +into the calling process. +.It Dv MADV_DONTNEED +Allows the VM system to decrease the in-memory priority +of pages in the specified address range. +Consequently, future references to this address range are more likely +to incur a page fault. +.It Dv MADV_FREE +Gives the VM system the freedom to free pages, +and tells the system that information in the specified page range +is no longer important. +This is an efficient way of allowing +.Xr malloc 3 +to free pages anywhere in the address space, while keeping the address space +valid. +The next time that the page is referenced, the page might be demand +zeroed, or might contain the data that was there before the +.Dv MADV_FREE +call. +References made to that address space range will not make the VM system +page the information back in from backing store until the page is +modified again. +.It Dv MADV_NOSYNC +Request that the system not flush the data associated with this map to +physical backing store unless it needs to. +Typically this prevents the +file system update daemon from gratuitously writing pages dirtied +by the VM system to physical disk. +Note that VM/file system coherency is +always maintained, this feature simply ensures that the mapped data is +only flush when it needs to be, usually by the system pager. +.Pp +This feature is typically used when you want to use a file-backed shared +memory area to communicate between processes (IPC) and do not particularly +need the data being stored in that area to be physically written to disk. +With this feature you get the equivalent performance with mmap that you +would expect to get with SysV shared memory calls, but in a more controllable +and less restrictive manner. +However, note that this feature is not portable +across UNIX platforms (though some may do the right thing by default). +For more information see the MAP_NOSYNC section of +.Xr mmap 2 +.It Dv MADV_AUTOSYNC +Undoes the effects of MADV_NOSYNC for any future pages dirtied within the +address range. +The effect on pages already dirtied is indeterminate - they +may or may not be reverted. +You can guarantee reversion by using the +.Xr msync 2 +or +.Xr fsync 2 +system calls. +.It Dv MADV_NOCORE +Region is not included in a core file. +.It Dv MADV_CORE +Include region in a core file. +.It Dv MADV_PROTECT +Informs the VM system this process should not be killed when the +swap space is exhausted. +The process must have superuser privileges. +This should be used judiciously in processes that must remain running +for the system to properly function. +.El +.Pp +Portable programs that call the +.Fn posix_madvise +interface should use the aliases +.Dv POSIX_MADV_NORMAL , POSIX_MADV_SEQUENTIAL , +.Dv POSIX_MADV_RANDOM , POSIX_MADV_WILLNEED , +and +.Dv POSIX_MADV_DONTNEED +rather than the flags described above. +.Sh RETURN VALUES +.Rv -std madvise +.Sh ERRORS +The +.Fn madvise +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa behav +argument is not valid. +.It Bq Er ENOMEM +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.It Bq Er EPERM +.Dv MADV_PROTECT +was specified and the process does not have superuser privileges. +.El +.Sh SEE ALSO +.Xr mincore 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr posix_fadvise 2 +.Sh STANDARDS +The +.Fn posix_madvise +interface conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn madvise +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/mincore.2 b/lib/libc/sys/mincore.2 new file mode 100644 index 000000000000..6c0fc670ef24 --- /dev/null +++ b/lib/libc/sys/mincore.2 @@ -0,0 +1,115 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mincore.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd January 17, 2003 +.Dt MINCORE 2 +.Os +.Sh NAME +.Nm mincore +.Nd determine residency of memory pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mincore "const void *addr" "size_t len" "char *vec" +.Sh DESCRIPTION +The +.Fn mincore +system call determines whether each of the pages in the region beginning at +.Fa addr +and continuing for +.Fa len +bytes is resident. +.\"The beginning address, +.\".Fa addr , +.\"is first rounded down to a multiple of the page size (see +.\".Xr getpagesize 3 ) . +.\"The end address, +.\".Fa addr No + Fa len , +.\"is rounded up to a multiple of the page size. +The status is returned in the +.Fa vec +array, one character per page. +Each character is either 0 if the page is not resident, or a combination of +the following flags (defined in +.In sys/mman.h ) : +.Bl -tag -width ".Dv MINCORE_REFERENCED_OTHER" +.It Dv MINCORE_INCORE +Page is in core (resident). +.It Dv MINCORE_REFERENCED +Page has been referenced by us. +.It Dv MINCORE_MODIFIED +Page has been modified by us. +.It Dv MINCORE_REFERENCED_OTHER +Page has been referenced. +.It Dv MINCORE_MODIFIED_OTHER +Page has been modified. +.It Dv MINCORE_SUPER +Page is part of a "super" page. (only i386 & amd64) +.El +.Pp +The information returned by +.Fn mincore +may be out of date by the time the system call returns. +The only way to ensure that a page is resident is to lock it into memory +with the +.Xr mlock 2 +system call. +.Sh RETURN VALUES +.Rv -std mincore +.Sh ERRORS +The +.Fn mincore +system call will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not fully mapped. +.It Bq Er EFAULT +The +.Fa vec +argument points to an illegal address. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr getpagesize 3 +.Sh HISTORY +The +.Fn mincore +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/minherit.2 b/lib/libc/sys/minherit.2 new file mode 100644 index 000000000000..dc85d09fd28e --- /dev/null +++ b/lib/libc/sys/minherit.2 @@ -0,0 +1,139 @@ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)minherit.2 8.1 (Berkeley) 6/9/93 +.\" +.Dd October 30, 2007 +.Dt MINHERIT 2 +.Os +.Sh NAME +.Nm minherit +.Nd control the inheritance of pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn minherit "void *addr" "size_t len" "int inherit" +.Sh DESCRIPTION +The +.Fn minherit +system call +changes the specified pages to have the inheritance characteristic +.Fa inherit . +Not all implementations will guarantee that the inheritance characteristic +can be set on a page basis; +the granularity of changes may be as large as an entire region. +.Fx +is capable of adjusting inheritance characteristics on a page basis. +Inheritance only effects children created by +.Fn fork . +It has no effect on +.Fn exec . +exec'd processes replace their address space entirely. +This system call also +has no effect on the parent's address space (other than to potentially +share the address space with its children). +.Pp +Inheritance is a rather esoteric feature largely superseded by the +.Dv MAP_SHARED +feature of +.Fn mmap . +However, it is possible to use +.Fn minherit +to share a block of memory between parent and child that has been mapped +.Dv MAP_PRIVATE . +That is, modifications made by parent or child are shared but +the original underlying file is left untouched. +.Bl -tag -width ".Dv INHERIT_SHARE" +.It Dv INHERIT_SHARE +This option causes the address space in question to be shared between +parent and child. +It has no effect on how the original underlying backing +store was mapped. +.It Dv INHERIT_NONE +This option prevents the address space in question from being inherited +at all. +The address space will be unmapped in the child. +.It Dv INHERIT_COPY +This option causes the child to inherit the address space as copy-on-write. +This option also has an unfortunate side effect of causing the parent +address space to become copy-on-write when the parent forks. +If the original mapping was +.Dv MAP_SHARED , +it will no longer be shared in the parent +after the parent forks and there is no way to get the previous +shared-backing-store mapping without unmapping and remapping the address +space in the parent. +.El +.Sh RETURN VALUES +.Rv -std minherit +.Sh ERRORS +The +.Fn minherit +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.It Bq Er EACCES +The flags specified by the +.Fa inherit +argument were not valid for the pages specified +by the +.Fa addr +and +.Fa len +arguments. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr madvise 2 , +.Xr mincore 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 , +.Xr rfork 2 +.Sh HISTORY +The +.Fn minherit +system call first appeared in +.Ox +and then in +.Fx 2.2 . +.Sh BUGS +Once you set inheritance to +.Dv MAP_PRIVATE +or +.Dv MAP_SHARED , +there is no way to recover the original copy-on-write semantics +short of unmapping and remapping the area. diff --git a/lib/libc/sys/mkdir.2 b/lib/libc/sys/mkdir.2 new file mode 100644 index 000000000000..1edb408f85c9 --- /dev/null +++ b/lib/libc/sys/mkdir.2 @@ -0,0 +1,176 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mkdir.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd June 26, 2008 +.Dt MKDIR 2 +.Os +.Sh NAME +.Nm mkdir , +.Nm mkdirat +.Nd make a directory file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn mkdir "const char *path" "mode_t mode" +.Ft int +.Fn mkdirat "int fd" "const char *path" "mode_t mode" +.Sh DESCRIPTION +The directory +.Fa path +is created with the access permissions specified by +.Fa mode +and restricted by the +.Xr umask 2 +of the calling process. +.Pp +The directory's owner ID is set to the process's effective user ID. +The directory's group ID is set to that of the parent directory in +which it is created. +.Pp +The +.Fn mkdirat +system call is equivalent to +.Fn mkdir +except in the case where +.Fa path +specifies a relative path. +In this case the newly created directory is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mkdirat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mkdir . +.Sh RETURN VALUES +.Rv -std mkdir +.Sh ERRORS +The +.Fn mkdir +system call +will fail and no directory will be created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path prefix does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix, +or write permission is denied +on the parent directory of the directory to be created. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The parent directory of the directory to be created has its immutable flag set, +see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The named directory would reside on a read-only file system. +.It Bq Er EMLINK +The new directory cannot be created because the parent directory contains +too many subdirectories. +.It Bq Er EEXIST +The named file exists. +.It Bq Er ENOSPC +The new directory cannot be created because there is no space left +on the file system that will contain the directory. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +directory is being created. +.It Bq Er EDQUOT +The new directory cannot be created because the user's +quota of disk blocks on the file system that will +contain the directory has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the directory is being created has been exhausted. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn mkdir , +the +.Fn mkdirat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr chmod 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mkdir +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn mkdirat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mkdirat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/mkfifo.2 b/lib/libc/sys/mkfifo.2 new file mode 100644 index 000000000000..9b4ac5d29fd9 --- /dev/null +++ b/lib/libc/sys/mkfifo.2 @@ -0,0 +1,185 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mkfifo.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt MKFIFO 2 +.Os +.Sh NAME +.Nm mkfifo , +.Nm mkfifoat +.Nd make a fifo file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.Ft int +.Fn mkfifo "const char *path" "mode_t mode" +.Ft int +.Fn mkfifoat "int fd" "const char *path" "mode_t mode" +.Sh DESCRIPTION +The +.Fn mkfifo +system call +creates a new fifo file with name +.Fa path . +The access permissions are +specified by +.Fa mode +and restricted by the +.Xr umask 2 +of the calling process. +.Pp +The fifo's owner ID is set to the process's effective user ID. +The fifo's group ID is set to that of the parent directory in +which it is created. +.Pp +The +.Fn mkfifoat +system call is equivalent to +.Fn mkfifo +except in the case where +.Fa path +specifies a relative path. +In this case the newly created FIFO is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mkfifoat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mkfifo . +.Sh RETURN VALUES +.Rv -std mkfifo +.Sh ERRORS +The +.Fn mkfifo +system call +will fail and no fifo will be created if: +.Bl -tag -width Er +.It Bq Er ENOTSUP +The kernel has not been configured to support fifo's. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path prefix does not exist. +.It Bq Er EACCES +A component of the path prefix denies search permission, or write permission +is denied on the parent directory of the fifo to be created. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EROFS +The named file would reside on a read-only file system. +.It Bq Er EEXIST +The named file exists. +.It Bq Er EPERM +The parent directory of the named file has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er ENOSPC +The directory in which the entry for the new fifo is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +fifo is being created. +.It Bq Er EDQUOT +The directory in which the entry for the new fifo +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the fifo is being created has been exhausted. +.It Bq Er EIO +An +.Tn I/O +error occurred while making the directory entry or allocating the inode. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn mkfifo , +the +.Fn mkfifoat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr chmod 2 , +.Xr mknod 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mkfifo +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn mkfifoat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mkfifoat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/mknod.2 b/lib/libc/sys/mknod.2 new file mode 100644 index 000000000000..a40606806a55 --- /dev/null +++ b/lib/libc/sys/mknod.2 @@ -0,0 +1,182 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mknod.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd January 16, 2011 +.Dt MKNOD 2 +.Os +.Sh NAME +.Nm mknod , +.Nm mknodat +.Nd make a special file node +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn mknod "const char *path" "mode_t mode" "dev_t dev" +.Ft int +.Fn mknodat "int fd" "const char *path" "mode_t mode" "dev_t dev" +.Sh DESCRIPTION +The file system node +.Fa path +is created with the file type and access permissions specified in +.Fa mode . +The access permissions are modified by the process's umask value. +.Pp +If +.Fa mode +indicates a block or character special file, +.Fa dev +is a configuration dependent specification denoting a particular device +on the system. +Otherwise, +.Fa dev +is ignored. +.Pp +The +.Fn mknod +system call +requires super-user privileges. +.Pp +The +.Fn mknodat +system call is equivalent to +.Fn mknod +except in the case where +.Fa path +specifies a relative path. +In this case the newly created device node is created relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn mknodat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn mknod . +.Sh RETURN VALUES +.Rv -std mknod +.Sh ERRORS +The +.Fn mknod +system call +will fail and the file will be not created if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the path prefix does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The process's effective user ID is not super-user. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er ENOSPC +The directory in which the entry for the new node is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +node is being created. +.It Bq Er EDQUOT +The directory in which the entry for the new node +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the node is being created has been exhausted. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EEXIST +The named file exists. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +Creating anything else than a block or character special +file (or a +.Em whiteout ) +is not supported. +.El +.Pp +In addition to the errors returned by the +.Fn mknod , +the +.Fn mknodat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr mkfifo 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh STANDARDS +The +.Fn mknodat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn mknod +function appeared in +.At v6 . +The +.Fn mknodat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/mlock.2 b/lib/libc/sys/mlock.2 new file mode 100644 index 000000000000..4f264206fd26 --- /dev/null +++ b/lib/libc/sys/mlock.2 @@ -0,0 +1,183 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd May 17, 2014 +.Dt MLOCK 2 +.Os +.Sh NAME +.Nm mlock , +.Nm munlock +.Nd lock (unlock) physical pages in memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mlock "const void *addr" "size_t len" +.Ft int +.Fn munlock "const void *addr" "size_t len" +.Sh DESCRIPTION +The +.Fn mlock +system call +locks into memory the physical pages associated with the virtual address +range starting at +.Fa addr +for +.Fa len +bytes. +The +.Fn munlock +system call unlocks pages previously locked by one or more +.Fn mlock +calls. +For both, the +.Fa addr +argument should be aligned to a multiple of the page size. +If the +.Fa len +argument is not a multiple of the page size, it will be rounded up +to be so. +The entire range must be allocated. +.Pp +After an +.Fn mlock +system call, the indicated pages will cause neither a non-resident page +nor address-translation fault until they are unlocked. +They may still cause protection-violation faults or TLB-miss faults on +architectures with software-managed TLBs. +The physical pages remain in memory until all locked mappings for the pages +are removed. +Multiple processes may have the same physical pages locked via their own +virtual address mappings. +A single process may likewise have pages multiply-locked via different virtual +mappings of the same pages or via nested +.Fn mlock +calls on the same address range. +Unlocking is performed explicitly by +.Fn munlock +or implicitly by a call to +.Fn munmap +which deallocates the unmapped address range. +Locked mappings are not inherited by the child process after a +.Xr fork 2 . +.Pp +Since physical memory is a potentially scarce resource, processes are +limited in how much they can lock down. +The amount of memory that a single process can +.Fn mlock +is limited by both the per-process +.Dv RLIMIT_MEMLOCK +resource limit and the +system-wide +.Dq wired pages +limit +.Va vm.max_wired . +.Va vm.max_wired +applies to the system as a whole, so the amount available to a single +process at any given time is the difference between +.Va vm.max_wired +and +.Va vm.stats.vm.v_wire_count . +.Pp +If +.Va security.bsd.unprivileged_mlock +is set to 0 these calls are only available to the super-user. +.Sh RETURN VALUES +.Rv -std +.Pp +If the call succeeds, all pages in the range become locked (unlocked); +otherwise the locked status of all pages in the range remains unchanged. +.Sh ERRORS +The +.Fn mlock +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Va security.bsd.unprivileged_mlock +is set to 0 and the caller is not the super-user. +.It Bq Er EINVAL +The address given is not page aligned or the length is negative. +.It Bq Er EAGAIN +Locking the indicated range would exceed the system limit for locked memory. +.It Bq Er ENOMEM +Some portion of the indicated address range is not allocated. +There was an error faulting/mapping a page. +Locking the indicated range would exceed the per-process limit for locked +memory. +.El +The +.Fn munlock +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +.Va security.bsd.unprivileged_mlock +is set to 0 and the caller is not the super-user. +.It Bq Er EINVAL +The address given is not page aligned or the length is negative. +.It Bq Er ENOMEM +Some or all of the address range specified by the addr and len +arguments does not correspond to valid mapped pages in the address space +of the process. +.It Bq Er ENOMEM +Locking the pages mapped by the specified range would exceed a limit on +the amount of memory that the process may lock. +.El +.Sh "SEE ALSO" +.Xr fork 2 , +.Xr mincore 2 , +.Xr minherit 2 , +.Xr mlockall 2 , +.Xr mmap 2 , +.Xr munlockall 2 , +.Xr munmap 2 , +.Xr setrlimit 2 , +.Xr getpagesize 3 +.Sh HISTORY +The +.Fn mlock +and +.Fn munlock +system calls first appeared in +.Bx 4.4 . +.Sh BUGS +Allocating too much wired memory can lead to a memory-allocation deadlock +which requires a reboot to recover from. +.Pp +The per-process resource limit is a limit on the amount of virtual +memory locked, while the system-wide limit is for the number of locked +physical pages. +Hence a process with two distinct locked mappings of the same physical page +counts as 2 pages against the per-process limit and as only a single page +in the system limit. +.Pp +The per-process resource limit is not currently supported. diff --git a/lib/libc/sys/mlockall.2 b/lib/libc/sys/mlockall.2 new file mode 100644 index 000000000000..23c644a8493f --- /dev/null +++ b/lib/libc/sys/mlockall.2 @@ -0,0 +1,146 @@ +.\" $NetBSD: mlockall.2,v 1.11 2003/04/16 13:34:54 wiz Exp $ +.\" +.\" Copyright (c) 1999 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 25, 2012 +.Dt MLOCKALL 2 +.Os +.Sh NAME +.Nm mlockall , +.Nm munlockall +.Nd lock (unlock) the address space of a process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mlockall "int flags" +.Ft int +.Fn munlockall "void" +.Sh DESCRIPTION +The +.Fn mlockall +system call locks into memory the physical pages associated with the +address space of a process until the address space is unlocked, the +process exits, or execs another program image. +.Pp +The following flags affect the behavior of +.Fn mlockall : +.Bl -tag -width ".Dv MCL_CURRENT" +.It Dv MCL_CURRENT +Lock all pages currently mapped into the process's address space. +.It Dv MCL_FUTURE +Lock all pages mapped into the process's address space in the future, +at the time the mapping is established. +Note that this may cause future mappings to fail if those mappings +cause resource limits to be exceeded. +.El +.Pp +Since physical memory is a potentially scarce resource, processes are +limited in how much they can lock down. +A single process can lock the minimum of a system-wide +.Dq wired pages +limit +.Va vm.max_wired +and the per-process +.Dv RLIMIT_MEMLOCK +resource limit. +.Pp +If +.Va security.bsd.unprivileged_mlock +is set to 0 these calls are only available to the super-user. +If +.Va vm.old_mlock +is set to 1 the per-process +.Dv RLIMIT_MEMLOCK +resource limit will not be applied for +.Fn mlockall +calls. +.Pp +The +.Fn munlockall +call unlocks any locked memory regions in the process address space. +Any regions mapped after an +.Fn munlockall +call will not be locked. +.Sh RETURN VALUES +A return value of 0 indicates that the call +succeeded and all pages in the range have either been locked or unlocked. +A return value of \-1 indicates an error occurred and the locked +status of all pages in the range remains unchanged. +In this case, the global location +.Va errno +is set to indicate the error. +.Sh ERRORS +.Fn mlockall +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument is zero, or includes unimplemented flags. +.It Bq Er ENOMEM +Locking the indicated range would exceed either the system or per-process +limit for locked memory. +.It Bq Er EAGAIN +Some or all of the memory mapped into the process's address space +could not be locked when the call was made. +.It Bq Er EPERM +The calling process does not have the appropriate privilege to perform +the requested operation. +.El +.Sh SEE ALSO +.Xr mincore 2 , +.Xr mlock 2 , +.Xr mmap 2 , +.Xr munmap 2 , +.Xr setrlimit 2 +.Sh STANDARDS +The +.Fn mlockall +and +.Fn munlockall +functions are believed to conform to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn mlockall +and +.Fn munlockall +functions first appeared in +.Fx 5.1 . +.Sh BUGS +The per-process resource limit is a limit on the amount of virtual +memory locked, while the system-wide limit is for the number of locked +physical pages. +Hence a process with two distinct locked mappings of the same physical page +counts as 2 pages against the per-process limit and as only a single page +in the system limit. diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 new file mode 100644 index 000000000000..82418bdbaeda --- /dev/null +++ b/lib/libc/sys/mmap.2 @@ -0,0 +1,452 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 +.\" $FreeBSD$ +.\" +.Dd November 25, 2016 +.Dt MMAP 2 +.Os +.Sh NAME +.Nm mmap +.Nd allocate memory, or map files or devices into memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft void * +.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" +.Sh DESCRIPTION +The +.Fn mmap +system call causes the pages starting at +.Fa addr +and continuing for at most +.Fa len +bytes to be mapped from the object described by +.Fa fd , +starting at byte offset +.Fa offset . +If +.Fa len +is not a multiple of the pagesize, the mapped region may extend past the +specified range. +Any such extension beyond the end of the mapped object will be zero-filled. +.Pp +If +.Fa addr +is non-zero, it is used as a hint to the system. +(As a convenience to the system, the actual address of the region may differ +from the address supplied.) +If +.Fa addr +is zero, an address will be selected by the system. +The actual starting address of the region is returned. +A successful +.Fa mmap +deletes any previous mapping in the allocated address range. +.Pp +The protections (region accessibility) are specified in the +.Fa prot +argument by +.Em or Ns 'ing +the following values: +.Pp +.Bl -tag -width PROT_WRITE -compact +.It Dv PROT_NONE +Pages may not be accessed. +.It Dv PROT_READ +Pages may be read. +.It Dv PROT_WRITE +Pages may be written. +.It Dv PROT_EXEC +Pages may be executed. +.El +.Pp +The +.Fa flags +argument specifies the type of the mapped object, mapping options and +whether modifications made to the mapped copy of the page are private +to the process or are to be shared with other references. +Sharing, mapping type and options are specified in the +.Fa flags +argument by +.Em or Ns 'ing +the following values: +.Bl -tag -width MAP_PREFAULT_READ +.It Dv MAP_32BIT +Request a region in the first 2GB of the current process's address space. +If a suitable region cannot be found, +.Fn mmap +will fail. +This flag is only available on 64-bit platforms. +.It Dv MAP_ALIGNED Ns Pq Fa n +Align the region on a requested boundary. +If a suitable region cannot be found, +.Fn mmap +will fail. +The +.Fa n +argument specifies the binary logarithm of the desired alignment. +.It Dv MAP_ALIGNED_SUPER +Align the region to maximize the potential use of large +.Pq Dq super +pages. +If a suitable region cannot be found, +.Fn mmap +will fail. +The system will choose a suitable page size based on the size of +mapping. +The page size used as well as the alignment of the region may both be +affected by properties of the file being mapped. +In particular, +the physical address of existing pages of a file may require a specific +alignment. +The region is not guaranteed to be aligned on any specific boundary. +.It Dv MAP_ANON +Map anonymous memory not associated with any specific file. +The file descriptor used for creating +.Dv MAP_ANON +must be \-1. +The +.Fa offset +argument must be 0. +.\".It Dv MAP_FILE +.\"Mapped from a regular file or character-special device memory. +.It Dv MAP_ANONYMOUS +This flag is identical to +.Dv MAP_ANON +and is provided for compatibility. +.It Dv MAP_EXCL +This flag can only be used in combination with +.Dv MAP_FIXED . +Please see the definition of +.Dv MAP_FIXED +for the description of its effect. +.It Dv MAP_FIXED +Do not permit the system to select a different address than the one +specified. +If the specified address cannot be used, +.Fn mmap +will fail. +If +.Dv MAP_FIXED +is specified, +.Fa addr +must be a multiple of the pagesize. +If +.Dv MAP_EXCL +is not specified, a successful +.Dv MAP_FIXED +request replaces any previous mappings for the process' +pages in the range from +.Fa addr +to +.Fa addr ++ +.Fa len . +In contrast, if +.Dv MAP_EXCL +is specified, the request will fail if a mapping +already exists within the range. +.It Dv MAP_HASSEMAPHORE +Notify the kernel that the region may contain semaphores and that special +handling may be necessary. +.It Dv MAP_NOCORE +Region is not included in a core file. +.It Dv MAP_NOSYNC +Causes data dirtied via this VM map to be flushed to physical media +only when necessary (usually by the pager) rather than gratuitously. +Typically this prevents the update daemons from flushing pages dirtied +through such maps and thus allows efficient sharing of memory across +unassociated processes using a file-backed shared memory map. +Without +this option any VM pages you dirty may be flushed to disk every so often +(every 30-60 seconds usually) which can create performance problems if you +do not need that to occur (such as when you are using shared file-backed +mmap regions for IPC purposes). +Dirty data will be flushed automatically when all mappings of an object are +removed and all descriptors referencing the object are closed. +Note that VM/file system coherency is +maintained whether you use +.Dv MAP_NOSYNC +or not. +This option is not portable +across +.Ux +platforms (yet), though some may implement the same behavior +by default. +.Pp +.Em WARNING ! +Extending a file with +.Xr ftruncate 2 , +thus creating a big hole, and then filling the hole by modifying a shared +.Fn mmap +can lead to severe file fragmentation. +In order to avoid such fragmentation you should always pre-allocate the +file's backing store by +.Fn write Ns ing +zero's into the newly extended area prior to modifying the area via your +.Fn mmap . +The fragmentation problem is especially sensitive to +.Dv MAP_NOSYNC +pages, because pages may be flushed to disk in a totally random order. +.Pp +The same applies when using +.Dv MAP_NOSYNC +to implement a file-based shared memory store. +It is recommended that you create the backing store by +.Fn write Ns ing +zero's to the backing file rather than +.Fn ftruncate Ns ing +it. +You can test file fragmentation by observing the KB/t (kilobytes per +transfer) results from an +.Dq Li iostat 1 +while reading a large file sequentially, e.g.,\& using +.Dq Li dd if=filename of=/dev/null bs=32k . +.Pp +The +.Xr fsync 2 +system call will flush all dirty data and metadata associated with a file, +including dirty NOSYNC VM data, to physical media. +The +.Xr sync 8 +command and +.Xr sync 2 +system call generally do not flush dirty NOSYNC VM data. +The +.Xr msync 2 +system call is usually not needed since +.Bx +implements a coherent file system buffer cache. +However, it may be +used to associate dirty VM pages with file system buffers and thus cause +them to be flushed to physical media sooner rather than later. +.It Dv MAP_PREFAULT_READ +Immediately update the calling process's lowest-level virtual address +translation structures, such as its page table, so that every memory +resident page within the region is mapped for read access. +Ordinarily these structures are updated lazily. +The effect of this option is to eliminate any soft faults that would +otherwise occur on the initial read accesses to the region. +Although this option does not preclude +.Fa prot +from including +.Dv PROT_WRITE , +it does not eliminate soft faults on the initial write accesses to the +region. +.It Dv MAP_PRIVATE +Modifications are private. +.It Dv MAP_SHARED +Modifications are shared. +.It Dv MAP_STACK +.Dv MAP_STACK +implies +.Dv MAP_ANON , +and +.Fa offset +of 0. +The +.Fa fd +argument +must be -1 and +.Fa prot +must include at least +.Dv PROT_READ +and +.Dv PROT_WRITE . +This option creates +a memory region that grows to at most +.Fa len +bytes in size, starting from the stack top and growing down. +The +stack top is the starting address returned by the call, plus +.Fa len +bytes. +The bottom of the stack at maximum growth is the starting +address returned by the call. +.El +.Pp +The +.Xr close 2 +system call does not unmap pages, see +.Xr munmap 2 +for further information. +.Sh NOTES +Although this implementation does not impose any alignment restrictions on +the +.Fa offset +argument, a portable program must only use page-aligned values. +.Pp +Large page mappings require that the pages backing an object be +aligned in matching blocks in both the virtual address space and RAM. +The system will automatically attempt to use large page mappings when +mapping an object that is already backed by large pages in RAM by +aligning the mapping request in the virtual address space to match the +alignment of the large physical pages. +The system may also use large page mappings when mapping portions of an +object that are not yet backed by pages in RAM. +The +.Dv MAP_ALIGNED_SUPER +flag is an optimization that will align the mapping request to the +size of a large page similar to +.Dv MAP_ALIGNED , +except that the system will override this alignment if an object already +uses large pages so that the mapping will be consistent with the existing +large pages. +This flag is mostly useful for maximizing the use of large pages on the +first mapping of objects that do not yet have pages present in RAM. +.Sh RETURN VALUES +Upon successful completion, +.Fn mmap +returns a pointer to the mapped region. +Otherwise, a value of +.Dv MAP_FAILED +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mmap +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The flag +.Dv PROT_READ +was specified as part of the +.Fa prot +argument and +.Fa fd +was not open for reading. +The flags +.Dv MAP_SHARED +and +.Dv PROT_WRITE +were specified as part of the +.Fa flags +and +.Fa prot +argument and +.Fa fd +was not open for writing. +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EINVAL +An invalid value was passed in the +.Fa prot +argument. +.It Bq Er EINVAL +An undefined option was set in the +.Fa flags +argument. +.It Bq Er EINVAL +Both +.Dv MAP_PRIVATE +and +.Dv MAP_SHARED +were specified. +.It Bq Er EINVAL +None of +.Dv MAP_ANON , +.Dv MAP_PRIVATE , +.Dv MAP_SHARED , +or +.Dv MAP_STACK +was specified. +At least one of these flags must be included. +.It Bq Er EINVAL +.Dv MAP_FIXED +was specified and the +.Fa addr +argument was not page aligned, or part of the desired address space +resides out of the valid address space for a user process. +.It Bq Er EINVAL +Both +.Dv MAP_FIXED +and +.Dv MAP_32BIT +were specified and part of the desired address space resides outside +of the first 2GB of user address space. +.It Bq Er EINVAL +The +.Fa len +argument +was equal to zero. +.It Bq Er EINVAL +.Dv MAP_ALIGNED +was specified and the desired alignment was either larger than the +virtual address size of the machine or smaller than a page. +.It Bq Er EINVAL +.Dv MAP_ANON +was specified and the +.Fa fd +argument was not -1. +.It Bq Er EINVAL +.Dv MAP_ANON +was specified and the +.Fa offset +argument was not 0. +.It Bq Er EINVAL +Both +.Dv MAP_FIXED +and +.Dv MAP_EXCL +were specified, but the requested region is already used by a mapping. +.It Bq Er EINVAL +.Dv MAP_EXCL +was specified, but +.Dv MAP_FIXED +was not. +.It Bq Er ENODEV +.Dv MAP_ANON +has not been specified and +.Fa fd +did not reference a regular or character special file. +.It Bq Er ENOMEM +.Dv MAP_FIXED +was specified and the +.Fa addr +argument was not available. +.Dv MAP_ANON +was specified and insufficient memory was available. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr minherit 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munlock 2 , +.Xr munmap 2 , +.Xr getpagesize 3 , +.Xr getpagesizes 3 diff --git a/lib/libc/sys/modfind.2 b/lib/libc/sys/modfind.2 new file mode 100644 index 000000000000..38d09c4ee9f3 --- /dev/null +++ b/lib/libc/sys/modfind.2 @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 28, 2000 +.Dt MODFIND 2 +.Os +.Sh NAME +.Nm modfind +.Nd returns the modid of a kernel module +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Ft int +.Fn modfind "const char *modname" +.Sh DESCRIPTION +The +.Fn modfind +system call +returns the modid of the kernel module referenced by +.Fa modname . +.Sh RETURN VALUES +The +.Fn modfind +system call +returns the modid of the kernel module referenced by +.Fa modname . +Upon error, +.Fn modfind +returns -1 and sets +.Va errno +to indicate the error. +.Sh ERRORS +.Va errno +is set to the following if +.Fn modfind +fails: +.Bl -tag -width Er +.It Bq Er EFAULT +The data required for this operation could not be read from the kernel space. +.It Bq Er ENOENT +The file specified is not loaded in the kernel. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/modnext.2 b/lib/libc/sys/modnext.2 new file mode 100644 index 000000000000..c0c0a0d3a223 --- /dev/null +++ b/lib/libc/sys/modnext.2 @@ -0,0 +1,97 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 28, 2000 +.Dt MODNEXT 2 +.Os +.Sh NAME +.Nm modnext +.Nd return the modid of the next kernel module +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Ft int +.Fn modnext "int modid" +.Ft int +.Fn modfnext "int modid" +.Sh DESCRIPTION +The +.Fn modnext +system call +returns the modid of the next kernel module (that is, the one after +.Va modid ) +or 0 if +.Va modid +is the last module in the list. +.Pp +If the +.Va modid +value is 0, then +.Fn modnext +will return the modid of the first module. +The +.Fn modfnext +system call +must always be given a valid modid. +.Sh RETURN VALUES +The +.Fn modnext +system call +returns the modid of the next module (see +.Sx DESCRIPTION ) +or 0. +If an error +occurs, +.Va errno +is set to indicate the error. +.Sh ERRORS +The only error set by +.Fn modnext +is +.Er ENOENT , +which is set when +.Va modid +refers to a kernel module that does not exist (is not loaded). +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modstat 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/modstat.2 b/lib/libc/sys/modstat.2 new file mode 100644 index 000000000000..5f106b4b1af3 --- /dev/null +++ b/lib/libc/sys/modstat.2 @@ -0,0 +1,127 @@ +.\" +.\" Copyright (c) 1999 Chris Costello +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 15, 2008 +.Dt MODSTAT 2 +.Os +.Sh NAME +.Nm modstat +.Nd get status of kernel module +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Ft int +.Fn modstat "int modid" "struct module_stat *stat" +.Sh DESCRIPTION +The +.Fn modstat +system call writes the info for the kernel module referred to by +.Fa modid +into +.Fa stat . +.Bd -literal +struct module_stat { + int version; /* set to sizeof(module_stat) */ + char name[MAXMODNAME]; + int refs; + int id; + modspecific_t data; +}; +typedef union modspecific { + int intval; + u_int uintval; + long longval; + u_long ulongval; +} modspecific_t; +.Ed +.Bl -tag -width XXXaddress +.It version +This field is set to the size of the structure mentioned above by the code +calling +.Fn modstat , +and not +.Fn modstat +itself. +.It name +The name of the module referred to by +.Fa modid . +.It refs +The number of modules referenced by +.Fa modid . +.It id +The id of the module specified in +.Fa modid . +.It data +Module specific data. +.El +.Sh RETURN VALUES +.Rv -std modstat +.Sh ERRORS +The information for the module referred to by +.Fa modid +is filled into the structure pointed to by +.Fa stat +unless: +.Bl -tag -width Er +.It Bq Er ENOENT +The module was not found (probably not loaded). +.It Bq Er EINVAL +The version specified in the +.Fa version +field of stat is not the proper version. +You would need to rebuild world, the +kernel, or your application, if this error occurs, given that you did properly +fill in the +.Fa version +field. +.It Bq Er EFAULT +There was a problem copying one, some, or all of the fields into +.Fa stat +in the +.Xr copyout 9 +function. +.El +.Sh SEE ALSO +.Xr kldfind 2 , +.Xr kldfirstmod 2 , +.Xr kldload 2 , +.Xr kldnext 2 , +.Xr kldstat 2 , +.Xr kldsym 2 , +.Xr kldunload 2 , +.Xr modfind 2 , +.Xr modfnext 2 , +.Xr modnext 2 , +.Xr kld 4 , +.Xr kldstat 8 +.Sh HISTORY +The +.Nm kld +interface first appeared in +.Fx 3.0 . diff --git a/lib/libc/sys/mount.2 b/lib/libc/sys/mount.2 new file mode 100644 index 000000000000..881d830967aa --- /dev/null +++ b/lib/libc/sys/mount.2 @@ -0,0 +1,378 @@ +.\" Copyright (c) 1980, 1989, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mount.2 8.3 (Berkeley) 5/24/95 +.\" $FreeBSD$ +.\" +.Dd April 13, 2015 +.Dt MOUNT 2 +.Os +.Sh NAME +.Nm mount , +.Nm nmount , +.Nm unmount +.Nd mount or dismount a file system +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn mount "const char *type" "const char *dir" "int flags" "void *data" +.Ft int +.Fn unmount "const char *dir" "int flags" +.In sys/uio.h +.Ft int +.Fn nmount "struct iovec *iov" "u_int niov" "int flags" +.Sh DESCRIPTION +The +.Fn mount +system call grafts +a file system object onto the system file tree +at the point +.Fa dir . +The argument +.Fa data +describes the file system object to be mounted. +The argument +.Fa type +tells the kernel how to interpret +.Fa data +(See +.Fa type +below). +The contents of the file system +become available through the new mount point +.Fa dir . +Any files in +.Fa dir +at the time +of a successful mount are swept under the carpet so to speak, and +are unavailable until the file system is unmounted. +.Pp +The +.Fn nmount +system call behaves similarly to +.Fn mount , +except that the mount options (file system type name, device to mount, +mount-point name, etc.) are passed as an array of name-value pairs +in the array +.Fa iov , +containing +.Fa niov +elements. +The following options are required by all file systems: +.Bl -column fstype -offset indent +.It +.Li fstype Ta file system type name (e.g., Dq Li procfs ) +.It +.Li fspath Ta mount point pathname (e.g., Dq Li /proc ) +.El +.Pp +Depending on the file system type, other options may be +recognized or required; +for example, most disk-based file systems require a +.Dq Li from +option containing the pathname of a special device +in addition to the options listed above. +.Pp +By default only the super-user may call the +.Fn mount +system call. +This restriction can be removed by setting the +.Va vfs.usermount +.Xr sysctl 8 +variable +to a non-zero value; see the BUGS section for more information. +.Pp +The following +.Fa flags +may be specified to +suppress default semantics which affect file system access. +.Bl -tag -width MNT_SYNCHRONOUS +.It Dv MNT_RDONLY +The file system should be treated as read-only; +even the super-user may not write on it. +Specifying MNT_UPDATE without this option will upgrade +a read-only file system to read/write. +.It Dv MNT_NOEXEC +Do not allow files to be executed from the file system. +.It Dv MNT_NOSUID +Do not honor setuid or setgid bits on files when executing them. +This flag is set automatically when the caller is not the super-user. +.It Dv MNT_NOATIME +Disable update of file access times. +.It Dv MNT_SNAPSHOT +Create a snapshot of the file system. +This is currently only supported on UFS2 file systems, see +.Xr mksnap_ffs 8 +for more information. +.It Dv MNT_SUIDDIR +Directories with the SUID bit set chown new files to their own owner. +This flag requires the SUIDDIR option to have been compiled into the kernel +to have any effect. +See the +.Xr mount 8 +and +.Xr chmod 2 +pages for more information. +.It Dv MNT_SYNCHRONOUS +All I/O to the file system should be done synchronously. +.It Dv MNT_ASYNC +All I/O to the file system should be done asynchronously. +.It Dv MNT_FORCE +Force a read-write mount even if the file system appears to be unclean. +Dangerous. +Together with +.Dv MNT_UPDATE +and +.Dv MNT_RDONLY , +specify that the file system is to be forcibly downgraded to a read-only +mount even if some files are open for writing. +.It Dv MNT_NOCLUSTERR +Disable read clustering. +.It Dv MNT_NOCLUSTERW +Disable write clustering. +.El +.Pp +The flag +.Dv MNT_UPDATE +indicates that the mount command is being applied +to an already mounted file system. +This allows the mount flags to be changed without requiring +that the file system be unmounted and remounted. +Some file systems may not allow all flags to be changed. +For example, +many file systems will not allow a change from read-write to read-only. +.Pp +The flag +.Dv MNT_RELOAD +causes the vfs subsystem to update its data structures pertaining to +the specified already mounted file system. +.Pp +The +.Fa type +argument names the file system. +The types of file systems known to the system can be obtained with +.Xr lsvfs 1 . +.Pp +The +.Fa data +argument +is a pointer to a structure that contains the type +specific arguments to mount. +The format for these argument structures is described in the +manual page for each file system. +By convention file system manual pages are named +by prefixing ``mount_'' to the name of the file system as returned by +.Xr lsvfs 1 . +Thus the +.Tn NFS +file system is described by the +.Xr mount_nfs 8 +manual page. +It should be noted that a manual page for default +file systems, known as UFS and UFS2, does not exist. +.Pp +The +.Fn unmount +system call disassociates the file system from the specified +mount point +.Fa dir . +.Pp +The +.Fa flags +argument may include +.Dv MNT_FORCE +to specify that the file system should be forcibly unmounted +even if files are still active. +Active special devices continue to work, +but any further accesses to any other active files result in errors +even if the file system is later remounted. +.Pp +If the +.Dv MNT_BYFSID +flag is specified, +.Fa dir +should instead be a file system ID encoded as +.Dq Li FSID : Ns Ar val0 : Ns Ar val1 , +where +.Ar val0 +and +.Ar val1 +are the contents of the +.Vt fsid_t +.Va val[] +array in decimal. +The file system that has the specified file system ID will be unmounted. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mount +and +.Fn nmount +system calls will fail when one of the following occurs: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is neither the super-user nor the owner of +.Fa dir . +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or the entire length of a path name exceeded 1023 characters. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating a pathname. +.It Bq Er ENOENT +A component of +.Fa dir +does not exist. +.It Bq Er ENOTDIR +A component of +.Fa name +is not a directory, +or a path prefix of +.Fa special +is not a directory. +.It Bq Er EBUSY +Another process currently holds a reference to +.Fa dir . +.It Bq Er EFAULT +The +.Fa dir +argument +points outside the process's allocated address space. +.El +.Pp +The following errors can occur for a +.Em ufs +file system mount: +.Bl -tag -width Er +.It Bq Er ENODEV +A component of ufs_args +.Fa fspec +does not exist. +.It Bq Er ENOTBLK +The +.Fa fspec +argument +is not a block device. +.It Bq Er ENXIO +The major device number of +.Fa fspec +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EBUSY +.Fa fspec +is already mounted. +.It Bq Er EMFILE +No space remains in the mount table. +.It Bq Er EINVAL +The super block for the file system had a bad magic +number or an out of range block size. +.It Bq Er ENOMEM +Not enough memory was available to read the cylinder +group information for the file system. +.It Bq Er EIO +An I/O error occurred while reading the super block or +cylinder group information. +.It Bq Er EFAULT +The +.Fa fspec +argument +points outside the process's allocated address space. +.El +.Pp +The following errors can occur for a +.Em nfs +file system mount: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +.Em Nfs +timed out trying to contact the server. +.It Bq Er EFAULT +Some part of the information described by nfs_args +points outside the process's allocated address space. +.El +.Pp +The +.Fn unmount +system call may fail with one of the following errors: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is neither the super-user nor the user who issued the corresponding +.Fn mount +call. +.It Bq Er ENAMETOOLONG +The length of the path name exceeded 1023 characters. +.It Bq Er EINVAL +The requested directory is not in the mount table. +.It Bq Er ENOENT +The file system ID specified using +.Dv MNT_BYFSID +was not found in the mount table. +.It Bq Er EINVAL +The file system ID specified using +.Dv MNT_BYFSID +could not be decoded. +.It Bq Er EINVAL +The specified file system is the root file system. +.It Bq Er EBUSY +A process is holding a reference to a file located +on the file system. +.It Bq Er EIO +An I/O error occurred while writing cached file system information. +.It Bq Er EFAULT +The +.Fa dir +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr lsvfs 1 , +.Xr mksnap_ffs 8 , +.Xr mount 8 , +.Xr umount 8 +.Sh HISTORY +The +.Fn mount +and +.Fn unmount +functions appeared in +.At v6 . +The +.Fn nmount +system call first appeared in +.Fx 5.0 . +.Sh BUGS +Some of the error codes need translation to more obvious messages. +.Pp +Allowing untrusted users to mount arbitrary media, e.g. by enabling +.Va vfs.usermount , +should not be considered safe. +Most file systems in +.Fx +were not built to safeguard against malicious devices. diff --git a/lib/libc/sys/mprotect.2 b/lib/libc/sys/mprotect.2 new file mode 100644 index 000000000000..9e12af82a55e --- /dev/null +++ b/lib/libc/sys/mprotect.2 @@ -0,0 +1,97 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mprotect.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd August 3, 2016 +.Dt MPROTECT 2 +.Os +.Sh NAME +.Nm mprotect +.Nd control the protection of pages +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn mprotect "void *addr" "size_t len" "int prot" +.Sh DESCRIPTION +The +.Fn mprotect +system call +changes the specified pages to have protection +.Fa prot . +Not all implementations will guarantee protection on a page basis; +the granularity of protection changes may be as large as an entire region. +A region is the virtual address space defined by the start +and end addresses of a +.Vt "struct vm_map_entry" . +.Pp +Currently these protection bits are known, +which can be combined, OR'd together: +.Pp +.Bl -tag -width ".Dv PROT_WRITE" -compact +.It Dv PROT_NONE +No permissions at all. +.It Dv PROT_READ +The pages can be read. +.It Dv PROT_WRITE +The pages can be written. +.It Dv PROT_EXEC +The pages can be executed. +.El +.Sh RETURN VALUES +.Rv -std mprotect +.Sh ERRORS +The +.Fn mprotect +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.It Bq Er EACCES +The calling process was not allowed to change +the protection to the value specified by +the +.Fa prot +argument. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr msync 2 , +.Xr munmap 2 +.Sh HISTORY +The +.Fn mprotect +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/mq_close.2 b/lib/libc/sys/mq_close.2 new file mode 100644 index 000000000000..f9ec06239c48 --- /dev/null +++ b/lib/libc/sys/mq_close.2 @@ -0,0 +1,105 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd November 29, 2005 +.Dt MQ_CLOSE 2 +.Os +.Sh NAME +.Nm mq_close +.Nd "close a message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_close "mqd_t mqdes" +.Sh DESCRIPTION +The +.Fn mq_close +system call removes the association between the message queue descriptor, +.Fa mqdes , +and its message queue. +The results of using this message queue descriptor +after successful return from this +.Fn mq_close , +and until the return of this message queue descriptor from a subsequent +.Fn mq_open , +are undefined. +.Pp +If the process has successfully attached a notification request to the +message queue via this +.Fa mqdes , +this attachment will be removed, and the message queue is available for +another process to attach for notification. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_close +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_unlink 2 +.Sh STANDARDS +The +.Fn mq_close +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/mq_getattr.2 b/lib/libc/sys/mq_getattr.2 new file mode 100644 index 000000000000..fc42d5914d04 --- /dev/null +++ b/lib/libc/sys/mq_getattr.2 @@ -0,0 +1,127 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd February 21, 2014 +.Dt MQ_GETATTR 2 +.Os +.Sh NAME +.Nm mq_getattr +.Nd "get message queue attributes (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_getattr "mqd_t mqdes" "struct mq_attr *mqstat" +.Sh DESCRIPTION +The +.Fn mq_getattr +system call obtains status information and attributes of the message queue and +the open message queue description associated with the message queue +descriptor. +.Pp +The +.Fa mqdes +argument specifies a message queue descriptor. +.Pp +The results are returned in the +.Vt mq_attr +structure referenced by the +.Fa mqstat +argument. +.Pp +Upon return, the following members will have the values associated with the +open message queue description as set when the message queue was opened and +as modified by subsequent +.Fn mq_setattr +calls: +.Va mq_flags . +.Pp +The following attributes of the message queue will be returned as set at +message queue creation: +.Va mq_maxmsg , mq_msgsize . +.Pp +Upon return, the following members within the +.Vt mq_attr +structure referenced by the +.Fa mqstat +argument will be set to the current state +of the message queue: +.Bl -tag -width ".Va mq_curmsgs" +.It Va mq_curmsgs +The number of messages currently on the queue. +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_getattr +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_setattr 2 , +.Xr mq_timedsend 2 +.Sh STANDARDS +The +.Fn mq_getattr +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/mq_notify.2 b/lib/libc/sys/mq_notify.2 new file mode 100644 index 000000000000..4418c60449d9 --- /dev/null +++ b/lib/libc/sys/mq_notify.2 @@ -0,0 +1,165 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd July 15, 2016 +.Dt MQ_NOTIFY 2 +.Os +.Sh NAME +.Nm mq_notify +.Nd "notify process that a message is available (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" +.Sh DESCRIPTION +If the argument notification is not +.Dv NULL , +this system call will register the calling process to be notified of message +arrival at an empty message queue associated with the specified message +queue descriptor, +.Fa mqdes . +The notification specified by the +.Fa notification +argument will be sent to +the process when the message queue transitions from empty to non-empty. +At any time, only one process may be registered for notification by a +message queue. +If the calling process or any other process has already +registered for notification of message arrival at the specified message +queue, subsequent attempts to register for that message queue will fail. +.Pp +The +.Fa notification +argument points to a +.Vt sigevent +structure that defines how the calling process will be notified. +If +.Fa notification->sigev_notify +is +.Dv SIGEV_NONE , +then no signal will be posted, but the error status and the return status +for the operation will be set appropriately. +For +.Dv SIGEV_SIGNO +and +.Dv SIGEV_THREAD_ID +notifications, +the signal specified in +.Fa notification->sigev_signo +will be sent to the calling process +.Pq Dv SIGEV_SIGNO +or to the thread whose LWP ID is +.Fa notification->sigev_notify_thread_id +.Pq Dv SIGEV_THREAD_ID . +The information for the queued signal will include: +.Bl -column ".Va si_value" +.It Sy Member Ta Sy Value +.It Va si_code Ta Dv SI_MESGQ +.It Va si_value Ta +the value stored in +.Fa notification->sigev_value +.It Va si_mqd Ta Fa mqdes +.El +.Pp +If +.Fa notification +is +.Dv NULL +and the process is currently registered for notification by the specified +message queue, the existing registration will be removed. +.Pp +When the notification is sent to the registered process, its registration +is removed. +The message queue then is available for registration. +.Pp +If a process has registered for notification of message arrival at a +message queue and some thread is blocked in +.Fn mq_receive +waiting to receive a message when a message arrives at the queue, the +arriving message will satisfy the appropriate +.Fn mq_receive . +The resulting behavior is as if the message queue remains empty, and no +notification will be sent. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn mq_notify +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.It Bq Er EBUSY +Process is already registered for notification by the message queue. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa notification->sigev_notify +is invalid or not supported. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 , +.Xr sigevent 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn mq_notify +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/mq_open.2 b/lib/libc/sys/mq_open.2 new file mode 100644 index 000000000000..ef6154b7ff5a --- /dev/null +++ b/lib/libc/sys/mq_open.2 @@ -0,0 +1,329 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd September 15, 2014 +.Dt MQ_OPEN 2 +.Os +.Sh NAME +.Nm mq_open +.Nd "open a message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft mqd_t +.Fn mq_open "const char *name" "int oflag" "..." +.Sh DESCRIPTION +The +.Fn mq_open +system call establishes the connection between a process and a message queue +with a message queue descriptor. +It creates an open message queue +description that refers to the message queue, and a message queue descriptor +that refers to that open message queue description. +The message queue +descriptor is used by other functions to refer to that message queue. +The +.Fa name +argument points to a string naming a message queue. +The +.Fa name +argument should conform to the construction rules for a pathname. +The +.Fa name +should begin with a slash character. +Processes calling +.Fn mq_open +with the same value of +.Fa name +refers to the same message queue object, as long as that name has not been +removed. +If the +.Fa name +argument is not the name of an existing message queue and creation is not +requested, +.Fn mq_open +will fail and return an error. +.Pp +The +.Fa oflag +argument requests the desired receive and/or send access to the message +queue. +The requested access permission to receive messages or send messages +would be granted if the calling process would be granted read or write access, +respectively, to an equivalently protected file. +.Pp +The value of +.Fa oflag +is the bitwise-inclusive OR of values from the following list. +Applications should specify exactly one of the first three values (access +modes) below in the value of +.Fa oflag : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_RDONLY +Open the message queue for receiving messages. +The process can use the +returned message queue descriptor with +.Fn mq_receive , +but not +.Fn mq_send . +A message queue may be open multiple times in the same or different processes +for receiving messages. +.It Dv O_WRONLY +Open the queue for sending messages. +The process can use the returned +message queue descriptor with +.Fn mq_send +but not +.Fn mq_receive . +A message queue may be open multiple times in the same or different processes +for sending messages. +.It Dv O_RDWR +Open the queue for both receiving and sending messages. +The process can use +any of the functions allowed for +.Dv O_RDONLY +and +.Dv O_WRONLY . +A message queue may be open multiple times in the same or different processes +for sending messages. +.El +.Pp +Any combination of the remaining flags may be specified in the value of +.Fa oflag : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_CREAT +Create a message queue. +It requires two additional arguments: +.Fa mode , +which is of type +.Vt mode_t , +and +.Fa attr , +which is a pointer to an +.Vt mq_attr +structure. +If the pathname +.Fa name +has already been used to create a message queue that still exists, then +this flag has no effect, except as noted under +.Dv O_EXCL . +Otherwise, a message queue will be created without any messages +in it. +The user ID of the message queue will be set to the effective user ID +of the process, and the group ID of the message queue will be set to the +effective group ID of the process. +The permission bits of the message queue +will be set to the value of the +.Fa mode +argument, except those set in the file mode creation mask of the process. +When bits in +.Fa mode +other than the file permission bits are specified, the effect is +unspecified. +If +.Fa attr +is +.Dv NULL , +the message queue is created with implementation-defined default message +queue attributes. +If attr is +.Pf non- Dv NULL +and the calling process has the +appropriate privilege on name, the message queue +.Va mq_maxmsg +and +.Va mq_msgsize +attributes will be set to the values of the corresponding members in the +.Vt mq_attr +structure referred to by +.Fa attr . +If +.Fa attr +is +.Pf non- Dv NULL , +but the calling process does not have the appropriate privilege +on name, the +.Fn mq_open +function will fail and return an error without creating the message queue. +.It Dv O_EXCL +If +.Dv O_EXCL +and +.Dv O_CREAT +are set, +.Fn mq_open +will fail if the message queue name exists. +.It Dv O_NONBLOCK +Determines whether an +.Fn mq_send +or +.Fn mq_receive +waits for resources or messages that are not currently available, or fails +with +.Va errno +set to +.Er EAGAIN ; +see +.Xr mq_send 2 +and +.Xr mq_receive 2 +for details. +.El +.Pp +The +.Fn mq_open +system call does not add or remove messages from the queue. +.Sh NOTES +.Fx +implements message queue based on file descriptor. +The descriptor +is inherited by child after +.Xr fork 2 . +The descriptor is closed in a new image after +.Xr exec 3 . +The +.Xr select 2 +and +.Xr kevent 2 +system calls are supported for message queue descriptor. +.Pp +Please see the +.Xr mqueuefs 5 +man page for instructions on loading the module or compiling the service into +the kernel. +.Sh RETURN VALUES +Upon successful completion, the function returns a message queue +descriptor; otherwise, the function returns +.Po Vt mqd_t Pc Ns \-1 +and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_open +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The message queue exists and the permissions specified by +.Fa oflag +are denied, or the message queue does not exist and permission to create the +message queue is denied. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are set and the named message queue already exists. +.It Bq Er EINTR +The +.Fn mq_open +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fn mq_open +function is not supported for the given name. +.It Bq Er EINVAL +.Dv O_CREAT +was specified in +.Fa oflag , +the value of +.Fa attr +is not +.Dv NULL , +and either +.Va mq_maxmsg +or +.Va mq_msgsize +was less than or equal to zero. +.It Bq Er EMFILE +Too many message queue descriptors or file descriptors are currently in use +by this process. +.It Bq Er ENAMETOOLONG +The length of the +.Fa name +argument exceeds +.Brq Dv PATH_MAX +or a pathname component +is longer than +.Brq Dv NAME_MAX . +.It Bq Er ENFILE +Too many message queues are currently open in the system. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named message queue does not exist. +.It Bq Er ENOSPC +There is insufficient space for the creation of the new message queue. +.El +.Sh SEE ALSO +.Xr mq_close 2 , +.Xr mq_getattr 2 , +.Xr mq_receive 2 , +.Xr mq_send 2 , +.Xr mq_setattr 2 , +.Xr mq_timedreceive 3 , +.Xr mq_timedsend 3 , +.Xr mq_unlink 3 , +.Xr mqueuefs 5 +.Sh STANDARDS +The +.Fn mq_open +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh BUGS +This implementation places strict requirements on the value of +.Fa name : +it must begin with a slash +.Pq Ql / +and contain no other slash characters. +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/mq_receive.2 b/lib/libc/sys/mq_receive.2 new file mode 100644 index 000000000000..730636bf31ee --- /dev/null +++ b/lib/libc/sys/mq_receive.2 @@ -0,0 +1,217 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd November 29, 2005 +.Dt MQ_RECEIVE 2 +.Os +.Sh NAME +.Nm mq_receive , mq_timedreceive +.Nd "receive a message from message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft ssize_t +.Fo mq_receive +.Fa "mqd_t mqdes" +.Fa "char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *msg_prio" +.Fc +.Ft ssize_t +.Fo mq_timedreceive +.Fa "mqd_t mqdes" +.Fa "char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned *msg_prio" +.Fa "const struct timespec *abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_receive +system call receives oldest of the highest priority message(s) from the +message queue specified by +.Fa mqdes . +If the size of the buffer in bytes, specified by the +.Fa msg_len +argument, is less than the +.Va mq_msgsize +attribute of the message queue, the system call will fail and return an +error. +Otherwise, the selected message will be removed from the queue +and copied to the buffer pointed to by the +.Fa msg_ptr +argument. +.Pp +If the argument +.Fa msg_prio +is not +.Dv NULL , +the priority of the selected message will be stored in the +location referenced by +.Fa msg_prio . +If the specified message queue is empty and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_receive +will block until a message is enqueued on the message queue or until +.Fn mq_receive +is interrupted by a signal. +If more than one thread is waiting to receive +a message when a message arrives at an empty queue and the Priority +Scheduling option is supported, then the thread of highest priority that +has been waiting the longest will be selected to receive the message. +Otherwise, it is unspecified which waiting thread receives the message. +If the specified message queue is empty and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +no message +will be removed from the queue, and +.Fn mq_receive +will return an error. +.Pp +The +.Fn mq_timedreceive +system call will receive the oldest of the highest priority messages from the +message queue specified by +.Fa mqdes +as described for the +.Fn mq_receive +system call. +However, if +.Dv O_NONBLOCK +was not specified when the message queue was opened via the +.Fn mq_open +system call, and no message exists on the queue to satisfy the receive, the wait +for such a message will be terminated when the specified timeout expires. +If +.Dv O_NONBLOCK +is set, this system call is equivalent to +.Fn mq_receive . +.Pp +The timeout expires when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, when +the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The timeout is based on the +.Dv CLOCK_REALTIME +clock. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_receive +and +.Fn mq_timedreceive +system calls return the length of the selected message in bytes and the +message is removed from the queue. +Otherwise, no message is removed +from the queue, the system call returns a value of \-1, +and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mq_receive +and +.Fn mq_timedreceive +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +.Dv O_NONBLOCK +flag is set in the message queue description associated with +.Fa mqdes , +and the specified message queue is empty. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for reading. +.It Bq Er EMSGSIZE +The specified message buffer size, +.Fa msg_len , +is less than the message size attribute of the message queue. +.It Bq Er EINTR +The +.Fn mq_receive +or +.Fn mq_timedreceive +operation was interrupted by a signal. +.It Bq Er EINVAL +The process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1000 million. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, but no message arrived +on the queue before the specified timeout expired. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 +.Sh STANDARDS +The +.Fn mq_receive +and +.Fn mq_timedreceive +system calls conform to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/mq_send.2 b/lib/libc/sys/mq_send.2 new file mode 100644 index 000000000000..6f18b90c14bc --- /dev/null +++ b/lib/libc/sys/mq_send.2 @@ -0,0 +1,236 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd November 29, 2005 +.Dt MQ_SEND 2 +.Os +.Sh NAME +.Nm mq_send , mq_timedsend +.Nd "send a message to message queue (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_send +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fc +.Ft int +.Fo mq_timedsend +.Fa "mqd_t mqdes" +.Fa "const char *msg_ptr" +.Fa "size_t msg_len" +.Fa "unsigned msg_prio" +.Fa "const struct timespec *abs_timeout" +.Fc +.Sh DESCRIPTION +The +.Fn mq_send +system call adds the message pointed to by the argument +.Fa msg_ptr +to the message queue specified by +.Fa mqdes . +The +.Fa msg_len +argument specifies the length of the message, in bytes, pointed to by +.Fa msg_ptr . +The value of +.Fa msg_len +should be less than or equal to the +.Va mq_msgsize +attribute of the message queue, or +.Fn mq_send +will fail. +.Pp +If the specified message queue is not full, +.Fn mq_send +will behave as if the message is inserted into the message queue at +the position indicated by the +.Fa msg_prio +argument. +A message with a larger numeric value of +.Fa msg_prio +will be inserted before messages with lower values of +.Fa msg_prio . +A message will be inserted after other messages in the queue, if any, +with equal +.Fa msg_prio . +The value of +.Fa msg_prio +should be less than +.Brq Dv MQ_PRIO_MAX . +.Pp +If the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +.Fn mq_send +will block until space becomes available to enqueue the +message, or until +.Fn mq_send +is interrupted by a signal. +If more than one thread is +waiting to send when space becomes available in the message queue and +the Priority Scheduling option is supported, then the thread of the +highest priority that has been waiting the longest will be unblocked +to send its message. +Otherwise, it is unspecified which waiting thread +is unblocked. +If the specified message queue is full and +.Dv O_NONBLOCK +is set in the message queue description associated with +.Fa mqdes , +the message will not be queued and +.Fn mq_send +will return an error. +.Pp +The +.Fn mq_timedsend +system call will add a message to the message queue specified by +.Fa mqdes +in the manner defined for the +.Fn mq_send +system call. +However, if the specified message queue is full and +.Dv O_NONBLOCK +is not set in the message queue description associated with +.Fa mqdes , +the wait for sufficient room in the queue will be terminated when +the specified timeout expires. +If +.Dv O_NONBLOCK +is set in the message queue description, this system call is +equivalent to +.Fn mq_send . +.Pp +The timeout will expire when the absolute time specified by +.Fa abs_timeout +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.Fa abs_timeout ) , +or if the absolute time specified by +.Fa abs_timeout +has already been passed at the time of the call. +.Pp +The timeout is based on the +.Dv CLOCK_REALTIME +clock. +.Sh RETURN VALUES +Upon successful completion, the +.Fn mq_send +and +.Fn mq_timedsend +system calls return a value of zero. +Otherwise, no message will be +enqueued, the system calls return \-1, and +the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mq_send +and +.Fn mq_timedsend +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The +.Dv O_NONBLOCK +flag is set in the message queue description associated with +.Fa mqdes , +and the specified message queue is full. +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor open for writing. +.It Bq Er EINTR +A signal interrupted the call to +.Fn mq_send +or +.Fn mq_timedsend . +.It Bq Er EINVAL +The value of +.Fa msg_prio +was outside the valid range. +.It Bq Er EINVAL +The process or thread would have blocked, and the +.Fa abs_timeout +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1000 million. +.It Bq Er EMSGSIZE +The specified message length, +.Fa msg_len , +exceeds the message size attribute of the message queue. +.It Bq Er ETIMEDOUT +The +.Dv O_NONBLOCK +flag was not set when the message queue was opened, but the timeout +expired before the message could be added to the queue. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_receive 2 , +.Xr mq_setattr 2 , +.Xr mq_timedreceive 2 +.Sh STANDARDS +The +.Fn mq_send +and +.Fn mq_timedsend +system calls conform to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/mq_setattr.2 b/lib/libc/sys/mq_setattr.2 new file mode 100644 index 000000000000..79e523d6dd75 --- /dev/null +++ b/lib/libc/sys/mq_setattr.2 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd May 17, 2011 +.Dt MQ_SETATTR 2 +.Os +.Sh NAME +.Nm mq_setattr +.Nd "set message queue attributes (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_setattr +.Fa "mqd_t mqdes" +.Fa "const struct mq_attr *restrict mqstat" +.Fa "struct mq_attr *restrict omqstat" +.Fc +.Sh DESCRIPTION +The +.Fn mq_setattr +system call sets attributes associated with the open message queue description +referenced by the message queue descriptor specified by +.Fa mqdes . +The message queue attributes corresponding to the following members defined +in the +.Vt mq_attr +structure will be set to the specified values upon successful completion of +.Fn mq_setattr : +.Bl -tag -width ".Va mq_flags" +.It Va mq_flags +The value of this member is zero or +.Dv O_NONBLOCK . +.El +.Pp +The values of the +.Va mq_maxmsg , mq_msgsize , +and +.Va mq_curmsgs +members of the +.Vt mq_attr +structure are ignored by +.Fn mq_setattr . +.Sh RETURN VALUES +Upon successful completion, the function returns a value of zero and the +attributes of the message queue will have been changed as specified. +.Pp +Otherwise, the message queue attributes are unchanged, and the function +returns a value of \-1 and sets the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn mq_setattr +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa mqdes +argument is not a valid message queue descriptor. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 +.Sh STANDARDS +The +.Fn mq_setattr +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +message queues first appeared in +.Fx 7.0 . +.Sh COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard is +the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html. diff --git a/lib/libc/sys/msgctl.2 b/lib/libc/sys/msgctl.2 new file mode 100644 index 000000000000..34c52633d8c8 --- /dev/null +++ b/lib/libc/sys/msgctl.2 @@ -0,0 +1,210 @@ +.\" $NetBSD: msgctl.2,v 1.1 1995/10/16 23:49:15 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\"/ +.Dd July 9, 2009 +.Dt MSGCTL 2 +.Os +.Sh NAME +.Nm msgctl +.Nd message control operations +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf" +.Sh DESCRIPTION +The +.Fn msgctl +system call performs some control operations on the message queue specified +by +.Fa msqid . +.Pp +Each message queue has a data structure associated with it, parts of which +may be altered by +.Fn msgctl +and parts of which determine the actions of +.Fn msgctl . +The data structure is defined in +.In sys/msg.h +and contains (amongst others) the following members: +.Bd -literal +struct msqid_ds { + struct ipc_perm msg_perm; /* msg queue permission bits */ + struct msg *msg_first; /* first message in the queue */ + struct msg *msg_last; /* last message in the queue */ + msglen_t msg_cbytes; /* number of bytes in use on the queue */ + msgqnum_t msg_qnum; /* number of msgs in the queue */ + msglen_t msg_qbytes; /* max # of bytes on the queue */ + pid_t msg_lspid; /* pid of last msgsnd() */ + pid_t msg_lrpid; /* pid of last msgrcv() */ + time_t msg_stime; /* time of last msgsnd() */ + time_t msg_rtime; /* time of last msgrcv() */ + time_t msg_ctime; /* time of last msgctl() */ +}; +.Ed +.Pp +The +.Vt ipc_perm +structure used inside the +.Vt msqid_ds +structure is defined in +.In sys/ipc.h +and looks like this: +.Bd -literal +struct ipc_perm { + uid_t cuid; /* creator user id */ + gid_t cgid; /* creator group id */ + uid_t uid; /* user id */ + gid_t gid; /* group id */ + mode_t mode; /* r/w permission */ + unsigned short seq; /* sequence # (to generate unique ipcid) */ + key_t key; /* user specified msg/sem/shm key */ +}; +.Ed +.Pp +The operation to be performed by +.Fn msgctl +is specified in +.Fa cmd +and is one of: +.Bl -tag -width IPC_RMIDX +.It Dv IPC_STAT +Gather information about the message queue and place it in the +structure pointed to by +.Fa buf . +.It Dv IPC_SET +Set the value of the +.Va msg_perm.uid , +.Va msg_perm.gid , +.Va msg_perm.mode +and +.Va msg_qbytes +fields in the structure associated with +.Fa msqid . +The values are taken from the corresponding fields in the structure +pointed to by +.Fa buf . +This operation can only be executed by the super-user, or a process that +has an effective user id equal to either +.Va msg_perm.cuid +or +.Va msg_perm.uid +in the data structure associated with the message queue. +The value of +.Va msg_qbytes +can only be increased by the super-user. +Values for +.Va msg_qbytes +that exceed the system limit (MSGMNB from +.In sys/msg.h ) +are silently truncated to that limit. +.It Dv IPC_RMID +Remove the message queue specified by +.Fa msqid +and destroy the data associated with it. +Only the super-user or a process +with an effective uid equal to the +.Va msg_perm.cuid +or +.Va msg_perm.uid +values in the data structure associated with the queue can do this. +.El +.Pp +The permission to read from or write to a message queue (see +.Xr msgsnd 2 +and +.Xr msgrcv 2 ) +is determined by the +.Va msg_perm.mode +field in the same way as is +done with files (see +.Xr chmod 2 ) , +but the effective uid can match either the +.Va msg_perm.cuid +field or the +.Va msg_perm.uid +field, and the +effective gid can match either +.Va msg_perm.cgid +or +.Va msg_perm.gid . +.Sh RETURN VALUES +.Rv -std msgctl +.Sh ERRORS +The +.Fn msgctl +function +will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The +.Fa cmd +argument +is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does +the effective uid match either the +.Va msg_perm.uid +or +.Va msg_perm.cuid +fields of the data structure associated with the message queue. +.Pp +An attempt is made to increase the value of +.Va msg_qbytes +through IPC_SET +but the caller is not the super-user. +.It Bq Er EACCES +The command is IPC_STAT +and the caller has no read permission for this message queue. +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +.Va cmd +is not a valid command. +.It Bq Er EFAULT +The +.Fa buf +argument +specifies an invalid address. +.El +.Sh SEE ALSO +.Xr msgget 2 , +.Xr msgrcv 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libc/sys/msgget.2 b/lib/libc/sys/msgget.2 new file mode 100644 index 000000000000..27e1766350ca --- /dev/null +++ b/lib/libc/sys/msgget.2 @@ -0,0 +1,141 @@ +.\" $NetBSD: msgget.2,v 1.1 1995/10/16 23:49:19 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" $FreeBSD$ +.\" +.\"/ +.Dd July 9, 2009 +.Dt MSGGET 2 +.Os +.Sh NAME +.Nm msgget +.Nd get message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgget "key_t key" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgget +function +returns the message queue identifier associated with +.Fa key . +A message queue identifier is a unique integer greater than zero. +.Pp +A message queue is created if either +.Fa key +is equal to +.Dv IPC_PRIVATE , +or +.Fa key +does not have a message queue identifier associated with it, and the +.Dv IPC_CREAT +bit is set in +.Fa msgflg . +.Pp +If a new message queue is created, the data structure associated with it (the +.Va msqid_ds +structure, see +.Xr msgctl 2 ) +is initialized as follows: +.Bl -bullet +.It +.Va msg_perm.cuid +and +.Va msg_perm.uid +are set to the effective uid of the calling process. +.It +.Va msg_perm.gid +and +.Va msg_perm.cgid +are set to the effective gid of the calling process. +.It +.Va msg_perm.mode +is set to the lower 9 bits of +.Fa msgflg . +.It +.Va msg_cbytes , +.Va msg_qnum , +.Va msg_lspid , +.Va msg_lrpid , +.Va msg_rtime , +and +.Va msg_stime +are set to 0. +.It +.Va msg_qbytes +is set to the system wide maximum value for the number of bytes in a queue +.Pf ( Dv MSGMNB ) . +.It +.Va msg_ctime +is set to the current time. +.El +.Sh RETURN VALUES +Upon successful completion a positive message queue identifier is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +A message queue is already associated with +.Fa key +and the caller has no permission to access it. +.It Bq Er EEXIST +Both +.Dv IPC_CREAT +and +.Dv IPC_EXCL +are set in +.Fa msgflg , +and a message queue is already associated with +.Fa key . +.It Bq Er ENOSPC +A new message queue could not be created because the system limit for +the number of message queues has been reached. +.It Bq Er ENOENT +.Dv IPC_CREAT +was not set in +.Fa msgflg +and no message queue associated with +.Fa key +was found. +.El +.Sh SEE ALSO +.Xr msgctl 2 , +.Xr msgrcv 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libc/sys/msgrcv.2 b/lib/libc/sys/msgrcv.2 new file mode 100644 index 000000000000..59eeec42f2d5 --- /dev/null +++ b/lib/libc/sys/msgrcv.2 @@ -0,0 +1,222 @@ +.\" $NetBSD: msgrcv.2,v 1.1 1995/10/16 23:49:20 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" $FreeBSD$ +.\" +.\"/ +.Dd July 28, 2016 +.Dt MSGRCV 2 +.Os +.Sh NAME +.Nm msgrcv +.Nd receive a message from a message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft ssize_t +.Fn msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgrcv +function receives a message from the message queue specified in +.Fa msqid , +and places it into the structure pointed to by +.Fa msgp . +This structure should consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed +.Pp +.Va mtype +is an integer greater than 0 that can be used for selecting messages, +.Va mtext +is an array of bytes, with a size up to that of the system limit +.Pf ( Dv MSGMAX ) . +.Pp +The value of +.Fa msgtyp +has one of the following meanings: +.Bl -bullet +.It +The +.Fa msgtyp +argument +is greater than 0. +The first message of type +.Fa msgtyp +will be received. +.It +The +.Fa msgtyp +argument +is equal to 0. +The first message on the queue will be received. +.It +The +.Fa msgtyp +argument +is less than 0. +The first message of the lowest message type that is +less than or equal to the absolute value of +.Fa msgtyp +will be received. +.El +.Pp +The +.Fa msgsz +argument +specifies the maximum length of the requested message. +If the received +message has a length greater than +.Fa msgsz +it will be silently truncated if the +.Dv MSG_NOERROR +flag is set in +.Fa msgflg , +otherwise an error will be returned. +.Pp +If no matching message is present on the message queue specified by +.Fa msqid , +the behavior of +.Fn msgrcv +depends on whether the +.Dv IPC_NOWAIT +flag is set in +.Fa msgflg +or not. +If +.Dv IPC_NOWAIT +is set, +.Fn msgrcv +will immediately return a value of -1, and set +.Va errno +to +.Er ENOMSG . +If +.Dv IPC_NOWAIT +is not set, the calling process will be blocked +until: +.Bl -bullet +.It +A message of the requested type becomes available on the message queue. +.It +The message queue is removed, in which case -1 will be returned, and +.Va errno +set to +.Er EINVAL . +.It +A signal is received and caught. +-1 is returned, and +.Va errno +set to +.Er EINTR . +.El +.Pp +If a message is successfully received, the data structure associated with +.Fa msqid +is updated as follows: +.Bl -bullet +.It +.Va msg_cbytes +is decremented by the size of the message. +.It +.Va msg_lrpid +is set to the pid of the caller. +.It +.Va msg_lrtime +is set to the current time. +.It +.Va msg_qnum +is decremented by 1. +.El +.Sh RETURN VALUES +Upon successful completion, +.Fn msgrcv +returns the number of bytes received into the +.Va mtext +field of the structure pointed to by +.Fa msgp . +Otherwise, -1 is returned, and +.Va errno +set to indicate the error. +.Sh ERRORS +The +.Fn msgrcv +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +The message queue was removed while +.Fn msgrcv +was waiting for a message of the requested type to become available on it. +.Pp +The +.Fa msgsz +argument +is less than 0. +.It Bq Er E2BIG +A matching message was received, but its size was greater than +.Fa msgsz +and the +.Dv MSG_NOERROR +flag was not set in +.Fa msgflg . +.It Bq Er EACCES +The calling process does not have read access to the message queue. +.It Bq Er EFAULT +The +.Fa msgp +argument +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.It Bq Er ENOMSG +There is no message of the requested type available on the message queue, +and +.Dv IPC_NOWAIT +is set in +.Fa msgflg . +.El +.Sh SEE ALSO +.Xr msgctl 2 , +.Xr msgget 2 , +.Xr msgsnd 2 +.Sh HISTORY +Message queues appeared in the first release of +.At V . diff --git a/lib/libc/sys/msgsnd.2 b/lib/libc/sys/msgsnd.2 new file mode 100644 index 000000000000..051c9922e58c --- /dev/null +++ b/lib/libc/sys/msgsnd.2 @@ -0,0 +1,184 @@ +.\" $NetBSD: msgsnd.2,v 1.1 1995/10/16 23:49:24 jtc Exp $ +.\" +.\" Copyright (c) 1995 Frank van der Linden +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Frank van der Linden +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 9, 2009 +.Dt MSGSND 2 +.Os +.Sh NAME +.Nm msgsnd +.Nd send a message to a message queue +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/msg.h +.Ft int +.Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg" +.Sh DESCRIPTION +The +.Fn msgsnd +function sends a message to the message queue specified in +.Fa msqid . +The +.Fa msgp +argument +points to a structure containing the message. +This structure should +consist of the following members: +.Bd -literal + long mtype; /* message type */ + char mtext[1]; /* body of message */ +.Ed +.Pp +.Va mtype +is an integer greater than 0 that can be used for selecting messages (see +.Xr msgrcv 2 ) , +.Va mtext +is an array of +.Fa msgsz +bytes. +The argument +.Fa msgsz +can range from 0 to a system-imposed maximum, +.Dv MSGMAX . +.Pp +If the number of bytes already on the message queue plus +.Fa msgsz +is bigger than the maximum number of bytes on the message queue +.Pf ( Va msg_qbytes , +see +.Xr msgctl 2 ) , +or the number of messages on all queues system-wide is already equal to +the system limit, +.Fa msgflg +determines the action of +.Fn msgsnd . +If +.Fa msgflg +has +.Dv IPC_NOWAIT +mask set in it, the call will return immediately. +If +.Fa msgflg +does not have +.Dv IPC_NOWAIT +set in it, the call will block until: +.Bl -bullet +.It +The condition which caused the call to block does no longer exist. +The message will be sent. +.It +The message queue is removed, in which case -1 will be returned, and +.Va errno +is set to +.Er EINVAL . +.It +The caller catches a signal. +The call returns with +.Va errno +set to +.Er EINTR . +.El +.Pp +After a successful call, the data structure associated with the message +queue is updated in the following way: +.Bl -bullet +.It +.Va msg_cbytes +is incremented by the size of the message. +.It +.Va msg_qnum +is incremented by 1. +.It +.Va msg_lspid +is set to the pid of the calling process. +.It +.Va msg_stime +is set to the current time. +.El +.Sh RETURN VALUES +.Rv -std msgsnd +.Sh ERRORS +The +.Fn msgsnd +function +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa msqid +argument +is not a valid message queue identifier. +.Pp +The message queue was removed while +.Fn msgsnd +was waiting for a resource to become available in order to deliver the +message. +.Pp +The +.Fa msgsz +argument +is greater than +.Va msg_qbytes . +.Pp +The +.Fa mtype +argument +is not greater than 0. +.It Bq Er EACCES +The calling process does not have write access to the message queue. +.It Bq Er EAGAIN +There was no space for this message either on the queue, or in the whole +system, and +.Dv IPC_NOWAIT +was set in +.Fa msgflg . +.It Bq Er EFAULT +The +.Fa msgp +argument +points to an invalid address. +.It Bq Er EINTR +The system call was interrupted by the delivery of a signal. +.El +.Sh HISTORY +Message queues appeared in the first release of AT&T Unix System V. +.Sh BUGS +.Nx +and +.Fx +do not define the +.Er EIDRM +error value, which should be used +in the case of a removed message queue. diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2 new file mode 100644 index 000000000000..a91faf2a66e0 --- /dev/null +++ b/lib/libc/sys/msync.2 @@ -0,0 +1,126 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)msync.2 8.2 (Berkeley) 6/21/94 +.\" $FreeBSD$ +.\" +.Dd March 18, 2012 +.Dt MSYNC 2 +.Os +.Sh NAME +.Nm msync +.Nd synchronize a mapped region +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn msync "void *addr" "size_t len" "int flags" +.Sh DESCRIPTION +The +.Fn msync +system call +writes any modified pages back to the file system and updates +the file modification time. +If +.Fa len +is 0, all modified pages within the region containing +.Fa addr +will be flushed; +if +.Fa len +is non-zero, only those pages containing +.Fa addr +and +.Fa len-1 +succeeding locations will be examined. +The +.Fa flags +argument may be specified as follows: +.Pp +.Bl -tag -width ".Dv MS_INVALIDATE" -compact +.It Dv MS_ASYNC +Return immediately +.It Dv MS_SYNC +Perform synchronous writes +.It Dv MS_INVALIDATE +Invalidate all cached data +.El +.Sh RETURN VALUES +.Rv -std msync +.Sh ERRORS +The +.Fn msync +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +Some or all of the pages in the specified region are locked and +.Dv MS_INVALIDATE +is specified. +.It Bq Er EINVAL +The +.Fa addr +argument +is not a multiple of the hardware page size. +.It Bq Er ENOMEM +The addresses in the range starting at +.Fa addr +and continuing for +.Fa len +bytes are outside the range allowed for the address space of a +process or specify one or more pages that are not mapped. +.It Bq Er EINVAL +The +.Fa flags +argument +was both MS_ASYNC and MS_INVALIDATE. +Only one of these flags is allowed. +.It Bq Er EIO +An error occurred while writing at least one of the pages in +the specified region. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr munmap 2 +.Sh HISTORY +The +.Fn msync +system call first appeared in +.Bx 4.4 . +.Sh BUGS +The +.Fn msync +system call is usually not needed since +.Bx +implements a coherent file system buffer cache. +However, it may be used to associate dirty VM pages with file system +buffers and thus cause them to be flushed to physical media sooner +rather than later. diff --git a/lib/libc/sys/msync.c b/lib/libc/sys/msync.c new file mode 100644 index 000000000000..d86cc0462dd8 --- /dev/null +++ b/lib/libc/sys/msync.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/fcntl.h> +#include <sys/mman.h> +#include "libc_private.h" + +__weak_reference(__sys_msync, __msync); + +#pragma weak msync +int +msync(void *addr, size_t len, int flags) +{ + + return (((int (*)(void *, size_t, int)) + __libc_interposing[INTERPOS_msync])(addr, len, flags)); +} diff --git a/lib/libc/sys/munmap.2 b/lib/libc/sys/munmap.2 new file mode 100644 index 000000000000..643107286203 --- /dev/null +++ b/lib/libc/sys/munmap.2 @@ -0,0 +1,78 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)munmap.2 8.3 (Berkeley) 5/27/94 +.\" $FreeBSD$ +.\" +.Dd May 27, 1994 +.Dt MUNMAP 2 +.Os +.Sh NAME +.Nm munmap +.Nd remove a mapping +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft int +.Fn munmap "void *addr" "size_t len" +.Sh DESCRIPTION +The +.Fn munmap +system call +deletes the mappings for the specified address range, +and causes further references to addresses within the range +to generate invalid memory references. +.Sh RETURN VALUES +.Rv -std munmap +.Sh ERRORS +The +.Fn munmap +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +argument was not page aligned, the +.Fa len +argument was zero or negative, or +some part of the region being unmapped is outside the +valid address range for a process. +.El +.Sh "SEE ALSO" +.Xr madvise 2 , +.Xr mincore 2 , +.Xr mmap 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr getpagesize 3 +.Sh HISTORY +The +.Fn munmap +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/nanosleep.2 b/lib/libc/sys/nanosleep.2 new file mode 100644 index 000000000000..f50544b83d69 --- /dev/null +++ b/lib/libc/sys/nanosleep.2 @@ -0,0 +1,111 @@ +.\" $OpenBSD: nanosleep.2,v 1.1 1997/04/20 20:56:20 tholo Exp $ +.\" $NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $ +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sleep.3 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 17, 1997 +.Dt NANOSLEEP 2 +.Os +.Sh NAME +.Nm nanosleep +.Nd suspend process execution for an interval measured in nanoseconds +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn nanosleep "const struct timespec *rqtp" "struct timespec *rmtp" +.Sh DESCRIPTION +The +.Fn nanosleep +system call +causes the calling thread to sleep until the time interval specified by +.Fa rqtp +has elapsed. +An unmasked signal will +cause it to terminate the sleep early, regardless of the +.Dv SA_RESTART +value on the interrupting signal. +.Sh RETURN VALUES +If the +.Fn nanosleep +system call returns because the requested time has elapsed, the value +returned will be zero. +.Pp +If the +.Fn nanosleep +system call returns due to the delivery of a signal, the value returned +will be -1, and the global variable +.Va errno +will be set to indicate the interruption. +If +.Fa rmtp +is +.No non- Ns Dv NULL , +the timespec structure it references is updated to contain the +unslept amount (the request time minus the time actually slept). +.Sh ERRORS +The +.Fn nanosleep +system call fails if: +.Bl -tag -width Er +.It Bq Er EFAULT +Either +.Fa rqtp +or +.Fa rmtp +points to memory that is not a valid part of the process +address space. +.It Bq Er EINTR +The +.Fn nanosleep +system call +was interrupted by the delivery of a signal. +.It Bq Er EINVAL +The +.Fa rqtp +argument +specified a nanosecond value less than zero +or greater than or equal to 1000 million. +.It Bq Er ENOSYS +The +.Fn nanosleep +system call +is not supported by this implementation. +.El +.Sh SEE ALSO +.Xr sigsuspend 2 , +.Xr sleep 3 +.Sh STANDARDS +The +.Fn nanosleep +system call conforms to +.St -p1003.1b-93 . diff --git a/lib/libc/sys/nanosleep.c b/lib/libc/sys/nanosleep.c new file mode 100644 index 000000000000..412b05e778b0 --- /dev/null +++ b/lib/libc/sys/nanosleep.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <time.h> +#include "libc_private.h" + +__weak_reference(__sys_nanosleep, __nanosleep); + +#pragma weak nanosleep +int +nanosleep(const struct timespec *rqtp, struct timespec *rmtp) +{ + + return (((int (*)(const struct timespec *, struct timespec *)) + __libc_interposing[INTERPOS_nanosleep])(rqtp, rmtp)); +} diff --git a/lib/libc/sys/nfssvc.2 b/lib/libc/sys/nfssvc.2 new file mode 100644 index 000000000000..f816231ef0a1 --- /dev/null +++ b/lib/libc/sys/nfssvc.2 @@ -0,0 +1,258 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)nfssvc.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd June 9, 1993 +.Dt NFSSVC 2 +.Os +.Sh NAME +.Nm nfssvc +.Nd NFS services +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/time.h +.In nfs/rpcv2.h +.In nfsserver/nfs.h +.In unistd.h +.Ft int +.Fn nfssvc "int flags" "void *argstructp" +.Sh DESCRIPTION +The +.Fn nfssvc +system call is used by the NFS daemons to pass information into and out +of the kernel and also to enter the kernel as a server daemon. +The +.Fa flags +argument consists of several bits that show what action is to be taken +once in the kernel and the +.Fa argstructp +points to one of three structures depending on which bits are set in +flags. +.Pp +On the client side, +.Xr nfsiod 8 +calls +.Fn nfssvc +with the +.Fa flags +argument set to +.Dv NFSSVC_BIOD +and +.Fa argstructp +set to +.Dv NULL +to enter the kernel as a block I/O server daemon. +For +.Tn NQNFS , +.Xr mount_nfs 8 +calls +.Fn nfssvc +with the +.Dv NFSSVC_MNTD +flag, optionally or'd with the flags +.Dv NFSSVC_GOTAUTH +and +.Dv NFSSVC_AUTHINFAIL +along with a pointer to a +.Bd -literal +struct nfsd_cargs { + char *ncd_dirp; /* Mount dir path */ + uid_t ncd_authuid; /* Effective uid */ + int ncd_authtype; /* Type of authenticator */ + int ncd_authlen; /* Length of authenticator string */ + u_char *ncd_authstr; /* Authenticator string */ + int ncd_verflen; /* and the verifier */ + u_char *ncd_verfstr; + NFSKERBKEY_T ncd_key; /* Session key */ +}; +.Ed +.Pp +structure. +The initial call has only the +.Dv NFSSVC_MNTD +flag set to specify service for the mount point. +If the mount point is using Kerberos, then the +.Xr mount_nfs 8 +utility will return from +.Fn nfssvc +with +.Va errno +== +.Er ENEEDAUTH +whenever the client side requires an ``rcmd'' +authentication ticket for the user. +The +.Xr mount_nfs 8 +utility will attempt to get the Kerberos ticket, and if successful will call +.Fn nfssvc +with the flags +.Dv NFSSVC_MNTD +and +.Dv NFSSVC_GOTAUTH +after filling the ticket into the +ncd_authstr field +and +setting the ncd_authlen and ncd_authtype +fields of the nfsd_cargs structure. +If +.Xr mount_nfs 8 +failed to get the ticket, +.Fn nfssvc +will be called with the flags +.Dv NFSSVC_MNTD , +.Dv NFSSVC_GOTAUTH +and +.Dv NFSSVC_AUTHINFAIL +to denote a failed authentication attempt. +.Pp +On the server side, +.Fn nfssvc +is called with the flag +.Dv NFSSVC_NFSD +and a pointer to a +.Bd -literal +struct nfsd_srvargs { + struct nfsd *nsd_nfsd; /* Pointer to in kernel nfsd struct */ + uid_t nsd_uid; /* Effective uid mapped to cred */ + uint32_t nsd_haddr; /* Ip address of client */ + struct ucred nsd_cr; /* Cred. uid maps to */ + int nsd_authlen; /* Length of auth string (ret) */ + u_char *nsd_authstr; /* Auth string (ret) */ + int nsd_verflen; /* and the verifier */ + u_char *nsd_verfstr; + struct timeval nsd_timestamp; /* timestamp from verifier */ + uint32_t nsd_ttl; /* credential ttl (sec) */ + NFSKERBKEY_T nsd_key; /* Session key */ +}; +.Ed +.Pp +to enter the kernel as an +.Xr nfsd 8 +daemon. +Whenever an +.Xr nfsd 8 +daemon receives a Kerberos authentication ticket, it will return from +.Fn nfssvc +with +.Va errno +== +.Er ENEEDAUTH . +The +.Xr nfsd 8 +utility will attempt to authenticate the ticket and generate a set of credentials +on the server for the ``user id'' specified in the field nsd_uid. +This is done by first authenticating the Kerberos ticket and then mapping +the Kerberos principal to a local name and getting a set of credentials for +that user via +.Xr getpwnam 3 +and +.Xr getgrouplist 3 . +If successful, the +.Xr nfsd 8 +utility will call +.Fn nfssvc +with the +.Dv NFSSVC_NFSD +and +.Dv NFSSVC_AUTHIN +flags set to pass the credential mapping in nsd_cr into the +kernel to be cached on the server socket for that client. +If the authentication failed, +.Xr nfsd 8 +calls +.Fn nfssvc +with the flags +.Dv NFSSVC_NFSD +and +.Dv NFSSVC_AUTHINFAIL +to denote an authentication failure. +.Pp +The master +.Xr nfsd 8 +server daemon calls +.Fn nfssvc +with the flag +.Dv NFSSVC_ADDSOCK +and a pointer to a +.Bd -literal +struct nfsd_args { + int sock; /* Socket to serve */ + caddr_t name; /* Client address for connection based sockets */ + int namelen;/* Length of name */ +}; +.Ed +.Pp +to pass a server side +.Tn NFS +socket into the kernel for servicing by the +.Xr nfsd 8 +daemons. +.Sh RETURN VALUES +Normally +.Fn nfssvc +does not return unless the server +is terminated by a signal when a value of 0 is returned. +Otherwise, -1 is returned and the global variable +.Va errno +is set to specify the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENEEDAUTH +This special error value +is really used for authentication support, particularly Kerberos, +as explained above. +.It Bq Er EPERM +The caller is not the super-user. +.El +.Sh SEE ALSO +.Xr mount_nfs 8 , +.Xr nfsd 8 , +.Xr nfsiod 8 +.Sh HISTORY +The +.Fn nfssvc +system call first appeared in +.Bx 4.4 . +.Sh BUGS +The +.Fn nfssvc +system call is designed specifically for the +.Tn NFS +support daemons and as such is specific to their requirements. +It should really return values to indicate the need for authentication +support, since +.Er ENEEDAUTH +is not really an error. +Several fields of the argument structures are assumed to be valid and +sometimes to be unchanged from a previous call, such that +.Fn nfssvc +must be used with extreme care. diff --git a/lib/libc/sys/ntp_adjtime.2 b/lib/libc/sys/ntp_adjtime.2 new file mode 100644 index 000000000000..8ce78e7fb86e --- /dev/null +++ b/lib/libc/sys/ntp_adjtime.2 @@ -0,0 +1,315 @@ +.\" $NetBSD: ntp_adjtime.2,v 1.6 2003/04/16 13:34:55 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Thomas Klausner. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 13, 2005 +.Dt NTP_ADJTIME 2 +.Os +.Sh NAME +.Nm ntp_adjtime , +.Nm ntp_gettime +.Nd Network Time Protocol (NTP) daemon interface system calls +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/timex.h +.Ft int +.Fn ntp_adjtime "struct timex *" +.Ft int +.Fn ntp_gettime "struct ntptimeval *" +.Sh DESCRIPTION +The two system calls +.Fn ntp_adjtime +and +.Fn ntp_gettime +are the kernel interface to the Network Time Protocol (NTP) daemon +.Xr ntpd 8 . +.Pp +The +.Fn ntp_adjtime +function is used by the NTP daemon to adjust the system clock to an +externally derived time. +The time offset and related variables which are set by +.Fn ntp_adjtime +are used by +.Fn hardclock +to adjust the phase and frequency of the phase- or frequency-lock loop +(PLL resp. FLL) which controls the system clock. +.Pp +The +.Fn ntp_gettime +function provides the time, maximum error (sync distance) and +estimated error (dispersion) to client user application programs. +.Pp +In the following, all variables that refer PPS are only relevant if +the +.Em PPS_SYNC +option is enabled in the kernel. +.Pp +.Fn ntp_adjtime +has as argument a +.Va struct timex * +of the following form: +.Bd -literal +struct timex { + unsigned int modes; /* clock mode bits (wo) */ + long offset; /* time offset (us) (rw) */ + long freq; /* frequency offset (scaled ppm) (rw) */ + long maxerror; /* maximum error (us) (rw) */ + long esterror; /* estimated error (us) (rw) */ + int status; /* clock status bits (rw) */ + long constant; /* pll time constant (rw) */ + long precision; /* clock precision (us) (ro) */ + long tolerance; /* clock frequency tolerance (scaled + * ppm) (ro) */ + /* + * The following read-only structure members are implemented + * only if the PPS signal discipline is configured in the + * kernel. + */ + long ppsfreq; /* pps frequency (scaled ppm) (ro) */ + long jitter; /* pps jitter (us) (ro) */ + int shift; /* interval duration (s) (shift) (ro) */ + long stabil; /* pps stability (scaled ppm) (ro) */ + long jitcnt; /* jitter limit exceeded (ro) */ + long calcnt; /* calibration intervals (ro) */ + long errcnt; /* calibration errors (ro) */ + long stbcnt; /* stability limit exceeded (ro) */ +}; +.Ed +.Pp +The members of this struct have the following meanings when used as +argument for +.Fn ntp_adjtime : +.Bl -tag -width tolerance -compact +.It Fa modes +Defines what settings should be changed with the current +.Fn ntp_adjtime +call (write-only). +Bitwise OR of the following: +.Bl -tag -width MOD_TIMECONST -compact -offset indent +.It MOD_OFFSET +set time offset +.It MOD_FREQUENCY +set frequency offset +.It MOD_MAXERROR +set maximum time error +.It MOD_ESTERROR +set estimated time error +.It MOD_STATUS +set clock status bits +.It MOD_TIMECONST +set PLL time constant +.It MOD_CLKA +set clock A +.It MOD_CLKB +set clock B +.El +.It Fa offset +Time offset (in microseconds), used by the PLL/FLL to adjust the +system time in small increments (read-write). +.It Fa freq +Frequency offset (scaled ppm) (read-write). +.It Fa maxerror +Maximum error (in microseconds). +Initialized by an +.Fn ntp_adjtime +call, and increased by the kernel once each second to reflect the maximum +error bound growth (read-write). +.It Fa esterror +Estimated error (in microseconds). +Set and read by +.Fn ntp_adjtime , +but unused by the kernel (read-write). +.It Fa status +System clock status bits (read-write). +Bitwise OR of the following: +.Bl -tag -width STA_PPSJITTER -compact -offset indent +.It STA_PLL +Enable PLL updates (read-write). +.It STA_PPSFREQ +Enable PPS freq discipline (read-write). +.It STA_PPSTIME +Enable PPS time discipline (read-write). +.It STA_FLL +Select frequency-lock mode (read-write). +.It STA_INS +Insert leap (read-write). +.It STA_DEL +Delete leap (read-write). +.It STA_UNSYNC +Clock unsynchronized (read-write). +.It STA_FREQHOLD +Hold frequency (read-write). +.It STA_PPSSIGNAL +PPS signal present (read-only). +.It STA_PPSJITTER +PPS signal jitter exceeded (read-only). +.It STA_PPSWANDER +PPS signal wander exceeded (read-only). +.It STA_PPSERROR +PPS signal calibration error (read-only). +.It STA_CLOCKERR +Clock hardware fault (read-only). +.El +.It Fa constant +PLL time constant, determines the bandwidth, or +.Dq stiffness , +of the PLL (read-write). +.It Fa precision +Clock precision (in microseconds). +In most cases the same as the kernel tick variable (see +.Xr hz 9 ) . +If a precision clock counter or external time-keeping signal is available, +it could be much lower (and depend on the state of the signal) +(read-only). +.It Fa tolerance +Maximum frequency error, or tolerance of the CPU clock oscillator (scaled +ppm). +Ordinarily a property of the architecture, but could change under +the influence of external time-keeping signals (read-only). +.It Fa ppsfreq +PPS frequency offset produced by the frequency median filter (scaled +ppm) (read-only). +.It Fa jitter +PPS jitter measured by the time median filter in microseconds +(read-only). +.It Fa shift +Logarithm to base 2 of the interval duration in seconds (PPS, +read-only). +.It Fa stabil +PPS stability (scaled ppm); dispersion (wander) measured by the +frequency median filter (read-only). +.It Fa jitcnt +Number of seconds that have been discarded because the jitter measured +by the time median filter exceeded the limit +.Em MAXTIME +(PPS, read-only). +.It Fa calcnt +Count of calibration intervals (PPS, read-only). +.It Fa errcnt +Number of calibration intervals that have been discarded because the +wander exceeded the limit +.Em MAXFREQ +or where the calibration interval jitter exceeded two ticks (PPS, +read-only). +.It Fa stbcnt +Number of calibration intervals that have been discarded because the +frequency wander exceeded the limit +.Em MAXFREQ Ns /4 +(PPS, read-only). +.El +After the +.Fn ntp_adjtime +call, the +.Va struct timex * +structure contains the current values of the corresponding variables. +.Pp +.Fn ntp_gettime +has as argument a +.Va struct ntptimeval * +with the following members: +.Bd -literal +struct ntptimeval { + struct timeval time; /* current time (ro) */ + long maxerror; /* maximum error (us) (ro) */ + long esterror; /* estimated error (us) (ro) */ +}; +.Ed +.Pp +These have the following meaning: +.Bl -tag -width tolerance -compact +.It Fa time +Current time (read-only). +.It Fa maxerror +Maximum error in microseconds (read-only). +.It Fa esterror +Estimated error in microseconds (read-only). +.El +.Sh RETURN VALUES +.Fn ntp_adjtime +and +.Fn ntp_gettime +return the current state of the clock on success, or any of the errors +of +.Xr copyin 9 +and +.Xr copyout 9 . +.Fn ntp_adjtime +may additionally return +.Er EPERM +if the user calling +.Fn ntp_adjtime +does not have sufficient permissions. +.Pp +Possible states of the clock are: +.Bl -tag -width TIME_ERROR -compact -offset indent +.It TIME_OK +Everything okay, no leap second warning. +.It TIME_INS +.Dq insert leap second +warning. +At the end of the day, a leap second will be inserted after 23:59:59. +.It TIME_DEL +.Dq delete leap second +warning. +At the end of the day, second 23:59:59 will be skipped. +.It TIME_OOP +Leap second in progress. +.It TIME_WAIT +Leap second has occurred within the last few seconds. +.It TIME_ERROR +Clock not synchronized. +.El +.Sh ERRORS +The +.Fn ntp_adjtime +system call may return +.Er EPERM +if the caller +does not have sufficient permissions. +.Sh SEE ALSO +.Xr options 4 , +.Xr ntpd 8 , +.Xr hardclock 9 , +.Xr hz 9 +.Bl -tag -width indent +.It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html +.It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm +.It Pa ftp://time.nist.gov/pub/leap-seconds.list +.El +.Sh BUGS +Take note that this +.Tn API +is extremely complex and stateful. +Users should not attempt modification without first +reviewing the +.Xr ntpd 8 +sources in depth. diff --git a/lib/libc/sys/numa_getaffinity.2 b/lib/libc/sys/numa_getaffinity.2 new file mode 100644 index 000000000000..efb78e988210 --- /dev/null +++ b/lib/libc/sys/numa_getaffinity.2 @@ -0,0 +1,197 @@ +.\" Copyright (c) 2008 Christian Brueffer +.\" Copyright (c) 2008 Jeffrey Roberson +.\" Copyright (c) 2015 Adrian Chadd +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 7, 2015 +.Dt NUMA_GETAFFINITY 2 +.Os +.Sh NAME +.Nm numa_getaffinity , +.Nm numa_setaffinity +.Nd manage NUMA affinity +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/numa.h +.Ft int +.Fn numa_getaffinity "cpuwhich_t which" "id_t id" "struct vm_domain_policy_entry *policy" +.Ft int +.Fn numa_setaffinity "cpuwhich_t which" "id_t id" "const struct vm_domain_policy_entry *policy" +.Sh DESCRIPTION +.Fn numa_getaffinity +and +.Fn numa_setaffinity +allow the manipulation of NUMA policies available to processes and threads. +These functions may manipulate NUMA policies that contain many processes +or affect only a single object. +.Pp +Valid values for the +.Fa which +argument are documented in +.Xr cpuset 2 . +These arguments specify which object set are used. +Only +.Dv CPU_WHICH_TID +and +.Dv CPU_WHICH_PID +can be manipulated. +.Pp +The +.Fa policy +entry contains a vm_domain_policy_entry with the following fields: +.Bd -literal +struct vm_domain_policy_entry { + vm_domain_policy_type_t policy; /* VM policy */ + int domain; /* VM domain, if applicable */ +} +.Ed +.Fa vm_domain_policy_type_t policy +is one these: +.Bl -tag -width VM_POLICY_NONE +.It Dv VM_POLICY_NONE +Reset the domain back to none. +Any parent object NUMA domain policy will apply. +The only valid value for +.Dv domain +is -1. +.It Dv VM_POLICY_ROUND_ROBIN +Select round-robin policy. +Pages will be allocated round-robin from each VM domain in order. +The only valid value for +.Dv domain +is -1. +.It Dv VM_POLICY_FIXED_DOMAIN +Select fixed-domain only policy. +Pages will be allocated from the given +.Dv domain +which must be set to a valid VM domain. +Pages will not be allocated from another domain if +.Dv domain +is out of free pages. +.It Dv VM_POLICY_FIXED_DOMAIN_ROUND_ROBIN +Select fixed-domain only policy. +Pages will be allocated from +.Dv domain +which must be set to a valid VM domain. +If page allocation fails, pages will be round-robin +allocated from another domain if +.Dv domain +is out of free pages. +.It Dv VM_POLICY_FIRST_TOUCH +Select first-touch policy. +Pages will be allocated from the NUMA domain which the thread +is currently scheduled upon. +Pages will not be allocated from another domain if the current domain +is out of free pages. +The only valid value for +.Dv domain +is -1. +.It Dv VM_POLICY_FIRST_TOUCH_ROUND_ROBIN +Select first-touch policy. +Pages will be allocated from the NUMA domain which the thread +is currently scheduled upon. +Pages will be allocated round-robin from another domain if the +current domain is out of free pages. +The only valid value for +.Dv domain +is -1. +.El +.Pp +Note that the VM might assign some pages from other domains. +For example, if an existing page allocation is covered by a superpage +allocation. +.Pp +.Fn numa_getaffinity +retrieves the +NUMA policy from the object specified by +.Fa which +and +.Fa id +and stores it in the space provided by +.Fa policy . +.Pp +.Fn numa_setaffinity +attempts to set the NUMA policy for the object specified by +.Fa which +and +.Fa id +to the policy in +.Fa policy . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Va errno +can contain these error codes: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa level +or +.Fa which +argument was not a valid value. +.It Bq Er EINVAL +The +.Fa policy +argument specified when calling +.Fn numa_setaffinity +did not contain a valid policy. +.It Bq Er EFAULT +The policy pointer passed was invalid. +.It Bq Er ESRCH +The object specified by the +.Fa id +and +.Fa which +arguments could not be found. +.It Bq Er ERANGE +The +.Fa domain +in the given policy +was out of the range of possible VM domains available. +.It Bq Er EPERM +The calling process did not have the credentials required to complete the +operation. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr numactl 1 , +.Xr cpuset 2 , +.Xr cpuset_getaffinity 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setaffinity 2 , +.Xr cpuset_setid 2 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr numa 4 +.Sh HISTORY +The +.Nm +family of system calls first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An Adrian Chadd Aq Mt adrian@FreeBSD.org diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 new file mode 100644 index 000000000000..c1701188b49a --- /dev/null +++ b/lib/libc/sys/open.2 @@ -0,0 +1,532 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)open.2 8.2 (Berkeley) 11/16/93 +.\" $FreeBSD$ +.\" +.Dd November 22, 2016 +.Dt OPEN 2 +.Os +.Sh NAME +.Nm open , openat +.Nd open or create a file for reading, writing or executing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn open "const char *path" "int flags" "..." +.Ft int +.Fn openat "int fd" "const char *path" "int flags" "..." +.Sh DESCRIPTION +The file name specified by +.Fa path +is opened +for either execution or reading and/or writing as specified by the +argument +.Fa flags +and the file descriptor returned to the calling process. +The +.Fa flags +argument may indicate the file is to be +created if it does not exist (by specifying the +.Dv O_CREAT +flag). +In this case +.Fn open +and +.Fn openat +require an additional argument +.Fa "mode_t mode" , +and the file is created with mode +.Fa mode +as described in +.Xr chmod 2 +and modified by the process' umask value (see +.Xr umask 2 ) . +.Pp +The +.Fn openat +function is equivalent to the +.Fn open +function except in the case where the +.Fa path +specifies a relative path. +In this case the file to be opened is determined relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +The +.Fa flag +parameter and the optional fourth parameter correspond exactly to +the parameters of +.Fn open . +If +.Fn openat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used +and the behavior is identical to a call to +.Fn open . +.Pp +In +.Xr capsicum 4 +capability mode, +.Fn open +is not permitted. +The +.Fa path +argument to +.Fn openat +must be strictly relative to a file descriptor +.Fa fd , +as defined in +.Pa sys/kern/vfs_lookup.c . +.Fa path +must not be an absolute path and must not contain ".." components. +Additionally, no symbolic link in +.Fa path +may contain ".." components either. +.Fa fd +must not be +.Dv AT_FDCWD . +.Pp +The flags specified are formed by +.Em or Ns 'ing +the following values +.Pp +.Bd -literal -offset indent -compact +O_RDONLY open for reading only +O_WRONLY open for writing only +O_RDWR open for reading and writing +O_EXEC open for execute only +O_NONBLOCK do not block on open +O_APPEND append on each write +O_CREAT create file if it does not exist +O_TRUNC truncate size to 0 +O_EXCL error if create and file exists +O_SHLOCK atomically obtain a shared lock +O_EXLOCK atomically obtain an exclusive lock +O_DIRECT eliminate or reduce cache effects +O_FSYNC synchronous writes +O_SYNC synchronous writes +O_NOFOLLOW do not follow symlinks +O_NOCTTY ignored +O_TTY_INIT ignored +O_DIRECTORY error if file is not a directory +O_CLOEXEC set FD_CLOEXEC upon open +.Ed +.Pp +Opening a file with +.Dv O_APPEND +set causes each write on the file +to be appended to the end. +If +.Dv O_TRUNC +is specified and the +file exists, the file is truncated to zero length. +If +.Dv O_EXCL +is set with +.Dv O_CREAT +and the file already +exists, +.Fn open +returns an error. +This may be used to +implement a simple exclusive access locking mechanism. +If +.Dv O_EXCL +is set and the last component of the pathname is +a symbolic link, +.Fn open +will fail even if the symbolic +link points to a non-existent name. +If the +.Dv O_NONBLOCK +flag is specified and the +.Fn open +system call would result +in the process being blocked for some reason (e.g., waiting for +carrier on a dialup line), +.Fn open +returns immediately. +The descriptor remains in non-blocking mode for subsequent operations. +.Pp +If +.Dv O_FSYNC +is used in the mask, all writes will +immediately be written to disk, +the kernel will not cache written data +and all writes on the descriptor will not return until +the data to be written completes. +.Pp +.Dv O_SYNC +is a synonym for +.Dv O_FSYNC +required by +.Tn POSIX . +.Pp +If +.Dv O_NOFOLLOW +is used in the mask and the target file passed to +.Fn open +is a symbolic link then the +.Fn open +will fail. +.Pp +When opening a file, a lock with +.Xr flock 2 +semantics can be obtained by setting +.Dv O_SHLOCK +for a shared lock, or +.Dv O_EXLOCK +for an exclusive lock. +If creating a file with +.Dv O_CREAT , +the request for the lock will never fail +(provided that the underlying file system supports locking). +.Pp +.Dv O_DIRECT +may be used to minimize or eliminate the cache effects of reading and writing. +The system will attempt to avoid caching the data you read or write. +If it cannot avoid caching the data, +it will minimize the impact the data has on the cache. +Use of this flag can drastically reduce performance if not used with care. +.Pp +.Dv O_NOCTTY +may be used to ensure the OS does not assign this file as the +controlling terminal when it opens a tty device. +This is the default on +.Fx , +but is present for +.Tn POSIX +compatibility. +The +.Fn open +system call will not assign controlling terminals on +.Fx . +.Pp +.Dv O_TTY_INIT +may be used to ensure the OS restores the terminal attributes when +initially opening a TTY. +This is the default on +.Fx , +but is present for +.Tn POSIX +compatibility. +The initial call to +.Fn open +on a TTY will always restore default terminal attributes on +.Fx . +.Pp +.Dv O_DIRECTORY +may be used to ensure the resulting file descriptor refers to a +directory. +This flag can be used to prevent applications with elevated privileges +from opening files which are even unsafe to open with +.Dv O_RDONLY , +such as device nodes. +.Pp +.Dv O_CLOEXEC +may be used to set +.Dv FD_CLOEXEC +flag for the newly returned file descriptor. +.Pp +If successful, +.Fn open +returns a non-negative integer, termed a file descriptor. +It returns \-1 on failure. +The file pointer used to mark the current position within the +file is set to the beginning of the file. +.Pp +If a sleeping open of a device node from +.Xr devfs 5 +is interrupted by a signal, the call always fails with +.Er EINTR , +even if the +.Dv SA_RESTART +flag is set for the signal. +A sleeping open of a fifo (see +.Xr mkfifo 2 ) +is restarted as normal. +.Pp +When a new file is created it is given the group of the directory +which contains it. +.Pp +Unless +.Dv O_CLOEXEC +flag was specified, +the new descriptor is set to remain open across +.Xr execve 2 +system calls; see +.Xr close 2 , +.Xr fcntl 2 +and +.Dv O_CLOEXEC +description. +.Pp +The system imposes a limit on the number of file descriptors +open simultaneously by one process. +The +.Xr getdtablesize 2 +system call returns the current system limit. +.Sh RETURN VALUES +If successful, +.Fn open +and +.Fn openat +return a non-negative integer, termed a file descriptor. +They return \-1 on failure, and set +.Va errno +to indicate the error. +.Sh ERRORS +The named file is opened unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +.Dv O_CREAT +is not set and the named file does not exist. +.It Bq Er ENOENT +A component of the path name that must exist does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The required permissions (for reading and/or writing) +are denied for the given flags. +.It Bq Er EACCES +.Dv O_TRUNC +is specified and write permission is denied. +.It Bq Er EACCES +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which it is to be created +does not permit writing. +.It Bq Er EPERM +.Dv O_CREAT +is specified, the file does not exist, and the directory in which it is to be +created has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The named file has its immutable flag set and the file is to be modified. +.It Bq Er EPERM +The named file has its append-only flag set, the file is to be modified, and +.Dv O_TRUNC +is specified or +.Dv O_APPEND +is not specified. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EISDIR +The named file is a directory, and the arguments specify +it is to be modified. +.It Bq Er EROFS +The named file resides on a read-only file system, +and the file is to be modified. +.It Bq Er EROFS +.Dv O_CREAT +is specified and the named file would reside on a read-only file system. +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EMLINK +.Dv O_NOFOLLOW +was specified and the target is a symbolic link. +.It Bq Er ENXIO +The named file is a character special or block +special file, and the device associated with this special file +does not exist. +.It Bq Er ENXIO +.Dv O_NONBLOCK +is set, the named file is a fifo, +.Dv O_WRONLY +is set, and no process has the file open for reading. +.It Bq Er EINTR +The +.Fn open +operation was interrupted by a signal. +.It Bq Er EOPNOTSUPP +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified but the underlying file system does not support locking. +.It Bq Er EOPNOTSUPP +The named file is a special file mounted through a file system that +does not support access to it (e.g.\& NFS). +.It Bq Er EWOULDBLOCK +.Dv O_NONBLOCK +and one of +.Dv O_SHLOCK +or +.Dv O_EXLOCK +is specified and the file is locked. +.It Bq Er ENOSPC +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which the entry for the new file is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +.Dv O_CREAT +is specified, +the file does not exist, +and there are no free inodes on the file system on which the +file is being created. +.It Bq Er EDQUOT +.Dv O_CREAT +is specified, +the file does not exist, +and the directory in which the entry for the new file +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +.Dv O_CREAT +is specified, +the file does not exist, +and the user's quota of inodes on the file system on +which the file is being created has been exhausted. +.It Bq Er EIO +An I/O error occurred while making the directory entry or +allocating the inode for +.Dv O_CREAT . +.It Bq Er ETXTBSY +The file is a pure procedure (shared text) file that is being +executed and the +.Fn open +system call requests write access. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +were specified and the file exists. +.It Bq Er EOPNOTSUPP +An attempt was made to open a socket (not currently implemented). +.It Bq Er EINVAL +An attempt was made to open a descriptor with an illegal combination +of +.Dv O_RDONLY , +.Dv O_WRONLY , +.Dv O_RDWR +and +.Dv O_EXEC . +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is +neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTDIR +.Dv O_DIRECTORY +is specified and the file is not a directory. +.It Bq Er ECAPMODE +.Dv AT_FDCWD +is specified and the process is in capability mode. +.It Bq Er ECAPMODE +.Fn open +was called and the process is in capability mode. +.It Bq Er ENOTCAPABLE +.Fa path +is an absolute path or contained "..". +.El +.Sh SEE ALSO +.Xr capsicum 4 , +.Xr chmod 2 , +.Xr close 2 , +.Xr dup 2 , +.Xr fexecve 2 , +.Xr fhopen 2 , +.Xr getdtablesize 2 , +.Xr getfh 2 , +.Xr lgetfh 2 , +.Xr lseek 2 , +.Xr read 2 , +.Xr umask 2 , +.Xr write 2 , +.Xr fopen 3 +.Sh HISTORY +The +.Fn open +function appeared in +.At v6 . +The +.Fn openat +function was introduced in +.Fx 8.0 . +.Sh STANDARDS +These functions are specified by +.St -p1003.1-2008 . +.Fx +sets +.Va errno +to +.Er EMLINK instead of +.Er ELOOP +as specified by +.Tn POSIX +when +.Dv O_NOFOLLOW +is set in flags and the final component of pathname is a symbolic link +to distinguish it from the case of too many symbolic link traversals +in one of its non-final components. +.Sh BUGS +The Open Group Extended API Set 2 specification requires that the test +for whether +.Fa fd +is searchable is based on whether +.Fa fd +is open for searching, not whether the underlying directory currently +permits searches. +The present implementation of the +.Fa openat +checks the current permissions of directory instead. diff --git a/lib/libc/sys/open.c b/lib/libc/sys/open.c new file mode 100644 index 000000000000..e0273c68a34c --- /dev/null +++ b/lib/libc/sys/open.c @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/fcntl.h> +#include <stdarg.h> +#include "libc_private.h" + +__weak_reference(__sys_open, __open); + +#pragma weak open +int +open(const char *path, int flags, ...) +{ + va_list ap; + int mode; + + if ((flags & O_CREAT) != 0) { + va_start(ap, flags); + mode = va_arg(ap, int); + va_end(ap); + } else { + mode = 0; + } + return (((int (*)(int, const char *, int, ...)) + __libc_interposing[INTERPOS_openat])(AT_FDCWD, path, flags, mode)); +} diff --git a/lib/libc/sys/openat.c b/lib/libc/sys/openat.c new file mode 100644 index 000000000000..1bd12ea2a8d8 --- /dev/null +++ b/lib/libc/sys/openat.c @@ -0,0 +1,62 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/fcntl.h> +#include <stdarg.h> +#include "libc_private.h" + +__weak_reference(__sys_openat, __openat); +__sym_compat(openat, __impl_openat, FBSD_1.1); +__weak_reference(openat, __impl_openat); +__sym_default(openat, openat, FBSD_1.2); + +#pragma weak openat +int +openat(int fd, const char *path, int flags, ...) +{ + va_list ap; + int mode; + + if ((flags & O_CREAT) != 0) { + va_start(ap, flags); + mode = va_arg(ap, int); + va_end(ap); + } else { + mode = 0; + } + return (((int (*)(int, const char *, int, ...)) + __libc_interposing[INTERPOS_openat])(fd, path, flags, mode)); +} diff --git a/lib/libc/sys/pathconf.2 b/lib/libc/sys/pathconf.2 new file mode 100644 index 000000000000..efa13387d651 --- /dev/null +++ b/lib/libc/sys/pathconf.2 @@ -0,0 +1,261 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)pathconf.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd July 7, 2009 +.Dt PATHCONF 2 +.Os +.Sh NAME +.Nm pathconf , +.Nm lpathconf , +.Nm fpathconf +.Nd get configurable pathname variables +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft long +.Fn pathconf "const char *path" "int name" +.Ft long +.Fn lpathconf "const char *path" "int name" +.Ft long +.Fn fpathconf "int fd" "int name" +.Sh DESCRIPTION +The +.Fn pathconf , +.Fn lpathconf +and +.Fn fpathconf +system calls provide a method for applications to determine the current +value of a configurable system limit or option variable associated +with a pathname or file descriptor. +.Pp +For +.Fn pathconf +and +.Fn lpathconf , +the +.Fa path +argument is the name of a file or directory. +For +.Fn fpathconf , +the +.Fa fd +argument is an open file descriptor. +The +.Fa name +argument specifies the system variable to be queried. +Symbolic constants for each name value are found in the include file +.Li <unistd.h> . +.Pp +The +.Fn lpathconf +system call is like +.Fn pathconf +except in the case where the named file is a symbolic link, +in which case +.Fn lpathconf +returns information about the link, +while +.Fn pathconf +returns information about the file the link references. +.Pp +The available values are as follows: +.Bl -tag -width 6n +.It Li _PC_LINK_MAX +The maximum file link count. +.It Li _PC_MAX_CANON +The maximum number of bytes in terminal canonical input line. +.It Li _PC_MAX_INPUT +The minimum maximum number of bytes for which space is available in +a terminal input queue. +.It Li _PC_NAME_MAX +The maximum number of bytes in a file name. +.It Li _PC_PATH_MAX +The maximum number of bytes in a pathname. +.It Li _PC_PIPE_BUF +The maximum number of bytes which will be written atomically to a pipe. +.It Li _PC_CHOWN_RESTRICTED +Return 1 if appropriate privilege is required for the +.Xr chown 2 +system call, otherwise 0. +.St -p1003.1-2001 +requires appropriate privilege in all cases, but this behavior was optional +in prior editions of the standard. +.It Li _PC_NO_TRUNC +Return greater than zero if attempts to use pathname components longer than +.Brq Dv NAME_MAX +will result in an +.Bq Er ENAMETOOLONG +error; otherwise, such components will be truncated to +.Brq Dv NAME_MAX . +.St -p1003.1-2001 +requires the error in all cases, but this behavior was optional in prior +editions of the standard, and some +.No non- Ns Tn POSIX Ns -compliant +file systems do not support this behavior. +.It Li _PC_VDISABLE +Returns the terminal character disabling value. +.It Li _PC_ASYNC_IO +Return 1 if asynchronous I/O is supported, otherwise 0. +.It Li _PC_PRIO_IO +Returns 1 if prioritised I/O is supported for this file, +otherwise 0. +.It Li _PC_SYNC_IO +Returns 1 if synchronised I/O is supported for this file, otherwise 0. +.It Li _PC_ALLOC_SIZE_MIN +Minimum number of bytes of storage allocated for any portion of a file. +.It Li _PC_FILESIZEBITS +Number of bits needed to represent the maximum file size. +.It Li _PC_REC_INCR_XFER_SIZE +Recommended increment for file transfer sizes between +.Dv _PC_REC_MIN_XFER_SIZE +and +.Dv _PC_REC_MAX_XFER_SIZE . +.It Li _PC_REC_MAX_XFER_SIZE +Maximum recommended file transfer size. +.It Li _PC_REC_MIN_XFER_SIZE +Minimum recommended file transfer size. +.It Li _PC_REC_XFER_ALIGN +Recommended file transfer buffer alignment. +.It Li _PC_SYMLINK_MAX +Maximum number of bytes in a symbolic link. +.It Li _PC_ACL_EXTENDED +Returns 1 if an Access Control List (ACL) can be set on the specified +file, otherwise 0. +.It Li _PC_ACL_NFS4 +Returns 1 if an NFSv4 ACLs can be set on the specified +file, otherwise 0. +.It Li _PC_ACL_PATH_MAX +Maximum number of ACL entries per file. +.It Li _PC_CAP_PRESENT +Returns 1 if a capability state can be set on the specified file, +otherwise 0. +.It Li _PC_INF_PRESENT +Returns 1 if an information label can be set on the specified file, +otherwise 0. +.It Li _PC_MAC_PRESENT +Returns 1 if a Mandatory Access Control (MAC) label can be set on the +specified file, otherwise 0. +.It Li _PC_MIN_HOLE_SIZE +If a file system supports the reporting of holes (see +.Xr lseek 2 ) , +.Fn pathconf +and +.Fn fpathconf +return a positive number that represents the minimum hole size returned in +bytes. +The offsets of holes returned will be aligned to this same value. +A special value of 1 is returned if the file system does not specify the minimum +hole size but still reports holes. +.El +.Sh RETURN VALUES +If the call to +.Fn pathconf +or +.Fn fpathconf +is not successful, \-1 is returned and +.Va errno +is set appropriately. +Otherwise, if the variable is associated with functionality that does +not have a limit in the system, \-1 is returned and +.Va errno +is not modified. +Otherwise, the current variable value is returned. +.Sh ERRORS +If any of the following conditions occur, the +.Fn pathconf +and +.Fn fpathconf +system calls shall return -1 and set +.Va errno +to the corresponding value. +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa name +argument is invalid. +.It Bq Er EINVAL +The implementation does not support an association of the variable +name with the associated file. +.El +.Pp +The +.Fn pathconf +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Brq Dv NAME_MAX +characters (but see +.Dv _PC_NO_TRUNC +above), +or an entire path name exceeded +.Brq Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Pp +The +.Fn fpathconf +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr lseek 2 , +.Xr sysctl 3 +.Sh HISTORY +The +.Fn pathconf +and +.Fn fpathconf +system calls first appeared in +.Bx 4.4 . +The +.Fn lpathconf +system call first appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/pdfork.2 b/lib/libc/sys/pdfork.2 new file mode 100644 index 000000000000..5f1a86e3b961 --- /dev/null +++ b/lib/libc/sys/pdfork.2 @@ -0,0 +1,202 @@ +.\" +.\" Copyright (c) 2009-2010, 2012-2013 Robert N. M. Watson +.\" All rights reserved. +.\" +.\" This software was developed at the University of Cambridge Computer +.\" Laboratory with support from a grant from Google, Inc. +.\" +.\" This software was developed by SRI International and the University of +.\" Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237) +.\" ("CTSRD"), as part of the DARPA CRASH research programme. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 8, 2016 +.Dt PDFORK 2 +.Os +.Sh NAME +.Nm pdfork , +.Nm pdgetpid , +.Nm pdkill , +.Nm pdwait4 +.Nd System calls to manage process descriptors +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/procdesc.h +.Ft pid_t +.Fn pdfork "int *fdp" "int flags" +.Ft int +.Fn pdgetpid "int fd" "pid_t *pidp" +.Ft int +.Fn pdkill "int fd" "int signum" +.Ft int +.Fn pdwait4 "int fd" "int *status" "int options" "struct rusage *rusage" +.Sh DESCRIPTION +Process descriptors are special file descriptors that represent processes, +and are created using +.Fn pdfork , +a variant of +.Xr fork 2 , +which, if successful, returns a process descriptor in the integer pointed to +by +.Fa fdp . +Processes created via +.Fn pdfork +will not cause +.Dv SIGCHLD +on termination. +.Fn pdfork +can accept the flags: +.Bl -tag -width ".Dv PD_DAEMON" +.It Dv PD_DAEMON +Instead of the default terminate-on-close behaviour, allow the process to +live until it is explicitly killed with +.Xr kill 2 . +.Pp +This option is not permitted in +.Xr capsicum 4 +capability mode (see +.Xr cap_enter 2 ) . +.El +.Bl -tag -width ".Dv PD_DAEMON" +.It Dv PD_CLOEXEC +Set close-on-exec on process descriptor. +.El +.Pp +.Fn pdgetpid +queries the process ID (PID) in the process descriptor +.Fa fd . +.Pp +.Fn pdkill +is functionally identical to +.Xr kill 2 , +except that it accepts a process descriptor, +.Fa fd , +rather than a PID. +.Pp +.Fn pdwait4 +behaves identically to +.Xr wait4 2 , +but operates with respect to a process descriptor argument rather than a PID. +.Pp +The following system calls also have effects specific to process descriptors: +.Pp +.Xr fstat 2 +queries status of a process descriptor; currently only the +.Fa st_mode , +.Fa st_birthtime , +.Fa st_atime , +.Fa st_ctime +and +.Fa st_mtime +fields are defined. +If the owner read, write, and execute bits are set then the +process represented by the process descriptor is still alive. +.Pp +.Xr poll 2 +and +.Xr select 2 +allow waiting for process state transitions; currently only +.Dv POLLHUP +is defined, and will be raised when the process dies. +Process state transitions can also be monitored using +.Xr kqueue 2 +filter +.Dv EVFILT_PROCDESC ; +currently only +.Dv NOTE_EXIT +is implemented. +.Pp +.Xr close 2 +will close the process descriptor unless +.Dv PD_DAEMON +is set; if the process is still alive and this is +the last reference to the process descriptor, the process will be terminated +with the signal +.Dv SIGKILL . +.Sh RETURN VALUES +.Fn pdfork +returns a PID, 0 or -1, as +.Xr fork 2 +does. +.Pp +.Fn pdgetpid +and +.Fn pdkill +return 0 on success and -1 on failure. +.Pp +.Fn pdwait4 +returns a PID on success and -1 on failure. +.Sh ERRORS +These functions may return the same error numbers as their PID-based equivalents +(e.g. +.Fn pdfork +may return the same error numbers as +.Xr fork 2 ) , +with the following additions: +.Bl -tag -width Er +.It Bq Er EINVAL +The signal number given to +.Fn pdkill +is invalid. +.It Bq Er ENOTCAPABLE +The process descriptor being operated on has insufficient rights (e.g. +.Dv CAP_PDKILL +for +.Fn pdkill ) . +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr fork 2 , +.Xr fstat 2 , +.Xr kill 2 , +.Xr poll 2 , +.Xr wait4 2 , +.Xr capsicum 4 , +.Xr procdesc 4 +.Sh HISTORY +The +.Fn pdfork , +.Fn pdgetpid , +.Fn pdkill +and +.Fn pdwait4 +system calls first appeared in +.Fx 9.0 . +.Pp +Support for process descriptors mode was developed as part of the +.Tn TrustedBSD +Project. +.Sh AUTHORS +.An -nosplit +These functions and the capability facility were created by +.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org +and +.An Jonathan Anderson Aq Mt jonathan@FreeBSD.org +at the University of Cambridge Computer Laboratory with support from a grant +from Google, Inc. +.Sh BUGS +.Fn pdwait4 +has not yet been implemented. diff --git a/lib/libc/sys/pipe.2 b/lib/libc/sys/pipe.2 new file mode 100644 index 000000000000..63e013a014b0 --- /dev/null +++ b/lib/libc/sys/pipe.2 @@ -0,0 +1,178 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)pipe.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd July 20, 2016 +.Dt PIPE 2 +.Os +.Sh NAME +.Nm pipe , +.Nm pipe2 +.Nd create descriptor pair for interprocess communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn pipe "int fildes[2]" +.Ft int +.Fn pipe2 "int fildes[2]" "int flags" +.Sh DESCRIPTION +The +.Fn pipe +function +creates a +.Em pipe , +which is an object allowing +bidirectional data flow, +and allocates a pair of file descriptors. +.Pp +The +.Fn pipe2 +system call allows control over the attributes of the file descriptors +via the +.Fa flags +argument. +Values for +.Fa flags +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width ".Dv O_NONBLOCK" +.It Dv O_CLOEXEC +Set the close-on-exec flag for the new file descriptors. +.It Dv O_NONBLOCK +Set the non-blocking flag for the ends of the pipe. +.El +.Pp +If the +.Fa flags +argument is 0, the behavior is identical to a call to +.Fn pipe . +.Pp +By convention, the first descriptor is normally used as the +.Em read end +of the pipe, +and the second is normally the +.Em write end , +so that data written to +.Fa fildes[1] +appears on (i.e., can be read from) +.Fa fildes[0] . +This allows the output of one program to be +sent +to another program: +the source's standard output is set up to be +the write end of the pipe, +and the sink's standard input is set up to be +the read end of the pipe. +The pipe itself persists until all its associated descriptors are +closed. +.Pp +A pipe that has had an end closed is considered +.Em widowed . +Writing on such a pipe causes the writing process to receive +a +.Dv SIGPIPE +signal. +Widowing a pipe is the only way to deliver end-of-file to a reader: +after the reader consumes any buffered data, reading a widowed pipe +returns a zero count. +.Pp +The bidirectional nature of this implementation of pipes is not +portable to older systems, so it is recommended to use the convention +for using the endpoints in the traditional manner when using a +pipe in one direction. +.Sh IMPLEMENTATION NOTES +The +.Fn pipe +function calls the +.Fn pipe2 +system call. +As a result, system call traces such as those captured by +.Xr dtrace 1 +or +.Xr ktrace 1 +will show calls to +.Fn pipe2 . +.Sh RETURN VALUES +.Rv -std pipe +.Sh ERRORS +The +.Fn pipe +and +.Fn pipe2 +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Ar fildes +argument points to an invalid memory location. +.It Bq Er EMFILE +Too many descriptors are active. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOMEM +Not enough kernel memory to establish a pipe. +.El +.Pp +The +.Fn pipe2 +system call will also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa flags +argument is invalid. +.El +.Sh SEE ALSO +.Xr sh 1 , +.Xr fork 2 , +.Xr read 2 , +.Xr socketpair 2 , +.Xr write 2 +.Sh HISTORY +The +.Fn pipe +function appeared in +.At v3 . +.Pp +Bidirectional pipes were first used on +.At V.4 . +.Pp +The +.Fn pipe2 +function appeared in +.Fx 10.0 . +.Pp +The +.Fn pipe +function became a wrapper around +.Fn pipe2 +in +.Fx 11.0 . diff --git a/lib/libc/sys/pipe.c b/lib/libc/sys/pipe.c new file mode 100644 index 000000000000..f5ade0eb914b --- /dev/null +++ b/lib/libc/sys/pipe.c @@ -0,0 +1,47 @@ +/*- + * Copyright (c) 2016 SRI International + * All rights reserved. + * + * This software was developed by SRI International and the University of + * Cambridge Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 + * ("CTSRD"), as part of the DARPA CRASH research programme. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * + * $FreeBSD$ + */ + +#include <sys/cdefs.h> + +#include <unistd.h> + +__weak_reference(__sys_pipe, pipe); +__weak_reference(__sys_pipe, _pipe); + +extern int __sys_pipe2(int fildes[2], int flags); + +int +__sys_pipe(int fildes[2]) +{ + + return (__sys_pipe2(fildes, 0)); +} diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 new file mode 100644 index 000000000000..dbd641f50bf7 --- /dev/null +++ b/lib/libc/sys/poll.2 @@ -0,0 +1,273 @@ +.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Charles M. Hannum. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 13, 2014 +.Dt POLL 2 +.Os +.Sh NAME +.Nm poll +.Nd synchronous I/O multiplexing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In poll.h +.Ft int +.Fn poll "struct pollfd fds[]" "nfds_t nfds" "int timeout" +.Ft int +.Fo ppoll +.Fa "struct pollfd fds[]" +.Fa "nfds_t nfds" +.Fa "const struct timespec * restrict timeout" +.Fa "const sigset_t * restrict newsigmask" +.Fc +.Sh DESCRIPTION +The +.Fn poll +system call +examines a set of file descriptors to see if some of them are ready for +I/O. +The +.Fa fds +argument is a pointer to an array of pollfd structures as defined in +.In poll.h +(shown below). +The +.Fa nfds +argument determines the size of the +.Fa fds +array. +.Bd -literal +struct pollfd { + int fd; /* file descriptor */ + short events; /* events to look for */ + short revents; /* events returned */ +}; +.Ed +.Pp +The fields of +.Fa struct pollfd +are as follows: +.Bl -tag -width XXXrevents +.It fd +File descriptor to poll. +If fd is equal to -1 then +.Fa revents +is cleared (set to zero), and that pollfd is not checked. +.It events +Events to poll for. +(See below.) +.It revents +Events which may occur. +(See below.) +.El +.Pp +The event bitmasks in +.Fa events +and +.Fa revents +have the following bits: +.Bl -tag -width XXXPOLLWRNORM +.It POLLIN +Data other than high priority data may be read without blocking. +.It POLLRDNORM +Normal data may be read without blocking. +.It POLLRDBAND +Data with a non-zero priority may be read without blocking. +.It POLLPRI +High priority data may be read without blocking. +.It POLLOUT +.It POLLWRNORM +Normal data may be written without blocking. +.It POLLWRBAND +Data with a non-zero priority may be written without blocking. +.It POLLERR +An exceptional condition has occurred on the device or socket. +This +flag is always checked, even if not present in the +.Fa events +bitmask. +.It POLLHUP +The device or socket has been disconnected. +This flag is always +checked, even if not present in the +.Fa events +bitmask. +Note that +POLLHUP +and +POLLOUT +should never be present in the +.Fa revents +bitmask at the same time. +.It POLLNVAL +The file descriptor is not open. +This flag is always checked, even +if not present in the +.Fa events +bitmask. +.El +.Pp +If +.Fa timeout +is neither zero nor INFTIM (-1), it specifies a maximum interval to +wait for any file descriptor to become ready, in milliseconds. +If +.Fa timeout +is INFTIM (-1), the poll blocks indefinitely. +If +.Fa timeout +is zero, then +.Fn poll +will return without blocking. +.Pp +The +.Fn ppoll +system call, unlike +.Fn poll , +is used to safely wait until either a set of file descriptors becomes +ready or until a signal is caught. +The +.Fa fds +and +.Fa nfds +arguments are identical to the analogous arguments of +.Fn poll . +The +.Fa timeout +argument in +.Fn ppoll +points to a +.Vt "const struct timespec" +which is defined in +.In sys/timespec.h +(shown below) rather than the +.Vt "int timeout" +used by +.Fn poll . +A null pointer may be passed to indicate that +.Fn ppoll +should wait indefinitely. +Finally, +.Fa newsigmask +specifies a signal mask which is set while waiting for input. +When +.Fn ppoll +returns, the original signal mask is restored. +.Bd -literal +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* and nanoseconds */ +}; +.Ed +.Sh RETURN VALUES +The +.Fn poll +system call +returns the number of descriptors that are ready for I/O, or -1 if an +error occurred. +If the time limit expires, +.Fn poll +returns 0. +If +.Fn poll +returns with an error, +including one due to an interrupted system call, +the +.Fa fds +array will be unmodified. +.Sh COMPATIBILITY +This implementation differs from the historical one in that a given +file descriptor may not cause +.Fn poll +to return with an error. +In cases where this would have happened in +the historical implementation (e.g.\& trying to poll a +.Xr revoke 2 Ns ed +descriptor), this implementation instead copies the +.Fa events +bitmask to the +.Fa revents +bitmask. +Attempting to perform I/O on this descriptor will then +return an error. +This behaviour is believed to be more useful. +.Sh ERRORS +An error return from +.Fn poll +indicates: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa fds +argument +points outside the process's allocated address space. +.It Bq Er EINTR +A signal was delivered before the time limit expired and +before any of the selected events occurred. +.It Bq Er EINVAL +The specified time limit is invalid. One of its components is negative or too large. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr kqueue 2 , +.Xr pselect 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr write 2 +.Sh STANDARDS +The +.Fn poll +function conforms to +.St -p1003.1-2001 . +The +.Fn ppoll +is not specified by POSIX. +.Sh HISTORY +The +.Fn poll +function appeared in +.At V . +This manual page and the core of the implementation was taken from +.Nx . +The +.Fn ppoll +function first appeared in +.Fx 11.0 +.Sh BUGS +The distinction between some of the fields in the +.Fa events +and +.Fa revents +bitmasks is really not useful without STREAMS. +The fields are +defined for compatibility with existing software. diff --git a/lib/libc/sys/poll.c b/lib/libc/sys/poll.c new file mode 100644 index 000000000000..43c17d2f65ce --- /dev/null +++ b/lib/libc/sys/poll.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/poll.h> +#include "libc_private.h" + +__weak_reference(__sys_poll, __poll); + +#pragma weak poll +int +poll(struct pollfd pfd[], nfds_t nfds, int timeout) +{ + + return (((int (*)(struct pollfd *, nfds_t, int)) + __libc_interposing[INTERPOS_poll])(pfd, nfds, timeout)); +} diff --git a/lib/libc/sys/posix_fadvise.2 b/lib/libc/sys/posix_fadvise.2 new file mode 100644 index 000000000000..641bc9bff5ef --- /dev/null +++ b/lib/libc/sys/posix_fadvise.2 @@ -0,0 +1,139 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)madvise.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd October 3, 2015 +.Dt POSIX_FADVISE 2 +.Os +.Sh NAME +.Nm posix_fadvise +.Nd give advice about use of file data +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn posix_fadvise "int fd" "off_t offset" "off_t len" "int advice" +.Sh DESCRIPTION +The +.Fn posix_fadvise +system call +allows a process to describe to the system its data access behavior for an +open file descriptor +.Fa fd . +The advice covers the data starting at offset +.Fa offset +and continuing for +.Fa len +bytes. +If +.Fa len +is zero, +all data from +.Fa offset +to the end of the file is covered. +.Pp +The behavior is specified by the +.Fa advice +parameter and may be one of: +.Bl -tag -width POSIX_FADV_SEQUENTIAL +.It Dv POSIX_FADV_NORMAL +Tells the system to revert to the default data access behavior. +.It Dv POSIX_FADV_RANDOM +Is a hint that file data will be accessed randomly, +and prefetching is likely not advantageous. +.It Dv POSIX_FADV_SEQUENTIAL +Tells the system that file data will be accessed sequentially. +This currently does nothing as the default behavior uses heuristics to +detect sequential behavior. +.It Dv POSIX_FADV_WILLNEED +Tells the system that the specified data will be accessed in the near future. +The system may initiate an asynchronous read of the data if it is not already +present in memory. +.It Dv POSIX_FADV_DONTNEED +Tells the system that the specified data will not be accessed in the near +future. +The system may decrease the in-memory priority of clean data within the +specified range and future access to this data may require a read operation. +.It Dv POSIX_FADV_NOREUSE +Tells the system that the specified data will only be accessed once and +then not reused. +The system may decrease the in-memory priority of data once it has been +read or written. +Future access to this data may require a read operation. +.El +.Sh RETURN VALUES +If successful, +.Fn posix_fadvise +returns zero. +It returns an error on failure, without setting +.Va errno . +.Sh ERRORS +Possible failure conditions: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +The +.Fa advice +argument is not valid. +.It Bq Er EINVAL +The +.Fa offset +or +.Fa len +arguments are negative, +or +.Fa offset ++ +.Fa len +is greater than the maximum file size. +.It Bq Er ENODEV +The +.Fa fd +argument does not refer to a regular file. +.It Bq Er ESPIPE +The +.Fa fd +argument is associated with a pipe or FIFO. +.El +.Sh SEE ALSO +.Xr madvise 2 +.Sh STANDARDS +The +.Fn posix_fadvise +interface conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn posix_fadvise +system call first appeared in +.Fx 9.1 . diff --git a/lib/libc/sys/posix_fallocate.2 b/lib/libc/sys/posix_fallocate.2 new file mode 100644 index 000000000000..4c92d9b9c2be --- /dev/null +++ b/lib/libc/sys/posix_fallocate.2 @@ -0,0 +1,144 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)open.2 8.2 (Berkeley) 11/16/93 +.\" $FreeBSD$ +.\" +.Dd January 23, 2014 +.Dt POSIX_FALLOCATE 2 +.Os +.Sh NAME +.Nm posix_fallocate +.Nd pre-allocate storage for a range in a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn posix_fallocate "int fd" "off_t offset" "off_t len" +.Sh DESCRIPTION +Required storage for the range +.Fa offset +to +.Fa offset + +.Fa len +in the file referenced by +.Fa fd +is guaranteed to be allocated upon successful return. +That is, if +.Fn posix_fallocate +returns successfully, subsequent writes to the specified file data +will not fail due to lack of free space on the file system storage +media. +Any existing file data in the specified range is unmodified. +If +.Fa offset + +.Fa len +is beyond the current file size, then +.Fn posix_fallocate +will adjust the file size to +.Fa offset + +.Fa len . +Otherwise, the file size will not be changed. +.Pp +Space allocated by +.Fn posix_fallocate +will be freed by a successful call to +.Xr creat 2 +or +.Xr open 2 +that truncates the size of the file. +Space allocated via +.Fn posix_fallocate +may be freed by a successful call to +.Xr ftruncate 2 +that reduces the file size to a size smaller than +.Fa offset + +.Fa len . +.Sh RETURN VALUES +If successful, +.Fn posix_fallocate +returns zero. +It returns an error on failure, without setting +.Va errno . +.Sh ERRORS +Possible failure conditions: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EBADF +The +.Fa fd +argument references a file that was opened without write permission. +.It Bq Er EFBIG +The value of +.Fa offset + +.Fa len +is greater than the maximum file size. +.It Bq Er EINTR +A signal was caught during execution. +.It Bq Er EINVAL +The +.Fa len +argument was less than or equal to zero or the +.Fa offset +argument was less than zero. +.It Bq Er EIO +An I/O error occurred while reading from or writing to a file system. +.It Bq Er ENODEV +The +.Fa fd +argument does not refer to a regular file. +.It Bq Er ENOSPC +There is insufficient free space remaining on the file system storage +media. +.It Bq Er ESPIPE +The +.Fa fd +argument is associated with a pipe or FIFO. +.El +.Sh SEE ALSO +.Xr creat 2 , +.Xr ftruncate 2 , +.Xr open 2 , +.Xr unlink 2 +.Sh STANDARDS +The +.Fn posix_fallocate +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +The +.Fn posix_fallocate +function appeared in +.Fx 9.0 . +.Sh AUTHORS +.Fn posix_fallocate +and this manual page were initially written by +.An Matthew Fleming Aq Mt mdf@FreeBSD.org . diff --git a/lib/libc/sys/posix_openpt.2 b/lib/libc/sys/posix_openpt.2 new file mode 100644 index 000000000000..01a372931af8 --- /dev/null +++ b/lib/libc/sys/posix_openpt.2 @@ -0,0 +1,140 @@ +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Portions of this software were developed under sponsorship from Snow +.\" B.V., the Netherlands. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.\" $FreeBSD$ +.\" +.Dd September 21, 2016 +.Dt POSIX_OPENPT 2 +.Os +.Sh NAME +.Nm posix_openpt +.Nd "open a pseudo-terminal device" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.In stdlib.h +.Ft int +.Fn posix_openpt "int oflag" +.Sh DESCRIPTION +The +.Fn posix_openpt +function allocates a new pseudo-terminal and establishes a connection +with its master device. +A slave device shall be created in +.Pa /dev/pts . +After the pseudo-terminal has been allocated, the slave device should +have the proper permissions before it can be used (see +.Xr grantpt 3 ) . +The name of the slave device can be determined by calling +.Xr ptsname 3 . +.Pp +The file status flags and file access modes of the open file description +shall be set according to the value of +.Fa oflag . +Values for +.Fa oflag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width ".Dv O_CLOEXEC" +.It Dv O_RDWR +Open for reading and writing. +.It Dv O_NOCTTY +If set +.Fn posix_openpt +shall not cause the terminal device to become the controlling terminal +for the process. +.It Dv O_CLOEXEC +Set the close-on-exec flag for the new file descriptor. +.El +.Pp +The +.Fn posix_openpt +function shall fail when +.Fa oflag +contains other values. +.Sh RETURN VALUES +Upon successful completion, the +.Fn posix_openpt +function shall allocate a new pseudo-terminal device and return a +non-negative integer representing a file descriptor, which is connected +to its master device. +Otherwise, -1 shall be returned and errno set to indicate the error. +.Sh ERRORS +The +.Fn posix_openpt +function shall fail if: +.Bl -tag -width Er +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EINVAL +The value of +.Fa oflag +is not valid. +.It Bq Er EAGAIN +Out of pseudo-terminal resources. +.El +.Sh SEE ALSO +.Xr ptsname 3 , +.Xr pts 4 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn posix_openpt +function conforms to +.St -p1003.1-2001 . +The ability to use +.Dv O_CLOEXEC +is an extension to the standard. +.Sh HISTORY +The +.Fn posix_openpt +function appeared in +.Fx 5.0 . +In +.Fx 8.0 , +this function was changed to a system call. +.Sh NOTES +The flag +.Dv O_NOCTTY +is included for compatibility; in +.Fx , +opening a terminal does not cause it to become a process's controlling +terminal. +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org diff --git a/lib/libc/sys/ppoll.c b/lib/libc/sys/ppoll.c new file mode 100644 index 000000000000..f62fd19cafe1 --- /dev/null +++ b/lib/libc/sys/ppoll.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2015 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/poll.h> +#include "libc_private.h" + +__weak_reference(__sys_ppoll, __ppoll); + +#pragma weak ppoll +int +ppoll(struct pollfd pfd[], nfds_t nfds, const struct timespec *__restrict + timeout, const sigset_t *__restrict newsigmask) +{ + + return (((int (*)(struct pollfd *, nfds_t, const struct timespec *, + const sigset_t *)) __libc_interposing[INTERPOS_ppoll])(pfd, nfds, + timeout, newsigmask)); +} diff --git a/lib/libc/sys/procctl.2 b/lib/libc/sys/procctl.2 new file mode 100644 index 000000000000..da73fb04f93d --- /dev/null +++ b/lib/libc/sys/procctl.2 @@ -0,0 +1,505 @@ +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin <jhb@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" Portions of this documentation were written by Konstantin Belousov +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 27, 2016 +.Dt PROCCTL 2 +.Os +.Sh NAME +.Nm procctl +.Nd control processes +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/procctl.h +.Ft int +.Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg" +.Sh DESCRIPTION +The +.Fn procctl +system call provides for control over processes. +The +.Fa idtype +and +.Fa id +arguments specify the set of processes to control. +If multiple processes match the identifier, +.Nm +will make a +.Dq best effort +to control as many of the selected processes as possible. +An error is only returned if no selected processes successfully complete +the request. +The following identifier types are supported: +.Bl -tag -width "Dv P_PGID" +.It Dv P_PID +Control the process with the process ID +.Fa id . +.It Dv P_PGID +Control processes belonging to the process group with the ID +.Fa id . +.El +.Pp +The control request to perform is specified by the +.Fa cmd +argument. +The following commands are supported: +.Bl -tag -width "Dv PROC_TRAPCAP_STATUS" +.It Dv PROC_SPROTECT +Set process protection state. +This is used to mark a process as protected from being killed if the system +exhausts the available memory and swap. +The +.Fa arg +parameter must point to an integer containing an operation and zero or more +optional flags. +The following operations are supported: +.Bl -tag -width "Dv PPROT_CLEAR" +.It Dv PPROT_SET +Mark the selected processes as protected. +.It Dv PPROT_CLEAR +Clear the protected state of selected processes. +.El +.Pp +The following optional flags are supported: +.Bl -tag -width "Dv PPROT_DESCEND" +.It Dv PPROT_DESCEND +Apply the requested operation to all child processes of each selected process +in addition to each selected process. +.It Dv PPROT_INHERIT +When used with +.Dv PPROT_SET , +mark all future child processes of each selected process as protected. +Future child processes will also mark all of their future child processes. +.El +.It Dv PROC_REAP_ACQUIRE +Acquires the reaper status for the current process. +Reaper status means that children orphaned by the reaper's descendants +that were forked after the acquisition of reaper status are reparented to the +reaper process. +After system initialization, +.Xr init 8 +is the default reaper. +.It Dv PROC_REAP_RELEASE +Release the reaper state for the current process. +The reaper of the current process becomes the new reaper of the +current process's descendants. +.It Dv PROC_REAP_STATUS +Provides information about the reaper of the specified process, +or the process itself when it is a reaper. +The +.Fa data +argument must point to a +.Vt procctl_reaper_status +structure which is filled in by the syscall on successful return. +.Bd -literal +struct procctl_reaper_status { + u_int rs_flags; + u_int rs_children; + u_int rs_descendants; + pid_t rs_reaper; + pid_t rs_pid; +}; +.Ed +The +.Fa rs_flags +may have the following flags returned: +.Bl -tag -width "Dv REAPER_STATUS_REALINIT" +.It Dv REAPER_STATUS_OWNED +The specified process has acquired reaper status and has not +released it. +When the flag is returned, the specified process +.Fa id , +pid, identifies the reaper, otherwise the +.Fa rs_reaper +field of the structure is set to the pid of the reaper +for the specified process id. +.It Dv REAPER_STATUS_REALINIT +The specified process is the root of the reaper tree, i.e., +.Xr init 8 . +.El +.Pp +The +.Fa rs_children +field returns the number of children of the reaper among the descendants. +It is possible to have a child whose reaper is not the specified process, +since the reaper for any existing children is not reset on the +.Dv PROC_REAP_ACQUIRE +operation. +The +.Fa rs_descendants +field returns the total number of descendants of the reaper(s), +not counting descendants of the reaper in the subtree. +The +.Fa rs_reaper +field returns the reaper pid. +The +.Fa rs_pid +returns the pid of one reaper child if there are any descendants. +.It Dv PROC_REAP_GETPIDS +Queries the list of descendants of the reaper of the specified process. +The request takes a pointer to a +.Vt procctl_reaper_pids +structure in the +.Fa data +parameter. +.Bd -literal +struct procctl_reaper_pids { + u_int rp_count; + struct procctl_reaper_pidinfo *rp_pids; +}; +.Ed +When called, the +.Fa rp_pids +field must point to an array of +.Vt procctl_reaper_pidinfo +structures, to be filled in on return, +and the +.Fa rp_count +field must specify the size of the array, +into which no more than +.Fa rp_count +elements will be filled in by the kernel. +.Pp +The +.Vt "struct procctl_reaper_pidinfo" +structure provides some information about one of the reaper's descendants. +Note that for a descendant that is not a child, it may be incorrectly +identified because of a race in which the original child process exited +and the exited process's pid was reused for an unrelated process. +.Bd -literal +struct procctl_reaper_pidinfo { + pid_t pi_pid; + pid_t pi_subtree; + u_int pi_flags; +}; +.Ed +The +.Fa pi_pid +field is the process id of the descendant. +The +.Fa pi_subtree +field provides the pid of the child of the reaper, which is the (grand-)parent +of the process. +The +.Fa pi_flags +field returns the following flags, further describing the descendant: +.Bl -tag -width "Dv REAPER_PIDINFO_VALID" +.It Dv REAPER_PIDINFO_VALID +Set to indicate that the +.Vt procctl_reaper_pidinfo +structure was filled in by the kernel. +Zero-filling the +.Fa rp_pids +array and testing the +.Dv REAPER_PIDINFO_VALID +flag allows the caller to detect the end +of the returned array. +.It Dv REAPER_PIDINFO_CHILD +The +.Fa pi_pid +field identifies the direct child of the reaper. +.El +.It Dv PROC_REAP_KILL +Request to deliver a signal to some subset of the descendants of the reaper. +The +.Fa data +parameter must point to a +.Vt procctl_reaper_kill +structure, which is used both for parameters and status return. +.Bd -literal +struct procctl_reaper_kill { + int rk_sig; + u_int rk_flags; + pid_t rk_subtree; + u_int rk_killed; + pid_t rk_fpid; +}; +.Ed +The +.Fa rk_sig +field specifies the signal to be delivered. +Zero is not a valid signal number, unlike for +.Xr kill 2 . +The +.Fa rk_flags +field further directs the operation. +It is or-ed from the following flags: +.Bl -tag -width "Dv REAPER_KILL_CHILDREN" +.It Dv REAPER_KILL_CHILDREN +Deliver the specified signal only to direct children of the reaper. +.It Dv REAPER_KILL_SUBTREE +Deliver the specified signal only to descendants that were forked by +the direct child with pid specified in the +.Fa rk_subtree +field. +.El +If neither the +.Dv REAPER_KILL_CHILDREN +nor the +.Dv REAPER_KILL_SUBTREE +flags are specified, all current descendants of the reaper are signalled. +.Pp +If a signal was delivered to any process, the return value from the request +is zero. +In this case, the +.Fa rk_killed +field identifies the number of processes signalled. +The +.Fa rk_fpid +field is set to the pid of the first process for which signal +delivery failed, e.g., due to permission problems. +If no such process exists, the +.Fa rk_fpid +field is set to -1. +.It Dv PROC_TRACE_CTL +Enable or disable tracing of the specified process(es), according to the +value of the integer argument. +Tracing includes attachment to the process using the +.Xr ptrace 2 +and +.Xr ktrace 2 , +debugging sysctls, +.Xr hwpmc 4 , +.Xr dtrace 1 , +and core dumping. +Possible values for the +.Fa data +argument are: +.Bl -tag -width "Dv PROC_TRACE_CTL_DISABLE_EXEC" +.It Dv PROC_TRACE_CTL_ENABLE +Enable tracing, after it was disabled by +.Dv PROC_TRACE_CTL_DISABLE . +Only allowed for self. +.It Dv PROC_TRACE_CTL_DISABLE +Disable tracing for the specified process. +Tracing is re-enabled when the process changes the executing +program with the +.Xr execve 2 +syscall. +A child inherits the trace settings from the parent on +.Xr fork 2 . +.It Dv PROC_TRACE_CTL_DISABLE_EXEC +Same as +.Dv PROC_TRACE_CTL_DISABLE , +but the setting persists for the process even after +.Xr execve 2 . +.El +.It Dv PROC_TRACE_STATUS +Returns the current tracing status for the specified process in +the integer variable pointed to by +.Fa data . +If tracing is disabled, +.Fa data +is set to -1. +If tracing is enabled, but no debugger is attached by the +.Xr ptrace 2 +syscall, +.Fa data +is set to 0. +If a debugger is attached, +.Fa data +is set to the pid of the debugger process. +.It Dv PROC_TRAPCAP_CTL +Controls the capability mode sandbox actions for the specified +sandboxed processes, +on a return from any syscall which gives either a +.Er ENOTCAPABLE +or +.Er ECAPMODE +error. +If the control is enabled, such errors from the syscalls cause +delivery of the synchronous +.Dv SIGTRAP +signal to the thread immediately before returning from the syscalls. +.Pp +Possible values for the +.Fa data +argument are: +.Bl -tag -width "Dv PROC_TRAPCAP_CTL_DISABLE" +.It Dv PROC_TRAPCAP_CTL_ENABLE +Enable the +.Dv SIGTRAP +signal delivery on capability mode access violations. +The enabled mode is inherited by the children of the process, +and is kept after +.Xr fexecve 2 +calls. +.It Dv PROC_TRAPCAP_CTL_DISABLE +Disable the signal delivery on capability mode access violations. +Note that the global sysctl +.Dv kern.trap_enocap +might still cause the signal to be delivered. +See +.Xr capsicum 4 . +.El +.Pp +On signal delivery, the +.Va si_errno +member of the +.Fa siginfo +signal handler parameter is set to the syscall error value, +and the +.Va si_code +member is set to +.Dv TRAP_CAP . +.Pp +See +.Xr capsicum 4 +for more information about the capability mode. +.It Dv PROC_TRAPCAP_STATUS +Return the current status of signalling capability mode access +violations for the specified process. +The integer value pointed to by the +.Fa data +argument is set to the +.Dv PROC_TRAPCAP_CTL_ENABLE +value if the process control enables signal delivery, and to +.Dv PROC_TRAPCAP_CTL_DISABLE +otherwise. +.Pp +See the note about sysctl +.Dv kern.trap_enocap +above, which gives independent global control of signal delivery. +.El +.Sh NOTES +Disabling tracing on a process should not be considered a security +feature, as it is bypassable both by the kernel and privileged processes, +and via other system mechanisms. +As such, it should not be utilized to reliably protect cryptographic +keying material or other confidential data. +.Sh RETURN VALUES +If an error occurs, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn procctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa arg +parameter points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Fa cmd +argument specifies an unsupported command. +.Pp +The +.Fa idtype +argument specifies an unsupported identifier type. +.It Bq Er EPERM +The calling process does not have permission to perform the requested +operation on any of the selected processes. +.It Bq Er ESRCH +No processes matched the requested +.Fa idtype +and +.Fa id . +.It Bq Er EINVAL +An invalid operation or flag was passed in +.Fa arg +for a +.Dv PROC_SPROTECT +command. +.It Bq Er EPERM +The +.Fa idtype +argument is not equal to +.Dv P_PID , +or +.Fa id +is not equal to the pid of the calling process, for +.Dv PROC_REAP_ACQUIRE +or +.Dv PROC_REAP_RELEASE +requests. +.It Bq Er EINVAL +Invalid or undefined flags were passed to a +.Dv PROC_REAP_KILL +request. +.It Bq Er EINVAL +An invalid or zero signal number was requested for a +.Dv PROC_REAP_KILL +request. +.It Bq Er EINVAL +The +.Dv PROC_REAP_RELEASE +request was issued by the +.Xr init 8 +process. +.It Bq Er EBUSY +The +.Dv PROC_REAP_ACQUIRE +request was issued by a process that had already acquired reaper status +and has not yet released it. +.It Bq Er EBUSY +The +.Dv PROC_TRACE_CTL +request was issued for a process already being traced. +.It Bq Er EPERM +The +.Dv PROC_TRACE_CTL +request to re-enable tracing of the process +.Po Dv PROC_TRACE_CTL_ENABLE Pc , +or to disable persistence of +.Dv PROC_TRACE_CTL_DISABLE +on +.Xr execve 2 +was issued for a non-current process. +.It Bq Er EINVAL +The value of the integer +.Fa data +parameter for the +.Dv PROC_TRACE_CTL +or +.Dv PROC_TRAPCAP_CTL +request is invalid. +.El +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr cap_enter 2, +.Xr kill 2 , +.Xr ktrace 2 , +.Xr ptrace 2 , +.Xr wait 2 , +.Xr capsicum 4 , +.Xr hwpmc 4 , +.Xr init 8 +.Sh HISTORY +The +.Fn procctl +function appeared in +.Fx 10.0 . +The reaper facility is based on a similar feature of Linux and +DragonflyBSD, and first appeared in +.Fx 10.2 . diff --git a/lib/libc/sys/profil.2 b/lib/libc/sys/profil.2 new file mode 100644 index 000000000000..444d3c3373c3 --- /dev/null +++ b/lib/libc/sys/profil.2 @@ -0,0 +1,122 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Donn Seeley of BSDI. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)profil.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt PROFIL 2 +.Os +.Sh NAME +.Nm profil +.Nd control process profiling +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn profil "char *samples" "size_t size" "vm_offset_t offset" "int scale" +.Sh DESCRIPTION +The +.Fn profil +system call enables or disables +program counter profiling of the current process. +If profiling is enabled, +then at every profiling clock tick, +the kernel updates an appropriate count in the +.Fa samples +buffer. +The frequency of the profiling clock is recorded +in the header in the profiling output file. +.Pp +The buffer +.Fa samples +contains +.Fa size +bytes and is divided into +a series of 16-bit bins. +Each bin counts the number of times the program counter +was in a particular address range in the process +when a profiling clock tick occurred while profiling was enabled. +For a given program counter address, +the number of the corresponding bin is given +by the relation: +.Bd -literal -offset indent +[(pc - offset) / 2] * scale / 65536 +.Ed +.Pp +The +.Fa offset +argument is the lowest address at which +the kernel takes program counter samples. +The +.Fa scale +argument ranges from 1 to 65536 and +can be used to change the span of the bins. +A scale of 65536 maps each bin to 2 bytes of address range; +a scale of 32768 gives 4 bytes, 16384 gives 8 bytes and so on. +Intermediate values provide approximate intermediate ranges. +A +.Fa scale +value of 0 disables profiling. +.Sh RETURN VALUES +.Rv -std profil +.Sh FILES +.Bl -tag -width /usr/lib/gcrt0.o -compact +.It Pa /usr/lib/gcrt0.o +profiling C run-time startup file +.It Pa gmon.out +conventional name for profiling output file +.El +.Sh ERRORS +The following error may be reported: +.Bl -tag -width Er +.It Bq Er EFAULT +The buffer +.Fa samples +contains an invalid address. +.El +.Sh SEE ALSO +.Xr gprof 1 +.Sh HISTORY +The +.Fn profil +function appeared in +.At v7 . +.Sh BUGS +This routine should be named +.Fn profile . +.Pp +The +.Fa samples +argument should really be a vector of type +.Fa "unsigned short" . +.Pp +The format of the gmon.out file is undocumented. diff --git a/lib/libc/sys/pselect.2 b/lib/libc/sys/pselect.2 new file mode 100644 index 000000000000..6221c473e7d7 --- /dev/null +++ b/lib/libc/sys/pselect.2 @@ -0,0 +1,123 @@ +.\" +.\" Copyright 2002 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 16, 2013 +.Dt PSELECT 2 +.Os +.Sh NAME +.Nm pselect +.Nd synchronous I/O multiplexing a la POSIX.1g +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/select.h +.Ft int +.Fo pselect +.Fa "int nfds" +.Fa "fd_set * restrict readfds" +.Fa "fd_set * restrict writefds" +.Fa "fd_set * restrict exceptfds" +.Fa "const struct timespec * restrict timeout" +.Fa "const sigset_t * restrict newsigmask" +.Fc +.Sh DESCRIPTION +The +.Fn pselect +function was introduced by +.St -p1003.1g-2000 +as a slightly stronger version of +.Xr select 2 . +The +.Fa nfds , readfds , writefds , +and +.Fa exceptfds +arguments are all identical to the analogous arguments of +.Fn select . +The +.Fa timeout +argument in +.Fn pselect +points to a +.Vt "const struct timespec" +rather than the (modifiable) +.Vt "struct timeval" +used by +.Fn select ; +as in +.Fn select , +a null pointer may be passed to indicate that +.Fn pselect +should wait indefinitely. +Finally, +.Fa newsigmask +specifies a signal mask which is set while waiting for input. +When +.Fn pselect +returns, the original signal mask is restored. +.Pp +See +.Xr select 2 +for a more detailed discussion of the semantics of this interface, and +for macros used to manipulate the +.Vt "fd_set" +data type. +.Sh RETURN VALUES +The +.Fn pselect +function returns the same values and under the same conditions as +.Fn select . +.Sh ERRORS +The +.Fn pselect +function may fail for any of the reasons documented for +.Xr select 2 +and (if a signal mask is provided) +.Xr sigprocmask 2 . +.Sh SEE ALSO +.Xr kqueue 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 +.Sh STANDARDS +The +.Fn pselect +function conforms to +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn pselect +function first appeared in +.Fx 5.0 . +.Sh AUTHORS +The first implementation of +.Fn pselect +function and this manual page were written by +.An Garrett Wollman Aq Mt wollman@FreeBSD.org . diff --git a/lib/libc/sys/pselect.c b/lib/libc/sys/pselect.c new file mode 100644 index 000000000000..a623a7d5cc74 --- /dev/null +++ b/lib/libc/sys/pselect.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/select.h> +#include "libc_private.h" + +__weak_reference(__sys_pselect, __pselect); + +#pragma weak pselect +int +pselect(int n, fd_set *rs, fd_set *ws, fd_set *es, const struct timespec *t, + const sigset_t *s) +{ + + return (((int (*)(int, fd_set *, fd_set *, fd_set *, + const struct timespec *, const sigset_t *)) + __libc_interposing[INTERPOS_pselect])(n, rs, ws, es, t, s)); +} diff --git a/lib/libc/sys/ptrace.2 b/lib/libc/sys/ptrace.2 new file mode 100644 index 000000000000..2cd26ee3465a --- /dev/null +++ b/lib/libc/sys/ptrace.2 @@ -0,0 +1,1066 @@ +.\" $FreeBSD$ +.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ +.\" +.\" This file is in the public domain. +.Dd August 29, 2016 +.Dt PTRACE 2 +.Os +.Sh NAME +.Nm ptrace +.Nd process tracing and debugging +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ptrace.h +.Ft int +.Fn ptrace "int request" "pid_t pid" "caddr_t addr" "int data" +.Sh DESCRIPTION +The +.Fn ptrace +system call +provides tracing and debugging facilities. +It allows one process +(the +.Em tracing +process) +to control another +(the +.Em traced +process). +The tracing process must first attach to the traced process, and then +issue a series of +.Fn ptrace +system calls to control the execution of the process, as well as access +process memory and register state. +For the duration of the tracing session, the traced process will be +.Dq re-parented , +with its parent process ID (and resulting behavior) +changed to the tracing process. +It is permissible for a tracing process to attach to more than one +other process at a time. +When the tracing process has completed its work, it must detach the +traced process; if a tracing process exits without first detaching all +processes it has attached, those processes will be killed. +.Pp +Most of the time, the traced process runs normally, but when it +receives a signal +(see +.Xr sigaction 2 ) , +it stops. +The tracing process is expected to notice this via +.Xr wait 2 +or the delivery of a +.Dv SIGCHLD +signal, examine the state of the stopped process, and cause it to +terminate or continue as appropriate. +The signal may be a normal process signal, generated as a result of +traced process behavior, or use of the +.Xr kill 2 +system call; alternatively, it may be generated by the tracing facility +as a result of attaching, stepping by the tracing +process, +or an event in the traced process. +The tracing process may choose to intercept the signal, using it to +observe process behavior (such as +.Dv SIGTRAP ) , +or forward the signal to the process if appropriate. +The +.Fn ptrace +system call +is the mechanism by which all this happens. +.Pp +A traced process may report additional signal stops corresponding to +events in the traced process. +These additional signal stops are reported as +.Dv SIGTRAP +or +.Dv SIGSTOP +signals. +The tracing process can use the +.Dv PT_LWPINFO +request to determine which events are associated with a +.Dv SIGTRAP +or +.Dv SIGSTOP +signal. +Note that multiple events may be associated with a single signal. +For example, events indicated by the +.Dv PL_FLAG_BORN , +.Dv PL_FLAG_FORKED , +and +.Dv PL_FLAG_EXEC +flags are also reported as a system call exit event +.Pq Dv PL_FLAG_SCX . +The signal stop for a new child process enabled via +.Dv PTRACE_FORK +will report a +.Dv SIGSTOP +signal. +All other additional signal stops use +.Dv SIGTRAP . +.Pp +Each traced process has a tracing event mask. +An event in the traced process only reports a +signal stop if the corresponding flag is set in the tracing event mask. +The current set of tracing event flags include: +.Bl -tag -width "Dv PTRACE_SYSCALL" +.It Dv PTRACE_EXEC +Report a stop for a successful invocation of +.Xr execve 2 . +This event is indicated by the +.Dv PL_FLAG_EXEC +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SCE +Report a stop on each system call entry. +This event is indicated by the +.Dv PL_FLAG_SCE +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SCX +Report a stop on each system call exit. +This event is indicated by the +.Dv PL_FLAG_SCX +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PTRACE_SYSCALL +Report stops for both system call entry and exit. +.It Dv PTRACE_FORK +This event flag controls tracing for new child processes of a traced process. +.Pp +When this event flag is enabled, +new child processes will enable tracing and stop before executing their +first instruction. +The new child process will include the +.Dv PL_FLAG_CHILD +flag in the +.Va pl_flags +member of +.Vt "struct ptrace_lwpinfo" . +The traced process will report a stop that includes the +.Dv PL_FLAG_FORKED +flag. +The process ID of the new child process will also be present in the +.Va pl_child_pid +member of +.Vt "struct ptrace_lwpinfo" . +If the new child process was created via +.Xr vfork 2 , +the traced process's stop will also include the +.Dv PL_FLAG_VFORKED +flag. +Note that new child processes will be attached with the default +tracing event mask; +they do not inherit the event mask of the traced process. +.Pp +When this event flag is not enabled, +new child processes will execute without tracing enabled. +.It Dv PTRACE_LWP +This event flag controls tracing of LWP +.Pq kernel thread +creation and destruction. +When this event is enabled, +new LWPs will stop and report an event with +.Dv PL_FLAG_BORN +set before executing their first instruction, +and exiting LWPs will stop and report an event with +.Dv PL_FLAG_EXITED +set before completing their termination. +.Pp +Note that new processes do not report an event for the creation of their +initial thread, +and exiting processes do not report an event for the termination of the +last thread. +.It Dv PTRACE_VFORK +Report a stop event when a parent process resumes after a +.Xr vfork 2 . +.Pp +When a thread in the traced process creates a new child process via +.Xr vfork 2 , +the stop that reports +.Dv PL_FLAG_FORKED +and +.Dv PL_FLAG_SCX +occurs just after the child process is created, +but before the thread waits for the child process to stop sharing process +memory. +If a debugger is not tracing the new child process, +it must ensure that no breakpoints are enabled in the shared process +memory before detaching from the new child process. +This means that no breakpoints are enabled in the parent process either. +.Pp +The +.Dv PTRACE_VFORK +flag enables a new stop that indicates when the new child process stops +sharing the process memory of the parent process. +A debugger can reinsert breakpoints in the parent process and resume it +in response to this event. +This event is indicated by setting the +.Dv PL_FLAG_VFORK_DONE +flag. +.El +.Pp +The default tracing event mask when attaching to a process via +.Dv PT_ATTACH , +.Dv PT_TRACE_ME , +or +.Dv PTRACE_FORK +includes only +.Dv PTRACE_EXEC +events. +All other event flags are disabled. +.Pp +The +.Fa request +argument specifies what operation is being performed; the meaning of +the rest of the arguments depends on the operation, but except for one +special case noted below, all +.Fn ptrace +calls are made by the tracing process, and the +.Fa pid +argument specifies the process ID of the traced process +or a corresponding thread ID. +The +.Fa request +argument +can be: +.Bl -tag -width "Dv PT_GET_EVENT_MASK" +.It Dv PT_TRACE_ME +This request is the only one used by the traced process; it declares +that the process expects to be traced by its parent. +All the other arguments are ignored. +(If the parent process does not expect to trace the child, it will +probably be rather confused by the results; once the traced process +stops, it cannot be made to continue except via +.Fn ptrace . ) +When a process has used this request and calls +.Xr execve 2 +or any of the routines built on it +(such as +.Xr execv 3 ) , +it will stop before executing the first instruction of the new image. +Also, any setuid or setgid bits on the executable being executed will +be ignored. +If the child was created by +.Xr vfork 2 +system call or +.Xr rfork 2 +call with the +.Dv RFMEM +flag specified, the debugging events are reported to the parent +only after the +.Xr execve 2 +is executed. +.It Dv PT_READ_I , Dv PT_READ_D +These requests read a single +.Vt int +of data from the traced process's address space. +Traditionally, +.Fn ptrace +has allowed for machines with distinct address spaces for instruction +and data, which is why there are two requests: conceptually, +.Dv PT_READ_I +reads from the instruction space and +.Dv PT_READ_D +reads from the data space. +In the current +.Fx +implementation, these two requests are completely identical. +The +.Fa addr +argument specifies the address +(in the traced process's virtual address space) +at which the read is to be done. +This address does not have to meet any alignment constraints. +The value read is returned as the return value from +.Fn ptrace . +.It Dv PT_WRITE_I , Dv PT_WRITE_D +These requests parallel +.Dv PT_READ_I +and +.Dv PT_READ_D , +except that they write rather than read. +The +.Fa data +argument supplies the value to be written. +.It Dv PT_IO +This request allows reading and writing arbitrary amounts of data in +the traced process's address space. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_io_desc" , +which is defined as follows: +.Bd -literal +struct ptrace_io_desc { + int piod_op; /* I/O operation */ + void *piod_offs; /* child offset */ + void *piod_addr; /* parent offset */ + size_t piod_len; /* request length */ +}; + +/* + * Operations in piod_op. + */ +#define PIOD_READ_D 1 /* Read from D space */ +#define PIOD_WRITE_D 2 /* Write to D space */ +#define PIOD_READ_I 3 /* Read from I space */ +#define PIOD_WRITE_I 4 /* Write to I space */ +.Ed +.Pp +The +.Fa data +argument is ignored. +The actual number of bytes read or written is stored in +.Va piod_len +upon return. +.It Dv PT_CONTINUE +The traced process continues execution. +The +.Fa addr +argument +is an address specifying the place where execution is to be resumed +(a new value for the program counter), +or +.Po Vt caddr_t Pc Ns 1 +to indicate that execution is to pick up where it left off. +The +.Fa data +argument +provides a signal number to be delivered to the traced process as it +resumes execution, or 0 if no signal is to be sent. +.It Dv PT_STEP +The traced process is single stepped one instruction. +The +.Fa addr +argument +should be passed +.Po Vt caddr_t Pc Ns 1 . +The +.Fa data +argument +provides a signal number to be delivered to the traced process as it +resumes execution, or 0 if no signal is to be sent. +.It Dv PT_KILL +The traced process terminates, as if +.Dv PT_CONTINUE +had been used with +.Dv SIGKILL +given as the signal to be delivered. +.It Dv PT_ATTACH +This request allows a process to gain control of an otherwise +unrelated process and begin tracing it. +It does not need any cooperation from the to-be-traced process. +In +this case, +.Fa pid +specifies the process ID of the to-be-traced process, and the other +two arguments are ignored. +This request requires that the target process must have the same real +UID as the tracing process, and that it must not be executing a setuid +or setgid executable. +(If the tracing process is running as root, these restrictions do not +apply.) +The tracing process will see the newly-traced process stop and may +then control it as if it had been traced all along. +.It Dv PT_DETACH +This request is like PT_CONTINUE, except that it does not allow +specifying an alternate place to continue execution, and after it +succeeds, the traced process is no longer traced and continues +execution normally. +.It Dv PT_GETREGS +This request reads the traced process's machine registers into the +.Do +.Vt "struct reg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETREGS +This request is the converse of +.Dv PT_GETREGS ; +it loads the traced process's machine registers from the +.Do +.Vt "struct reg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETFPREGS +This request reads the traced process's floating-point registers into +the +.Do +.Vt "struct fpreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETFPREGS +This request is the converse of +.Dv PT_GETFPREGS ; +it loads the traced process's floating-point registers from the +.Do +.Vt "struct fpreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_GETDBREGS +This request reads the traced process's debug registers into +the +.Do +.Vt "struct dbreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_SETDBREGS +This request is the converse of +.Dv PT_GETDBREGS ; +it loads the traced process's debug registers from the +.Do +.Vt "struct dbreg" +.Dc +(defined in +.In machine/reg.h ) +pointed to by +.Fa addr . +.It Dv PT_LWPINFO +This request can be used to obtain information about the kernel thread, +also known as light-weight process, that caused the traced process to stop. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_lwpinfo" , +which is defined as follows: +.Bd -literal +struct ptrace_lwpinfo { + lwpid_t pl_lwpid; + int pl_event; + int pl_flags; + sigset_t pl_sigmask; + sigset_t pl_siglist; + siginfo_t pl_siginfo; + char pl_tdname[MAXCOMLEN + 1]; + pid_t pl_child_pid; + u_int pl_syscall_code; + u_int pl_syscall_narg; +}; +.Ed +.Pp +The +.Fa data +argument is to be set to the size of the structure known to the caller. +This allows the structure to grow without affecting older programs. +.Pp +The fields in the +.Vt "struct ptrace_lwpinfo" +have the following meaning: +.Bl -tag -width indent -compact +.It Va pl_lwpid +LWP id of the thread +.It Va pl_event +Event that caused the stop. +Currently defined events are: +.Bl -tag -width "Dv PL_EVENT_SIGNAL" -compact +.It Dv PL_EVENT_NONE +No reason given +.It Dv PL_EVENT_SIGNAL +Thread stopped due to the pending signal +.El +.It Va pl_flags +Flags that specify additional details about observed stop. +Currently defined flags are: +.Bl -tag -width indent -compact +.It Dv PL_FLAG_SCE +The thread stopped due to system call entry, right after the kernel is entered. +The debugger may examine syscall arguments that are stored in memory and +registers according to the ABI of the current process, and modify them, +if needed. +.It Dv PL_FLAG_SCX +The thread is stopped immediately before syscall is returning to the usermode. +The debugger may examine system call return values in the ABI-defined registers +and/or memory. +.It Dv PL_FLAG_EXEC +When +.Dv PL_FLAG_SCX +is set, this flag may be additionally specified to inform that the +program being executed by debuggee process has been changed by successful +execution of a system call from the +.Fn execve 2 +family. +.It Dv PL_FLAG_SI +Indicates that +.Va pl_siginfo +member of +.Vt "struct ptrace_lwpinfo" +contains valid information. +.It Dv PL_FLAG_FORKED +Indicates that the process is returning from a call to +.Fn fork 2 +that created a new child process. +The process identifier of the new process is available in the +.Va pl_child_pid +member of +.Vt "struct ptrace_lwpinfo" . +.It Dv PL_FLAG_CHILD +The flag is set for first event reported from a new child which is +automatically attached when +.Dv PTRACE_FORK +is enabled. +.It Dv PL_FLAG_BORN +This flag is set for the first event reported from a new LWP when +.Dv PTRACE_LWP +is enabled. +It is reported along with +.Dv PL_FLAG_SCX . +.It Dv PL_FLAG_EXITED +This flag is set for the last event reported by an exiting LWP when +.Dv PTRACE_LWP +is enabled. +Note that this event is not reported when the last LWP in a process exits. +The termination of the last thread is reported via a normal process exit +event. +.It Dv PL_FLAG_VFORKED +Indicates that the thread is returning from a call to +.Xr vfork 2 +that created a new child process. +This flag is set in addition to +.Dv PL_FLAG_FORKED . +.It Dv PL_FLAG_VFORK_DONE +Indicates that the thread has resumed after a child process created via +.Xr vfork 2 +has stopped sharing its address space with the traced process. +.El +.It Va pl_sigmask +The current signal mask of the LWP +.It Va pl_siglist +The current pending set of signals for the LWP. +Note that signals that are delivered to the process would not appear +on an LWP siglist until the thread is selected for delivery. +.It Va pl_siginfo +The siginfo that accompanies the signal pending. +Only valid for +.Dv PL_EVENT_SIGNAL +stop when +.Dv PL_FLAG_SI +is set in +.Va pl_flags . +.It Va pl_tdname +The name of the thread. +.It Va pl_child_pid +The process identifier of the new child process. +Only valid for a +.Dv PL_EVENT_SIGNAL +stop when +.Dv PL_FLAG_FORKED +is set in +.Va pl_flags . +.It Va pl_syscall_code +The ABI-specific identifier of the current system call. +Note that for indirect system calls this field reports the indirected +system call. +Only valid when +.Dv PL_FLAG_SCE +or +.Dv PL_FLAG_SCX +is set in +.Va pl_flags. +.It Va pl_syscall_narg +The number of arguments passed to the current system call not counting +the system call identifier. +Note that for indirect system calls this field reports the arguments +passed to the indirected system call. +Only valid when +.Dv PL_FLAG_SCE +or +.Dv PL_FLAG_SCX +is set in +.Va pl_flags. +.El +.It Dv PT_GETNUMLWPS +This request returns the number of kernel threads associated with the +traced process. +.It Dv PT_GETLWPLIST +This request can be used to get the current thread list. +A pointer to an array of type +.Vt lwpid_t +should be passed in +.Fa addr , +with the array size specified by +.Fa data . +The return value from +.Fn ptrace +is the count of array entries filled in. +.It Dv PT_SETSTEP +This request will turn on single stepping of the specified process. +.It Dv PT_CLEARSTEP +This request will turn off single stepping of the specified process. +.It Dv PT_SUSPEND +This request will suspend the specified thread. +.It Dv PT_RESUME +This request will resume the specified thread. +.It Dv PT_TO_SCE +This request will set the +.Dv PTRACE_SCE +event flag to trace all future system call entries and continue the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE. +.It Dv PT_TO_SCX +This request will set the +.Dv PTRACE_SCX +event flag to trace all future system call exits and continue the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE. +.It Dv PT_SYSCALL +This request will set the +.Dv PTRACE_SYSCALL +event flag to trace all future system call entries and exits and continue +the process. +The +.Fa addr +and +.Fa data +arguments are used the same as for +.Dv PT_CONTINUE. +.It Dv PT_FOLLOW_FORK +This request controls tracing for new child processes of a traced process. +If +.Fa data +is non-zero, +.Dv PTRACE_FORK +is set in the traced process's event tracing mask. +If +.Fa data +is zero, +.Dv PTRACE_FORK +is cleared from the traced process's event tracing mask. +.It Dv PT_LWP_EVENTS +This request controls tracing of LWP creation and destruction. +If +.Fa data +is non-zero, +.Dv PTRACE_LWP +is set in the traced process's event tracing mask. +If +.Fa data +is zero, +.Dv PTRACE_LWP +is cleared from the traced process's event tracing mask. +.It Dv PT_GET_EVENT_MASK +This request reads the traced process's event tracing mask into the +integer pointed to by +.Fa addr . +The size of the integer must be passed in +.Fa data . +.It Dv PT_SET_EVENT_MASK +This request sets the traced process's event tracing mask from the +integer pointed to by +.Fa addr . +The size of the integer must be passed in +.Fa data . +.It Dv PT_VM_TIMESTAMP +This request returns the generation number or timestamp of the memory map of +the traced process as the return value from +.Fn ptrace . +This provides a low-cost way for the tracing process to determine if the +VM map changed since the last time this request was made. +.It Dv PT_VM_ENTRY +This request is used to iterate over the entries of the VM map of the traced +process. +The +.Fa addr +argument specifies a pointer to a +.Vt "struct ptrace_vm_entry" , +which is defined as follows: +.Bd -literal +struct ptrace_vm_entry { + int pve_entry; + int pve_timestamp; + u_long pve_start; + u_long pve_end; + u_long pve_offset; + u_int pve_prot; + u_int pve_pathlen; + long pve_fileid; + uint32_t pve_fsid; + char *pve_path; +}; +.Ed +.Pp +The first entry is returned by setting +.Va pve_entry +to zero. +Subsequent entries are returned by leaving +.Va pve_entry +unmodified from the value returned by previous requests. +The +.Va pve_timestamp +field can be used to detect changes to the VM map while iterating over the +entries. +The tracing process can then take appropriate action, such as restarting. +By setting +.Va pve_pathlen +to a non-zero value on entry, the pathname of the backing object is returned +in the buffer pointed to by +.Va pve_path , +provided the entry is backed by a vnode. +The +.Va pve_pathlen +field is updated with the actual length of the pathname (including the +terminating null character). +The +.Va pve_offset +field is the offset within the backing object at which the range starts. +The range is located in the VM space at +.Va pve_start +and extends up to +.Va pve_end +(inclusive). +.Pp +The +.Fa data +argument is ignored. +.El +.Sh x86 MACHINE-SPECIFIC REQUESTS +.Bl -tag -width "Dv PT_GETXSTATE_INFO" +.It Dv PT_GETXMMREGS +Copy the XMM FPU state into the buffer pointed to by the +argument +.Fa addr . +The buffer has the same layout as the 32-bit save buffer for the +machine instruction +.Dv FXSAVE . +.Pp +This request is only valid for i386 programs, both on native 32-bit +systems and on amd64 kernels. +For 64-bit amd64 programs, the XMM state is reported as part of +the FPU state returned by the +.Dv PT_GETFPREGS +request. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETXMMREGS +Load the XMM FPU state for the thread from the buffer pointed to +by the argument +.Fa addr . +The buffer has the same layout as the 32-bit load buffer for the +machine instruction +.Dv FXRSTOR . +.Pp +As with +.Dv PT_GETXMMREGS, +this request is only valid for i386 programs. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_GETXSTATE_INFO +Report which XSAVE FPU extensions are supported by the CPU +and allowed in userspace programs. +The +.Fa addr +argument must point to a variable of type +.Vt struct ptrace_xstate_info , +which contains the information on the request return. +.Vt struct ptrace_xstate_info +is defined as follows: +.Bd -literal +struct ptrace_xstate_info { + uint64_t xsave_mask; + uint32_t xsave_len; +}; +.Ed +The +.Dv xsave_mask +field is a bitmask of the currently enabled extensions. +The meaning of the bits is defined in the Intel and AMD +processor documentation. +The +.Dv xsave_len +field reports the length of the XSAVE area for storing the hardware +state for currently enabled extensions in the format defined by the x86 +.Dv XSAVE +machine instruction. +.Pp +The +.Fa data +argument value must be equal to the size of the +.Vt struct ptrace_xstate_info . +.It Dv PT_GETXSTATE +Return the content of the XSAVE area for the thread. +The +.Fa addr +argument points to the buffer where the content is copied, and the +.Fa data +argument specifies the size of the buffer. +The kernel copies out as much content as allowed by the buffer size. +The buffer layout is specified by the layout of the save area for the +.Dv XSAVE +machine instruction. +.It Dv PT_SETXSTATE +Load the XSAVE state for the thread from the buffer specified by the +.Fa addr +pointer. +The buffer size is passed in the +.Fa data +argument. +The buffer must be at least as large as the +.Vt struct savefpu +(defined in +.Pa x86/fpu.h ) +to allow the complete x87 FPU and XMM state load. +It must not be larger than the XSAVE state length, as reported by the +.Dv xsave_len +field from the +.Vt struct ptrace_xstate_info +of the +.Dv PT_GETXSTATE_INFO +request. +Layout of the buffer is identical to the layout of the load area for the +.Dv XRSTOR +machine instruction. +.It Dv PT_GETFSBASE +Return the value of the base used when doing segmented +memory addressing using the %fs segment register. +The +.Fa addr +argument points to an +.Vt unsigned long +variable where the base value is stored. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_GETGSBASE +Like the +.Dv PT_GETFSBASE +request, but returns the base for the %gs segment register. +.It Dv PT_SETFSBASE +Set the base for the %fs segment register to the value pointed to +by the +.Fa addr +argument. +.Fa addr +must point to the +.Vt unsigned long +variable containing the new base. +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETGSBASE +Like the +.Dv PT_SETFSBASE +request, but sets the base for the %gs segment register. +.El +.Sh PowerPC MACHINE-SPECIFIC REQUESTS +.Bl -tag -width "Dv PT_SETVRREGS" +.It Dv PT_GETVRREGS +Return the thread's +.Dv ALTIVEC +machine state in the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.It Dv PT_SETVRREGS +Set the thread's +.Dv ALTIVEC +machine state from the buffer pointed to by +.Fa addr . +.Pp +The +.Fa data +argument is ignored. +.El +.Pp +Additionally, other machine-specific requests can exist. +.Sh RETURN VALUES +Most requests return 0 on success and \-1 on error. +Some requests can cause +.Fn ptrace +to return +\-1 +as a non-error value, among them are +.Dv PT_READ_I +and +.Dv PT_READ_D , +which return the value read from the process memory on success. +To disambiguate, +.Va errno +can be set to 0 before the call and checked afterwards. +.Pp +The current +.Fn ptrace +implementation always sets +.Va errno +to 0 before calling into the kernel, both for historic reasons and for +consistency with other operating systems. +It is recommended to assign zero to +.Va errno +explicitly for forward compatibility. +.Sh ERRORS +The +.Fn ptrace +system call may fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +.Bl -bullet -compact +.It +No process having the specified process ID exists. +.El +.It Bq Er EINVAL +.Bl -bullet -compact +.It +A process attempted to use +.Dv PT_ATTACH +on itself. +.It +The +.Fa request +argument +was not one of the legal requests. +.It +The signal number +(in +.Fa data ) +to +.Dv PT_CONTINUE +was neither 0 nor a legal signal number. +.It +.Dv PT_GETREGS , +.Dv PT_SETREGS , +.Dv PT_GETFPREGS , +.Dv PT_SETFPREGS , +.Dv PT_GETDBREGS , +or +.Dv PT_SETDBREGS +was attempted on a process with no valid register set. +(This is normally true only of system processes.) +.It +.Dv PT_VM_ENTRY +was given an invalid value for +.Fa pve_entry . +This can also be caused by changes to the VM map of the process. +.It +The size (in +.Fa data ) +provided to +.Dv PT_LWPINFO +was less than or equal to zero, or larger than the +.Vt ptrace_lwpinfo +structure known to the kernel. +.It +The size (in +.Fa data ) +provided to the x86-specific +.Dv PT_GETXSTATE_INFO +request was not equal to the size of the +.Vt struct ptrace_xstate_info . +.It +The size (in +.Fa data ) +provided to the x86-specific +.Dv PT_SETXSTATE +request was less than the size of the x87 plus the XMM save area. +.It +The size (in +.Fa data ) +provided to the x86-specific +.Dv PT_SETXSTATE +request was larger than returned in the +.Dv xsave_len +member of the +.Vt struct ptrace_xstate_info +from the +.Dv PT_GETXSTATE_INFO +request. +.It +The base value, provided to the amd64-specific requests +.Dv PT_SETFSBASE +or +.Dv PT_SETGSBASE , +pointed outside of the valid user address space. +This error will not occur in 32-bit programs. +.El +.It Bq Er EBUSY +.Bl -bullet -compact +.It +.Dv PT_ATTACH +was attempted on a process that was already being traced. +.It +A request attempted to manipulate a process that was being traced by +some process other than the one making the request. +.It +A request +(other than +.Dv PT_ATTACH ) +specified a process that was not stopped. +.El +.It Bq Er EPERM +.Bl -bullet -compact +.It +A request +(other than +.Dv PT_ATTACH ) +attempted to manipulate a process that was not being traced at all. +.It +An attempt was made to use +.Dv PT_ATTACH +on a process in violation of the requirements listed under +.Dv PT_ATTACH +above. +.El +.It Bq Er ENOENT +.Bl -bullet -compact +.It +.Dv PT_VM_ENTRY +previously returned the last entry of the memory map. +No more entries exist. +.El +.It Bq Er ENAMETOOLONG +.Bl -bullet -compact +.It +.Dv PT_VM_ENTRY +cannot return the pathname of the backing object because the buffer is not big +enough. +.Fa pve_pathlen +holds the minimum buffer size required on return. +.El +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr execv 3 , +.Xr i386_clr_watch 3 , +.Xr i386_set_watch 3 +.Sh HISTORY +The +.Fn ptrace +function appeared in +.At v7 . diff --git a/lib/libc/sys/ptrace.c b/lib/libc/sys/ptrace.c new file mode 100644 index 000000000000..2bb615fe563e --- /dev/null +++ b/lib/libc/sys/ptrace.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2016 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/ptrace.h> +#include <errno.h> +#include "libc_private.h" + +__weak_reference(_ptrace, ptrace); + +int +_ptrace(int request, pid_t pid, caddr_t addr, int data) +{ + + errno = 0; + return (__sys_ptrace(request, pid, addr, data)); +} diff --git a/lib/libc/sys/quotactl.2 b/lib/libc/sys/quotactl.2 new file mode 100644 index 000000000000..6dabff0ec30c --- /dev/null +++ b/lib/libc/sys/quotactl.2 @@ -0,0 +1,261 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Robert Elz at The University of Melbourne. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)quotactl.2 8.2 (Berkeley) 3/10/95 +.\" $FreeBSD$ +.\" +.Dd March 5, 1999 +.Dt QUOTACTL 2 +.Os +.Sh NAME +.Nm quotactl +.Nd manipulate file system quotas +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In ufs/ufs/quota.h +.Ft int +.Fn quotactl "const char *path" "int cmd" "int id" "void *addr" +.Sh DESCRIPTION +The +.Fn quotactl +system call enables, disables and +manipulates file system quotas. +A quota control command +given by +.Fa cmd +operates on the given filename +.Fa path +for the given user or group +.Fa id . +(NOTE: One should use the QCMD macro defined in +.In ufs/ufs/quota.h +to formulate the value for +.Fa cmd . ) +The address of an optional command specific data structure, +.Fa addr , +may be given; its interpretation +is discussed below with each command. +.Pp +For commands that use the +.Fa id +identifier, it must be either -1 or any positive value. +The value of -1 indicates that the current UID or GID should be used. +Any other negative value will return an error. +.Pp +Currently quotas are supported only for the +.Dq ufs +file system. +For +.Dq ufs , +a command is composed of a primary command (see below) +and a command type used to interpret the +.Fa id . +Types are supported for interpretation of user identifiers (USRQUOTA) +and group identifiers (GRPQUOTA). +The +.Dq ufs +specific commands are: +.Bl -tag -width Q_GETQUOTASIZEx +.It Dv Q_QUOTAON +Enable disk quotas for the file system specified by +.Fa path . +The command type specifies the type of the quotas being enabled. +The +.Fa addr +argument specifies a file from which to take the quotas. +The quota file must exist; +it is normally created with the +.Xr quotacheck 8 +program. +The +.Fa id +argument is unused. +Only the super-user may turn quotas on. +.It Dv Q_QUOTAOFF +Disable disk quotas for the file system specified by +.Fa path . +The command type specifies the type of the quotas being disabled. +The +.Fa addr +and +.Fa id +arguments are unused. +Only the super-user may turn quotas off. +.It Dv Q_GETQUOTASIZE +Get the wordsize used to represent the quotas for the user or group +(as determined by the command type). +Possible values are 32 for the old-style quota file +and 64 for the new-style quota file. +The +.Fa addr +argument is a pointer to an integer into which the size is stored. +The identifier +.Fa id +is not used. +.It Dv Q_GETQUOTA +Get disk quota limits and current usage for the user or group +(as determined by the command type) with identifier +.Fa id . +The +.Fa addr +argument +is a pointer to a +.Fa struct dqblk +structure (defined in +.In ufs/ufs/quota.h ) . +.It Dv Q_SETQUOTA +Set disk quota limits for the user or group +(as determined by the command type) with identifier +.Fa id . +The +.Fa addr +argument +is a pointer to a +.Fa struct dqblk +structure (defined in +.In ufs/ufs/quota.h ) . +The usage fields of the +.Fa dqblk +structure are ignored. +This system call is restricted to the super-user. +.It Dv Q_SETUSE +Set disk usage limits for the user or group +(as determined by the command type) with identifier +.Fa id . +The +.Fa addr +argument +is a pointer to a +.Fa struct dqblk +structure (defined in +.In ufs/ufs/quota.h ) . +Only the usage fields are used. +This system call is restricted to the super-user. +.It Dv Q_SYNC +Update the on-disk copy of quota usages. +The command type specifies which type of quotas are to be updated. +The +.Fa id +and +.Fa addr +arguments are ignored. +.El +.Sh RETURN VALUES +.Rv -std quotactl +.Sh ERRORS +The +.Fn quotactl +system call will fail if: +.Bl -tag -width Er +.It Bq Er EOPNOTSUPP +The kernel has not been compiled with the +.Dv QUOTA +option. +.It Bq Er EUSERS +The quota table cannot be expanded. +.It Bq Er EINVAL +The +.Fa cmd +argument +or the command type is invalid. +In +.Dv Q_GETQUOTASIZE , +.Dv Q_GETQUOTA , +.Dv Q_SETQUOTA , +and +.Dv Q_SETUSE , +quotas are not currently enabled for this file system. +.Pp +The +.Fa id +argument to +.Dv Q_GETQUOTA , +.Dv Q_SETQUOTA +or +.Dv Q_SETUSE +is a negative value. +.It Bq Er EACCES +In +.Dv Q_QUOTAON , +the quota file is not a plain file. +.It Bq Er EACCES +Search permission is denied for a component of a path prefix. +.It Bq Er ENOTDIR +A component of a path prefix was not a directory. +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A filename does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating a pathname. +.It Bq Er EROFS +In +.Dv Q_QUOTAON , +either the file system on which quotas are to be enabled is mounted read-only +or the quota file resides on a read-only file system. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing +to a file containing quotas. +.It Bq Er EFAULT +An invalid +.Fa addr +was supplied; the associated structure could not be copied in or out +of the kernel. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EPERM +The call was privileged and the caller was not the super-user. +.El +.Sh SEE ALSO +.Xr quota 1 , +.Xr fstab 5 , +.Xr edquota 8 , +.Xr quotacheck 8 , +.Xr quotaon 8 , +.Xr repquota 8 +.Sh HISTORY +The +.Fn quotactl +system call appeared in +.Bx 4.3 Reno . +.Sh BUGS +There should be some way to integrate this call with the resource +limit interface provided by +.Xr setrlimit 2 +and +.Xr getrlimit 2 . diff --git a/lib/libc/sys/rctl_add_rule.2 b/lib/libc/sys/rctl_add_rule.2 new file mode 100644 index 000000000000..667a0059470d --- /dev/null +++ b/lib/libc/sys/rctl_add_rule.2 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2016 Eric Badger +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 14, 2016 +.Dt RCTL_ADD_RULE 2 +.Os +.Sh NAME +.Nm rctl_add_rule, +.Nm rctl_get_limits +.Nm rctl_get_racct, +.Nm rctl_get_rules, +.Nm rctl_remove_rule +.Nd manipulate and query the resource limits database +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/rctl.h +.Ft int +.Fo rctl_add_rule +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_limits +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_racct +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_get_rules +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Ft int +.Fo rctl_remove_rule +.Fa "const char *inbufp" "size_t inbuflen" "char *outbufp" "size_t outbuflen" +.Fc +.Sh DESCRIPTION +These system calls are used to manipulate and query the resource limits +database. +For all functions, +.Fa inbuflen +refers to the length of the buffer pointed to by +.Fa inbufp +and +.Fa outbuflen +refers to the length of the buffer pointed to by +.Fa outbufp . +.Pp +The +.Fn rctl_add_rule +function adds the rule pointed to by +.Fa inbufp +to the resource limits database. +The +.Fa outbufp +and +.Fa outbuflen +arguments are unused. +Rule format is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +.Pp +The +.Fn rctl_get_limits +function returns in +.Fa outbufp +a comma-separated list of rules that apply to the process that +matches the filter specified in +.Fa inbufp . +This includes rules with a subject of the process itself as well as rules +with a different subject (such as user or loginclass) that apply to the +process. +.Pp +The +.Fn rctl_get_racct +function returns resource usage information for a given subject. +The subject is specified by passing a filter in +.Fa inbufp . +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +A comma-separated list of resources and the amount used of each by the +specified subject is returned in +.Fa outbufp . +The resource and amount is formatted as +.Qq resource=amount . +.Pp +The +.Fn rctl_get_rules +function returns in +.Fa outbufp +a comma-separated list of rules from the resource limits database that +match the filter passed in +.Fa inbufp . +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +A filter of +.Va :: +may be passed to return all rules. +.Pp +The +.Fn rctl_remove_rule +function removes all rules matching the filter passed in +.Fa inbufp +from the resource limits database. +Filter syntax is as described in +.Xr rctl 8 , +with exceptions noted in the +.Sx RULES AND FILTERS +section. +.Fa outbufp +and +.Fa outbuflen +are unused. +.Sh RULES AND FILTERS +This section explains how the rule and filter format described in +.Xr rctl 8 +differs from the format passed to the system calls themselves. +The rctl tool provides several conveniences that the system calls do not. +When using the system call: +.Bl -dash -offset indent +.It +The subject must be fully specified. +For example, abbreviating +.Ql user +to +.Ql u +is not acceptable. +.It +User and group IDs must be numeric. +For example, +.Ql root +must be expressed as +.Ql 0 . +.It +Units are not permitted on resource amounts. +For example, a quantity of 1024 bytes must be expressed as +.Ql 1024 +and not +.Ql 1k . +.El +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The rctl system calls may fail if: +.Bl -tag -width Er +.It Bq Er ENOSYS +RACCT/RCTL support is not present in the kernel or the +.Va kern.racct.enable +sysctl is 0. +.It Bq Er EINVAL +The rule or filter passed in +.Fa inbufp +is invalid. +.It Bq Er EPERM +User has insufficient privileges to carry out the requested operation. +.It Bq Er E2BIG +.Fa inbufp +or +.Fa outbufp +are too large. +.It Bq Er ESRCH +No process matched the provided rule or filter. +.It Bq Er ENAMETOOLONG +The loginclass or jail name specified is too long. +.It Bq Er ERANGE +The rule amount is outside of the allowable range or +.Fa outbufp +is too small. +.It Bq Er EOPNOTSUPP +The requested operation is not supported for the given rule or filter. +.It Bq Er EFAULT +.Fa inbufp +or +.Fa outbufp +refer to invalid addresses. +.El +.Sh SEE ALSO +.Xr rctl 8 +.Sh HISTORY +The rctl family of system calls appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The rctl system calls were developed by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org +under sponsorship from the FreeBSD Foundation. +This manual page was written by +.An Eric Badger Aq Mt badger@FreeBSD.org . diff --git a/lib/libc/sys/read.2 b/lib/libc/sys/read.2 new file mode 100644 index 000000000000..a0a7be838c0b --- /dev/null +++ b/lib/libc/sys/read.2 @@ -0,0 +1,284 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)read.2 8.4 (Berkeley) 2/26/94 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt READ 2 +.Os +.Sh NAME +.Nm read , +.Nm readv , +.Nm pread , +.Nm preadv +.Nd read input +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn read "int fd" "void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pread "int fd" "void *buf" "size_t nbytes" "off_t offset" +.In sys/uio.h +.Ft ssize_t +.Fn readv "int fd" "const struct iovec *iov" "int iovcnt" +.Ft ssize_t +.Fn preadv "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset" +.Sh DESCRIPTION +The +.Fn read +system call +attempts to read +.Fa nbytes +of data from the object referenced by the descriptor +.Fa fd +into the buffer pointed to by +.Fa buf . +The +.Fn readv +system call +performs the same action, but scatters the input data +into the +.Fa iovcnt +buffers specified by the members of the +.Fa iov +array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. +The +.Fn pread +and +.Fn preadv +system calls +perform the same functions, but read from the specified position in +the file without modifying the file pointer. +.Pp +For +.Fn readv +and +.Fn preadv , +the +.Fa iovec +structure is defined as: +.Pp +.Bd -literal -offset indent -compact +struct iovec { + void *iov_base; /* Base address. */ + size_t iov_len; /* Length. */ +}; +.Ed +.Pp +Each +.Fa iovec +entry specifies the base address and length of an area +in memory where data should be placed. +The +.Fn readv +system call +will always fill an area completely before proceeding +to the next. +.Pp +On objects capable of seeking, the +.Fn read +starts at a position +given by the pointer associated with +.Fa fd +(see +.Xr lseek 2 ) . +Upon return from +.Fn read , +the pointer is incremented by the number of bytes actually read. +.Pp +Objects that are not capable of seeking always read from the current +position. +The value of the pointer associated with such an +object is undefined. +.Pp +Upon successful completion, +.Fn read , +.Fn readv , +.Fn pread +and +.Fn preadv +return the number of bytes actually read and placed in the buffer. +The system guarantees to read the number of bytes requested if +the descriptor references a normal file that has that many bytes left +before the end-of-file, but in no other case. +.Sh RETURN VALUES +If successful, the +number of bytes actually read is returned. +Upon reading end-of-file, +zero is returned. +Otherwise, a -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn read , +.Fn readv , +.Fn pread +and +.Fn preadv +system calls +will succeed unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid file or socket descriptor open for reading. +.It Bq Er ECONNRESET +The +.Fa fd +argument refers to a socket, and the remote socket end is +forcibly closed. +.It Bq Er EFAULT +The +.Fa buf +argument +points outside the allocated address space. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er EBUSY +Failed to read from a file, e.g. /proc/<pid>/regs while <pid> is not stopped +.It Bq Er EINTR +A read from a slow device +(i.e.\& one that might block for an arbitrary amount of time) +was interrupted by the delivery of a signal +before any data arrived. +.It Bq Er EINVAL +The pointer associated with +.Fa fd +was negative. +.It Bq Er EAGAIN +The file was marked for non-blocking I/O, +and no data were ready to be read. +.It Bq Er EISDIR +The file descriptor is associated with a directory residing +on a file system that does not allow regular read operations on +directories (e.g.\& NFS). +.It Bq Er EOPNOTSUPP +The file descriptor is associated with a file system and file type that +do not allow regular read operations on it. +.It Bq Er EOVERFLOW +The file descriptor is associated with a regular file, +.Fa nbytes +is greater than 0, +.Fa offset +is before the end-of-file, and +.Fa offset +is greater than or equal to the offset maximum established +for this file system. +.It Bq Er EINVAL +The value +.Fa nbytes +is greater than +.Dv INT_MAX . +.El +.Pp +In addition, +.Fn readv +and +.Fn preadv +may return one of the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa iovcnt +argument +was less than or equal to 0, or greater than +.Dv IOV_MAX . +.It Bq Er EINVAL +One of the +.Fa iov_len +values in the +.Fa iov +array was negative. +.It Bq Er EINVAL +The sum of the +.Fa iov_len +values in the +.Fa iov +array overflowed a 32-bit integer. +.It Bq Er EFAULT +Part of the +.Fa iov +array points outside the process's allocated address space. +.El +.Pp +The +.Fn pread +and +.Fn preadv +system calls may also return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa offset +value was negative. +.It Bq Er ESPIPE +The file descriptor is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr dup 2 , +.Xr fcntl 2 , +.Xr getdirentries 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr socketpair 2 , +.Xr fread 3 , +.Xr readdir 3 +.Sh STANDARDS +The +.Fn read +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn readv +and +.Fn pread +system calls are expected to conform to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn preadv +system call appeared in +.Fx 6.0 . +The +.Fn pread +function appeared in +.At V.4 . +The +.Fn readv +system call appeared in +.Bx 4.2 . +The +.Fn read +function appeared in +.At v6 . diff --git a/lib/libc/sys/read.c b/lib/libc/sys/read.c new file mode 100644 index 000000000000..ab30189026e3 --- /dev/null +++ b/lib/libc/sys/read.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_read, __read); + +#pragma weak read +ssize_t +read(int fd, void *buf, size_t nbytes) +{ + + return (((ssize_t (*)(int, void *, size_t)) + __libc_interposing[INTERPOS_read])(fd, buf, nbytes)); +} diff --git a/lib/libc/sys/readlink.2 b/lib/libc/sys/readlink.2 new file mode 100644 index 000000000000..4b2405254538 --- /dev/null +++ b/lib/libc/sys/readlink.2 @@ -0,0 +1,158 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)readlink.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt READLINK 2 +.Os +.Sh NAME +.Nm readlink , +.Nm readlinkat +.Nd read value of a symbolic link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn readlink "const char *restrict path" "char *restrict buf" "size_t bufsiz" +.Ft ssize_t +.Fo readlinkat +.Fa "int fd" "const char *restrict path" "char *restrict buf" "size_t bufsize" +.Fc +.Sh DESCRIPTION +The +.Fn readlink +system call +places the contents of the symbolic link +.Fa path +in the buffer +.Fa buf , +which has size +.Fa bufsiz . +The +.Fn readlink +system call does not append a +.Dv NUL +character to +.Fa buf . +.Pp +The +.Fn readlinkat +system call is equivalent to +.Fn readlink +except in the case where +.Fa path +specifies a relative path. +In this case the symbolic link whose content is read relative to the +directory associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn readlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn readlink . +.Sh RETURN VALUES +The call returns the count of characters placed in the buffer +if it succeeds, or a \-1 if an error occurs, placing the error +code in the global variable +.Va errno . +.Sh ERRORS +The +.Fn readlink +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EINVAL +The named file is not a symbolic link. +.It Bq Er EIO +An I/O error occurred while reading from the file system. +.It Bq Er EFAULT +The +.Fa buf +argument +extends outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn readlink , +the +.Fn readlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr lstat 2 , +.Xr stat 2 , +.Xr symlink 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn readlinkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn readlink +system call appeared in +.Bx 4.2 . +The +.Fn readlinkat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/readv.c b/lib/libc/sys/readv.c new file mode 100644 index 000000000000..567292750da0 --- /dev/null +++ b/lib/libc/sys/readv.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/uio.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_readv, __readv); + +#pragma weak readv +ssize_t +readv(int fd, const struct iovec *iov, int iovcnt) +{ + + return (((ssize_t (*)(int, const struct iovec *, int)) + __libc_interposing[INTERPOS_readv])(fd, iov, iovcnt)); +} diff --git a/lib/libc/sys/reboot.2 b/lib/libc/sys/reboot.2 new file mode 100644 index 000000000000..ce8cc713d931 --- /dev/null +++ b/lib/libc/sys/reboot.2 @@ -0,0 +1,168 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)reboot.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd September 18, 2015 +.Dt REBOOT 2 +.Os +.Sh NAME +.Nm reboot +.Nd reboot system or halt processor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.In sys/reboot.h +.Ft int +.Fn reboot "int howto" +.Sh DESCRIPTION +The +.Fn reboot +system call +reboots the system. +Only the super-user may reboot a machine on demand. +However, a reboot is invoked +automatically in the event of unrecoverable system failures. +.Pp +The +.Fa howto +argument +is a mask of options; the system call interface allows the following +options, defined in the include file +.In sys/reboot.h , +to be passed +to the new kernel or the new bootstrap and init programs. +.Bl -tag -width RB_INITNAMEA +.It Dv RB_AUTOBOOT +The default, causing the system to reboot in its usual fashion. +.It Dv RB_ASKNAME +Interpreted by the bootstrap program itself, causing it to +prompt on the console as to what file should be booted. +Normally, the system is booted from the file +.Dq Ar xx Ns No (0,0)kernel , +where +.Ar xx +is the default disk name, +without prompting for the file name. +.It Dv RB_DFLTROOT +Use the compiled in root device. +Normally, the system uses the device from which it was booted +as the root device if possible. +(The default behavior is dependent on the ability of the bootstrap program +to determine the drive from which it was loaded, which is not possible +on all systems.) +.It Dv RB_DUMP +Dump kernel memory before rebooting; see +.Xr savecore 8 +for more information. +.It Dv RB_HALT +The processor is simply halted; no reboot takes place. +This option should be used with caution. +.It Dv RB_POWEROFF +After halting, the shutdown code will do what it can to turn +off the power. +This requires hardware support. +.It Dv RB_INITNAME +An option allowing the specification of an init program (see +.Xr init 8 ) +other than +.Pa /sbin/init +to be run when the system reboots. +This switch is not currently available. +.It Dv RB_KDB +Load the symbol table and enable a built-in debugger in the system. +This option will have no useful function if the kernel is not configured +for debugging. +Several other options have different meaning if combined +with this option, although their use may not be possible +via the +.Fn reboot +system call. +See +.Xr ddb 4 +for more information. +.It Dv RB_NOSYNC +Normally, the disks are sync'd (see +.Xr sync 8 ) +before the processor is halted or rebooted. +This option may be useful if file system changes have been made manually +or if the processor is on fire. +.It Dv RB_REROOT +Instead of rebooting, unmount all filesystems except the one containing +currently-running executable, and mount root filesystem using the same +mechanism which is used during normal boot, based on +vfs.root.mountfrom +.Xr kenv 1 +variable. +.It Dv RB_RDONLY +Initially mount the root file system read-only. +This is currently the default, and this option has been deprecated. +.It Dv RB_SINGLE +Normally, the reboot procedure involves an automatic disk consistency +check and then multi-user operations. +.Dv RB_SINGLE +prevents this, booting the system with a single-user shell +on the console. +.Dv RB_SINGLE +is actually interpreted by the +.Xr init 8 +program in the newly booted system. +.El +.Pp +When no options are given (i.e., +.Dv RB_AUTOBOOT +is used), the system is +rebooted from file +.Dq kernel +in the root file system of unit 0 +of a disk chosen in a processor specific way. +An automatic consistency check of the disks is normally performed +(see +.Xr fsck 8 ) . +.Sh RETURN VALUES +If successful, this call never returns. +Otherwise, a -1 is returned and an error is returned in the global +variable +.Va errno . +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.El +.Sh SEE ALSO +.Xr crash 8 , +.Xr halt 8 , +.Xr init 8 , +.Xr reboot 8 , +.Xr savecore 8 +.Sh HISTORY +The +.Fn reboot +system call appeared in +.Bx 4.0 . diff --git a/lib/libc/sys/recv.2 b/lib/libc/sys/recv.2 new file mode 100644 index 000000000000..b0b008fec514 --- /dev/null +++ b/lib/libc/sys/recv.2 @@ -0,0 +1,423 @@ +.\" Copyright (c) 1983, 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)recv.2 8.3 (Berkeley) 2/21/94 +.\" $FreeBSD$ +.\" +.Dd August 18, 2016 +.Dt RECV 2 +.Os +.Sh NAME +.Nm recv , +.Nm recvfrom , +.Nm recvmsg , +.Nm recvmmsg +.Nd receive message(s) from a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft ssize_t +.Fn recv "int s" "void *buf" "size_t len" "int flags" +.Ft ssize_t +.Fn recvfrom "int s" "void *buf" "size_t len" "int flags" "struct sockaddr * restrict from" "socklen_t * restrict fromlen" +.Ft ssize_t +.Fn recvmsg "int s" "struct msghdr *msg" "int flags" +.Ft ssize_t +.Fn recvmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags" "const struct timespec * restrict timeout" +.Sh DESCRIPTION +The +.Fn recvfrom , +.Fn recvmsg , +and +.Fn recvmmsg +system calls +are used to receive messages from a socket, +and may be used to receive data on a socket whether or not +it is connection-oriented. +.Pp +If +.Fa from +is not a null pointer +and the socket is not connection-oriented, +the source address of the message is filled in. +The +.Fa fromlen +argument +is a value-result argument, initialized to the size of +the buffer associated with +.Fa from , +and modified on return to indicate the actual size of the +address stored there. +.Pp +The +.Fn recv +function is normally used only on a +.Em connected +socket (see +.Xr connect 2 ) +and is identical to +.Fn recvfrom +with a +null pointer passed as its +.Fa from +argument. +.Pp +The +.Fn recvmmsg +function is used to receive multiple +messages at a call. +Their number is supplied by +.Fa vlen . +The messages are placed in the buffers described by +.Fa msgvec +vector, after reception. +The size of each received message is placed in the +.Fa msg_len +field of each element of the vector. +If +.Fa timeout +is NULL the call blocks until the data is available for each +supplied message buffer. +Otherwise it waits for data for the specified amount of time. +If the timeout expired and there is no data received, +a value 0 is returned. +The +.Xr ppoll 2 +system call is used to implement the timeout mechanism, +before first receive is performed. +.Pp +The +.Fn recv , +.Fn recvfrom +and +.Fn recvmsg +return the length of the message on successful +completion, whereas +.Fn recvmmsg +returns the number of received messages. +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 (see +.Xr socket 2 ) . +.Pp +If no messages are available at the socket, the +receive call waits for a message to arrive, unless +the socket is non-blocking (see +.Xr fcntl 2 ) +in which case the value +\-1 is returned and the global variable +.Va errno +is set to +.Er EAGAIN . +The receive calls except +.Fn recvmmsg +normally return any data available, +up to the requested amount, +rather than waiting for receipt of the full amount requested; +this behavior is affected by the socket-level options +.Dv SO_RCVLOWAT +and +.Dv SO_RCVTIMEO +described in +.Xr getsockopt 2 . +The +.Fn recvmmsg +function implements this behaviour for each message in the vector. +.Pp +The +.Xr select 2 +system call may be used to determine when more data arrives. +.Pp +The +.Fa flags +argument to a +.Fn recv +function is formed by +.Em or Ap ing +one or more of the values: +.Bl -column ".Dv MSG_CMSG_CLOEXEC" -offset indent +.It Dv MSG_OOB Ta process out-of-band data +.It Dv MSG_PEEK Ta peek at incoming message +.It Dv MSG_WAITALL Ta wait for full request or error +.It Dv MSG_DONTWAIT Ta do not block +.It Dv MSG_CMSG_CLOEXEC Ta set received fds close-on-exec +.It Dv MSG_WAITFORONE Ta do not block after receiving the first message +(only for +.Fn recvmmsg +) +.El +.Pp +The +.Dv MSG_OOB +flag requests receipt of out-of-band data +that would not be received in the normal data stream. +Some protocols place expedited data at the head of the normal +data queue, and thus this flag cannot be used with such protocols. +The +.Dv MSG_PEEK +flag causes the receive operation to return data +from the beginning of the receive queue without removing that +data from the queue. +Thus, a subsequent receive call will return the same data. +The +.Dv MSG_WAITALL +flag requests that the operation block until +the full request is satisfied. +However, the call may still return less data than requested +if a signal is caught, an error or disconnect occurs, +or the next data to be received is of a different type than that returned. +The +.Dv MSG_DONTWAIT +flag requests the call to return when it would block otherwise. +If no data is available, +.Va errno +is set to +.Er EAGAIN . +This flag is not available in strict +.Tn ANSI +or C99 compilation mode. +The +.Dv MSG_WAITFORONE +flag sets MSG_DONTWAIT after the first message has been received. +This flag is only relevant for +.Fn recvmmsg . +.Pp +The +.Fn recvmsg +system call uses a +.Fa msghdr +structure to minimize the number of directly supplied arguments. +This structure has the following form, as defined in +.In sys/socket.h : +.Bd -literal +struct msghdr { + void *msg_name; /* optional address */ + socklen_t msg_namelen; /* size of address */ + struct iovec *msg_iov; /* scatter/gather array */ + int msg_iovlen; /* # elements in msg_iov */ + void *msg_control; /* ancillary data, see below */ + socklen_t msg_controllen;/* ancillary data buffer len */ + int msg_flags; /* flags on received message */ +}; +.Ed +.Pp +Here +.Fa msg_name +and +.Fa msg_namelen +specify the destination address if the socket is unconnected; +.Fa msg_name +may be given as a null pointer if no names are desired or required. +The +.Fa msg_iov +and +.Fa msg_iovlen +arguments +describe scatter gather locations, as discussed in +.Xr read 2 . +The +.Fa msg_control +argument, +which has length +.Fa msg_controllen , +points to a buffer for other protocol control related messages +or other miscellaneous ancillary data. +The messages are of the form: +.Bd -literal +struct cmsghdr { + socklen_t cmsg_len; /* data byte count, including hdr */ + int cmsg_level; /* originating protocol */ + int cmsg_type; /* protocol-specific type */ +/* followed by + u_char cmsg_data[]; */ +}; +.Ed +.Pp +As an example, one could use this to learn of changes in the data-stream +in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting +a +.Fn recvmsg +with no data buffer provided immediately after an +.Fn accept +system call. +.Pp +Open file descriptors are now passed as ancillary data for +.Dv AF_UNIX +domain sockets, with +.Fa cmsg_level +set to +.Dv SOL_SOCKET +and +.Fa cmsg_type +set to +.Dv SCM_RIGHTS . +The close-on-exec flag on received descriptors is set according to the +.Dv MSG_CMSG_CLOEXEC +flag passed to +.Fn recvmsg . +.Pp +Process credentials can also be passed as ancillary data for +.Dv AF_UNIX +domain sockets using a +.Fa cmsg_type +of +.Dv SCM_CREDS . +In this case, +.Fa cmsg_data +should be a structure of type +.Fa cmsgcred , +which is defined in +.In sys/socket.h +as follows: +.Bd -literal +struct cmsgcred { + pid_t cmcred_pid; /* PID of sending process */ + uid_t cmcred_uid; /* real UID of sending process */ + uid_t cmcred_euid; /* effective UID of sending process */ + gid_t cmcred_gid; /* real GID of sending process */ + short cmcred_ngroups; /* number or groups */ + gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ +}; +.Ed +.Pp +If a sender supplies ancillary data with enough space for the above struct +tagged as +.Dv SCM_CREDS +control message type to the +.Fn sendmsg +system call, then kernel will fill in the credential information of the +sending process and deliver it to the receiver. +Since receiver usually has no control over a sender, this method of retrieving +credential information isn't reliable. +For reliable retrieval of remote side credentials it is advised to use the +.Dv LOCAL_CREDS +socket option on the receiving socket. +See +.Xr unix 4 +for details. +.Pp +The +.Fa msg_flags +field is set on return according to the message received. +.Dv MSG_EOR +indicates end-of-record; +the data returned completed a record (generally used with sockets of type +.Dv SOCK_SEQPACKET ) . +.Dv MSG_TRUNC +indicates that +the trailing portion of a datagram was discarded because the datagram +was larger than the buffer supplied. +.Dv MSG_CTRUNC +indicates that some +control data were discarded due to lack of space in the buffer +for ancillary data. +.Dv MSG_OOB +is returned to indicate that expedited or out-of-band data were received. +.Pp +The +.Fn recvmmsg +system call uses the +.Fa mmsghdr +structure, defined as follows in the +.In sys/socket.h +header : +.Bd -literal +struct mmsghdr { + struct msghdr msg_hdr; /* message header */ + ssize_t msg_len; /* message length */ +}; +.Ed +.Pp +On data reception the +.Fa msg_len +field is updated to the length of the received message. +.Sh RETURN VALUES +These calls except +.Fn recvmmsg +return the number of bytes received. +.Fn recvmmsg +returns the number of messages received. +A value of -1 is returned if an error occurred. +.Sh ERRORS +The calls fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is an invalid descriptor. +.It Bq Er ECONNRESET +The remote socket end is forcibly closed. +.It Bq Er ENOTCONN +The socket is associated with a connection-oriented protocol +and has not been connected (see +.Xr connect 2 +and +.Xr accept 2 ) . +.It Bq Er ENOTSOCK +The argument +.Fa s +does not refer to a socket. +.It Bq Er EMSGSIZE +The +.Fn recvmsg +system call +was used to receive rights (file descriptors) that were in flight on the +connection. +However, the receiving program did not have enough free file +descriptor slots to accept them. +In this case the descriptors are +closed, any pending data can be returned by another call to +.Fn recvmsg . +.It Bq Er EAGAIN +The socket is marked non-blocking and the receive operation +would block, or +a receive timeout had been set +and the timeout expired before data were received. +.It Bq Er EINTR +The receive was interrupted by delivery of a signal before +any data were available. +.It Bq Er EFAULT +The receive buffer pointer(s) point outside the process's +address space. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr read 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr unix 4 +.Sh HISTORY +The +.Fn recv +function appeared in +.Bx 4.2 . +The +.Fn recvmmsg +function appeared in +.Fx 11.0 . diff --git a/lib/libc/sys/recvfrom.c b/lib/libc/sys/recvfrom.c new file mode 100644 index 000000000000..aa6ef3fb7be2 --- /dev/null +++ b/lib/libc/sys/recvfrom.c @@ -0,0 +1,53 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_recvfrom, __recvfrom); + +#pragma weak recvfrom +ssize_t +recvfrom(int s, void *buf, size_t len, int flags, + struct sockaddr * __restrict from, socklen_t * __restrict fromlen) +{ + + return (((ssize_t (*)(int, void *, size_t, int, + struct sockaddr *, socklen_t *)) + __libc_interposing[INTERPOS_recvfrom])(s, buf, len, flags, + from, fromlen)); +} diff --git a/lib/libc/sys/recvmsg.c b/lib/libc/sys/recvmsg.c new file mode 100644 index 000000000000..282ede9995ff --- /dev/null +++ b/lib/libc/sys/recvmsg.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_recvmsg, __recvmsg); + +#pragma weak recvmsg +ssize_t +recvmsg(int s, struct msghdr *msg, int flags) +{ + + return (((int (*)(int, struct msghdr *, int)) + __libc_interposing[INTERPOS_recvmsg])(s, msg, flags)); +} diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 new file mode 100644 index 000000000000..b98edd5e23cb --- /dev/null +++ b/lib/libc/sys/rename.2 @@ -0,0 +1,308 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)rename.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt RENAME 2 +.Os +.Sh NAME +.Nm rename +.Nd change the name of a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft int +.Fn rename "const char *from" "const char *to" +.Ft int +.Fn renameat "int fromfd" "const char *from" "int tofd" "const char *to" +.Sh DESCRIPTION +The +.Fn rename +system call +causes the link named +.Fa from +to be renamed as +.Fa to . +If +.Fa to +exists, it is first removed. +Both +.Fa from +and +.Fa to +must be of the same type (that is, both directories or both +non-directories), and must reside on the same file system. +.Pp +The +.Fn rename +system call +guarantees that if +.Fa to +already exists, an instance of +.Fa to +will always exist, even if the system should crash in +the middle of the operation. +.Pp +If the final component of +.Fa from +is a symbolic link, +the symbolic link is renamed, +not the file or directory to which it points. +.Pp +The +.Fn renameat +system call is equivalent to +.Fn rename +except in the case where either +.Fa from +or +.Fa to +specifies a relative path. +If +.Fa from +is a relative path, the file to be renamed is located +relative to the directory associated with the file descriptor +.Fa fromfd +instead of the current working directory. +If the +.Fa to +is a relative path, the same happens only relative to the directory associated +with +.Fa tofd . +If the +.Fn renameat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fromfd +or +.Fa tofd +parameter, the current working directory is used in the determination +of the file for the respective path parameter. +.\".Sh CAVEAT +.\"The system can deadlock if a loop in the file system graph is present. +.\"This loop takes the form of an entry in directory +.\".Pa a , +.\"say +.\".Pa a/foo , +.\"being a hard link to directory +.\".Pa b , +.\"and an entry in +.\"directory +.\".Pa b , +.\"say +.\".Pa b/bar , +.\"being a hard link +.\"to directory +.\".Pa a . +.\"When such a loop exists and two separate processes attempt to +.\"perform +.\".Ql rename a/foo b/bar +.\"and +.\".Ql rename b/bar a/foo , +.\"respectively, +.\"the system may deadlock attempting to lock +.\"both directories for modification. +.\"Hard links to directories should be +.\"replaced by symbolic links by the system administrator. +.Sh RETURN VALUES +.Rv -std rename +.Sh ERRORS +The +.Fn rename +system call +will fail and neither of the argument files will be +affected if: +.Bl -tag -width Er +.It Bq Er ENAMETOOLONG +A component of either pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the +.Fa from +path does not exist, +or a path prefix of +.Fa to +does not exist. +.It Bq Er EACCES +A component of either path prefix denies search permission. +.It Bq Er EACCES +The requested link requires writing in a directory with a mode +that denies write permission. +.It Bq Er EACCES +The directory pointed at by the +.Fa from +argument denies write permission, and the operation would move +it to another parent directory. +.It Bq Er EPERM +The file pointed at by the +.Fa from +argument has its immutable, undeletable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the file pointed at by the +.Fa from +argument has its immutable or append-only flag set. +.It Bq Er EPERM +The parent directory of the file pointed at by the +.Fa to +argument has its immutable flag set. +.It Bq Er EPERM +The directory containing +.Fa from +is marked sticky, +and neither the containing directory nor +.Fa from +are owned by the effective user ID. +.It Bq Er EPERM +The file pointed at by the +.Fa to +argument +exists, +the directory containing +.Fa to +is marked sticky, +and neither the containing directory nor +.Fa to +are owned by the effective user ID. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating either pathname. +.It Bq Er ENOTDIR +A component of either path prefix is not a directory. +.It Bq Er ENOTDIR +The +.Fa from +argument +is a directory, but +.Fa to +is not a directory. +.It Bq Er EISDIR +The +.Fa to +argument +is a directory, but +.Fa from +is not a directory. +.It Bq Er EXDEV +The link named by +.Fa to +and the file named by +.Fa from +are on different logical devices (file systems). +Note that this error +code will not be returned if the implementation permits cross-device +links. +.It Bq Er ENOSPC +The directory in which the entry for the new name is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er EDQUOT +The directory in which the entry for the new name +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EIO +An I/O error occurred while making or updating a directory entry. +.It Bq Er EROFS +The requested link requires writing in a directory on a read-only file +system. +.It Bq Er EFAULT +Path +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Fa from +argument +is a parent directory of +.Fa to , +or an attempt is made to rename +.Ql .\& +or +.Ql \&.. . +.It Bq Er ENOTEMPTY +The +.Fa to +argument +is a directory and is not empty. +.El +.Pp +In addition to the errors returned by the +.Fn rename , +the +.Fn renameat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa from +argument does not specify an absolute path and the +.Fa fromfd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching, or the +.Fa to +argument does not specify an absolute path and the +.Fa tofd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa from +argument is not an absolute path and +.Fa fromfd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory, or the +.Fa to +argument is not an absolute path and +.Fa tofd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr open 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn rename +system call is expected to conform to +.St -p1003.1-96 . +The +.Fn renameat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn renameat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/revoke.2 b/lib/libc/sys/revoke.2 new file mode 100644 index 000000000000..3d7ad00bfe34 --- /dev/null +++ b/lib/libc/sys/revoke.2 @@ -0,0 +1,110 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Berkeley Software Design, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)revoke.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd Jan 25, 2016 +.Dt REVOKE 2 +.Os +.Sh NAME +.Nm revoke +.Nd revoke file access +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn revoke "const char *path" +.Sh DESCRIPTION +The +.Fn revoke +system call invalidates all current open file descriptors in the system +for the file named by +.Fa path . +Subsequent operations on any such descriptors +fail, with the exceptions that a +.Fn read +from a character device file which has been revoked +returns a count of zero (end of file), +and a +.Fn close +system call will succeed. +If the file is a special file for a device which is open, +the device close function +is called as if all open references to the file had been closed +using a special close method which does not block. +.Pp +Access to a file may be revoked only by its owner or the super user. +The +.Fn revoke +system call is currently supported only for block and character special +device files. +It is normally used to prepare a terminal device for a new login session, +preventing any access by a previous user of the terminal. +.Sh RETURN VALUES +.Rv -std revoke +.Sh ERRORS +Access to the named file is revoked unless one of the following: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1024 characters. +.It Bq Er ENOENT +The named file or a component of the path name does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +The implementation does not support the +.Fn revoke +operation on the named file. +.It Bq Er EPERM +The caller is neither the owner of the file nor the super user. +.El +.Sh SEE ALSO +.Xr revoke 1 , +.Xr close 2 +.Sh HISTORY +The +.Fn revoke +system call first appeared in +.Bx 4.3 Reno . +.Sh BUGS +The non-blocking close method is only correctly implemented for +terminal devices. diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 new file mode 100644 index 000000000000..222bac425496 --- /dev/null +++ b/lib/libc/sys/rfork.2 @@ -0,0 +1,192 @@ +.\" +.\" This manual page is taken directly from Plan9, and modified to +.\" describe the actual BSD implementation. Permission for +.\" use of this page comes from Rob Pike <rob@plan9.att.com>. +.\" +.\" $FreeBSD$ +.\" +.Dd July 12, 2011 +.Dt RFORK 2 +.Os +.Sh NAME +.Nm rfork +.Nd manipulate process resources +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn rfork "int flags" +.Sh DESCRIPTION +Forking, vforking or rforking are the only ways new processes are created. +The +.Fa flags +argument to +.Fn rfork +selects which resources of the +invoking process (parent) are shared +by the new process (child) or initialized to +their default values. +The resources include +the open file descriptor table (which, when shared, permits processes +to open and close files for other processes), +and open files. +The +.Fa flags +argument +is the logical OR of some subset of: +.Bl -tag -width ".Dv RFLINUXTHPN" +.It Dv RFPROC +If set a new process is created; otherwise changes affect the +current process. +.It Dv RFNOWAIT +If set, the child process will be dissociated from the parent. +Upon +exit the child will not leave a status for the parent to collect. +See +.Xr wait 2 . +.It Dv RFFDG +If set, the invoker's file descriptor table (see +.Xr intro 2 ) +is copied; otherwise the two processes share a +single table. +.It Dv RFCFDG +If set, the new process starts with a clean file descriptor table. +Is mutually exclusive with +.Dv RFFDG . +.It Dv RFTHREAD +If set, the new process shares file descriptor to process leaders table +with its parent. +Only applies when neither +.Dv RFFDG +nor +.Dv RFCFDG +are set. +.It Dv RFMEM +If set, the kernel will force sharing of the entire address space, +typically by sharing the hardware page table directly. +The child +will thus inherit and share all the segments the parent process owns, +whether they are normally shareable or not. +The stack segment is +not split (both the parent and child return on the same stack) and thus +.Fn rfork +with the RFMEM flag may not generally be called directly from high level +languages including C. +May be set only with +.Dv RFPROC . +A helper function is provided to assist with this problem and will cause +the new process to run on the provided stack. +See +.Xr rfork_thread 3 +for information. +Note that a lot of code will not run correctly in such an environment. +.It Dv RFSIGSHARE +If set, the kernel will force sharing the sigacts structure between the +child and the parent. +.It Dv RFTSIGZMB +If set, the kernel will deliver a specified signal to the parent +upon the child exit, instead of default SIGCHLD. +The signal number +.Dv signum +is specified by oring the +.Dv RFTSIGFLAGS(signum) +expression into +.Fa flags . +Specifying signal number 0 disables signal delivery upon the child exit. +.It Dv RFLINUXTHPN +If set, the kernel will deliver SIGUSR1 instead of SIGCHLD upon thread +exit for the child. +This is intended to mimic certain Linux clone behaviour. +.El +.Pp +File descriptors in a shared file descriptor table are kept +open until either they are explicitly closed +or all processes sharing the table exit. +.Pp +If +.Dv RFPROC +is set, the +value returned in the parent process +is the process id +of the child process; the value returned in the child is zero. +Without +.Dv RFPROC , +the return value is zero. +Process id's range from 1 to the maximum integer +.Ft ( int ) +value. +The +.Fn rfork +system call +will sleep, if necessary, until required process resources are available. +.Pp +The +.Fn fork +system call +can be implemented as a call to +.Fn rfork "RFFDG | RFPROC" +but is not for backwards compatibility. +.Sh RETURN VALUES +Upon successful completion, +.Fn rfork +returns a value +of 0 to the child process and returns the process ID of the child +process to the parent process. +Otherwise, a value of -1 is returned +to the parent process, no child process is created, and the global +variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn rfork +system call +will fail and no child process will be created if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +(The limit is actually ten less than this +except for the super user). +.It Bq Er EAGAIN +The user is not the super user, and +the system-imposed limit +on the total number of +processes under execution by a single user would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROCPERUID . +.It Bq Er EAGAIN +The user is not the super user, and +the soft resource limit corresponding to the +.Fa resource +argument +.Dv RLIMIT_NOFILE +would be exceeded (see +.Xr getrlimit 2 ) . +.It Bq Er EINVAL +Both the RFFDG and the RFCFDG flags were specified. +.It Bq Er EINVAL +Any flags not listed above were specified. +.It Bq Er EINVAL +An invalid signal number was specified. +.It Bq Er ENOMEM +There is insufficient swap space for the new process. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr intro 2 , +.Xr minherit 2 , +.Xr vfork 2 , +.Xr pthread_create 3 , +.Xr rfork_thread 3 +.Sh HISTORY +The +.Fn rfork +function first appeared in Plan9. diff --git a/lib/libc/sys/rmdir.2 b/lib/libc/sys/rmdir.2 new file mode 100644 index 000000000000..597c94647fae --- /dev/null +++ b/lib/libc/sys/rmdir.2 @@ -0,0 +1,118 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)rmdir.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd December 9, 2006 +.Dt RMDIR 2 +.Os +.Sh NAME +.Nm rmdir +.Nd remove a directory file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn rmdir "const char *path" +.Sh DESCRIPTION +The +.Fn rmdir +system call +removes a directory file +whose name is given by +.Fa path . +The directory must not have any entries other +than +.Ql .\& +and +.Ql \&.. . +.Sh RETURN VALUES +.Rv -std rmdir +.Sh ERRORS +The named file is removed unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named directory does not exist. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENOTEMPTY +The named directory contains files other than +.Ql .\& +and +.Ql ..\& +in it. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write permission is denied on the directory containing the link +to be removed. +.It Bq Er EPERM +The directory to be removed has its immutable, undeletable or append-only flag +set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the directory to be removed has its immutable or +append-only flag set. +.It Bq Er EPERM +The directory containing the directory to be removed is marked sticky, +and neither the containing directory nor the directory to be removed +are owned by the effective user ID. +.It Bq Er EINVAL +The last component of the path is +.Ql .\& +or +.Ql .. . +.It Bq Er EBUSY +The directory to be removed is the mount point +for a mounted file system. +.It Bq Er EIO +An I/O error occurred while deleting the directory entry +or deallocating the inode. +.It Bq Er EROFS +The directory entry to be removed resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr mkdir 2 , +.Xr unlink 2 +.Sh HISTORY +The +.Fn rmdir +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/rtprio.2 b/lib/libc/sys/rtprio.2 new file mode 100644 index 000000000000..23088a705967 --- /dev/null +++ b/lib/libc/sys/rtprio.2 @@ -0,0 +1,199 @@ +.\"- +.\" Copyright (c) 1994, Henrik Vestergaard Draboel +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Henrik Vestergaard Draboel. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\"- +.\" Copyright (c) 2011 Xin LI <delphij@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 27, 2011 +.Dt RTPRIO 2 +.Os +.Sh NAME +.Nm rtprio , +.Nm rtprio_thread +.Nd examine or modify realtime or idle priority +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/rtprio.h +.Ft int +.Fn rtprio "int function" "pid_t pid" "struct rtprio *rtp" +.Ft int +.Fn rtprio_thread "int function" "lwpid_t lwpid" "struct rtprio *rtp" +.Sh DESCRIPTION +The +.Fn rtprio +system call +is used to lookup or change the realtime or idle priority of a process, +or the calling thread. +The +.Fn rtprio_thread +system call +is used to lookup or change the realtime or idle priority of a thread. +.Pp +The +.Fa function +argument +specifies the operation to be performed. +RTP_LOOKUP to lookup the current priority, +and RTP_SET to set the priority. +.Pp +For the +.Fn rtprio +system call, +the +.Fa pid +argument +specifies the process to operate on, +0 for the calling thread. +When +.Fa pid +is non-zero, +the system call reports the highest priority in the process, +or sets all threads' priority in the process, +depending on value of the +.Fa function +argument. +.Pp +For the +.Fn rtprio_thread +system call, +the +.Fa lwpid +specifies the thread to operate on, +0 for the calling thread. +.Pp +The +.Fa *rtp +argument +is a pointer to a struct rtprio which is used to specify the priority and priority type. +This structure has the following form: +.Bd -literal +struct rtprio { + u_short type; + u_short prio; +}; +.Ed +.Pp +The value of the +.Va type +field may be RTP_PRIO_REALTIME for realtime priorities, +RTP_PRIO_NORMAL for normal priorities, and RTP_PRIO_IDLE for idle priorities. +The priority specified by the +.Va prio +field ranges between 0 and +.Dv RTP_PRIO_MAX +.Pq usually 31 . +0 is the highest possible priority. +.Pp +Realtime and idle priority is inherited through fork() and exec(). +.Pp +A realtime thread can only be preempted by a thread of equal or +higher priority, or by an interrupt; idle priority threads will run only +when no other real/normal priority thread is runnable. +Higher real/idle priority threads +preempt lower real/idle priority threads. +Threads of equal real/idle priority are run round-robin. +.Sh RETURN VALUES +.Rv -std rtprio rtprio_thread +.Sh ERRORS +The +.Fn rtprio +and +.Fn rtprio_thread +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The rtp pointer passed to +.Fn rtprio +or +.Fn rtprio_thread +was invalid. +.It Bq Er EINVAL +The specified +.Fa prio +was out of range. +.It Bq Er EPERM +The calling thread is not allowed to set the realtime priority. +Only +root is allowed to change the realtime priority of any thread, and non-root +may only change the idle priority of threads the user owns, +when the +.Xr sysctl 8 +variable +.Va security.bsd.unprivileged_idprio +is set to non-zero. +.It Bq Er ESRCH +The specified process or thread was not found or visible. +.El +.Sh SEE ALSO +.Xr nice 1 , +.Xr ps 1 , +.Xr rtprio 1 , +.Xr setpriority 2 , +.Xr nice 3 , +.Xr renice 8 , +.Xr p_cansee 9 +.Sh AUTHORS +.An -nosplit +The original author was +.An Henrik Vestergaard Draboel Aq Mt hvd@terry.ping.dk . +This implementation in +.Fx +was substantially rewritten by +.An David Greenman . +The +.Fn rtprio_thread +system call was implemented by +.An David Xu . diff --git a/lib/libc/sys/sched_get_priority_max.2 b/lib/libc/sys/sched_get_priority_max.2 new file mode 100644 index 000000000000..88d1d6d1460d --- /dev/null +++ b/lib/libc/sys/sched_get_priority_max.2 @@ -0,0 +1,123 @@ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 12, 1998 +.Dt SCHED_GET_PRIORITY_MAX 2 +.Os +.Sh NAME +.Nm sched_get_priority_max , +.Nm sched_get_priority_min , +.Nm sched_rr_get_interval +.Nd get scheduling parameter limits +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_get_priority_max "int policy" +.Ft int +.Fn sched_get_priority_min "int policy" +.Ft int +.Fn sched_rr_get_interval "pid_t pid" "struct timespec *interval" +.Sh DESCRIPTION +The +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +system calls return the appropriate maximum or minimum, respectively, +for the scheduling policy specified by +.Fa policy . +The +.Fn sched_rr_get_interval +system call updates the +.Fa timespec +structure referenced by the +.Fa interval +argument to contain the current execution time limit (i.e., time +quantum) for the process specified by +.Fa pid . +If +.Fa pid +is zero, the current execution time limit for the calling process is +returned. +.Pp +The value of +.Fa policy +should be one of the scheduling policy values defined in +.Fa <sched.h> : +.Bl -tag -width [SCHED_OTHER] +.It Bq Er SCHED_FIFO +First-in-first-out fixed priority scheduling with no round robin scheduling; +.It Bq Er SCHED_OTHER +The standard time sharing scheduler; +.It Bq Er SCHED_RR +Round-robin scheduling across same priority processes. +.El +.Sh RETURN VALUES +If successful, the +.Fn sched_get_priority_max +and +.Fn sched_get_priority_min +system calls shall return the appropriate maximum or minimum values, +respectively. +If unsuccessful, they shall return a value of -1 and set +.Fa errno +to indicate the error. +.Pp +.Rv -std sched_rr_get_interval +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er EINVAL +The value of the +.Fa policy +argument does not represent a defined scheduling policy. +.It Bq Er ENOSYS +The +.Fn sched_get_priority_max , +.Fn sched_get_priority_min , +and +.Fn sched_rr_get_interval +system calls are not supported by the implementation. +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid . +.El +.Sh SEE ALSO +.Xr sched_getparam 2 , +.Xr sched_getscheduler 2 , +.Xr sched_setparam 2 , +.Xr sched_setscheduler 2 +.Sh STANDARDS +The +.Fn sched_get_priority_max , +.Fn sched_get_priority_min , +and +.Fn sched_rr_get_interval +system calls conform to +.St -p1003.1b-93 . diff --git a/lib/libc/sys/sched_setparam.2 b/lib/libc/sys/sched_setparam.2 new file mode 100644 index 000000000000..315fd826cc7d --- /dev/null +++ b/lib/libc/sys/sched_setparam.2 @@ -0,0 +1,174 @@ +.\" $FreeBSD$ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 12, 1998 +.Dt SCHED_SETPARAM 2 +.Os +.Sh NAME +.Nm sched_setparam , +.Nm sched_getparam +.Nd set/get scheduling parameters +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_setparam "pid_t pid" "const struct sched_param *param" +.Ft int +.Fn sched_getparam "pid_t pid" "struct sched_param *param" +.Sh DESCRIPTION +The +.Fn sched_setparam +system call sets the scheduling parameters of the process specified by +.Fa pid +to the values specified by the +.Fa sched_param +structure pointed to by +.Fa param . +The value of the +.Fa sched_priority +member in the +.Fa param +structure must be any integer within the inclusive priority range for +the current scheduling policy of the process specified by +.Fa pid . +Higher numerical values for the priority represent higher priorities. +.Pp +In this implementation, if the value of +.Fa pid +is negative the system call will fail. +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, the scheduling +parameters are set for the process whose process ID is equal to +.Fa pid . +.Pp +If +.Fa pid +is zero, the scheduling parameters are set for the calling process. +.Pp +In this implementation, the policy of when a process can affect +the scheduling parameters of another process is specified in +.St -p1003.1b-93 +as a write-style operation. +.Pp +The target process, whether it is running or not running, will resume +execution after all other runnable processes of equal or greater +priority have been scheduled to run. +.Pp +If the priority of the process specified by the +.Fa pid +argument is set higher than that of the lowest priority running process +and if the specified process is ready to run, the process specified by +the +.Fa pid +argument will preempt a lowest priority running process. +Similarly, if +the process calling +.Fn sched_setparam +sets its own priority lower than that of one or more other nonempty +process lists, then the process that is the head of the highest priority +list will also preempt the calling process. +Thus, in either case, the +originating process might not receive notification of the completion of +the requested priority change until the higher priority process has +executed. +.Pp +In this implementation, when the current scheduling policy for the +process specified by +.Fa pid +is normal timesharing (SCHED_OTHER, aka SCHED_NORMAL when not POSIX-source) +or the idle policy (SCHED_IDLE when not POSIX-source) then the behavior +is as if the process had been running under SCHED_RR with a priority +lower than any actual realtime priority. +.Pp +The +.Fn sched_getparam +system call will return the scheduling parameters of a process specified +by +.Fa pid +in the +.Fa sched_param +structure pointed to by +.Fa param . +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, +the scheduling parameters for the process whose process ID is equal to +.Fa pid +are returned. +.Pp +In this implementation, the policy of when a process can obtain the +scheduling parameters of another process are detailed in +.St -p1003.1b-93 +as a read-style operation. +.Pp +If +.Fa pid +is zero, the scheduling parameters for the calling process will be +returned. +In this implementation, the +.Fa sched_getparam +system call will fail if +.Fa pid +is negative. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOSYS +The system is not configured to support this functionality. +.It Bq Er EPERM +The requesting process doesn not have permission as detailed in +.St -p1003.1b-93 . +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid . +.It Bq Er EINVAL +For +.Fn sched_setparam : +one or more of the requested scheduling parameters +is outside the range defined for the scheduling policy of the specified +.Fa pid . +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 2 , +.Xr sched_getscheduler 2 , +.Xr sched_rr_get_interval 2 , +.Xr sched_setscheduler 2 , +.Xr sched_yield 2 +.Sh STANDARDS +The +.Fn sched_setparam +and +.Fn sched_getparam +system calls conform to +.St -p1003.1b-93 . diff --git a/lib/libc/sys/sched_setscheduler.2 b/lib/libc/sys/sched_setscheduler.2 new file mode 100644 index 000000000000..b84c1a1c9e35 --- /dev/null +++ b/lib/libc/sys/sched_setscheduler.2 @@ -0,0 +1,166 @@ +.\" $FreeBSD$ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 12, 1998 +.Dt SCHED_SETSCHEDULER 2 +.Os +.Sh NAME +.Nm sched_setscheduler , +.Nm sched_getscheduler +.Nd set/get scheduling policy and scheduler parameters +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param" +.Ft int +.Fn sched_getscheduler "pid_t pid" +.Sh DESCRIPTION +The +.Fn sched_setscheduler +system call sets the scheduling policy and scheduling parameters +of the process specified by +.Fa pid +to +.Fa policy +and the parameters specified in the +.Vt sched_param +structure pointed to by +.Fa param , +respectively. +The value of the +.Fa sched_priority +member in the +.Fa param +structure must be any integer within the inclusive priority range for +the scheduling policy specified by +.Fa policy . +.Pp +In this implementation, if the value of +.Fa pid +is negative the system call will fail. +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, the scheduling +policy and scheduling parameters will be set for the process +whose process ID is equal to +.Fa pid . +.Pp +If +.Fa pid +is zero, the scheduling policy and scheduling +parameters are set for the calling process. +.Pp +In this implementation, the policy of when a process can affect +the scheduling parameters of another process is specified in +.St -p1003.1b-93 +as a write-style operation. +.Pp +The scheduling policies are in +.Fa <sched.h> : +.Bl -tag -width [SCHED_OTHER] +.It Bq Er SCHED_FIFO +First-in-first-out fixed priority scheduling with no round robin scheduling; +.It Bq Er SCHED_OTHER +The standard time sharing scheduler; +.It Bq Er SCHED_RR +Round-robin scheduling across same priority processes. +.El +.Pp +The +.Vt sched_param +structure is defined in +.Fa <sched.h> : +.Bd -literal -offset indent +struct sched_param { + int sched_priority; /* scheduling priority */ +}; +.Ed +.Pp +The +.Fn sched_getscheduler +system call returns the scheduling policy of the process specified +by +.Fa pid . +.Pp +If a process specified by +.Fa pid +exists and if the calling process has permission, +the scheduling parameters for the process whose process ID is equal to +.Fa pid +are returned. +.Pp +In this implementation, the policy of when a process can obtain the +scheduling parameters of another process are detailed in +.St -p1003.1b-93 +as a read-style operation. +.Pp +If +.Fa pid +is zero, the scheduling parameters for the calling process will be +returned. +In this implementation, the +.Fa sched_getscheduler +system call will fail if +.Fa pid +is negative. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOSYS +The system is not configured to support this functionality. +.It Bq Er EPERM +The requesting process doesn not have permission as detailed in +.St -p1003.1b-93 . +.It Bq Er ESRCH +No process can be found corresponding to that specified by +.Fa pid . +.It Bq Er EINVAL +The value of the +.Fa policy +argument is invalid, or one or more of the parameters contained in +.Fa param +is outside the valid range for the specified scheduling policy. +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 2 , +.Xr sched_getparam 2 , +.Xr sched_rr_get_interval 2 , +.Xr sched_setparam 2 , +.Xr sched_yield 2 +.Sh STANDARDS +The +.Fn sched_setscheduler +and +.Fn sched_getscheduler +system calls conform to +.St -p1003.1b-93 . diff --git a/lib/libc/sys/sched_yield.2 b/lib/libc/sys/sched_yield.2 new file mode 100644 index 000000000000..9db8942249e2 --- /dev/null +++ b/lib/libc/sys/sched_yield.2 @@ -0,0 +1,58 @@ +.\" $FreeBSD$ +.\" Copyright (c) 1998 HD Associates, Inc. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 12, 1998 +.Dt SCHED_YIELD 2 +.Os +.Sh NAME +.Nm sched_yield +.Nd yield processor +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sched.h +.Ft int +.Fn sched_yield void +.Sh DESCRIPTION +The +.Fn sched_yield +system call forces the running process to relinquish the processor until it +again becomes the head of its process list. +It takes no arguments. +.Sh RETURN VALUES +.Rv -std sched_yield +.Sh ERRORS +On failure +.Va errno +will be set to the corresponding value: +.Bl -tag -width Er +.It Bq Er ENOSYS +The system is not configured to support this functionality. +.El +.Sh STANDARDS +The +.Fn sched_yield +system call conforms to +.St -p1003.1b-93 . diff --git a/lib/libc/sys/sctp_generic_recvmsg.2 b/lib/libc/sys/sctp_generic_recvmsg.2 new file mode 100644 index 000000000000..8ee3d36f90e9 --- /dev/null +++ b/lib/libc/sys/sctp_generic_recvmsg.2 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 30, 2007 +.Dt SCTP_GENERIC_RECVMSG 2 +.Os +.Sh NAME +.Nm sctp_generic_recvmsg +.Nd receive data from a peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_generic_recvmsg "int s" "struct iovec *iov" "int iovlen" "struct sockaddr *from" "socklen_t *fromlen" "struct sctp_sndrcvinfo *sinfo" "int *msgflags" +.Sh DESCRIPTION +.Fn sctp_generic_recvmsg +is the true system call used by the +.Xr sctp_recvmsg 3 +function call. +This call is more efficient since it is a +true system call but it is specific to +.Fx +and can be expected +.Em not +to be present on any other operating +system. +For detailed usage please see the +.Xr sctp_recvmsg 3 +function call. +.Sh RETURN VALUES +The call returns the number of bytes read on success and -1 upon failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp_recvmsg 3 , +.Xr sctp 4 diff --git a/lib/libc/sys/sctp_generic_sendmsg.2 b/lib/libc/sys/sctp_generic_sendmsg.2 new file mode 100644 index 000000000000..bf54e95473d5 --- /dev/null +++ b/lib/libc/sys/sctp_generic_sendmsg.2 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 30, 2007 +.Dt SCTP_GENERIC_SENDMSG 2 +.Os +.Sh NAME +.Nm sctp_generic_sendmsg +.Nm sctp_generic_sendmsg_iov +.Nd send data to a peer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_generic_sendmsg "int s" "void *msg" "int msglen" "struct sockaddr *to" "socklen_t len" "struct sctp_sndrcvinfo *sinfo" "int flags" +.Ft int +.Fn sctp_generic_sendmsg_iov "int s" "struct iovec *iov" "int iovlen" "struct sockaddr *to" "struct sctp_sndrcvinfo *sinfo" "int flags" +.Sh DESCRIPTION +.Fn sctp_generic_sendmsg +and +.Fn sctp_generic_sendmsg_iov +are the true system calls used by the +.Xr sctp_sendmsg 3 +and +.Xr sctp_send 3 +function calls. +These are more efficient since they are +true system calls but they are specific to +.Fx +and can be expected +.Em not +to be present on any other operating +system. +For detailed usage please see either the +.Xr sctp_send 3 +or +.Xr sctp_sendmsg 3 +function calls. +.Sh RETURN VALUES +The call returns the number of bytes written on success and -1 upon failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp_send 3 , +.Xr sctp_sendmsg 3 , +.Xr sctp_sendmsgx 3 , +.Xr sctp_sendx 3 , +.Xr sctp 4 diff --git a/lib/libc/sys/sctp_peeloff.2 b/lib/libc/sys/sctp_peeloff.2 new file mode 100644 index 000000000000..9964586c9e9e --- /dev/null +++ b/lib/libc/sys/sctp_peeloff.2 @@ -0,0 +1,76 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 30, 2007 +.Dt SCTP_PEELOFF 2 +.Os +.Sh NAME +.Nm sctp_peeloff +.Nd detach an association from a one-to-many socket to its own fd +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In netinet/sctp.h +.Ft int +.Fn sctp_peeloff "int s" "sctp_assoc_t id" +.Sh DESCRIPTION +The +.Fn sctp_peeloff +system call attempts detach the association specified by +.Fa id +into its own separate socket. +.Sh RETURN VALUES +The call returns -1 on failure and the new socket descriptor +upon success. +.Sh ERRORS +The +.Fn sctp_peeloff +system call can return the following errors: +.Bl -tag -width Er +.It Bq Er ENOTCONN +The +.Fa id +given to the call does not map to a valid +association. +.It Bq Er E2BIG +The size of the address list exceeds the amount of +data provided. +.It Bq Er EBADF +The argument +.Fa s +is not a valid descriptor. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.El +.Sh SEE ALSO +.Xr sctp 4 diff --git a/lib/libc/sys/select.2 b/lib/libc/sys/select.2 new file mode 100644 index 000000000000..59a79984f546 --- /dev/null +++ b/lib/libc/sys/select.2 @@ -0,0 +1,227 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)select.2 8.2 (Berkeley) 3/25/94 +.\" $FreeBSD$ +.\" +.Dd November 17, 2002 +.Dt SELECT 2 +.Os +.Sh NAME +.Nm select +.Nd synchronous I/O multiplexing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/select.h +.Ft int +.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout" +.Fn FD_SET fd &fdset +.Fn FD_CLR fd &fdset +.Fn FD_ISSET fd &fdset +.Fn FD_ZERO &fdset +.Sh DESCRIPTION +The +.Fn select +system call +examines the I/O descriptor sets whose addresses are passed in +.Fa readfds , +.Fa writefds , +and +.Fa exceptfds +to see if some of their descriptors +are ready for reading, are ready for writing, or have an exceptional +condition pending, respectively. +The only exceptional condition detectable is out-of-band +data received on a socket. +The first +.Fa nfds +descriptors are checked in each set; +i.e., the descriptors from 0 through +.Fa nfds Ns No -1 +in the descriptor sets are examined. +On return, +.Fn select +replaces the given descriptor sets +with subsets consisting of those descriptors that are ready +for the requested operation. +The +.Fn select +system call +returns the total number of ready descriptors in all the sets. +.Pp +The descriptor sets are stored as bit fields in arrays of integers. +The following macros are provided for manipulating such descriptor sets: +.Fn FD_ZERO &fdset +initializes a descriptor set +.Fa fdset +to the null set. +.Fn FD_SET fd &fdset +includes a particular descriptor +.Fa fd +in +.Fa fdset . +.Fn FD_CLR fd &fdset +removes +.Fa fd +from +.Fa fdset . +.Fn FD_ISSET fd &fdset +is non-zero if +.Fa fd +is a member of +.Fa fdset , +zero otherwise. +The behavior of these macros is undefined if +a descriptor value is less than zero or greater than or equal to +.Dv FD_SETSIZE , +which is normally at least equal +to the maximum number of descriptors supported by the system. +.Pp +If +.Fa timeout +is not a null pointer, it specifies the maximum interval to wait for the +selection to complete. +System activity can lengthen the interval by +an indeterminate amount. +.Pp +If +.Fa timeout +is a null pointer, the select blocks indefinitely. +.Pp +To effect a poll, the +.Fa timeout +argument should not be a null pointer, +but it should point to a zero-valued timeval structure. +.Pp +Any of +.Fa readfds , +.Fa writefds , +and +.Fa exceptfds +may be given as null pointers if no descriptors are of interest. +.Sh RETURN VALUES +The +.Fn select +system call +returns the number of ready descriptors that are contained in +the descriptor sets, +or -1 if an error occurred. +If the time limit expires, +.Fn select +returns 0. +If +.Fn select +returns with an error, +including one due to an interrupted system call, +the descriptor sets will be unmodified. +.Sh ERRORS +An error return from +.Fn select +indicates: +.Bl -tag -width Er +.It Bq Er EBADF +One of the descriptor sets specified an invalid descriptor. +.It Bq Er EFAULT +One of the arguments +.Fa readfds , writefds , exceptfds , +or +.Fa timeout +points to an invalid address. +.It Bq Er EINTR +A signal was delivered before the time limit expired and +before any of the selected events occurred. +.It Bq Er EINVAL +The specified time limit is invalid. +One of its components is +negative or too large. +.It Bq Er EINVAL +The +.Fa nfds +argument +was invalid. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr getdtablesize 2 , +.Xr gettimeofday 2 , +.Xr kqueue 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr write 2 , +.Xr clocks 7 +.Sh NOTES +The default size of +.Dv FD_SETSIZE +is currently 1024. +In order to accommodate programs which might potentially +use a larger number of open files with +.Fn select , +it is possible +to increase this size by having the program define +.Dv FD_SETSIZE +before the inclusion of any header which includes +.In sys/types.h . +.Pp +If +.Fa nfds +is greater than the number of open files, +.Fn select +is not guaranteed to examine the unused file descriptors. +For historical +reasons, +.Fn select +will always examine the first 256 descriptors. +.Sh STANDARDS +The +.Fn select +system call and +.Fn FD_CLR , +.Fn FD_ISSET , +.Fn FD_SET , +and +.Fn FD_ZERO +macros conform with +.St -p1003.1-2001 . +.Sh HISTORY +The +.Fn select +system call appeared in +.Bx 4.2 . +.Sh BUGS +.St -susv2 +allows systems to modify the original timeout in place. +Thus, it is unwise to assume that the timeout value will be unmodified +by the +.Fn select +system call. +.Fx +does not modify the return value, which can cause problems for applications +ported from other systems. diff --git a/lib/libc/sys/select.c b/lib/libc/sys/select.c new file mode 100644 index 000000000000..3990496ec412 --- /dev/null +++ b/lib/libc/sys/select.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/select.h> +#include "libc_private.h" + +__weak_reference(__sys_select, __select); + +#pragma weak select +int +select(int n, fd_set *rs, fd_set *ws, fd_set *es, struct timeval *t) +{ + + return (((int (*)(int, fd_set *, fd_set *, fd_set *, struct timeval *)) + __libc_interposing[INTERPOS_select])(n, rs, ws, es, t)); +} diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 new file mode 100644 index 000000000000..adfb9ef52d79 --- /dev/null +++ b/lib/libc/sys/semctl.2 @@ -0,0 +1,200 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 12, 1995 +.Dt SEMCTL 2 +.Os +.Sh NAME +.Nm semctl +.Nd control operations on a semaphore set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/sem.h +.Ft int +.Fn semctl "int semid" "int semnum" "int cmd" ... +.Sh DESCRIPTION +The +.Fn semctl +system call +performs the operation indicated by +.Fa cmd +on the semaphore set indicated by +.Fa semid . +A fourth argument, a +.Fa "union semun arg" , +is required for certain values of +.Fa cmd . +For the commands that use the +.Fa arg +argument, +.Fa "union semun" +is defined as follows: +.\" +.\" From <sys/sem.h>: +.\" +.Bd -literal +union semun { + int val; /* value for SETVAL */ + struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ + u_short *array; /* array for GETALL & SETALL */ +}; +.Ed +.Pp +Commands are performed as follows: +.\" +.\" This section based on Stevens, _Advanced Programming in the UNIX +.\" Environment_. +.\" +.Bl -tag -width IPC_RMIDXXX +.It Dv IPC_STAT +Fetch the semaphore set's +.Fa "struct semid_ds" , +storing it in the memory pointed to by +.Fa arg.buf . +.It Dv IPC_SET +Changes the +.Fa sem_perm.uid , +.Fa sem_perm.gid , +and +.Fa sem_perm.mode +members of the semaphore set's +.Fa "struct semid_ds" +to match those of the struct pointed to by +.Fa arg.buf . +The calling process's effective uid must +match either +.Fa sem_perm.uid +or +.Fa sem_perm.cuid , +or it must have superuser privileges. +.It IPC_RMID +Immediately removes the semaphore set from the system. +The calling +process's effective uid must equal the semaphore set's +.Fa sem_perm.uid +or +.Fa sem_perm.cuid , +or the process must have superuser privileges. +.It Dv GETVAL +Return the value of semaphore number +.Fa semnum . +.It Dv SETVAL +Set the value of semaphore number +.Fa semnum +to +.Fa arg.val . +Outstanding adjust on exit values for this semaphore in any process +are cleared. +.It Dv GETPID +Return the pid of the last process to perform an operation on +semaphore number +.Fa semnum . +.It Dv GETNCNT +Return the number of processes waiting for semaphore number +.Fa semnum Ns 's +value to become greater than its current value. +.It Dv GETZCNT +Return the number of processes waiting for semaphore number +.Fa semnum Ns 's +value to become 0. +.It Dv GETALL +Fetch the value of all of the semaphores in the set into the +array pointed to by +.Fa arg.array . +.It Dv SETALL +Set the values of all of the semaphores in the set to the values +in the array pointed to by +.Fa arg.array . +Outstanding adjust on exit values for all semaphores in this set, +in any process are cleared. +.El +.Pp +The +.Vt "struct semid_ds" +is defined as follows: +.\" +.\" Taken straight from <sys/sem.h>. +.\" +.Bd -literal +struct semid_ds { + struct ipc_perm sem_perm; /* operation permission struct */ + struct sem *sem_base; /* pointer to first semaphore in set */ + u_short sem_nsems; /* number of sems in set */ + time_t sem_otime; /* last operation time */ + time_t sem_ctime; /* last change time */ + /* Times measured in secs since */ + /* 00:00:00 GMT, Jan. 1, 1970 */ +}; +.Ed +.Sh RETURN VALUES +On success, when +.Fa cmd +is one of +.Dv GETVAL , GETPID , GETNCNT +or +.Dv GETZCNT , +.Fn semctl +returns the corresponding value; otherwise, 0 is returned. +On failure, -1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn semctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No semaphore set corresponds to +.Fa semid . +.It Bq Er EINVAL +The +.Fa semnum +argument +is not in the range of valid semaphores for given semaphore set. +.It Bq Er EPERM +The calling process's effective uid does not match the uid of +the semaphore set's owner or creator. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +semaphore set. +.It Bq Er ERANGE +.Dv SETVAL +or +.Dv SETALL +attempted to set a semaphore outside the allowable range +.Bq 0 .. Dv SEMVMX . +.El +.Sh SEE ALSO +.Xr semget 2 , +.Xr semop 2 +.Sh BUGS +.Dv SETALL +may update some semaphore elements before returning an error. diff --git a/lib/libc/sys/semget.2 b/lib/libc/sys/semget.2 new file mode 100644 index 000000000000..debcf11224ae --- /dev/null +++ b/lib/libc/sys/semget.2 @@ -0,0 +1,159 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 7, 2016 +.Dt SEMGET 2 +.Os +.Sh NAME +.Nm semget +.Nd obtain a semaphore id +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/sem.h +.Ft int +.Fn semget "key_t key" "int nsems" "int flag" +.Sh DESCRIPTION +Based on the values of +.Fa key +and +.Fa flag , +.Fn semget +returns the identifier of a newly created or previously existing +set of semaphores. +.\" +.\" This is copied verbatim from the shmget manpage. Perhaps +.\" it should go in a common manpage, such as .Xr ipc 2 +.\" +The key +is analogous to a filename: it provides a handle that names an +IPC object. +There are three ways to specify a key: +.Bl -bullet +.It +IPC_PRIVATE may be specified, in which case a new IPC object +will be created. +.It +An integer constant may be specified. +If no IPC object corresponding +to +.Fa key +is specified and the IPC_CREAT bit is set in +.Fa flag , +a new one will be created. +.It +The +.Xr ftok 3 +function +may be used to generate a key from a pathname. +.El +.\" +.\" Likewise for this section, except SHM_* becomes SEM_*. +.\" +.Pp +The mode of a newly created IPC object is determined by +.Em OR Ns 'ing +the following constants into the +.Fa flag +argument: +.Bl -tag -width XSEM_WXX6XXX +.It Dv SEM_R +Read access for user. +.It Dv SEM_A +Alter access for user. +.It Dv ( SEM_R>>3 ) +Read access for group. +.It Dv ( SEM_A>>3 ) +Alter access for group. +.It Dv ( SEM_R>>6 ) +Read access for other. +.It Dv ( SEM_A>>6 ) +Alter access for other. +.El +.Pp +If a new set of semaphores is being created, +.Fa nsems +is used to indicate the number of semaphores the set should contain. +Otherwise, +.Fa nsems +may be specified as 0. +.Sh RETURN VALUES +The +.Fn semget +system call +returns the id of a semaphore set if successful; otherwise, -1 +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn semget +system call +will fail if: +.Bl -tag -width Er +.\" ipcperm could fail (we are opening to read and write, as it were) +.It Bq Er EACCES +Access permission failure. +.\" +.\" sysv_sem.c is quite explicit about these, so I'm pretty sure +.\" this is accurate +.\" +.It Bq Er EEXIST +IPC_CREAT and IPC_EXCL were specified, and a semaphore set +corresponding to +.Fa key +already exists. +.It Bq Er EINVAL +The number of semaphores requested exceeds the system imposed maximum +per set. +.It Bq Er EINVAL +A semaphore set corresponding to +.Fa key +already exists and contains fewer semaphores than +.Fa nsems . +.It Bq Er EINVAL +A semaphore set corresponding to +.Fa key +does not exist and +.Fa nsems +is 0 or negative. +.It Bq Er ENOSPC +Insufficiently many semaphores are available. +.It Bq Er ENOSPC +The kernel could not allocate a +.Fa "struct semid_ds" . +.It Bq Er ENOENT +No semaphore set was found corresponding to +.Fa key , +and IPC_CREAT was not specified. +.El +.Sh SEE ALSO +.Xr semctl 2 , +.Xr semop 2 , +.Xr ftok 3 diff --git a/lib/libc/sys/semop.2 b/lib/libc/sys/semop.2 new file mode 100644 index 000000000000..a08f65e8e8bd --- /dev/null +++ b/lib/libc/sys/semop.2 @@ -0,0 +1,289 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 22, 1995 +.Dt SEMOP 2 +.Os +.Sh NAME +.Nm semop +.Nd atomic array of operations on a semaphore set +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/sem.h +.Ft int +.Fn semop "int semid" "struct sembuf *array" "size_t nops" +.Sh DESCRIPTION +The +.Fn semop +system call +atomically performs the array of operations indicated by +.Fa array +on the semaphore set indicated by +.Fa semid . +The length of +.Fa array +is indicated by +.Fa nops . +Each operation is encoded in a +.Vt "struct sembuf" , +which is defined as follows: +.\" +.\" From <sys/sem.h> +.\" +.Bd -literal +struct sembuf { + u_short sem_num; /* semaphore # */ + short sem_op; /* semaphore operation */ + short sem_flg; /* operation flags */ +}; +.Ed +.Pp +For each element in +.Fa array , +.Va sem_op +and +.Va sem_flg +determine an operation to be performed on semaphore number +.Va sem_num +in the set. +The values +.Dv SEM_UNDO +and +.Dv IPC_NOWAIT +may be +.Em OR Ns 'ed +into the +.Va sem_flg +member in order to modify the behavior of the given operation. +.Pp +The operation performed depends as follows on the value of +.Va sem_op : +.\" +.\" This section is based on the description of semop() in +.\" Stevens, _Advanced Programming in the UNIX Environment_, +.\" and the semop(2) description in The Open Group Unix2 specification. +.\" +.Bl -bullet +.It +When +.Va sem_op +is positive and the process has alter permission, +the semaphore's value is incremented by +.Va sem_op Ns 's +value. +If +.Dv SEM_UNDO +is specified, the semaphore's adjust on exit value is decremented by +.Va sem_op Ns 's +value. +A positive value for +.Va sem_op +generally corresponds to a process releasing a resource +associated with the semaphore. +.It +The behavior when +.Va sem_op +is negative and the process has alter permission, +depends on the current value of the semaphore: +.Bl -bullet +.It +If the current value of the semaphore is greater than or equal to +the absolute value of +.Va sem_op , +then the value is decremented by the absolute value of +.Va sem_op . +If +.Dv SEM_UNDO +is specified, the semaphore's adjust on exit +value is incremented by the absolute value of +.Va sem_op . +.It +If the current value of the semaphore is less than the absolute value of +.Va sem_op , +one of the following happens: +.\" XXX a *second* sublist? +.Bl -bullet +.It +If +.Dv IPC_NOWAIT +was specified, then +.Fn semop +returns immediately with a return value of +.Er EAGAIN . +.It +Otherwise, the calling process is put to sleep until one of the following +conditions is satisfied: +.\" XXX We already have two sublists, why not a third? +.Bl -bullet +.It +Some other process removes the semaphore with the +.Dv IPC_RMID +option of +.Xr semctl 2 . +In this case, +.Fn semop +returns immediately with a return value of +.Er EIDRM . +.It +The process receives a signal that is to be caught. +In this case, the process will resume execution as defined by +.Xr sigaction 2 . +.It +The semaphore's +value is greater than or equal to the absolute value of +.Va sem_op . +When this condition becomes true, the semaphore's value is decremented +by the absolute value of +.Va sem_op , +the semaphore's adjust on exit value is incremented by the +absolute value of +.Va sem_op . +.El +.El +.El +.Pp +A negative value for +.Va sem_op +generally means that a process is waiting for a resource to become +available. +.It +When +.Va sem_op +is zero and the process has read permission, +one of the following will occur: +.Bl -bullet +.It +If the current value of the semaphore is equal to zero +then +.Fn semop +can return immediately. +.It +If +.Dv IPC_NOWAIT +was specified, then +.Fn semop +returns immediately with a return value of +.Er EAGAIN . +.It +Otherwise, the calling process is put to sleep until one of the following +conditions is satisfied: +.\" XXX Another nested sublists +.Bl -bullet +.It +Some other process removes the semaphore with the +.Dv IPC_RMID +option of +.Xr semctl 2 . +In this case, +.Fn semop +returns immediately with a return value of +.Er EIDRM . +.It +The process receives a signal that is to be caught. +In this case, the process will resume execution as defined by +.Xr sigaction 2 . +.It +The semaphore's value becomes zero. +.El +.El +.El +.Pp +For each semaphore a process has in use, the kernel maintains an +.Dq "adjust on exit" +value, as alluded to earlier. +When a process +exits, either voluntarily or involuntarily, the adjust on exit value +for each semaphore is added to the semaphore's value. +This can +be used to ensure that a resource is released if a process terminates +unexpectedly. +.Sh RETURN VALUES +.Rv -std semop +.Sh ERRORS +The +.Fn semop +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No semaphore set corresponds to +.Fa semid , +or the process would exceed the system-defined limit for the number of +per-process +.Dv SEM_UNDO +structures. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +semaphore set. +.It Bq Er EAGAIN +The semaphore's value would have resulted in the process being put to sleep +and +.Dv IPC_NOWAIT +was specified. +.It Bq Er E2BIG +Too many operations were specified. +.Bq Dv SEMOPM +.It Bq Er EFBIG +.\" +.\" I'd have thought this would be EINVAL, but the source says +.\" EFBIG. +.\" +.Va sem_num +was not in the range of valid semaphores for the set. +.It Bq Er EIDRM +The semaphore set was removed from the system. +.It Bq Er EINTR +The +.Fn semop +system call was interrupted by a signal. +.It Bq Er ENOSPC +The system +.Dv SEM_UNDO +pool +.Bq Dv SEMMNU +is full. +.It Bq Er ERANGE +The requested operation would cause either +the semaphore's current value +.Bq Dv SEMVMX +or its adjust on exit value +.Bq Dv SEMAEM +to exceed the system-imposed limits. +.El +.Sh SEE ALSO +.Xr semctl 2 , +.Xr semget 2 , +.Xr sigaction 2 +.Sh BUGS +The +.Fn semop +system call +may block waiting for memory even if +.Dv IPC_NOWAIT +was specified. diff --git a/lib/libc/sys/send.2 b/lib/libc/sys/send.2 new file mode 100644 index 000000000000..160bda1a0e62 --- /dev/null +++ b/lib/libc/sys/send.2 @@ -0,0 +1,269 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 +.\" $FreeBSD$ +.\" +.Dd August 18, 2016 +.Dt SEND 2 +.Os +.Sh NAME +.Nm send , +.Nm sendto , +.Nm sendmsg , +.Nm sendmmsg +.Nd send message(s) from a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft ssize_t +.Fn send "int s" "const void *msg" "size_t len" "int flags" +.Ft ssize_t +.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen" +.Ft ssize_t +.Fn sendmsg "int s" "const struct msghdr *msg" "int flags" +.Ft ssize_t +.Fn sendmmsg "int s" "struct mmsghdr * restrict msgvec" "size_t vlen" "int flags" +.Sh DESCRIPTION +The +.Fn send +and +.Fn sendmmsg +functions, +and +.Fn sendto +and +.Fn sendmsg +system calls +are used to transmit one or more messages (with the +.Fn sendmmsg +call) to +another socket. +The +.Fn send +function +may be used only when the socket is in a +.Em connected +state, while +.Fn sendto , +.Fn sendmsg +and +.Fn sendmmsg +may be used at any time. +.Pp +The address of the target is given by +.Fa to +with +.Fa tolen +specifying its size. +The length of the message is given by +.Fa len . +If the message is too long to pass atomically through the +underlying protocol, the error +.Er EMSGSIZE +is returned, and +the message is not transmitted. +.Pp +The +.Fn sendmmsg +function sends multiple messages at a call. +They are given by the +.Fa msgvec +vector along with +.Fa vlen +specifying the vector size. +The number of octets sent per each message is placed in the +.Fa msg_len +field of each processed element of the vector after transmission. +.Pp +No indication of failure to deliver is implicit in a +.Fn send . +Locally detected errors are indicated by a return value of -1. +.Pp +If no messages space is available at the socket to hold +the message to be transmitted, then +.Fn send +normally blocks, unless the socket has been placed in +non-blocking I/O mode. +The +.Xr select 2 +system call may be used to determine when it is possible to +send more data. +.Pp +The +.Fa flags +argument may include one or more of the following: +.Bd -literal +#define MSG_OOB 0x00001 /* process out-of-band data */ +#define MSG_DONTROUTE 0x00004 /* bypass routing, use direct interface */ +#define MSG_EOR 0x00008 /* data completes record */ +#define MSG_EOF 0x00100 /* data completes transaction */ +#define MSG_NOSIGNAL 0x20000 /* do not generate SIGPIPE on EOF */ +.Ed +.Pp +The flag +.Dv MSG_OOB +is used to send +.Dq out-of-band +data on sockets that support this notion (e.g.\& +.Dv SOCK_STREAM ) ; +the underlying protocol must also support +.Dq out-of-band +data. +.Dv MSG_EOR +is used to indicate a record mark for protocols which support the +concept. +.Dv MSG_EOF +requests that the sender side of a socket be shut down, and that an +appropriate indication be sent at the end of the specified data; +this flag is only implemented for +.Dv SOCK_STREAM +sockets in the +.Dv PF_INET +protocol family. +.Dv MSG_DONTROUTE +is usually used only by diagnostic or routing programs. +.Dv MSG_NOSIGNAL +is used to prevent +.Dv SIGPIPE +generation when writing a socket that +may be closed. +.Pp +See +.Xr recv 2 +for a description of the +.Fa msghdr +structure and the +.Fa mmsghdr +structure. +.Sh RETURN VALUES +The +.Fn send , +.Fn sendto +and +.Fn sendmsg +calls +return the number of octets sent. +The +.Fn sendmmsg +call returns the number of messages sent. +If an error occurred a value of -1 is returned. +.Sh ERRORS +The +.Fn send +and +.Fn sendmmsg +functions and +.Fn sendto +and +.Fn sendmsg +system calls +fail if: +.Bl -tag -width Er +.It Bq Er EBADF +An invalid descriptor was specified. +.It Bq Er EACCES +The destination address is a broadcast address, and +.Dv SO_BROADCAST +has not been set on the socket. +.It Bq Er ENOTSOCK +The argument +.Fa s +is not a socket. +.It Bq Er EFAULT +An invalid user space address was specified for an argument. +.It Bq Er EMSGSIZE +The socket requires that message be sent atomically, +and the size of the message to be sent made this impossible. +.It Bq Er EAGAIN +The socket is marked non-blocking and the requested operation +would block. +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +The operation may succeed when buffers become available. +.It Bq Er ENOBUFS +The output queue for a network interface was full. +This generally indicates that the interface has stopped sending, +but may be caused by transient congestion. +.It Bq Er EHOSTUNREACH +The remote host was unreachable. +.It Bq Er EISCONN +A destination address was specified and the socket is already connected. +.It Bq Er ECONNREFUSED +The socket received an ICMP destination unreachable message +from the last message sent. +This typically means that the +receiver is not listening on the remote port. +.It Bq Er EHOSTDOWN +The remote host was down. +.It Bq Er ENETDOWN +The remote network was down. +.It Bq Er EADDRNOTAVAIL +The process using a +.Dv SOCK_RAW +socket was jailed and the source +address specified in the IP header did not match the IP +address bound to the prison. +.It Bq Er EPIPE +The socket is unable to send anymore data +.Dv ( SBS_CANTSENDMORE +has been set on the socket). +This typically means that the socket +is not connected. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr socket 2 , +.Xr write 2 +.Sh HISTORY +The +.Fn send +function appeared in +.Bx 4.2 . +The +.Fn sendmmsg +function appeared in +.Fx 11.0 . +.Sh BUGS +Because +.Fn sendmsg +does not necessarily block until the data has been transferred, it +is possible to transfer an open file descriptor across an +.Dv AF_UNIX +domain socket +(see +.Xr recv 2 ) , +then +.Fn close +it before it has actually been sent, the result being that the receiver +gets a closed file descriptor. +It is left to the application to +implement an acknowledgment mechanism to prevent this from happening. diff --git a/lib/libc/sys/sendfile.2 b/lib/libc/sys/sendfile.2 new file mode 100644 index 000000000000..313c349ee9ff --- /dev/null +++ b/lib/libc/sys/sendfile.2 @@ -0,0 +1,399 @@ +.\" Copyright (c) 2003, David G. Lawrence +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice unmodified, this list of conditions, and the following +.\" disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 17, 2016 +.Dt SENDFILE 2 +.Os +.Sh NAME +.Nm sendfile +.Nd send a file to a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In sys/uio.h +.Ft int +.Fo sendfile +.Fa "int fd" "int s" "off_t offset" "size_t nbytes" +.Fa "struct sf_hdtr *hdtr" "off_t *sbytes" "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn sendfile +system call +sends a regular file or shared memory object specified by descriptor +.Fa fd +out a stream socket specified by descriptor +.Fa s . +.Pp +The +.Fa offset +argument specifies where to begin in the file. +Should +.Fa offset +fall beyond the end of file, the system will return +success and report 0 bytes sent as described below. +The +.Fa nbytes +argument specifies how many bytes of the file should be sent, with 0 having the special +meaning of send until the end of file has been reached. +.Pp +An optional header and/or trailer can be sent before and after the file data by specifying +a pointer to a +.Vt "struct sf_hdtr" , +which has the following structure: +.Pp +.Bd -literal -offset indent -compact +struct sf_hdtr { + struct iovec *headers; /* pointer to header iovecs */ + int hdr_cnt; /* number of header iovecs */ + struct iovec *trailers; /* pointer to trailer iovecs */ + int trl_cnt; /* number of trailer iovecs */ +}; +.Ed +.Pp +The +.Fa headers +and +.Fa trailers +pointers, if +.Pf non- Dv NULL , +point to arrays of +.Vt "struct iovec" +structures. +See the +.Fn writev +system call for information on the iovec structure. +The number of iovecs in these +arrays is specified by +.Fa hdr_cnt +and +.Fa trl_cnt . +.Pp +If +.Pf non- Dv NULL , +the system will write the total number of bytes sent on the socket to the +variable pointed to by +.Fa sbytes . +.Pp +The least significant 16 bits of +.Fa flags +argument is a bitmap of these values: +.Bl -tag -offset indent +.It Dv SF_NODISKIO +This flag causes +.Nm +to return +.Er EBUSY +instead of blocking when a busy page is encountered. +This rare situation can happen if some other process is now working +with the same region of the file. +It is advised to retry the operation after a short period. +.Pp +Note that in older +.Fx +versions the +.Dv SF_NODISKIO +had slightly different notion. +The flag prevented +.Nm +to run I/O operations in case if an invalid (not cached) page is encountered, +thus avoiding blocking on I/O. +Starting with +.Fx 11 +.Nm +sending files off the +.Xr ffs 7 +filesystem doesn't block on I/O +(see +.Sx IMPLEMENTATION NOTES +), so the condition no longer applies. +However, it is safe if an application utilizes +.Dv SF_NODISKIO +and on +.Er EBUSY +performs the same action as it did in +older +.Fx +versions, e.g. +.Xr aio_read 2, +.Xr read 2 +or +.Nm +in a different context. +.It Dv SF_NOCACHE +The data sent to socket will not be cached by the virtual memory system, +and will be freed directly to the pool of free pages. +.It Dv SF_SYNC +.Nm +sleeps until the network stack no longer references the VM pages +of the file, making subsequent modifications to it safe. +Please note that this is not a guarantee that the data has actually +been sent. +.It Dv SF_USER_READAHEAD +.Nm +has some internal heuristics to do readahead when sending data. +This flag forces +.Nm +to override any heuristically calculated readahead and use exactly the +application specified readahead. +See +.Sx SETTING READAHEAD +for more details on readahead. +.El +.Pp +When using a socket marked for non-blocking I/O, +.Fn sendfile +may send fewer bytes than requested. +In this case, the number of bytes successfully +written is returned in +.Fa *sbytes +(if specified), +and the error +.Er EAGAIN +is returned. +.Sh SETTING READAHEAD +.Nm +uses internal heuristics based on request size and file system layout +to do readahead. +Additionally application may request extra readahead. +The most significant 16 bits of +.Fa flags +specify amount of pages that +.Nm +may read ahead when reading the file. +A macro +.Fn SF_FLAGS +is provided to combine readahead amount and flags. +Example shows specifing readahead of 16 pages and +.Dv SF_NOCACHE +flag: +.Pp +.Bd -literal -offset indent -compact + SF_FLAGS(16, SF_NOCACHE) +.Ed +.Pp +.Nm +will use either application specified readahead or internally calculated, +whichever is bigger. +Setting flag +.Dv SF_USER_READAHEAD +would turn off any heuristics and set maximum possible readahead length to +the number of pages specified via flags. +.Sh IMPLEMENTATION NOTES +The +.Fx +implementation of +.Fn sendfile +doesn't block on disk I/O when it sends a file off the +.Xr ffs 7 +filesystem. +The syscall returns success before the actual I/O completes, and data +is put into the socket later unattended. +However, the order of data in the socket is preserved, so it is safe +to do further writes to the socket. +.Pp +The +.Fx +implementation of +.Fn sendfile +is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided. +.Sh TUNING +On some architectures, this system call internally uses a special +.Fn sendfile +buffer +.Pq Vt "struct sf_buf" +to handle sending file data to the client. +If the sending socket is +blocking, and there are not enough +.Fn sendfile +buffers available, +.Fn sendfile +will block and report a state of +.Dq Li sfbufa . +If the sending socket is non-blocking and there are not enough +.Fn sendfile +buffers available, the call will block and wait for the +necessary buffers to become available before finishing the call. +.Pp +The number of +.Vt sf_buf Ns 's +allocated should be proportional to the number of nmbclusters used to +send data to a client via +.Fn sendfile . +Tune accordingly to avoid blocking! +Busy installations that make extensive use of +.Fn sendfile +may want to increase these values to be inline with their +.Va kern.ipc.nmbclusters +(see +.Xr tuning 7 +for details). +.Pp +The number of +.Fn sendfile +buffers available is determined at boot time by either the +.Va kern.ipc.nsfbufs +.Xr loader.conf 5 +variable or the +.Dv NSFBUFS +kernel configuration tunable. +The number of +.Fn sendfile +buffers scales with +.Va kern.maxusers . +The +.Va kern.ipc.nsfbufsused +and +.Va kern.ipc.nsfbufspeak +read-only +.Xr sysctl 8 +variables show current and peak +.Fn sendfile +buffers usage respectively. +These values may also be viewed through +.Nm netstat Fl m . +.Pp +If a value of zero is reported for +.Va kern.ipc.nsfbufs , +your architecture does not need to use +.Fn sendfile +buffers because their task can be efficiently performed +by the generic virtual memory structures. +.Sh RETURN VALUES +.Rv -std sendfile +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EAGAIN +The socket is marked for non-blocking I/O and not all data was sent due to +the socket buffer being filled. +If specified, the number of bytes successfully sent will be returned in +.Fa *sbytes . +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid file descriptor. +.It Bq Er EBADF +The +.Fa s +argument +is not a valid socket descriptor. +.It Bq Er EBUSY +A busy page was encountered and +.Dv SF_NODISKIO +had been specified. +Partial data may have been sent. +.It Bq Er EFAULT +An invalid address was specified for an argument. +.It Bq Er EINTR +A signal interrupted +.Fn sendfile +before it could be completed. +If specified, the number +of bytes successfully sent will be returned in +.Fa *sbytes . +.It Bq Er EINVAL +The +.Fa fd +argument +is not a regular file. +.It Bq Er EINVAL +The +.Fa s +argument +is not a SOCK_STREAM type socket. +.It Bq Er EINVAL +The +.Fa offset +argument +is negative. +.It Bq Er EIO +An error occurred while reading from +.Fa fd . +.It Bq Er ENOBUFS +The system was unable to allocate an internal buffer. +.It Bq Er ENOTCONN +The +.Fa s +argument +points to an unconnected socket. +.It Bq Er ENOTSOCK +The +.Fa s +argument +is not a socket. +.It Bq Er EOPNOTSUPP +The file system for descriptor +.Fa fd +does not support +.Fn sendfile . +.It Bq Er EPIPE +The socket peer has closed the connection. +.El +.Sh SEE ALSO +.Xr netstat 1 , +.Xr open 2 , +.Xr send 2 , +.Xr socket 2 , +.Xr writev 2 , +.Xr tuning 7 +.Rs +.%A K. Elmeleegy +.%A A. Chanda +.%A A. L. Cox +.%A W. Zwaenepoel +.%T A Portable Kernel Abstraction for Low-Overhead Ephemeral Mapping Management +.%J The Proceedings of the 2005 USENIX Annual Technical Conference +.%P pp 223-236 +.%D 2005 +.Re +.Sh HISTORY +The +.Fn sendfile +system call +first appeared in +.Fx 3.0 . +This manual page first appeared in +.Fx 3.1 . +In +.Fx 10 +support for sending shared memory descriptors had been introduced. +In +.Fx 11 +a non-blocking implementation had been introduced. +.Sh AUTHORS +The initial implementation of +.Fn sendfile +system call +and this manual page were written by +.An David G. Lawrence Aq Mt dg@dglawrence.com . +The +.Fx 11 +implementation was written by +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org . diff --git a/lib/libc/sys/sendmsg.c b/lib/libc/sys/sendmsg.c new file mode 100644 index 000000000000..794464339043 --- /dev/null +++ b/lib/libc/sys/sendmsg.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_sendmsg, __sendmsg); + +#pragma weak sendmsg +ssize_t +sendmsg(int s, const struct msghdr *msg, int flags) +{ + + return (((int (*)(int, const struct msghdr *, int)) + __libc_interposing[INTERPOS_sendmsg])(s, msg, flags)); +} diff --git a/lib/libc/sys/sendto.c b/lib/libc/sys/sendto.c new file mode 100644 index 000000000000..ecf98ee05b19 --- /dev/null +++ b/lib/libc/sys/sendto.c @@ -0,0 +1,53 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/socket.h> +#include "libc_private.h" + +__weak_reference(__sys_sendto, __sendto); + +#pragma weak sendto +ssize_t +sendto(int s, const void *msg, size_t len, int flags, + const struct sockaddr *to, socklen_t tolen) +{ + + return (((ssize_t (*)(int, const void *, size_t, int, + const struct sockaddr *, socklen_t)) + __libc_interposing[INTERPOS_sendto])(s, msg, len, flags, + to, tolen)); +} diff --git a/lib/libc/sys/setcontext.c b/lib/libc/sys/setcontext.c new file mode 100644 index 000000000000..31b888f2bcff --- /dev/null +++ b/lib/libc/sys/setcontext.c @@ -0,0 +1,52 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <ucontext.h> +#include "libc_private.h" + +__weak_reference(__sys_setcontext, __setcontext); +__sym_compat(setcontext, __impl_setcontext, FBSD_1.0); +__weak_reference(setcontext, __impl_setcontext); +__sym_default(setcontext, setcontext, FBSD_1.2); + +#pragma weak setcontext +int +setcontext(const ucontext_t *uc) +{ + + return (((int (*)(const ucontext_t *)) + __libc_interposing[INTERPOS_setcontext])(uc)); +} diff --git a/lib/libc/sys/setfib.2 b/lib/libc/sys/setfib.2 new file mode 100644 index 000000000000..d759109fa39e --- /dev/null +++ b/lib/libc/sys/setfib.2 @@ -0,0 +1,107 @@ +.\" Copyright (c) 2008 Cisco Systems. All rights reserved. +.\" Author: Julian Elischer +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Neither the name of the Cisco Systems nor the names of its employees +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 19, 2012 +.Dt SETFIB 2 +.Os +.Sh NAME +.Nm setfib +.Nd set the default FIB (routing table) for the calling process. +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn setfib "int fib" +.Sh DESCRIPTION +The +.Fn setfib +system call sets the associated fib for all sockets opened +subsequent to the call, to be that of the argument +.Fa fib . +The +.Fa fib +argument +must be greater than or equal to 0 +and less than the current system maximum which +may be retrieved by the +.Va net.fibs +sysctl. +The system maximum is set in the kernel configuration file with +.Bd -ragged -offset indent +.Cd "options ROUTETABLES=" Ns Em N +.Ed +.Pp +or in +.Pa /boot/loader.conf +with +.Pp +.Dl net.fibs= Ns Qq Em N +.Pp +where +.Em N +is an integer. +This maximum is capped at 65536 due to the implementation storing +the fib number in a 16-bit field in the +.Xr mbuf 9 +packet header, however it is not suggested that one use such a large number +as memory is allocated for every FIB regardless of whether it is used, and +there are places where all FIBs are iterated over. +.Pp +The default fib of the process will be applied to all protocol families +that support multiple fibs, and ignored by those that do not. +The default fib for a process may be overridden for a socket with the use +of the +.Dv SO_SETFIB +socket option. +.Sh RETURN VALUES +.Rv -std setfib +.Sh ERRORS +The +.Fn setfib +system call +will fail and no action will be taken and return +.Er EINVAL +if the +.Fa fib +argument is greater than the current system maximum. +.Sh SEE ALSO +.Xr setfib 1 , +.Xr setsockopt 2 +.Sh STANDARDS +The +.Fn setfib +system call is a +.Fx +extension however similar extensions +have been added to many other +.Ux +style kernels. +.Sh HISTORY +The +.Fn setfib +function appeared in +.Fx 7.1 . diff --git a/lib/libc/sys/setgroups.2 b/lib/libc/sys/setgroups.2 new file mode 100644 index 000000000000..ef4c34c266e1 --- /dev/null +++ b/lib/libc/sys/setgroups.2 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1983, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setgroups.2 8.2 (Berkeley) 4/16/94 +.\" $FreeBSD$ +.\" +.Dd April 16, 1994 +.Dt SETGROUPS 2 +.Os +.Sh NAME +.Nm setgroups +.Nd set group access list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In unistd.h +.Ft int +.Fn setgroups "int ngroups" "const gid_t *gidset" +.Sh DESCRIPTION +The +.Fn setgroups +system call +sets the group access list of the current user process +according to the array +.Fa gidset . +The +.Fa ngroups +argument +indicates the number of entries in the array and must be no +more than +.Dv {NGROUPS_MAX}+1 . +.Pp +Only the super-user may set a new group list. +.Sh RETURN VALUES +.Rv -std setgroups +.Sh ERRORS +The +.Fn setgroups +system call will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er EINVAL +The number specified in the +.Fa ngroups +argument is larger than the +.Dv {NGROUPS_MAX}+1 +limit. +.It Bq Er EFAULT +The address specified for +.Fa gidset +is outside the process +address space. +.El +.Sh SEE ALSO +.Xr getgroups 2 , +.Xr initgroups 3 +.Sh HISTORY +The +.Fn setgroups +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/setpgid.2 b/lib/libc/sys/setpgid.2 new file mode 100644 index 000000000000..4ad89de3263f --- /dev/null +++ b/lib/libc/sys/setpgid.2 @@ -0,0 +1,110 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setpgid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd February 8, 2004 +.Dt SETPGID 2 +.Os +.Sh NAME +.Nm setpgid , +.Nm setpgrp +.Nd set process group +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setpgid "pid_t pid" "pid_t pgrp" +.Ft int +.Fn setpgrp "pid_t pid" "pid_t pgrp" +.Sh DESCRIPTION +The +.Fn setpgid +system call +sets the process group of the specified process +.Fa pid +to the specified +.Fa pgrp . +If +.Fa pid +is zero, then the call applies to the current process. +If +.Fa pgrp +is zero, then the process id of the process specified by +.Fa pid +is used instead. +.Pp +If the affected process is not the invoking process, then it must be a +child of the invoking process, it must not have performed an +.Xr exec 3 +operation, and both processes must be in the same session. +The requested process group ID must already exist in the session of +the caller, or it must be equal to the target process ID. +.Sh RETURN VALUES +.Rv -std setpgid +.Sh COMPATIBILITY +The +.Fn setpgrp +system call +is identical to +.Fn setpgid , +and is retained for calling convention compatibility with historical +versions of +.Bx . +.Sh ERRORS +The +.Fn setpgid +system call +will fail and the process group will not be altered if: +.Bl -tag -width Er +.It Bq Er EINVAL +The requested process group ID is not legal. +.It Bq Er ESRCH +The requested process does not exist. +.It Bq Er ESRCH +The target process is not the calling process or +a child of the calling process. +.It Bq Er EACCES +The requested process is a child of the calling process, +but it has performed an +.Xr exec 3 +operation. +.It Bq Er EPERM +The target process is a session leader. +.It Bq Er EPERM +The requested process group ID is not in the session of the caller, +and it is not equal to the process ID of the target process. +.El +.Sh SEE ALSO +.Xr getpgrp 2 +.Sh STANDARDS +The +.Fn setpgid +system call is expected to conform to +.St -p1003.1-90 . diff --git a/lib/libc/sys/setregid.2 b/lib/libc/sys/setregid.2 new file mode 100644 index 000000000000..2eedae2ceda1 --- /dev/null +++ b/lib/libc/sys/setregid.2 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setregid.2 8.2 (Berkeley) 4/16/94 +.\" $FreeBSD$ +.\" +.Dd April 16, 1994 +.Dt SETREGID 2 +.Os +.Sh NAME +.Nm setregid +.Nd set real and effective group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setregid "gid_t rgid" "gid_t egid" +.Sh DESCRIPTION +The real and effective group ID's of the current process +are set to the arguments. +If the real group ID is changed, the saved group ID is changed to the +new value of the effective group ID. +.Pp +Unprivileged users may change the real group +ID to the effective group ID and vice-versa; only the super-user may +make other changes. +.Pp +Supplying a value of -1 for either the real or effective +group ID forces the system to substitute the current +ID in place of the -1 argument. +.Pp +The +.Fn setregid +system call was intended to allow swapping +the real and effective group IDs +in set-group-ID programs to temporarily relinquish the set-group-ID value. +This system call did not work correctly, +and its purpose is now better served by the use of the +.Xr setegid 2 +system call. +.Pp +When setting the real and effective group IDs to the same value, +the standard +.Fn setgid +system call is preferred. +.Sh RETURN VALUES +.Rv -std setregid +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The current process is not the super-user and a change +other than changing the effective group-id to the real group-id +was specified. +.El +.Sh SEE ALSO +.Xr getgid 2 , +.Xr issetugid 2 , +.Xr setegid 2 , +.Xr setgid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn setregid +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/setresuid.2 b/lib/libc/sys/setresuid.2 new file mode 100644 index 000000000000..602166f80c38 --- /dev/null +++ b/lib/libc/sys/setresuid.2 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2000 +.\" Sheldon Hearn. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES +.\" +.\" $FreeBSD$ +.\" +.Dd February 7, 2015 +.Dt SETRESUID 2 +.Os +.Sh NAME +.Nm getresgid , +.Nm getresuid , +.Nm setresgid , +.Nm setresuid +.Nd "get or set real, effective and saved user or group ID" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In unistd.h +.Ft int +.Fn getresgid "gid_t *rgid" "gid_t *egid" "gid_t *sgid" +.Ft int +.Fn getresuid "uid_t *ruid" "uid_t *euid" "uid_t *suid" +.Ft int +.Fn setresgid "gid_t rgid" "gid_t egid" "gid_t sgid" +.Ft int +.Fn setresuid "uid_t ruid" "uid_t euid" "uid_t suid" +.Sh DESCRIPTION +The +.Fn setresuid +system call sets the real, +effective and saved user IDs of the current process. +The analogous +.Fn setresgid +sets the real, effective and saved group IDs. +.Pp +Privileged processes may set these IDs +to arbitrary values. +Unprivileged processes are restricted +in that each of the new IDs must match one of the current IDs. +.Pp +Passing -1 as an argument causes the corresponding value +to remain unchanged. +.Pp +The +.Fn getresgid +and +.Fn getresuid +calls retrieve the real, effective, and saved group and user IDs of +the current process, respectively. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The calling process was not privileged +and tried to change one or more IDs to a value +which was not the current real ID, the current effective ID +nor the current saved ID. +.It Bq Er EFAULT +An address passed to +.Fn getresgid +or +.Fn getresuid +was invalid. +.El +.Sh SEE ALSO +.Xr getegid 2 , +.Xr geteuid 2 , +.Xr getgid 2 , +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr setgid 2 , +.Xr setregid 2 , +.Xr setreuid 2 , +.Xr setuid 2 +.Sh HISTORY +These functions first appeared in HP-UX. diff --git a/lib/libc/sys/setreuid.2 b/lib/libc/sys/setreuid.2 new file mode 100644 index 000000000000..2983820334c9 --- /dev/null +++ b/lib/libc/sys/setreuid.2 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setreuid.2 8.2 (Berkeley) 4/16/94 +.\" $FreeBSD$ +.\" +.Dd February 8, 2001 +.Dt SETREUID 2 +.Os +.Sh NAME +.Nm setreuid +.Nd set real and effective user ID's +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setreuid "uid_t ruid" "uid_t euid" +.Sh DESCRIPTION +The real and effective user IDs of the +current process are set according to the arguments. +If +.Fa ruid +or +.Fa euid +is -1, the current uid is filled in by the system. +Unprivileged users may change the real user +ID to the effective user ID and vice-versa; only the super-user may +make other changes. +.Pp +If the real user ID is changed (i.e.\& +.Fa ruid +is not -1) or the effective user ID is changed to something other than +the real user ID, then the saved user ID will be set to the effective user ID. +.Pp +The +.Fn setreuid +system call has been used to swap the real and effective user IDs +in set-user-ID programs to temporarily relinquish the set-user-ID value. +This purpose is now better served by the use of the +.Xr seteuid 2 +system call. +.Pp +When setting the real and effective user IDs to the same value, +the standard +.Fn setuid +system call is preferred. +.Sh RETURN VALUES +.Rv -std setreuid +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The current process is not the super-user and a change +other than changing the effective user-id to the real user-id +was specified. +.El +.Sh SEE ALSO +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr seteuid 2 , +.Xr setuid 2 +.Sh HISTORY +The +.Fn setreuid +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/setsid.2 b/lib/libc/sys/setsid.2 new file mode 100644 index 000000000000..a09a31ae715a --- /dev/null +++ b/lib/libc/sys/setsid.2 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setsid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt SETSID 2 +.Os +.Sh NAME +.Nm setsid +.Nd create session and set process group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn setsid void +.Sh DESCRIPTION +The +.Fn setsid +system call creates a new session. +The calling process is the session leader of the new session, is the +process group leader of a new process group and has no controlling +terminal. +The calling process is the only process in either the session or the +process group. +.Sh RETURN VALUES +Upon successful completion, the +.Fn setsid +system call returns the value of the process group ID of the new process +group, which is the same as the process ID of the calling process. +If an error occurs, +.Fn setsid +returns -1 and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn setsid +system call will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The calling process is already a process group leader, or the process +group ID of a process other than the calling process matches the process +ID of the calling process. +.El +.Sh SEE ALSO +.Xr setpgid 2 , +.Xr tcgetpgrp 3 , +.Xr tcsetpgrp 3 +.Sh STANDARDS +The +.Fn setsid +system call is expected to be compliant with the +.St -p1003.1-90 +specification. diff --git a/lib/libc/sys/setuid.2 b/lib/libc/sys/setuid.2 new file mode 100644 index 000000000000..949d93633c03 --- /dev/null +++ b/lib/libc/sys/setuid.2 @@ -0,0 +1,187 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setuid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt SETUID 2 +.Os +.Sh NAME +.Nm setuid , +.Nm seteuid , +.Nm setgid , +.Nm setegid +.Nd set user and group ID +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn setuid "uid_t uid" +.Ft int +.Fn seteuid "uid_t euid" +.Ft int +.Fn setgid "gid_t gid" +.Ft int +.Fn setegid "gid_t egid" +.Sh DESCRIPTION +The +.Fn setuid +system call +sets the real and effective +user IDs and the saved set-user-ID of the current process +to the specified value. +.\" Comment out next block for !_POSIX_SAVED_IDS +.\" The real user ID and the saved set-user-ID are changed only if the +.\" effective user ID is that of the super user. +.\" I.e. +.\" .Fn setuid +.\" system call is equal to +.\" .Fn seteuid +.\" system call if the effective user ID is not that of the super user. +.\" End of block +The +.Fn setuid +system call is permitted if the specified ID is equal to the real user ID +.\" Comment out next line for !_POSIX_SAVED_IDS +.\" or the saved set-user-ID +.\" Next line is for Appendix B.4.2.2 case. +or the effective user ID +of the process, or if the effective user ID is that of the super user. +.Pp +The +.Fn setgid +system call +sets the real and effective +group IDs and the saved set-group-ID of the current process +to the specified value. +.\" Comment out next block for !_POSIX_SAVED_IDS +.\" The real group ID and the saved set-group-ID are changed only if the +.\" effective user ID is that of the super user. +.\" I.e. +.\" .Fn setgid +.\" system call is equal to +.\" .Fn setegid +.\" system call if the effective user ID is not that of the super user. +.\" End of block +The +.Fn setgid +system call is permitted if the specified ID is equal to the real group ID +.\" Comment out next line for !_POSIX_SAVED_IDS +.\" or the saved set-group-ID +.\" Next line is for Appendix B.4.2.2 case. +or the effective group ID +of the process, or if the effective user ID is that of the super user. +.Pp +The +.Fn seteuid +system call +.Pq Fn setegid +sets the effective user ID (group ID) of the +current process. +The effective user ID may be set to the value +of the real user ID or the saved set-user-ID (see +.Xr intro 2 +and +.Xr execve 2 ) ; +in this way, the effective user ID of a set-user-ID executable +may be toggled by switching to the real user ID, then re-enabled +by reverting to the set-user-ID value. +Similarly, the effective group ID may be set to the value +of the real group ID or the saved set-group-ID. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The system calls will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The user is not the super user and the ID +specified is not the real, effective ID, or saved ID. +.El +.Sh SEE ALSO +.Xr getgid 2 , +.Xr getuid 2 , +.Xr issetugid 2 , +.Xr setregid 2 , +.Xr setreuid 2 +.Sh STANDARDS +The +.Fn setuid +and +.Fn setgid +system calls are compliant with the +.St -p1003.1-90 +specification with +.Li _POSIX_SAVED_IDS +.\" Uncomment next line for !_POSIX_SAVED_IDS +not +defined with the permitted extensions from Appendix B.4.2.2. +The +.Fn seteuid +and +.Fn setegid +system calls are extensions based on the +.Tn POSIX +concept of +.Li _POSIX_SAVED_IDS , +and have been proposed for a future revision of the standard. +.Sh HISTORY +The +.Fn setuid +and +.Fn setgid +functions appeared in +.At v7 . +.Sh SECURITY CONSIDERATIONS +Read and write permissions to files are determined upon a call to +.Xr open 2 . +Once a file descriptor is open, dropping privilege does not affect +the process's read/write permissions, even if the user ID specified +has no read or write permissions to the file. +These files normally remain open in any new process executed, +resulting in a user being able to read or modify +potentially sensitive data. +.Pp +To prevent these files from remaining open after an +.Xr exec 3 +call, be sure to set the close-on-exec flag: +.Bd -literal +void +pseudocode(void) +{ + int fd; + /* ... */ + + fd = open("/path/to/sensitive/data", O_RDWR | O_CLOEXEC); + if (fd == -1) + err(1, "open"); + + /* ... */ + execve(path, argv, environ); +} +.Ed diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2 new file mode 100644 index 000000000000..0855c076faf5 --- /dev/null +++ b/lib/libc/sys/shm_open.2 @@ -0,0 +1,313 @@ +.\" +.\" Copyright 2000 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 20, 2017 +.Dt SHM_OPEN 2 +.Os +.Sh NAME +.Nm shm_open , shm_unlink +.Nd "shared memory object operations" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/mman.h +.In fcntl.h +.Ft int +.Fn shm_open "const char *path" "int flags" "mode_t mode" +.Ft int +.Fn shm_unlink "const char *path" +.Sh DESCRIPTION +The +.Fn shm_open +system call opens (or optionally creates) a +.Tn POSIX +shared memory object named +.Fa path . +The +.Fa flags +argument contains a subset of the flags used by +.Xr open 2 . +An access mode of either +.Dv O_RDONLY +or +.Dv O_RDWR +must be included in +.Fa flags . +The optional flags +.Dv O_CREAT , +.Dv O_EXCL , +and +.Dv O_TRUNC +may also be specified. +.Pp +If +.Dv O_CREAT +is specified, +then a new shared memory object named +.Fa path +will be created if it does not exist. +In this case, +the shared memory object is created with mode +.Fa mode +subject to the process' umask value. +If both the +.Dv O_CREAT +and +.Dv O_EXCL +flags are specified and a shared memory object named +.Fa path +already exists, +then +.Fn shm_open +will fail with +.Er EEXIST . +.Pp +Newly created objects start off with a size of zero. +If an existing shared memory object is opened with +.Dv O_RDWR +and the +.Dv O_TRUNC +flag is specified, +then the shared memory object will be truncated to a size of zero. +The size of the object can be adjusted via +.Xr ftruncate 2 +and queried via +.Xr fstat 2 . +.Pp +The new descriptor is set to close during +.Xr execve 2 +system calls; +see +.Xr close 2 +and +.Xr fcntl 2 . +.Pp +As a FreeBSD extension, +the constant +.Dv SHM_ANON +may be used for the +.Fa path +argument to +.Fn shm_open . +In this case, an anonymous, unnamed shared memory object is created. +Since the object has no name, +it cannot be removed via a subsequent call to +.Fn shm_unlink . +Instead, +the shared memory object will be garbage collected when the last reference to +the shared memory object is removed. +The shared memory object may be shared with other processes by sharing the +file descriptor via +.Xr fork 2 +or +.Xr sendmsg 2 . +Attempting to open an anonymous shared memory object with +.Dv O_RDONLY +will fail with +.Er EINVAL . +All other flags are ignored. +.Pp +The +.Fn shm_unlink +system call removes a shared memory object named +.Fa path . +.Sh RETURN VALUES +If successful, +.Fn shm_open +returns a non-negative integer, +and +.Fn shm_unlink +returns zero. +Both functions return -1 on failure, and set +.Va errno +to indicate the error. +.Sh COMPATIBILITY +The +.Fa path +argument does not necessarily represent a pathname (although it does in +most other implementations). +Two processes opening the same +.Fa path +are guaranteed to access the same shared memory object if and only if +.Fa path +begins with a slash +.Pq Ql \&/ +character. +.Pp +Only the +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_CREAT , +.Dv O_EXCL , +and +.Dv O_TRUNC +flags may be used in portable programs. +.Pp +.Tn POSIX +specifications state that the result of using +.Xr open 2 , +.Xr read 2 , +or +.Xr write 2 +on a shared memory object, or on the descriptor returned by +.Fn shm_open , +is undefined. +However, the +.Fx +kernel implementation explicitly includes support for +.Xr read 2 +and +.Xr write 2 . +.Pp +.Fx +also supports zero-copy transmission of data from shared memory +objects with +.Xr sendfile 2 . +.Pp +Neither shared memory objects nor their contents persist across reboots. +.Pp +Writes do not extend shared memory objects, so +.Xr ftruncate 2 +must be called before any data can be written. +See +.Sx EXAMPLES . +.Sh EXAMPLES +This example fails without the call to +.Xr ftruncate 2 : +.Bd -literal -compact + + uint8_t buffer[getpagesize()]; + ssize_t len; + int fd; + + fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600); + if (fd < 0) + err(EX_OSERR, "%s: shm_open", __func__); + if (ftruncate(fd, getpagesize()) < 0) + err(EX_IOERR, "%s: ftruncate", __func__); + len = pwrite(fd, buffer, getpagesize(), 0); + if (len < 0) + err(EX_IOERR, "%s: pwrite", __func__); + if (len != getpagesize()) + errx(EX_IOERR, "%s: pwrite length mismatch", __func__); +.Ed +.Sh ERRORS +.Fn shm_open +fails with these error codes for these conditions: +.Bl -tag -width Er +.It Bq Er EINVAL +A flag other than +.Dv O_RDONLY , +.Dv O_RDWR , +.Dv O_CREAT , +.Dv O_EXCL , +or +.Dv O_TRUNC +was included in +.Fa flags . +.It Bq Er EMFILE +The process has already reached its limit for open file descriptors. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EINVAL +.Dv O_RDONLY +was specified while creating an anonymous shared memory object via +.Dv SHM_ANON . +.It Bq Er EFAULT +The +.Fa path +argument points outside the process' allocated address space. +.It Bq Er ENAMETOOLONG +The entire pathname exceeded 1023 characters. +.It Bq Er EINVAL +The +.Fa path +does not begin with a slash +.Pq Ql \&/ +character. +.It Bq Er ENOENT +.Dv O_CREAT +is specified and the named shared memory object does not exist. +.It Bq Er EEXIST +.Dv O_CREAT +and +.Dv O_EXCL +are specified and the named shared memory object does exist. +.It Bq Er EACCES +The required permissions (for reading or reading and writing) are denied. +.El +.Pp +.Fn shm_unlink +fails with these error codes for these conditions: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa path +argument points outside the process' allocated address space. +.It Bq Er ENAMETOOLONG +The entire pathname exceeded 1023 characters. +.It Bq Er ENOENT +The named shared memory object does not exist. +.It Bq Er EACCES +The required permissions are denied. +.Fn shm_unlink +requires write permission to the shared memory object. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr fstat 2 , +.Xr ftruncate 2 , +.Xr mmap 2 , +.Xr munmap 2 , +.Xr sendfile 2 +.Sh STANDARDS +The +.Fn shm_open +and +.Fn shm_unlink +functions are believed to conform to +.St -p1003.1b-93 . +.Sh HISTORY +The +.Fn shm_open +and +.Fn shm_unlink +functions first appeared in +.Fx 4.3 . +The functions were reimplemented as system calls using shared memory objects +directly rather than files in +.Fx 8.0 . +.Sh AUTHORS +.An Garrett A. Wollman Aq Mt wollman@FreeBSD.org +(C library support and this manual page) +.Pp +.An Matthew Dillon Aq Mt dillon@FreeBSD.org +.Pq Dv MAP_NOSYNC diff --git a/lib/libc/sys/shmat.2 b/lib/libc/sys/shmat.2 new file mode 100644 index 000000000000..fd1db932ce85 --- /dev/null +++ b/lib/libc/sys/shmat.2 @@ -0,0 +1,122 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 2, 1995 +.Dt SHMAT 2 +.Os +.Sh NAME +.Nm shmat , +.Nm shmdt +.Nd attach or detach shared memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/shm.h +.Ft void * +.Fn shmat "int shmid" "const void *addr" "int flag" +.Ft int +.Fn shmdt "const void *addr" +.Sh DESCRIPTION +The +.Fn shmat +system call +attaches the shared memory segment identified by +.Fa shmid +to the calling process's address space. +The address where the segment +is attached is determined as follows: +.\" +.\" These are cribbed almost exactly from Stevens, _Advanced Programming in +.\" the UNIX Environment_. +.\" +.Bl -bullet +.It +If +.Fa addr +is 0, the segment is attached at an address selected by the +kernel. +.It +If +.Fa addr +is nonzero and SHM_RND is not specified in +.Fa flag , +the segment is attached the specified address. +.It +If +.Fa addr +is specified and SHM_RND is specified, +.Fa addr +is rounded down to the nearest multiple of SHMLBA. +.El +.Pp +The +.Fn shmdt +system call +detaches the shared memory segment at the address specified by +.Fa addr +from the calling process's address space. +.Sh RETURN VALUES +Upon success, +.Fn shmat +returns the address where the segment is attached; otherwise, -1 +is returned and +.Va errno +is set to indicate the error. +.Pp +.Rv -std shmdt +.Sh ERRORS +The +.Fn shmat +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +No shared memory segment was found corresponding to +.Fa shmid . +.It Bq Er EINVAL +The +.Fa addr +argument +was not an acceptable address. +.El +.Pp +The +.Fn shmdt +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +argument +does not point to a shared memory segment. +.El +.Sh "SEE ALSO" +.Xr shmctl 2 , +.Xr shmget 2 diff --git a/lib/libc/sys/shmctl.2 b/lib/libc/sys/shmctl.2 new file mode 100644 index 000000000000..788e79f1900d --- /dev/null +++ b/lib/libc/sys/shmctl.2 @@ -0,0 +1,141 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 10, 2015 +.Dt SHMCTL 2 +.Os +.Sh NAME +.Nm shmctl +.Nd shared memory control +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/shm.h +.Ft int +.Fn shmctl "int shmid" "int cmd" "struct shmid_ds *buf" +.Sh DESCRIPTION +Performs the action specified by +.Fa cmd +on the shared memory segment identified by +.Fa shmid : +.Bl -tag -width SHM_UNLOCKX +.It Dv IPC_STAT +Fetch the segment's +.Fa "struct shmid_ds" , +storing it in the memory pointed to by +.Fa buf . +.\" +.\" XXX need to make sure that this is correct for FreeBSD +.\" +.It Dv IPC_SET +Changes the +.Fa shm_perm.uid , +.Fa shm_perm.gid , +and +.Fa shm_perm.mode +members of the segment's +.Fa "struct shmid_ds" +to match those of the struct pointed to by +.Fa buf . +The calling process's effective uid must +match either +.Fa shm_perm.uid +or +.Fa shm_perm.cuid , +or it must have superuser privileges. +.It Dv IPC_RMID +Removes the segment from the system. +The removal will not take +effect until all processes having attached the segment have exited. +For the operation +to succeed, the calling process's effective uid must match +.Fa shm_perm.uid +or +.Fa shm_perm.cuid , +or the process must have superuser privileges. +If the +.Va kern.ipc.shm_allow_removed +.Xr sysctl 3 +variable is set to 0, once the IPC_RMID operation has taken place, +no further processes will be allowed to attach the segment. +.\" .It Dv SHM_LOCK +.\" Locks the segment in memory. The calling process must have +.\" superuser privileges. Not implemented in FreeBSD. +.\" .It Dv SHM_UNLOCK +.\" Unlocks the segment from memory. The calling process must +.\" have superuser privileges. Not implemented in FreeBSD. +.El +.Pp +The +.Vt shmid_ds +structure is defined as follows: +.\" +.\" I fiddled with the spaces a bit to make it fit well when viewed +.\" with nroff, but otherwise it is straight from sys/shm.h +.\" +.Bd -literal +struct shmid_ds { + struct ipc_perm shm_perm; /* operation permission structure */ + size_t shm_segsz; /* size of segment in bytes */ + pid_t shm_lpid; /* process ID of last shared memory op */ + pid_t shm_cpid; /* process ID of creator */ + int shm_nattch; /* number of current attaches */ + time_t shm_atime; /* time of last shmat() */ + time_t shm_dtime; /* time of last shmdt() */ + time_t shm_ctime; /* time of last change by shmctl() */ +}; +.Ed +.Sh RETURN VALUES +.Rv -std shmctl +.Sh ERRORS +The +.Fn shmctl +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid operation, or +no shared memory segment was found corresponding to +.Fa shmid . +.\" +.\" XXX I think the following is right: ipcperm() only returns EPERM +.\" when an attempt is made to modify (IPC_M) by a non-creator +.\" non-owner +.It Bq Er EPERM +The calling process's effective uid does not match the uid of +the shared memory segment's owner or creator. +.It Bq Er EACCES +Permission denied due to mismatch between operation and mode of +shared memory segment. +.El +.Sh "SEE ALSO" +.Xr shmat 2 , +.Xr shmdt 2 , +.Xr shmget 2 , +.Xr ftok 3 diff --git a/lib/libc/sys/shmget.2 b/lib/libc/sys/shmget.2 new file mode 100644 index 000000000000..309434553162 --- /dev/null +++ b/lib/libc/sys/shmget.2 @@ -0,0 +1,146 @@ +.\" +.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 17, 2010 +.Dt SHMGET 2 +.Os +.Sh NAME +.Nm shmget +.Nd obtain a shared memory identifier +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/ipc.h +.In sys/shm.h +.Ft int +.Fn shmget "key_t key" "size_t size" "int flag" +.Sh DESCRIPTION +Based on the values of +.Fa key +and +.Fa flag , +.Fn shmget +returns the identifier of a newly created or previously existing shared +memory segment. +.\" +.\" The following bit about keys and modes also applies to semaphores +.\" and message queues. +.\" +The key +is analogous to a filename: it provides a handle that names an +IPC object. +There are three ways to specify a key: +.Bl -bullet +.It +IPC_PRIVATE may be specified, in which case a new IPC object +will be created. +.It +An integer constant may be specified. +If no IPC object corresponding +to +.Fa key +is specified and the IPC_CREAT bit is set in +.Fa flag , +a new one will be created. +.It +The +.Xr ftok 3 +may be used to generate a key from a pathname. +.El +.Pp +The mode of a newly created IPC object is determined by +.Em OR Ns 'ing +the following constants into the +.Fa flag +argument: +.Bl -tag -width XSHM_WXX6XXX +.It Dv S_IRUSR +Read access for owner. +.It Dv S_IWUSR +Write access for owner. +.It Dv S_IRGRP +Read access for group. +.It Dv S_IWGRP +Write access for group. +.It Dv S_IROTH +Read access for other. +.It Dv S_IWOTH +Write access for other. +.El +.\" +.\" XXX - we should also mention how uid, euid, and gid affect ownership +.\" and use +.\" +.\" end section about keys and modes +.\" +.Pp +When creating a new shared memory segment, +.Fa size +indicates the desired size of the new segment in bytes. +The size +of the segment may be rounded up to a multiple convenient to the +kernel (i.e., the page size). +.Sh RETURN VALUES +Upon successful completion, +.Fn shmget +returns the positive integer identifier of a shared memory segment. +Otherwise, -1 is returned and +.Va errno +set to indicate the error. +.Sh ERRORS +The +.Fn shmget +system call +will fail if: +.Bl -tag -width Er +.\" +.\" XXX What about ipcperm failing? +.\" +.It Bq Er EINVAL +Size specified is greater than the size of the previously existing segment. +Size specified is less than the system imposed minimum, or greater than +the system imposed maximum. +.It Bq Er ENOENT +No shared memory segment was found matching +.Fa key , +and IPC_CREAT was not specified. +.It Bq Er ENOSPC +The kernel was unable to allocate enough memory to +satisfy the request. +.It Bq Er EEXIST +IPC_CREAT and IPC_EXCL were specified, and a shared memory segment +corresponding to +.Fa key +already exists. +.El +.Sh "SEE ALSO" +.Xr shmat 2 , +.Xr shmctl 2 , +.Xr shmdt 2 , +.Xr stat 2 , +.Xr ftok 3 diff --git a/lib/libc/sys/shutdown.2 b/lib/libc/sys/shutdown.2 new file mode 100644 index 000000000000..35c464e9fe2e --- /dev/null +++ b/lib/libc/sys/shutdown.2 @@ -0,0 +1,171 @@ +.\" Copyright (c) 2007 Bruce M. Simpson. +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)shutdown.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd July 27, 2015 +.Dt SHUTDOWN 2 +.Os +.Sh NAME +.Nm shutdown +.Nd disable sends and/or receives on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn shutdown "int s" "int how" +.Sh DESCRIPTION +The +.Fn shutdown +system call disables sends or receives on a socket. +The +.Fa how +argument specifies the type of shutdown. +Possible values are: +.Bl -tag -width ".Dv SHUT_RDWR" +.It Dv SHUT_RD +Further receives will be disallowed. +.It Dv SHUT_WR +Further sends will be disallowed. +This may cause actions specific to the protocol family of the socket +.Fa s +to happen; see +.Sx IMPLEMENTATION NOTES . +.It Dv SHUT_RDWR +Further sends and receives will be disallowed. +Implies +.Dv SHUT_WR . +.El +.Pp +If the file descriptor +.Fa s +is associated with a +.Dv SOCK_STREAM +socket, all or part of the full-duplex connection will be shut down. +.\" +.Sh IMPLEMENTATION NOTES +The following protocol specific actions apply to the use of +.Dv SHUT_WR +(and potentially also +.Dv SHUT_RDWR ) , +based on the properties of the socket associated with the file descriptor +.Fa s . +.Bl -column ".Dv PF_INET6" ".Dv SOCK_STREAM" ".Dv IPPROTO_SCTP" +.It Sy Domain Ta Sy Type Ta Sy Protocol Ta Sy Action +.It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta +Failure, +as socket is not connected. +.It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta +Failure, +as socket is not connected. +.It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta +Send queued data and tear down association. +.It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta +Send queued data, wait for ACK, then send FIN. +.It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta +Failure, +as socket is not connected. +.It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta +Failure, +as socket is not connected. +.It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta +Send queued data and tear down association. +.It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta +Send queued data, wait for ACK, then send FIN. +.El +.\" +.Sh RETURN VALUES +.Rv -std shutdown +.Sh ERRORS +The +.Fn shutdown +system call fails if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa s +argument is not a valid file descriptor. +.It Bq Er EINVAL +The +.Fa how +argument is invalid. +.It Bq Er ENOTCONN +The +.Fa s +argument specifies a socket which is not connected. +.It Bq Er ENOTSOCK +The +.Fa s +argument does not refer to a socket. +.El +.Sh SEE ALSO +.Xr connect 2 , +.Xr socket 2 , +.Xr inet 4 , +.Xr inet6 4 +.Sh STANDARDS +The +.Fn shutdown +system call is expected to comply with +.St -p1003.1g-2000 , +when finalized. +.Sh HISTORY +The +.Fn shutdown +system call appeared in +.Bx 4.2 . +The +.Dv SHUT_RD , SHUT_WR , +and +.Dv SHUT_RDWR +constants appeared in +.St -p1003.1g-2000 . +.Sh AUTHORS +.An -nosplit +This manual page was updated by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +to reflect how +.Fn shutdown +behaves with +.Dv PF_INET +and +.Dv PF_INET6 +sockets. +.Sh BUGS +The ICMP +.Dq Li "port unreachable" +message should be generated in response to +datagrams received on a local port to which +.Fa s +is bound +after +.Fn shutdown +is called. diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 new file mode 100644 index 000000000000..00d8215d7b1d --- /dev/null +++ b/lib/libc/sys/sigaction.2 @@ -0,0 +1,791 @@ +.\" Copyright (c) 1980, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)sigaction.2 8.2 (Berkeley) 4/3/94 +.\" $FreeBSD$ +.\" +.Dd September 30, 2016 +.Dt SIGACTION 2 +.Os +.Sh NAME +.Nm sigaction +.Nd software signal facilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Bd -literal +struct sigaction { + void (*sa_handler)(int); + void (*sa_sigaction)(int, siginfo_t *, void *); + int sa_flags; /* see signal options below */ + sigset_t sa_mask; /* signal mask to apply */ +}; +.Ed +.Ft int +.Fo sigaction +.Fa "int sig" +.Fa "const struct sigaction * restrict act" +.Fa "struct sigaction * restrict oact" +.Fc +.Sh DESCRIPTION +The system defines a set of signals that may be delivered to a process. +Signal delivery resembles the occurrence of a hardware interrupt: +the signal is normally blocked from further occurrence, the current thread +context is saved, and a new one is built. +A process may specify a +.Em handler +to which a signal is delivered, or specify that a signal is to be +.Em ignored . +A process may also specify that a default action is to be taken +by the system when a signal occurs. +A signal may also be +.Em blocked +for a thread, +in which case it will not be delivered to that thread until it is +.Em unblocked . +The action to be taken on delivery is determined at the time +of delivery. +Normally, signal handlers execute on the current stack +of the thread. +This may be changed, on a per-handler basis, +so that signals are taken on a special +.Em "signal stack" . +.Pp +Signal routines normally execute with the signal that caused their +invocation +.Em blocked , +but other signals may yet occur. +A global +.Em "signal mask" +defines the set of signals currently blocked from delivery +to a thread. +The signal mask for a thread is initialized +from that of its parent (normally empty). +It may be changed with a +.Xr sigprocmask 2 +or +.Xr pthread_sigmask 3 +call, or when a signal is delivered to the thread. +.Pp +When a signal +condition arises for a process or thread, the signal is added to a set of +signals pending for the process or thread. +Whether the signal is directed at the process in general or at a specific +thread depends on how it is generated. +For signals directed at a specific thread, +if the signal is not currently +.Em blocked +by the thread then it is delivered to the thread. +For signals directed at the process, +if the signal is not currently +.Em blocked +by all threads then it is delivered to one thread that does not have it blocked +(the selection of which is unspecified). +Signals may be delivered any time a thread enters the operating system +(e.g., during a system call, page fault or trap, or clock interrupt). +If multiple signals are ready to be delivered at the same time, +any signals that could be caused by traps are delivered first. +Additional signals may be processed at the same time, with each +appearing to interrupt the handlers for the previous signals +before their first instructions. +The set of pending signals is returned by the +.Xr sigpending 2 +system call. +When a caught signal +is delivered, the current state of the thread is saved, +a new signal mask is calculated (as described below), +and the signal handler is invoked. +The call to the handler +is arranged so that if the signal handling routine returns +normally the thread will resume execution in the context +from before the signal's delivery. +If the thread wishes to resume in a different context, then it +must arrange to restore the previous context itself. +.Pp +When a signal is delivered to a thread a new signal mask is +installed for the duration of the process' signal handler +(or until a +.Xr sigprocmask 2 +system call is made). +This mask is formed by taking the union of the current signal mask set, +the signal to be delivered, and +the signal mask associated with the handler to be invoked. +.Pp +The +.Fn sigaction +system call +assigns an action for a signal specified by +.Fa sig . +If +.Fa act +is non-zero, it +specifies an action +.Dv ( SIG_DFL , +.Dv SIG_IGN , +or a handler routine) and mask +to be used when delivering the specified signal. +If +.Fa oact +is non-zero, the previous handling information for the signal +is returned to the user. +.Pp +The above declaration of +.Vt "struct sigaction" +is not literal. +It is provided only to list the accessible members. +See +.In sys/signal.h +for the actual definition. +In particular, the storage occupied by sa_handler and sa_sigaction overlaps, +and an application can not use both simultaneously. +.Pp +Once a signal handler is installed, it normally remains installed +until another +.Fn sigaction +system call is made, or an +.Xr execve 2 +is performed. +A signal-specific default action may be reset by +setting +.Va sa_handler +to +.Dv SIG_DFL . +The defaults are process termination, possibly with core dump; +no action; stopping the process; or continuing the process. +See the signal list below for each signal's default action. +If +.Va sa_handler +is +.Dv SIG_DFL , +the default action for the signal is to discard the signal, +and if a signal is pending, +the pending signal is discarded even if the signal is masked. +If +.Va sa_handler +is set to +.Dv SIG_IGN +current and pending instances +of the signal are ignored and discarded. +.Pp +Options may be specified by setting +.Va sa_flags . +The meaning of the various bits is as follows: +.Bl -tag -offset indent -width SA_RESETHANDXX +.It Dv SA_NOCLDSTOP +If this bit is set when installing a catching function +for the +.Dv SIGCHLD +signal, +the +.Dv SIGCHLD +signal will be generated only when a child process exits, +not when a child process stops. +.It Dv SA_NOCLDWAIT +If this bit is set when calling +.Fn sigaction +for the +.Dv SIGCHLD +signal, the system will not create zombie processes when children of +the calling process exit. +If the calling process subsequently issues a +.Xr wait 2 +(or equivalent), it blocks until all of the calling process's child +processes terminate, and then returns a value of \-1 with +.Va errno +set to +.Er ECHILD . +The same effect of avoiding zombie creation can also be achieved by setting +.Va sa_handler +for +.Dv SIGCHLD +to +.Dv SIG_IGN . +.It Dv SA_ONSTACK +If this bit is set, the system will deliver the signal to the process +on a +.Em "signal stack" , +specified by each thread with +.Xr sigaltstack 2 . +.It Dv SA_NODEFER +If this bit is set, further occurrences of the delivered signal are +not masked during the execution of the handler. +.It Dv SA_RESETHAND +If this bit is set, the handler is reset back to +.Dv SIG_DFL +at the moment the signal is delivered. +.It Dv SA_RESTART +See paragraph below. +.It Dv SA_SIGINFO +If this bit is set, the handler function is assumed to be pointed to by the +.Va sa_sigaction +member of +.Vt "struct sigaction" +and should match the prototype shown above or as below in +.Sx EXAMPLES . +This bit should not be set when assigning +.Dv SIG_DFL +or +.Dv SIG_IGN . +.El +.Pp +If a signal is caught during the system calls listed below, +the call may be forced to terminate +with the error +.Er EINTR , +the call may return with a data transfer shorter than requested, +or the call may be restarted. +Restart of pending calls is requested +by setting the +.Dv SA_RESTART +bit in +.Va sa_flags . +The affected system calls include +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr sendto 2 , +.Xr recvfrom 2 , +.Xr sendmsg 2 +and +.Xr recvmsg 2 +on a communications channel or a slow device (such as a terminal, +but not a regular file) +and during a +.Xr wait 2 +or +.Xr ioctl 2 . +However, calls that have already committed are not restarted, +but instead return a partial success (for example, a short read count). +.Pp +After a +.Xr pthread_create 3 +the signal mask is inherited by the new thread and +the set of pending signals and the signal stack for the new thread are empty. +.Pp +After a +.Xr fork 2 +or +.Xr vfork 2 +all signals, the signal mask, the signal stack, +and the restart/interrupt flags are inherited by the child. +.Pp +The +.Xr execve 2 +system call reinstates the default +action for all signals which were caught and +resets all signals to be caught on the user stack. +Ignored signals remain ignored; +the signal mask remains the same; +signals that restart pending system calls continue to do so. +.Pp +The following is a list of all signals +with names as in the include file +.In signal.h : +.Bl -column SIGVTALARMXX "create core imagexxx" +.It Sy NAME Ta Sy Default Action Ta Sy Description +.It Dv SIGHUP Ta terminate process Ta terminal line hangup +.It Dv SIGINT Ta terminate process Ta interrupt program +.It Dv SIGQUIT Ta create core image Ta quit program +.It Dv SIGILL Ta create core image Ta illegal instruction +.It Dv SIGTRAP Ta create core image Ta trace trap +.It Dv SIGABRT Ta create core image Ta Xr abort 3 call (formerly Dv SIGIOT ) +.It Dv SIGEMT Ta create core image Ta emulate instruction executed +.It Dv SIGFPE Ta create core image Ta floating-point exception +.It Dv SIGKILL Ta terminate process Ta kill program +.It Dv SIGBUS Ta create core image Ta bus error +.It Dv SIGSEGV Ta create core image Ta segmentation violation +.It Dv SIGSYS Ta create core image Ta non-existent system call invoked +.It Dv SIGPIPE Ta terminate process Ta write on a pipe with no reader +.It Dv SIGALRM Ta terminate process Ta real-time timer expired +.It Dv SIGTERM Ta terminate process Ta software termination signal +.It Dv SIGURG Ta discard signal Ta urgent condition present on socket +.It Dv SIGSTOP Ta stop process Ta stop (cannot be caught or ignored) +.It Dv SIGTSTP Ta stop process Ta stop signal generated from keyboard +.It Dv SIGCONT Ta discard signal Ta continue after stop +.It Dv SIGCHLD Ta discard signal Ta child status has changed +.It Dv SIGTTIN Ta stop process Ta background read attempted from control terminal +.It Dv SIGTTOU Ta stop process Ta background write attempted to control terminal +.It Dv SIGIO Ta discard signal Ta I/O is possible on a descriptor (see Xr fcntl 2 ) +.It Dv SIGXCPU Ta terminate process Ta cpu time limit exceeded (see Xr setrlimit 2 ) +.It Dv SIGXFSZ Ta terminate process Ta file size limit exceeded (see Xr setrlimit 2 ) +.It Dv SIGVTALRM Ta terminate process Ta virtual time alarm (see Xr setitimer 2 ) +.It Dv SIGPROF Ta terminate process Ta profiling timer alarm (see Xr setitimer 2 ) +.It Dv SIGWINCH Ta discard signal Ta window size change +.It Dv SIGINFO Ta discard signal Ta status request from keyboard +.It Dv SIGUSR1 Ta terminate process Ta user defined signal 1 +.It Dv SIGUSR2 Ta terminate process Ta user defined signal 2 +.El +.Sh NOTE +The +.Va sa_mask +field specified in +.Fa act +is not allowed to block +.Dv SIGKILL +or +.Dv SIGSTOP . +Any attempt to do so will be silently ignored. +.Pp +The following functions are either reentrant or not interruptible +by signals and are async-signal safe. +Therefore applications may +invoke them, without restriction, from signal-catching functions +or from a child process after calling +.Xr fork 2 +in a multi-threaded process: +.Pp +Base Interfaces: +.Pp +.Fn _Exit , +.Fn _exit , +.Fn accept , +.Fn access , +.Fn alarm , +.Fn bind , +.Fn cfgetispeed , +.Fn cfgetospeed , +.Fn cfsetispeed , +.Fn cfsetospeed , +.Fn chdir , +.Fn chmod , +.Fn chown , +.Fn close , +.Fn connect , +.Fn creat , +.Fn dup , +.Fn dup2 , +.Fn execl , +.Fn execle , +.Fn execv , +.Fn execve , +.Fn faccessat , +.Fn fchdir , +.Fn fchmod , +.Fn fchmodat , +.Fn fchown , +.Fn fchownat , +.Fn fcntl , +.Fn fork , +.Fn fstat , +.Fn fstatat , +.Fn fsync , +.Fn ftruncate , +.Fn getegid , +.Fn geteuid , +.Fn getgid , +.Fn getgroups , +.Fn getpeername , +.Fn getpgrp , +.Fn getpid , +.Fn getppid , +.Fn getsockname , +.Fn getsockopt , +.Fn getuid , +.Fn kill , +.Fn link , +.Fn linkat , +.Fn listen , +.Fn lseek , +.Fn lstat , +.Fn mkdir , +.Fn mkdirat , +.Fn mkfifo , +.Fn mkfifoat , +.Fn mknod , +.Fn mknodat , +.Fn open , +.Fn openat , +.Fn pause , +.Fn pipe , +.Fn poll , +.Fn pselect , +.Fn pthread_sigmask , +.Fn raise , +.Fn read , +.Fn readlink , +.Fn readlinkat , +.Fn recv , +.Fn recvfrom , +.Fn recvmsg , +.Fn rename , +.Fn renameat , +.Fn rmdir , +.Fn select , +.Fn send , +.Fn sendmsg , +.Fn sendto , +.Fn setgid , +.Fn setpgid , +.Fn setsid , +.Fn setsockopt , +.Fn setuid , +.Fn shutdown , +.Fn sigaction , +.Fn sigaddset , +.Fn sigdelset , +.Fn sigemptyset , +.Fn sigfillset , +.Fn sigismember , +.Fn signal , +.Fn sigpending , +.Fn sigprocmask , +.Fn sigsuspend , +.Fn sleep , +.Fn sockatmark , +.Fn socket , +.Fn socketpair , +.Fn stat , +.Fn symlink , +.Fn symlinkat , +.Fn tcdrain , +.Fn tcflow , +.Fn tcflush , +.Fn tcgetattr , +.Fn tcgetpgrp , +.Fn tcsendbreak , +.Fn tcsetattr , +.Fn tcsetpgrp , +.Fn time , +.Fn times , +.Fn umask , +.Fn uname , +.Fn unlink , +.Fn unlinkat , +.Fn utime , +.Fn wait , +.Fn waitpid , +.Fn write . +.Pp +X/Open Systems Interfaces: +.Pp +.Fn sigpause , +.Fn sigset , +.Fn utimes . +.Pp +Realtime Interfaces: +.Pp +.Fn aio_error , +.Fn clock_gettime , +.Fn timer_getoverrun , +.Fn aio_return , +.Fn fdatasync , +.Fn sigqueue , +.Fn timer_gettime , +.Fn aio_suspend , +.Fn sem_post , +.Fn timer_settime . +.Pp +Base Interfaces not specified as async-signal safe by +.Tn POSIX : +.Pp +.Fn fpathconf , +.Fn pathconf , +.Fn sysconf . +.Pp +Base Interfaces not specified as async-signal safe by +.Tn POSIX , +but planned to be: +.Pp +.Fn ffs , +.Fn htonl , +.Fn htons , +.Fn memccpy , +.Fn memchr , +.Fn memcmp , +.Fn memcpy , +.Fn memmove , +.Fn memset , +.Fn ntohl , +.Fn ntohs , +.Fn stpcpy , +.Fn stpncpy , +.Fn strcat , +.Fn strchr , +.Fn strcmp , +.Fn strcpy , +.Fn strcspn , +.Fn strlen , +.Fn strncat , +.Fn strncmp , +.Fn strncpy , +.Fn strnlen , +.Fn strpbrk , +.Fn strrchr , +.Fn strspn , +.Fn strstr , +.Fn strtok_r , +.Fn wcpcpy , +.Fn wcpncpy , +.Fn wcscat , +.Fn wcschr , +.Fn wcscmp , +.Fn wcscpy , +.Fn wcscspn , +.Fn wcslen , +.Fn wcsncat , +.Fn wcsncmp , +.Fn wcsncpy , +.Fn wcsnlen , +.Fn wcspbrk , +.Fn wcsrchr , +.Fn wcsspn , +.Fn wcsstr , +.Fn wcstok , +.Fn wmemchr , +.Fn wmemcmp , +.Fn wmemcpy , +.Fn wmemmove , +.Fn wmemset . +.Pp +Extension Interfaces: +.Pp +.Fn accept4 , +.Fn bindat , +.Fn closefrom , +.Fn connectat , +.Fn eaccess , +.Fn ffsl , +.Fn ffsll , +.Fn flock , +.Fn fls , +.Fn flsl , +.Fn flsll , +.Fn futimesat , +.Fn pipe2 , +.Fn strlcat . +.Fn strlcpy , +.Fn strsep . +.Pp +In addition, reading or writing +.Va errno +is async-signal safe. +.Pp +All functions not in the above lists are considered to be unsafe +with respect to signals. +That is to say, the behaviour of such +functions is undefined when they are called from a signal handler +that interrupted an unsafe function. +In general though, signal handlers should do little more than set a +flag; most other actions are not safe. +.Pp +Also, it is good practice to make a copy of the global variable +.Va errno +and restore it before returning from the signal handler. +This protects against the side effect of +.Va errno +being set by functions called from inside the signal handler. +.Sh RETURN VALUES +.Rv -std sigaction +.Sh EXAMPLES +There are three possible prototypes the handler may match: +.Bl -tag -offset indent -width short +.It Tn ANSI C : +.Ft void +.Fn handler int ; +.It Traditional BSD style: +.Ft void +.Fn handler int "int code" "struct sigcontext *scp" ; +.It Tn POSIX Dv SA_SIGINFO : +.Ft void +.Fn handler int "siginfo_t *info" "ucontext_t *uap" ; +.El +.Pp +The handler function should match the +.Dv SA_SIGINFO +prototype if the +.Dv SA_SIGINFO +bit is set in +.Va sa_flags . +It then should be pointed to by the +.Va sa_sigaction +member of +.Vt "struct sigaction" . +Note that you should not assign +.Dv SIG_DFL +or +.Dv SIG_IGN +this way. +.Pp +If the +.Dv SA_SIGINFO +flag is not set, the handler function should match +either the +.Tn ANSI C +or traditional +.Bx +prototype and be pointed to by +the +.Va sa_handler +member of +.Vt "struct sigaction" . +In practice, +.Fx +always sends the three arguments of the latter and since the +.Tn ANSI C +prototype is a subset, both will work. +The +.Va sa_handler +member declaration in +.Fx +include files is that of +.Tn ANSI C +(as required by +.Tn POSIX ) , +so a function pointer of a +.Bx Ns -style +function needs to be casted to +compile without warning. +The traditional +.Bx +style is not portable and since its capabilities +are a full subset of a +.Dv SA_SIGINFO +handler, +its use is deprecated. +.Pp +The +.Fa sig +argument is the signal number, one of the +.Dv SIG... +values from +.In signal.h . +.Pp +The +.Fa code +argument of the +.Bx Ns -style +handler and the +.Va si_code +member of the +.Fa info +argument to a +.Dv SA_SIGINFO +handler contain a numeric code explaining the +cause of the signal, usually one of the +.Dv SI_... +values from +.In sys/signal.h +or codes specific to a signal, i.e., one of the +.Dv FPE_... +values for +.Dv SIGFPE . +.Pp +The +.Fa scp +argument to a +.Bx Ns -style +handler points to an instance of +.Vt "struct sigcontext" . +.Pp +The +.Fa uap +argument to a +.Tn POSIX +.Dv SA_SIGINFO +handler points to an instance of +ucontext_t. +.Sh ERRORS +The +.Fn sigaction +system call +will fail and no new signal handler will be installed if one +of the following occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sig +argument +is not a valid signal number. +.It Bq Er EINVAL +An attempt is made to ignore or supply a handler for +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr kill 1 , +.Xr kill 2 , +.Xr ptrace 2 , +.Xr setitimer 2 , +.Xr setrlimit 2 , +.Xr sigaltstack 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr wait 2 , +.Xr fpsetmask 3 , +.Xr setjmp 3 , +.Xr siginfo 3 , +.Xr siginterrupt 3 , +.Xr sigsetops 3 , +.Xr ucontext 3 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn sigaction +system call is expected to conform to +.St -p1003.1-90 . +The +.Dv SA_ONSTACK +and +.Dv SA_RESTART +flags are Berkeley extensions, +as are the signals, +.Dv SIGTRAP , +.Dv SIGEMT , +.Dv SIGBUS , +.Dv SIGSYS , +.Dv SIGURG , +.Dv SIGIO , +.Dv SIGXCPU , +.Dv SIGXFSZ , +.Dv SIGVTALRM , +.Dv SIGPROF , +.Dv SIGWINCH , +and +.Dv SIGINFO . +Those signals are available on most +.Bx Ns \-derived +systems. +The +.Dv SA_NODEFER +and +.Dv SA_RESETHAND +flags are intended for backwards compatibility with other operating +systems. +The +.Dv SA_NOCLDSTOP , +and +.Dv SA_NOCLDWAIT +.\" and +.\" SA_SIGINFO +flags are featuring options commonly found in other operating systems. +The flags are approved by +.St -susv2 , +along with the option to avoid zombie creation by ignoring +.Dv SIGCHLD . diff --git a/lib/libc/sys/sigaction.c b/lib/libc/sys/sigaction.c new file mode 100644 index 000000000000..b4d65639b816 --- /dev/null +++ b/lib/libc/sys/sigaction.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__sys_sigaction, __sigaction); +__weak_reference(sigaction, __libc_sigaction); + +#pragma weak sigaction +int +sigaction(int sig, const struct sigaction *act, struct sigaction *oact) +{ + + return (((int (*)(int, const struct sigaction *, struct sigaction *)) + __libc_interposing[INTERPOS_sigaction])(sig, act, oact)); +} diff --git a/lib/libc/sys/sigaltstack.2 b/lib/libc/sys/sigaltstack.2 new file mode 100644 index 000000000000..d9cb27362592 --- /dev/null +++ b/lib/libc/sys/sigaltstack.2 @@ -0,0 +1,162 @@ +.\" Copyright (c) 1983, 1991, 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigaltstack.2 8.2 (Berkeley) 5/1/95 +.\" $FreeBSD$ +.\" +.Dd May 6, 2010 +.Dt SIGALTSTACK 2 +.Os +.Sh NAME +.Nm sigaltstack +.Nd set and/or get signal stack context +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Bd -literal +typedef struct { + char *ss_sp; + size_t ss_size; + int ss_flags; +} stack_t; +.Ed +.Ft int +.Fn sigaltstack "const stack_t * restrict ss" "stack_t * restrict oss" +.Sh DESCRIPTION +The +.Fn sigaltstack +system call +allows defining an alternate stack on which signals +are to be processed for the current thread. +If +.Fa ss +is non-zero, +it specifies a pointer to and the size of a +.Em "signal stack" +on which to deliver signals. +When a signal's action indicates its handler +should execute on the signal stack (specified with a +.Xr sigaction 2 +system call), the system checks to see +if the thread is currently executing on that stack. +If the thread is not currently executing on the signal stack, +the system arranges a switch to the signal stack for the +duration of the signal handler's execution. +.Pp +An active stack cannot be modified. +.Pp +If +.Dv SS_DISABLE +is set in +.Fa ss_flags , +.Fa ss_sp +and +.Fa ss_size +are ignored and the signal stack will be disabled. +A disabled stack will cause all signals to be +taken on the regular user stack. +If the stack is later re-enabled then all signals that were specified +to be processed on an alternate stack will resume doing so. +.Pp +If +.Fa oss +is non-zero, the current signal stack state is returned. +The +.Fa ss_flags +field will contain the value +.Dv SS_ONSTACK +if the thread is currently on a signal stack and +.Dv SS_DISABLE +if the signal stack is currently disabled. +.Sh NOTES +The value +.Dv SIGSTKSZ +is defined to be the number of bytes/chars that would be used to cover +the usual case when allocating an alternate stack area. +The following code fragment is typically used to allocate an alternate stack. +.Bd -literal -offset indent +if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) + /* error return */ +sigstk.ss_size = SIGSTKSZ; +sigstk.ss_flags = 0; +if (sigaltstack(&sigstk, NULL) < 0) + perror("sigaltstack"); +.Ed +An alternative approach is provided for programs with signal handlers +that require a specific amount of stack space other than the default size. +The value +.Dv MINSIGSTKSZ +is defined to be the number of bytes/chars that is required by +the operating system to implement the alternate stack feature. +In computing an alternate stack size, +programs should add +.Dv MINSIGSTKSZ +to their stack requirements to allow for the operating system overhead. +.Pp +Signal stacks are automatically adjusted for the direction of stack +growth and alignment requirements. +Signal stacks may or may not be protected by the hardware and +are not ``grown'' automatically as is done for the normal stack. +If the stack overflows and this space is not protected +unpredictable results may occur. +.Sh RETURN VALUES +.Rv -std sigaltstack +.Sh ERRORS +The +.Fn sigaltstack +system call +will fail and the signal stack context will remain unchanged +if one of the following occurs. +.Bl -tag -width Er +.It Bq Er EFAULT +Either +.Fa ss +or +.Fa oss +points to memory that is not a valid part of the process +address space. +.It Bq Er EPERM +An attempt was made to modify an active stack. +.It Bq Er EINVAL +The +.Fa ss_flags +field was invalid. +.It Bq Er ENOMEM +Size of alternate stack area is less than or equal to +.Dv MINSIGSTKSZ . +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr setjmp 3 +.Sh HISTORY +The predecessor to +.Fn sigaltstack , +the +.Fn sigstack +system call, appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/sigpending.2 b/lib/libc/sys/sigpending.2 new file mode 100644 index 000000000000..06ecc004501d --- /dev/null +++ b/lib/libc/sys/sigpending.2 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Berkeley Software Design, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigpending.2 8.3 (Berkeley) 1/12/94 +.\" $FreeBSD$ +.\" +.Dd September 6, 2013 +.Dt SIGPENDING 2 +.Os +.Sh NAME +.Nm sigpending +.Nd get pending signals +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigpending "sigset_t *set" +.Sh DESCRIPTION +The +.Fn sigpending +system call returns a mask of the signals pending for delivery +to the calling thread or the calling process in the location indicated by +.Fa set . +Signals may be pending because they are currently masked, +or transiently before delivery (although the latter case is not +normally detectable). +.Sh RETURN VALUES +.Rv -std sigpending +.Sh ERRORS +The +.Fn sigpending +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa set +argument specified an invalid address. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn sigpending +system call is expected to conform to +.St -p1003.1-90 . diff --git a/lib/libc/sys/sigprocmask.2 b/lib/libc/sys/sigprocmask.2 new file mode 100644 index 000000000000..f7c833535882 --- /dev/null +++ b/lib/libc/sys/sigprocmask.2 @@ -0,0 +1,131 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigprocmask.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd May 7, 2010 +.Dt SIGPROCMASK 2 +.Os +.Sh NAME +.Nm sigprocmask +.Nd manipulate current signal mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fo sigprocmask +.Fa "int how" +.Fa "const sigset_t * restrict set" +.Fa "sigset_t * restrict oset" +.Fc +.Sh DESCRIPTION +The +.Fn sigprocmask +system call examines and/or changes the current signal mask (those signals +that are blocked from delivery). +Signals are blocked if they are members of the current signal mask set. +.Pp +If +.Fa set +is not null, the action of +.Fn sigprocmask +depends on the value of the +.Fa how +argument. +The signal mask is changed as a function of the specified +.Fa set +and the current mask. +The function is specified by +.Fa how +using one of the following values from +.In signal.h : +.Bl -tag -width SIG_UNBLOCK +.It Dv SIG_BLOCK +The new mask is the union of the current mask and the specified +.Fa set . +.It Dv SIG_UNBLOCK +The new mask is the intersection of the current mask +and the complement of the specified +.Fa set . +.It Dv SIG_SETMASK +The current mask is replaced by the specified +.Fa set . +.El +.Pp +If +.Fa oset +is not null, it is set to +the previous value of the signal mask. +When +.Fa set +is null, +the value of +.Fa how +is insignificant and the mask remains unset +providing a way to examine the signal mask without modification. +.Pp +The system +quietly disallows +.Dv SIGKILL +or +.Dv SIGSTOP +to be blocked. +.Pp +In threaded applications, +.Xr pthread_sigmask 3 +must be used instead of +.Fn sigprocmask . +.Sh RETURN VALUES +.Rv -std sigprocmask +.Sh ERRORS +The +.Fn sigprocmask +system call will fail and the signal mask will be unchanged if one +of the following occurs: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa how +argument +has a value other than those listed here. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigsuspend 2 , +.Xr fpsetmask 3 , +.Xr pthread_sigmask 3 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn sigprocmask +system call is expected to +conform to +.St -p1003.1-90 . diff --git a/lib/libc/sys/sigprocmask.c b/lib/libc/sys/sigprocmask.c new file mode 100644 index 000000000000..d24bb89c1f79 --- /dev/null +++ b/lib/libc/sys/sigprocmask.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__sys_sigprocmask, __sigprocmask); +__weak_reference(sigprocmask, __libc_sigprocmask); + +#pragma weak sigprocmask +int +sigprocmask(int how, const sigset_t *set, sigset_t *oset) +{ + + return (((int (*)(int, const sigset_t *, sigset_t *)) + __libc_interposing[INTERPOS_sigprocmask])(how, set, oset)); +} diff --git a/lib/libc/sys/sigqueue.2 b/lib/libc/sys/sigqueue.2 new file mode 100644 index 000000000000..04e101bc3443 --- /dev/null +++ b/lib/libc/sys/sigqueue.2 @@ -0,0 +1,149 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 10, 2012 +.Dt SIGQUEUE 2 +.Os +.Sh NAME +.Nm sigqueue +.Nd "queue a signal to a process (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigqueue "pid_t pid" "int signo" "const union sigval value" +.Sh DESCRIPTION +The +.Fn sigqueue +system call causes the signal specified by +.Fa signo +to be sent with the value specified by +.Fa value +to the process specified by +.Fa pid . +If +.Fa signo +is zero (the null signal), error checking is performed but +no signal is actually sent. +The null signal can be used to check the +validity of PID. +.Pp +The conditions required for a process to have permission to queue a +signal to another process are the same as for the +.Xr kill 2 +system call. +The +.Fn sigqueue +system call queues a signal to a single process specified by the +.Fa pid +argument. +.Pp +The +.Fn sigqueue +system call returns immediately. +If the resources were +available to queue the signal, the signal will be queued and sent to +the receiving process. +.Pp +If the value of +.Fa pid +causes +.Fa signo +to be generated for the sending process, and if +.Fa signo +is not blocked for the calling thread and if no other thread has +.Fa signo +unblocked or is waiting in a +.Fn sigwait +system call for +.Fa signo , +either +.Fa signo +or at least the pending, unblocked signal will be delivered to the +calling thread before +.Fn sigqueue +returns. +Should any multiple pending signals in the range +.Dv SIGRTMIN +to +.Dv SIGRTMAX +be selected for delivery, it is the lowest numbered +one. +The selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn sigqueue +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No resources are available to queue the signal. +The process has already +queued +.Brq Dv SIGQUEUE_MAX +signals that are still pending at the receiver(s), +or a system-wide resource limit has been exceeded. +.It Bq Er EINVAL +The value of the +.Fa signo +argument is an invalid or unsupported signal number. +.It Bq Er EPERM +The process does not have the appropriate privilege to send the signal +to the receiving process. +.It Bq Er ESRCH +The process +.Fa pid +does not exist. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigqueue 2 , +.Xr sigsuspend 2 , +.Xr sigtimedwait 2 , +.Xr sigwait 2 , +.Xr sigwaitinfo 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn sigqueue +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +realtime signal queue first appeared in +.Fx 7.0 . diff --git a/lib/libc/sys/sigreturn.2 b/lib/libc/sys/sigreturn.2 new file mode 100644 index 000000000000..1b76468a84ec --- /dev/null +++ b/lib/libc/sys/sigreturn.2 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1985, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigreturn.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd September 6, 2013 +.Dt SIGRETURN 2 +.Os +.Sh NAME +.Nm sigreturn +.Nd return from signal +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigreturn "const ucontext_t *scp" +.Sh DESCRIPTION +The +.Fn sigreturn +system call +allows users to atomically unmask, switch stacks, +and return from a signal context. +The thread's signal mask and stack status are +restored from the context structure pointed to by +.Fa scp . +The system call does not return; +the users stack pointer, frame pointer, argument pointer, +and processor status longword are restored from the context. +Execution resumes at the specified pc. +This system call is used by the trampoline code and +.Xr longjmp 3 +when returning from a signal to the previously executing program. +.Sh RETURN VALUES +If successful, the system call does not return. +Otherwise, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn sigreturn +system call +will fail and the thread context will remain unchanged +if one of the following occurs. +.Bl -tag -width Er +.It Bq Er EFAULT +The +.Fa scp +argument +points to memory that is not a valid part of the process +address space. +.It Bq Er EINVAL +The process status longword is invalid or would improperly +raise the privilege level of the process. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr setjmp 3 , +.Xr ucontext 3 +.Sh HISTORY +The +.Fn sigreturn +system call appeared in +.Bx 4.3 . diff --git a/lib/libc/sys/sigstack.2 b/lib/libc/sys/sigstack.2 new file mode 100644 index 000000000000..efd7ed76e673 --- /dev/null +++ b/lib/libc/sys/sigstack.2 @@ -0,0 +1,50 @@ +.\" Copyright (c) 1983, 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigstack.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt SIGSTACK 2 +.Os +.Sh NAME +.Nm sigstack +.Nd set and/or get signal stack context +.Sh LIBRARY +.Lb libc +.Sh DESCRIPTION +The +.Fn sigstack +function has been deprecated in favor of the interface described in +.Xr sigaltstack 2 . +.Sh SEE ALSO +.Xr sigaltstack 2 +.Sh HISTORY +The +.Fn sigstack +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/sigsuspend.2 b/lib/libc/sys/sigsuspend.2 new file mode 100644 index 000000000000..0ffc11dc4f3e --- /dev/null +++ b/lib/libc/sys/sigsuspend.2 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sigsuspend.2 8.2 (Berkeley) 5/16/95 +.\" $FreeBSD$ +.\" +.Dd August 16, 2013 +.Dt SIGSUSPEND 2 +.Os +.Sh NAME +.Nm sigsuspend +.Nd atomically release blocked signals and wait for interrupt +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigsuspend "const sigset_t *sigmask" +.Sh DESCRIPTION +The +.Fn sigsuspend +system call +temporarily changes the blocked signal mask to the set to which +.Fa sigmask +points, +and then waits for a signal to arrive; +on return the previous set of masked signals is restored. +The signal mask set +is usually empty to indicate that all +signals are to be unblocked for the duration of the call. +.Pp +In normal usage, a signal is blocked using +.Xr sigprocmask 2 +to begin a critical section, variables modified on the occurrence +of the signal are examined to determine that there is no work +to be done, and the process pauses awaiting work by using +.Fn sigsuspend +with the previous mask returned by +.Xr sigprocmask 2 . +.Sh RETURN VALUES +The +.Fn sigsuspend +system call +always terminates by being interrupted, returning -1 with +.Va errno +set to +.Er EINTR . +.Sh SEE ALSO +.Xr pselect 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigtimedwait 2 , +.Xr sigwait 2 , +.Xr sigwaitinfo 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn sigsuspend +system call is expected to conform to +.St -p1003.1-90 . diff --git a/lib/libc/sys/sigsuspend.c b/lib/libc/sys/sigsuspend.c new file mode 100644 index 000000000000..1f980a117a1b --- /dev/null +++ b/lib/libc/sys/sigsuspend.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__sys_sigsuspend, __sigsuspend); +__weak_reference(sigsuspend, __libc_sigsuspend); + +#pragma weak sigsuspend +int +sigsuspend(const sigset_t *set) +{ + + return (((int (*)(const sigset_t *)) + __libc_interposing[INTERPOS_sigsuspend])(set)); +} diff --git a/lib/libc/sys/sigtimedwait.c b/lib/libc/sys/sigtimedwait.c new file mode 100644 index 000000000000..4e067192ca4b --- /dev/null +++ b/lib/libc/sys/sigtimedwait.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__sys_sigtimedwait, __sigtimedwait); + +#pragma weak sigtimedwait +int +sigtimedwait(const sigset_t * __restrict set, siginfo_t * __restrict info, + const struct timespec * __restrict t) +{ + + return (((int (*)(const sigset_t *, siginfo_t *, + const struct timespec *)) + __libc_interposing[INTERPOS_sigtimedwait])(set, info, t)); +} diff --git a/lib/libc/sys/sigwait.2 b/lib/libc/sys/sigwait.2 new file mode 100644 index 000000000000..4da64a99dddd --- /dev/null +++ b/lib/libc/sys/sigwait.2 @@ -0,0 +1,124 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 6, 2013 +.Dt SIGWAIT 2 +.Os +.Sh NAME +.Nm sigwait +.Nd select a set of signals +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigwait "const sigset_t * restrict set" "int * restrict sig" +.Sh DESCRIPTION +The +.Fn sigwait +system call selects a set of signals, specified by +.Fa set . +If none of the selected signals are pending, +.Fn sigwait +waits until one or more of the selected signals has been generated. +Then +.Fn sigwait +atomically clears one of the selected signals from the set of pending signals +(for the process or for the current thread) and sets the location pointed to by +.Fa sig +to the signal number that was cleared. +.Pp +The signals specified by +.Fa set +should be blocked at the time of the call to +.Fn sigwait . +.Pp +If more than one thread is using +.Fn sigwait +to wait for the same signal, no more than one of these threads will return from +.Fn sigwait +with the signal number. +If more than a single thread is blocked in +.Fn sigwait +for a signal when that signal is generated for the process, it is unspecified +which of the waiting threads returns from +.Fn sigwait . +If the signal is generated for a specific thread, as by +.Fn pthread_kill , +only that thread will return. +.Pp +Should any of the multiple pending signals in the range +.Dv SIGRTMIN +to +.Dv SIGRTMAX +be +selected, it will be the lowest numbered one. +The selection order between realtime +and non-realtime signals, or between multiple pending non-realtime signals, +is unspecified. +.Sh IMPLEMENTATION NOTES +The +.Fn sigwait +function is implemented as a wrapper around the +.Fn __sys_sigwait +system call, which retries the call on +.Er EINTR +error. +.Sh RETURN VALUES +If successful, +.Fn sigwait +returns 0 and sets the location pointed to by +.Fa sig +to the cleared signal number. +Otherwise, an error number is returned. +.Sh ERRORS +The +.Fn sigwait +system call will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa set +argument +specifies one or more invalid signal numbers. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigqueue 2 , +.Xr sigsuspend 2 , +.Xr sigtimedwait 2 , +.Xr sigwaitinfo 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 +.Sh STANDARDS +The +.Fn sigwait +function conforms to +.St -p1003.1-96 . diff --git a/lib/libc/sys/sigwait.c b/lib/libc/sys/sigwait.c new file mode 100644 index 000000000000..b21cabdeac55 --- /dev/null +++ b/lib/libc/sys/sigwait.c @@ -0,0 +1,54 @@ +/*- + * Copyright (c) 2010 davidxu@freebsd.org + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <errno.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__libc_sigwait, __sigwait); + +#pragma weak sigwait +int +sigwait(const sigset_t *set, int *sig) +{ + + return (((int (*)(const sigset_t *, int *)) + __libc_interposing[INTERPOS_sigwait])(set, sig)); +} + +int +__libc_sigwait(const sigset_t *set, int *sig) +{ + int ret; + + /* POSIX does not allow EINTR to be returned */ + do { + ret = __sys_sigwait(set, sig); + } while (ret == EINTR); + return (ret); +} diff --git a/lib/libc/sys/sigwaitinfo.2 b/lib/libc/sys/sigwaitinfo.2 new file mode 100644 index 000000000000..b497592ed1f3 --- /dev/null +++ b/lib/libc/sys/sigwaitinfo.2 @@ -0,0 +1,206 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 27, 2012 +.Dt SIGTIMEDWAIT 2 +.Os +.Sh NAME +.Nm sigtimedwait , sigwaitinfo +.Nd "wait for queued signals (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fo sigtimedwait +.Fa "const sigset_t *restrict set" "siginfo_t *restrict info" +.Fa "const struct timespec *restrict timeout" +.Fc +.Ft int +.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" +.Sh DESCRIPTION +The +.Fn sigtimedwait +system call is equivalent to +.Fn sigwaitinfo +except that if none of the signals specified by +.Fa set +are pending, +.Fn sigtimedwait +waits for the time interval specified in the +.Vt timespec +structure referenced by +.Fa timeout . +If the +.Vt timespec +structure pointed to by +.Fa timeout +is zero-valued and if none of the signals specified by +.Fa set +are pending, then +.Fn sigtimedwait +returns immediately with an error. +If +.Fa timeout +is the +.Dv NULL +pointer, the behavior is unspecified. +.Dv CLOCK_MONOTONIC +clock is used to measure the time interval specified by the +.Fa timeout +argument. +.Pp +The +.Fn sigwaitinfo +system call selects the pending signal from the set specified by +.Fa set . +Should any of multiple pending signals in the range +.Dv SIGRTMIN +to +.Dv SIGRTMAX +be selected, it shall be the lowest numbered one. +The +selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +If no signal in +.Fa set +is pending at the time of the call, the calling thread +is suspended until one or more signals in +.Fa set +become pending or until it is interrupted by an unblocked, caught signal. +.Pp +The +.Fn sigwaitinfo +system call is equivalent to the +.Fn sigwait +system call if the +.Fa info +argument is +.Dv NULL . +If the +.Fa info +argument is +.Pf non- Dv NULL , +the +.Fn sigwaitinfo +function is equivalent to +.Fn sigwait , +except that the selected signal number shall be stored in the +.Va si_signo +member, and the cause of the signal shall be stored in the +.Va si_code +member. +Besides this, the +.Fn sigwaitinfo +and +.Fn sigtimedwait +system calls may return +.Er EINTR +if interrupted by signal, which is not allowed for the +.Fn sigwait +function. +.Pp +If any value is queued to the selected signal, the first such queued +value is dequeued and, if the info argument is +.Pf non- Dv NULL , +the value is stored in the +.Va si_value +member of +.Fa info . +The system resource used to queue the signal +is released and returned to the system for other use. +If no value is queued, +the content of the +.Va si_value +member is zero-valued. +If no further signals are +queued for the selected signal, the pending indication for that signal +is reset. +.Sh RETURN VALUES +Upon successful completion (that is, one of the signals specified by +.Fa set +is pending or is generated) +.Fn sigwaitinfo +and +.Fn sigtimedwait +return the selected signal number. +Otherwise, the functions return a value of \-1 +and set the global variable +.Va errno +to indicate the error. +.Sh ERRORS +The +.Fn sigtimedwait +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No signal specified by set was generated within the specified timeout period. +.El +.Pp +The +.Fn sigtimedwait +and +.Fn sigwaitinfo +system calls fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The wait was interrupted by an unblocked, caught signal. +.El +.Pp +The +.Fn sigtimedwait +system call may also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa timeout +argument specified a +.Va tv_nsec +value less than zero or greater than or equal +to 1000 million. +Kernel only checks for this error if no signal is pending in set and it +is necessary to wait. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigqueue 2 , +.Xr sigsuspend 2 , +.Xr sigwait 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn sigtimedwait +and +.Fn sigwaitinfo +system calls conform to +.St -p1003.1-96 . diff --git a/lib/libc/sys/sigwaitinfo.c b/lib/libc/sys/sigwaitinfo.c new file mode 100644 index 000000000000..b9cdc79bc224 --- /dev/null +++ b/lib/libc/sys/sigwaitinfo.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__sys_sigwaitinfo, __sigwaitinfo); + +#pragma weak sigwaitinfo +int +sigwaitinfo(const sigset_t * __restrict set, siginfo_t * __restrict info) +{ + + return (((int (*)(const sigset_t *, siginfo_t *)) + __libc_interposing[INTERPOS_sigwaitinfo])(set, info)); +} diff --git a/lib/libc/sys/socket.2 b/lib/libc/sys/socket.2 new file mode 100644 index 000000000000..3e7e9d92d151 --- /dev/null +++ b/lib/libc/sys/socket.2 @@ -0,0 +1,350 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)socket.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd August 18, 2016 +.Dt SOCKET 2 +.Os +.Sh NAME +.Nm socket +.Nd create an endpoint for communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn socket "int domain" "int type" "int protocol" +.Sh DESCRIPTION +The +.Fn socket +system call +creates an endpoint for communication and returns a descriptor. +.Pp +The +.Fa domain +argument specifies a communications domain within which +communication will take place; this selects the protocol family +which should be used. +These families are defined in the include file +.In sys/socket.h . +The currently understood formats are: +.Pp +.Bd -literal -offset indent -compact +PF_LOCAL Host-internal protocols (alias for PF_UNIX), +PF_UNIX Host-internal protocols, +PF_INET Internet version 4 protocols, +PF_INET6 Internet version 6 protocols, +PF_ROUTE Internal routing protocol, +PF_LINK Link layer interface, +PF_KEY Internal key-management function, +PF_NATM Asynchronous transfer mode protocols, +PF_NETGRAPH Netgraph sockets, +PF_IEEE80211 IEEE 802.11 wireless link-layer protocols (WiFi), +PF_BLUETOOTH Bluetooth protocols, +PF_INET_SDP OFED socket direct protocol (IPv4), +PF_INET6_SDP OFED socket direct protocol (IPv6) +.Ed +.Pp +Each protocol family is connected to an address family, which has the +same name except that the prefix is +.Dq Dv AF_ +in place of +.Dq Dv PF_ . +Other protocol families may be also defined, beginning with +.Dq Dv PF_ , +with corresponding address families. +.Pp +The socket has the indicated +.Fa type , +which specifies the semantics of communication. +Currently +defined types are: +.Pp +.Bd -literal -offset indent -compact +SOCK_STREAM Stream socket, +SOCK_DGRAM Datagram socket, +SOCK_RAW Raw-protocol interface, +SOCK_RDM Reliably-delivered packet, +SOCK_SEQPACKET Sequenced packet stream +.Ed +.Pp +A +.Dv SOCK_STREAM +type provides sequenced, reliable, +two-way connection based byte streams. +An out-of-band data transmission mechanism may be supported. +A +.Dv SOCK_DGRAM +socket supports +datagrams (connectionless, unreliable messages of +a fixed (typically small) maximum length). +A +.Dv SOCK_SEQPACKET +socket may provide a sequenced, reliable, +two-way connection-based data transmission path for datagrams +of fixed maximum length; a consumer may be required to read +an entire packet with each read system call. +This facility is protocol specific, and presently unimplemented. +.Dv SOCK_RAW +sockets provide access to internal network protocols and interfaces. +The types +.Dv SOCK_RAW , +which is available only to the super-user, and +.Dv SOCK_RDM , +which is planned, +but not yet implemented, are not described here. +.Pp +Additionally, the following flags are allowed in the +.Fa type +argument: +.Pp +.Bd -literal -offset indent -compact +SOCK_CLOEXEC Set close-on-exec on the new descriptor, +SOCK_NONBLOCK Set non-blocking mode on the new socket +.Ed +.Pp +The +.Fa protocol +argument +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +socket type within a given protocol family. +However, it is possible +that many protocols may exist, in which case a particular protocol +must be specified in this manner. +The protocol number to use is +particular to the +.Dq "communication domain" +in which communication +is to take place; see +.Xr protocols 5 . +.Pp +The +.Fa protocol +argument may be set to zero (0) to request the default +implementation of a socket type for the protocol, if any. +.Pp +Sockets of type +.Dv SOCK_STREAM +are full-duplex byte streams, similar +to pipes. +A stream socket must be in a +.Em connected +state before any data may be sent or received +on it. +A connection to another socket is created with a +.Xr connect 2 +system call. +Once connected, data may be transferred using +.Xr read 2 +and +.Xr write 2 +calls or some variant of the +.Xr send 2 +and +.Xr recv 2 +functions. +(Some protocol families, such as the Internet family, +support the notion of an +.Dq implied connect , +which permits data to be sent piggybacked onto a connect operation by +using the +.Xr sendto 2 +system call.) +When a session has been completed a +.Xr close 2 +may be performed. +Out-of-band data may also be transmitted as described in +.Xr send 2 +and received as described in +.Xr recv 2 . +.Pp +The communications protocols used to implement a +.Dv SOCK_STREAM +ensure that data +is not lost or duplicated. +If a piece of data for which the +peer protocol has buffer space cannot be successfully transmitted +within a reasonable length of time, then +the connection is considered broken and calls +will indicate an error with +-1 returns and with +.Er ETIMEDOUT +as the specific code +in the global variable +.Va errno . +The protocols optionally keep sockets +.Dq warm +by forcing transmissions +roughly every minute in the absence of other activity. +An error is then indicated if no response can be +elicited on an otherwise +idle connection for an extended period (e.g.\& 5 minutes). +By default, a +.Dv SIGPIPE +signal is raised if a process sends +on a broken stream, but this behavior may be inhibited via +.Xr setsockopt 2 . +.Pp +.Dv SOCK_SEQPACKET +sockets employ the same system calls +as +.Dv SOCK_STREAM +sockets. +The only difference +is that +.Xr read 2 +calls will return only the amount of data requested, +and any remaining in the arriving packet will be discarded. +.Pp +.Dv SOCK_DGRAM +and +.Dv SOCK_RAW +sockets allow sending of datagrams to correspondents +named in +.Xr send 2 +calls. +Datagrams are generally received with +.Xr recvfrom 2 , +which returns the next datagram with its return address. +.Pp +An +.Xr fcntl 2 +system call can be used to specify a process group to receive +a +.Dv SIGURG +signal when the out-of-band data arrives. +It may also enable non-blocking I/O +and asynchronous notification of I/O events +via +.Dv SIGIO . +.Pp +The operation of sockets is controlled by socket level +.Em options . +These options are defined in the file +.In sys/socket.h . +The +.Xr setsockopt 2 +and +.Xr getsockopt 2 +system calls are used to set and get options, respectively. +.Sh RETURN VALUES +A -1 is returned if an error occurs, otherwise the return +value is a descriptor referencing the socket. +.Sh ERRORS +The +.Fn socket +system call fails if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.It Bq Er EAFNOSUPPORT +The address family (domain) is not supported or the +specified domain is not supported by this protocol family. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOBUFS +Insufficient buffer space is available. +The socket cannot be created until sufficient resources are freed. +.It Bq Er EPERM +User has insufficient privileges to carry out the requested operation. +.It Bq Er EPROTONOSUPPORT +The protocol type or the specified protocol is not supported +within this domain. +.It Bq Er EPROTOTYPE +The socket type is not supported by the protocol. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr getpeername 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr ioctl 2 , +.Xr listen 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr shutdown 2 , +.Xr socketpair 2 , +.Xr write 2 , +.Xr getprotoent 3 , +.Xr netgraph 4 , +.Xr protocols 5 +.Rs +.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 7 +.Re +.Rs +.%T "BSD Interprocess Communication Tutorial" +.%B PS1 +.%N 8 +.Re +.Sh STANDARDS +The +.Fn socket +function conforms to +.St -p1003.1-2008 . +The +.Tn POSIX +standard specifies only the +.Dv AF_INET , +.Dv AF_INET6 , +and +.Dv AF_UNIX +constants for address families, and requires the use of +.Dv AF_* +constants for the +.Fa domain +argument of +.Fn socket . +The +.Dv SOCK_CLOEXEC +flag is expected to conform to the next revision of the +.Tn POSIX +standard. +The +.Dv SOCK_RDM +.Fa type , +the +.Dv PF_* +constants, and other address families are +.Fx +extensions. +.Sh HISTORY +The +.Fn socket +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/socketpair.2 b/lib/libc/sys/socketpair.2 new file mode 100644 index 000000000000..b15553afc583 --- /dev/null +++ b/lib/libc/sys/socketpair.2 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)socketpair.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd May 4, 2015 +.Dt SOCKETPAIR 2 +.Os +.Sh NAME +.Nm socketpair +.Nd create a pair of connected sockets +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.Ft int +.Fn socketpair "int domain" "int type" "int protocol" "int *sv" +.Sh DESCRIPTION +The +.Fn socketpair +system call creates an unnamed pair of connected sockets in +the specified communications +.Fa domain , +of the specified +.Fa type , +and using the optionally specified +.Fa protocol . +The descriptors used in referencing the new sockets +are returned in +.Fa sv Ns [0] +and +.Fa sv Ns [1] . +The two sockets are indistinguishable. +.Pp +The +.Dv SOCK_CLOEXEC +and +.Dv SOCK_NONBLOCK +flags in the +.Fa type +argument apply to both descriptors. +.Sh RETURN VALUES +.Rv -std socketpair +.Sh ERRORS +The call succeeds unless: +.Bl -tag -width Er +.It Bq Er EMFILE +Too many descriptors are in use by this process. +.It Bq Er EAFNOSUPPORT +The specified address family is not supported on this machine. +.It Bq Er EPROTONOSUPPORT +The specified protocol is not supported on this machine. +.It Bq Er EOPNOTSUPP +The specified protocol does not support creation of socket pairs. +.It Bq Er EFAULT +The address +.Fa sv +does not specify a valid part of the +process address space. +.El +.Sh SEE ALSO +.Xr pipe 2 , +.Xr read 2 , +.Xr socket 2 , +.Xr write 2 +.Sh HISTORY +The +.Fn socketpair +system call appeared in +.Bx 4.2 . +.Sh BUGS +This call is currently implemented only for the +.Ux +domain. diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 new file mode 100644 index 000000000000..3405d6e3511c --- /dev/null +++ b/lib/libc/sys/stat.2 @@ -0,0 +1,436 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)stat.2 8.4 (Berkeley) 5/1/95 +.\" $FreeBSD$ +.\" +.Dd January 14, 2016 +.Dt STAT 2 +.Os +.Sh NAME +.Nm stat , +.Nm lstat , +.Nm fstat , +.Nm fstatat +.Nd get file status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn stat "const char * restrict path" "struct stat * restrict sb" +.Ft int +.Fn lstat "const char * restrict path" "struct stat * restrict sb" +.Ft int +.Fn fstat "int fd" "struct stat *sb" +.Ft int +.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" +.Sh DESCRIPTION +The +.Fn stat +system call obtains information about the file pointed to by +.Fa path . +Read, write or execute +permission of the named file is not required, but all directories +listed in the path name leading to the file must be searchable. +.Pp +The +.Fn lstat +system call is like +.Fn stat +except in the case where the named file is a symbolic link, +in which case +.Fn lstat +returns information about the link, +while +.Fn stat +returns information about the file the link references. +.Pp +The +.Fn fstat +system call obtains the same information about an open file +known by the file descriptor +.Fa fd . +.Pp +The +.Fn fstatat +system call is equivalent to +.Fn stat +and +.Fn lstat +except in the case where the +.Fa path +specifies a relative path. +In this case the status is retrieved from a file relative to +the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for the +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the status of the symbolic link is returned. +.El +.Pp +If +.Fn fstatat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn stat +or +.Fn lstat +respectively, depending on whether or not the +.Dv AT_SYMLINK_NOFOLLOW +bit is set in +.Fa flag . +.Pp +The +.Fa sb +argument is a pointer to a +.Vt stat +structure +as defined by +.In sys/stat.h +and into which information is placed concerning the file. +.Pp +The fields of +.Vt "struct stat" +related to the file system are as follows: +.Bl -tag -width ".Va st_nlink" +.It Va st_dev +The numeric ID of the device containing the file. +.It Va st_ino +The file's inode number. +.It Va st_nlink +The number of hard links to the file. +.El +.Pp +The +.Va st_dev +and +.Va st_ino +fields together identify the file uniquely within the system. +.Pp +The time-related fields of +.Vt "struct stat" +are as follows: +.Bl -tag -width ".Va st_birthtim" +.It Va st_atim +Time when file data last accessed. +Changed by the +.Xr mknod 2 , +.Xr utimes 2 , +.Xr read 2 +and +.Xr readv 2 +system calls. +.It Va st_mtim +Time when file data last modified. +Changed by the +.Xr mkdir 2 , +.Xr mkfifo 2 , +.Xr mknod 2 , +.Xr utimes 2 , +.Xr write 2 +and +.Xr writev 2 +system calls. +.It Va st_ctim +Time when file status was last changed (inode data modification). +Changed by the +.Xr chflags 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr creat 2 , +.Xr link 2 , +.Xr mkdir 2 , +.Xr mkfifo 2 , +.Xr mknod 2 , +.Xr rename 2 , +.Xr rmdir 2 , +.Xr symlink 2 , +.Xr truncate 2 , +.Xr unlink 2 , +.Xr utimes 2 , +.Xr write 2 +and +.Xr writev 2 +system calls. +.It Va st_birthtim +Time when the inode was created. +.El +.Pp +The following time-related macros are defined for compatibility: +.Bd -literal +#define st_atime st_atim.tv_sec +#define st_mtime st_mtim.tv_sec +#define st_ctime st_ctim.tv_sec +#ifndef _POSIX_SOURCE +#define st_birthtime st_birthtim.tv_sec +#endif + +#ifndef _POSIX_SOURCE +#define st_atimespec st_atim +#define st_mtimespec st_mtim +#define st_ctimespec st_ctim +#define st_birthtimespec st_birthtim +#endif +.Ed +.Pp +The size-related fields of the +.Vt "struct stat" +are as follows: +.Bl -tag -width ".Va st_blksize" +.It Va st_size +The file size in bytes. +.It Va st_blksize +The optimal I/O block size for the file. +.It Va st_blocks +The actual number of blocks allocated for the file in 512-byte units. +As short symbolic links are stored in the inode, this number may +be zero. +.El +.Pp +The access-related fields of +.Vt "struct stat" +are as follows: +.Bl -tag -width ".Va st_mode" +.It Va st_uid +The user ID of the file's owner. +.It Va st_gid +The group ID of the file. +.It Va st_mode +Status of the file (see below). +.El +.Pp +The status information word +.Fa st_mode +has the following bits: +.Bd -literal +#define S_IFMT 0170000 /* type of file mask */ +#define S_IFIFO 0010000 /* named pipe (fifo) */ +#define S_IFCHR 0020000 /* character special */ +#define S_IFDIR 0040000 /* directory */ +#define S_IFBLK 0060000 /* block special */ +#define S_IFREG 0100000 /* regular */ +#define S_IFLNK 0120000 /* symbolic link */ +#define S_IFSOCK 0140000 /* socket */ +#define S_IFWHT 0160000 /* whiteout */ +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* save swapped text even after use */ +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* read permission, owner */ +#define S_IWUSR 0000200 /* write permission, owner */ +#define S_IXUSR 0000100 /* execute/search permission, owner */ +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* read permission, group */ +#define S_IWGRP 0000020 /* write permission, group */ +#define S_IXGRP 0000010 /* execute/search permission, group */ +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* read permission, other */ +#define S_IWOTH 0000002 /* write permission, other */ +#define S_IXOTH 0000001 /* execute/search permission, other */ +.Ed +.Pp +For a list of access modes, see +.In sys/stat.h , +.Xr access 2 +and +.Xr chmod 2 . +The following macros are available to test whether a +.Va st_mode +value passed in the +.Fa m +argument corresponds to a file of the specified type: +.Bl -tag -width ".Fn S_ISFIFO m" +.It Fn S_ISBLK m +Test for a block special file. +.It Fn S_ISCHR m +Test for a character special file. +.It Fn S_ISDIR m +Test for a directory. +.It Fn S_ISFIFO m +Test for a pipe or FIFO special file. +.It Fn S_ISLNK m +Test for a symbolic link. +.It Fn S_ISREG m +Test for a regular file. +.It Fn S_ISSOCK m +Test for a socket. +.It Fn S_ISWHT m +Test for a whiteout. +.El +.Pp +The macros evaluate to a non-zero value if the test is true +or to the value 0 if the test is false. +.Sh RETURN VALUES +.Rv -std +.Sh COMPATIBILITY +Previous versions of the system used different types for the +.Va st_dev , +.Va st_uid , +.Va st_gid , +.Va st_rdev , +.Va st_size , +.Va st_blksize +and +.Va st_blocks +fields. +.Sh ERRORS +The +.Fn stat +and +.Fn lstat +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EFAULT +The +.Fa sb +or +.Fa path +argument +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EOVERFLOW +The file size in bytes cannot be +represented correctly in the structure pointed to by +.Fa sb . +.El +.Pp +The +.Fn fstat +system call will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EFAULT +The +.Fa sb +argument +points to an invalid address. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EOVERFLOW +The file size in bytes cannot be +represented correctly in the structure pointed to by +.Fa sb . +.El +.Pp +In addition to the errors returned by the +.Fn lstat , +the +.Fn fstatat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr access 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr fhstat 2 , +.Xr statfs 2 , +.Xr utimes 2 , +.Xr sticky 7 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn stat +and +.Fn fstat +system calls are expected to conform to +.St -p1003.1-90 . +The +.Fn fstatat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn stat +and +.Fn fstat +system calls appeared in +.At v7 . +The +.Fn lstat +system call appeared in +.Bx 4.2 . +The +.Fn fstatat +system call appeared in +.Fx 8.0 . +.Sh BUGS +Applying +.Fn fstat +to a socket +returns a zeroed buffer, +except for the blocksize field, +and a unique device and inode number. diff --git a/lib/libc/sys/statfs.2 b/lib/libc/sys/statfs.2 new file mode 100644 index 000000000000..888f97641434 --- /dev/null +++ b/lib/libc/sys/statfs.2 @@ -0,0 +1,235 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)statfs.2 8.5 (Berkeley) 5/24/95 +.\" $FreeBSD$ +.\" +.Dd November 1, 2006 +.Dt STATFS 2 +.Os +.Sh NAME +.Nm statfs +.Nd get file system statistics +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn statfs "const char *path" "struct statfs *buf" +.Ft int +.Fn fstatfs "int fd" "struct statfs *buf" +.Sh DESCRIPTION +The +.Fn statfs +system call +returns information about a mounted file system. +The +.Fa path +argument +is the path name of any file within the mounted file system. +The +.Fa buf +argument +is a pointer to a +.Vt statfs +structure defined as follows: +.Bd -literal +typedef struct fsid { int32_t val[2]; } fsid_t; /* file system id type */ + +/* + * filesystem statistics + */ + +#define MFSNAMELEN 16 /* length of type name including null */ +#define MNAMELEN 88 /* size of on/from name bufs */ +#define STATFS_VERSION 0x20030518 /* current version number */ + +struct statfs { +uint32_t f_version; /* structure version number */ +uint32_t f_type; /* type of filesystem */ +uint64_t f_flags; /* copy of mount exported flags */ +uint64_t f_bsize; /* filesystem fragment size */ +uint64_t f_iosize; /* optimal transfer block size */ +uint64_t f_blocks; /* total data blocks in filesystem */ +uint64_t f_bfree; /* free blocks in filesystem */ +int64_t f_bavail; /* free blocks avail to non-superuser */ +uint64_t f_files; /* total file nodes in filesystem */ +int64_t f_ffree; /* free nodes avail to non-superuser */ +uint64_t f_syncwrites; /* count of sync writes since mount */ +uint64_t f_asyncwrites; /* count of async writes since mount */ +uint64_t f_syncreads; /* count of sync reads since mount */ +uint64_t f_asyncreads; /* count of async reads since mount */ +uint64_t f_spare[10]; /* unused spare */ +uint32_t f_namemax; /* maximum filename length */ +uid_t f_owner; /* user that mounted the filesystem */ +fsid_t f_fsid; /* filesystem id */ +char f_charspare[80]; /* spare string space */ +char f_fstypename[MFSNAMELEN]; /* filesystem type name */ +char f_mntfromname[MNAMELEN]; /* mounted filesystem */ +char f_mntonname[MNAMELEN]; /* directory on which mounted */ +}; +.Ed +.Pp +The flags that may be returned include: +.Bl -tag -width MNT_SYNCHRONOUS +.It Dv MNT_RDONLY +The file system is mounted read-only; +Even the super-user may not write on it. +.It Dv MNT_NOEXEC +Files may not be executed from the file system. +.It Dv MNT_NOSUID +Setuid and setgid bits on files are not honored when they are executed. +.It Dv MNT_SYNCHRONOUS +All I/O to the file system is done synchronously. +.It Dv MNT_ASYNC +No file system I/O is done synchronously. +.It Dv MNT_SOFTDEP +Soft updates being done (see +.Xr ffs 7 ) . +.It Dv MNT_GJOURNAL +Journaling with gjournal is enabled (see +.Xr gjournal 8 ) . +.It Dv MNT_SUIDDIR +Special handling of SUID bit on directories. +.It Dv MNT_UNION +Union with underlying file system. +.It Dv MNT_NOSYMFOLLOW +Symbolic links are not followed. +.It Dv MNT_NOCLUSTERR +Read clustering is disabled. +.It Dv MNT_NOCLUSTERW +Write clustering is disabled. +.\".It Dv MNT_JAILDEVFS +.\"XXX +.It Dv MNT_MULTILABEL +Mandatory Access Control (MAC) support for individual objects +(see +.Xr mac 4 ) . +.It Dv MNT_ACLS +Access Control List (ACL) support enabled. +.It Dv MNT_LOCAL +The file system resides locally. +.It Dv MNT_QUOTA +The file system has quotas enabled on it. +.It Dv MNT_ROOTFS +Identifies the root file system. +.It Dv MNT_EXRDONLY +The file system is exported read-only. +.It Dv MNT_NOATIME +Updating of file access times is disabled. +.It Dv MNT_USER +The file system has been mounted by a user. +.\".It Dv MNT_IGNORE +.\"XXX +.It Dv MNT_EXPORTED +The file system is exported for both reading and writing. +.It Dv MNT_DEFEXPORTED +The file system is exported for both reading and writing to any Internet host. +.It Dv MNT_EXPORTANON +The file system maps all remote accesses to the anonymous user. +.It Dv MNT_EXKERB +The file system is exported with Kerberos uid mapping. +.It Dv MNT_EXPUBLIC +The file system is exported publicly (WebNFS). +.El +.Pp +Fields that are undefined for a particular file system are set to -1. +The +.Fn fstatfs +system call +returns the same information about an open file referenced by descriptor +.Fa fd . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn statfs +system call +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix of +.Fa path +is not a directory. +.It Bq Er ENAMETOOLONG +The length of a component of +.Fa path +exceeds 255 characters, +or the length of +.Fa path +exceeds 1023 characters. +.It Bq Er ENOENT +The file referred to by +.Fa path +does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix of +.Fa path . +.It Bq Er ELOOP +Too many symbolic links were encountered in translating +.Fa path . +.It Bq Er EFAULT +The +.Fa buf +or +.Fa path +argument +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Pp +The +.Fn fstatfs +system call +fails if one or more of the following are true: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EFAULT +The +.Fa buf +argument +points to an invalid address. +.It Bq Er EIO +An +.Tn I/O +error occurred while reading from or writing to the file system. +.El +.Sh SEE ALSO +.Xr fhstatfs 2 +.Sh HISTORY +The +.Fn statfs +system call first appeared in +.Bx 4.4 . diff --git a/lib/libc/sys/swapcontext.c b/lib/libc/sys/swapcontext.c new file mode 100644 index 000000000000..0a8125eeabb5 --- /dev/null +++ b/lib/libc/sys/swapcontext.c @@ -0,0 +1,53 @@ +/* + * Copyright (c) 2001 Daniel M. Eischen <deischen@freebsd.org> + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Neither the name of the author nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/param.h> +#include <sys/signal.h> +#include <sys/ucontext.h> +#include <errno.h> +#include <stddef.h> +#include "libc_private.h" + +__weak_reference(__sys_swapcontext, __swapcontext); +__sym_compat(swapcontext, __impl_swapcontext, FBSD_1.0); +__weak_reference(swapcontext, __impl_swapcontext); +__sym_default(swapcontext, swapcontext, FBSD_1.2); + +#pragma weak swapcontext +int +swapcontext(ucontext_t *oucp, const ucontext_t *ucp) +{ + + return (((int (*)(ucontext_t *, const ucontext_t *)) + __libc_interposing[INTERPOS_swapcontext])(oucp, ucp)); +} diff --git a/lib/libc/sys/swapon.2 b/lib/libc/sys/swapon.2 new file mode 100644 index 000000000000..6879513ce300 --- /dev/null +++ b/lib/libc/sys/swapon.2 @@ -0,0 +1,143 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)swapon.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd October 4, 2013 +.Dt SWAPON 2 +.Os +.Sh NAME +.Nm swapon , swapoff +.Nd control devices for interleaved paging/swapping +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn swapon "const char *special" +.Ft int +.Fn swapoff "const char *special" +.Sh DESCRIPTION +The +.Fn swapon +system call +makes the block device +.Fa special +available to the system for +allocation for paging and swapping. +The names of potentially +available devices are known to the system and defined at system +configuration time. +The size of the swap area on +.Fa special +is calculated at the time the device is first made available +for swapping. +.Pp +The +.Fn swapoff +system call disables paging and swapping on the given device. +All associated swap metadata are deallocated, and the device +is made available for other purposes. +.Sh RETURN VALUES +If an error has occurred, a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +Both +.Fn swapon +and +.Fn swapoff +can fail if: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named device does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The caller is not the super-user. +.It Bq Er EFAULT +The +.Fa special +argument +points outside the process's allocated address space. +.El +.Pp +Additionally, +.Fn swapon +can fail for the following reasons: +.Bl -tag -width Er +.It Bq Er ENOTBLK +The +.Fa special +argument +is not a block device. +.It Bq Er EBUSY +The device specified by +.Fa special +has already +been made available for swapping +.It Bq Er ENXIO +The major device number of +.Fa special +is out of range (this indicates no device driver exists +for the associated hardware). +.It Bq Er EIO +An I/O error occurred while opening the swap device. +.El +.Pp +Lastly, +.Fn swapoff +can fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The system is not currently swapping to +.Fa special . +.It Bq Er ENOMEM +Not enough virtual memory is available to safely disable +paging and swapping to the given device. +.El +.Sh SEE ALSO +.Xr config 8 , +.Xr swapon 8 , +.Xr sysctl 8 +.Sh HISTORY +The +.Fn swapon +system call appeared in +.Bx 4.0 . +The +.Fn swapoff +system call appeared in +.Fx 5.0 . diff --git a/lib/libc/sys/symlink.2 b/lib/libc/sys/symlink.2 new file mode 100644 index 000000000000..bfe2ede25f8a --- /dev/null +++ b/lib/libc/sys/symlink.2 @@ -0,0 +1,206 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)symlink.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd April 10, 2008 +.Dt SYMLINK 2 +.Os +.Sh NAME +.Nm symlink , +.Nm symlinkat +.Nd make symbolic link to a file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn symlink "const char *name1" "const char *name2" +.Ft int +.Fn symlinkat "const char *name1" "int fd" "const char *name2" +.Sh DESCRIPTION +A symbolic link +.Fa name2 +is created to +.Fa name1 +.Fa ( name2 +is the name of the +file created, +.Fa name1 +is the string +used in creating the symbolic link). +Either name may be an arbitrary path name; the files need not +be on the same file system. +.Pp +The +.Fn symlinkat +system call is equivalent to +.Fn symlink +except in the case where +.Fa name2 +specifies a relative path. +In this case the symbolic link is created relative to the directory +associated with the file descriptor +.Fa fd +instead of the current working directory. +If +.Fn symlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fn symlink . +.Sh RETURN VALUES +.Rv -std symlink +.Sh ERRORS +The symbolic link succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the +.Fa name2 +path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of the +.Fa name2 +pathname exceeded 255 characters, +or the entire length of either path name exceeded 1023 characters. +.It Bq Er ENOENT +A component of the +.Fa name2 +path prefix does not exist. +.It Bq Er EACCES +A component of the +.Fa name2 +path prefix denies search permission, or write permission is denied on the +parent directory of the file to be created. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the +.Fa name2 +path name. +.It Bq Er EEXIST +The path name pointed at by the +.Fa name2 +argument +already exists. +.It Bq Er EPERM +The parent directory of the file named by +.Fa name2 +has its immutable flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EIO +An I/O error occurred while making the directory entry for +.Fa name2 , +or allocating the inode for +.Fa name2 , +or writing out the link contents of +.Fa name2 . +.It Bq Er EROFS +The file +.Fa name2 +would reside on a read-only file system. +.It Bq Er ENOSPC +The directory in which the entry for the new symbolic link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.It Bq Er ENOSPC +The new symbolic link cannot be created because +there is no space left on the file +system that will contain the symbolic link. +.It Bq Er ENOSPC +There are no free inodes on the file system on which the +symbolic link is being created. +.It Bq Er EDQUOT +The directory in which the entry for the new symbolic link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.It Bq Er EDQUOT +The new symbolic link cannot be created because the user's +quota of disk blocks on the file system that will +contain the symbolic link has been exhausted. +.It Bq Er EDQUOT +The user's quota of inodes on the file system on +which the symbolic link is being created has been exhausted. +.It Bq Er EIO +An I/O error occurred while making the directory entry or allocating the inode. +.It Bq Er EFAULT +The +.Fa name1 +or +.Fa name2 +argument +points outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn symlink , +the +.Fn symlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name2 +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa name2 +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr ln 1 , +.Xr chflags 2 , +.Xr link 2 , +.Xr lstat 2 , +.Xr readlink 2 , +.Xr unlink 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn symlinkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn symlink +system call appeared in +.Bx 4.2 . +The +.Fn symlinkat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/sync.2 b/lib/libc/sys/sync.2 new file mode 100644 index 000000000000..06d5e935c6b2 --- /dev/null +++ b/lib/libc/sys/sync.2 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sync.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt SYNC 2 +.Os +.Sh NAME +.Nm sync +.Nd "schedule file system updates" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft void +.Fn sync void +.Sh DESCRIPTION +The +.Fn sync +system call forces a write of dirty (modified) buffers +in the block buffer cache out +to disk. +The kernel keeps this information in core to reduce +the number of disk I/O transfers required by the system. +As information in the cache is lost after a system crash, a +.Fn sync +system call is issued +frequently +by the kernel process +.Xr syncer 4 +(about every 30 seconds). +.Pp +The +.Xr fsync 2 +system call +may be used to synchronize individual file descriptor +attributes. +.Sh SEE ALSO +.Xr fsync 2 , +.Xr syncer 4 , +.Xr sync 8 +.Sh HISTORY +The +.Fn sync +function appeared in +.At v6 . +.Sh BUGS +The +.Fn sync +system call +may return before the buffers are completely flushed. diff --git a/lib/libc/sys/sysarch.2 b/lib/libc/sys/sysarch.2 new file mode 100644 index 000000000000..bd060d17790c --- /dev/null +++ b/lib/libc/sys/sysarch.2 @@ -0,0 +1,81 @@ +.\" $NetBSD: sysarch.2,v 1.6 1998/02/25 21:24:57 perry Exp $ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" from: @(#)syscall.2 6.3 (Berkeley) 3/10/91 +.\" +.Dd October 11, 1993 +.Dt SYSARCH 2 +.Os +.Sh NAME +.Nm sysarch +.Nd architecture-dependent system call +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/sysarch.h +.Ft int +.Fn sysarch "int number" "void *args" +.Sh DESCRIPTION +The +.Fn sysarch +system call +performs the architecture-dependent function +specified by +.Fa number +with the arguments specified by the +.Fa args +pointer. +The +.Fa args +argument +is a pointer to a structure defining the actual +arguments of the function. +Symbolic constants and argument structures +for the architecture-dependent +functions can be found in the header file +.In machine/sysarch.h . +.Pp +The +.Fn sysarch +system call should never be called directly by +user programs. +Instead, they should access +its functions using the architecture-dependent +library. +.Sh RETURN VALUES +See the manual pages for specific architecture-dependent system calls +for information about their return values. +.Sh SEE ALSO +.Xr i386_get_ioperm 2 , +.Xr i386_get_ldt 2 , +.Xr i386_vm86 2 +.Sh HISTORY +This manual page was taken from +.Nx . diff --git a/lib/libc/sys/syscall.2 b/lib/libc/sys/syscall.2 new file mode 100644 index 000000000000..a9402d62bcf7 --- /dev/null +++ b/lib/libc/sys/syscall.2 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)syscall.2 8.1 (Berkeley) 6/16/93 +.\" $FreeBSD$ +.\" +.Dd June 16, 1993 +.Dt SYSCALL 2 +.Os +.Sh NAME +.Nm syscall , +.Nm __syscall +.Nd indirect system call +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/syscall.h +.In unistd.h +.Ft int +.Fn syscall "int number" ... +.Ft off_t +.Fn __syscall "quad_t number" ... +.Sh DESCRIPTION +The +.Fn syscall +function +performs the system call whose assembly language +interface has the specified +.Fa number +with the specified arguments. +Symbolic constants for system calls can be found in the header file +.In sys/syscall.h . +The +.Fn __syscall +form should be used when one or more of the arguments is a +64-bit argument to ensure that argument alignment is correct. +This system call is useful for testing new system calls that +do not have entries in the C library. +.Sh RETURN VALUES +The return values are defined by the system call being invoked. +In general, a 0 return value indicates success. +A -1 return value indicates an error, +and an error code is stored in +.Va errno . +.Sh HISTORY +The +.Fn syscall +function appeared in +.Bx 4.0 . +.Sh BUGS +There is no way to simulate system calls that have multiple return values +such as +.Xr pipe 2 . diff --git a/lib/libc/sys/thr_exit.2 b/lib/libc/sys/thr_exit.2 new file mode 100644 index 000000000000..781b07fde7e8 --- /dev/null +++ b/lib/libc/sys/thr_exit.2 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 1, 2016 +.Dt THR_EXIT 2 +.Os +.Sh NAME +.Nm thr_exit +.Nd terminate current thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft void +.Fn thr_exit "long *state" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should call +.Xr pthread_exit 3 +instead. +.Ef +.Pp +The +.Fn thr_exit +system call terminates the current kernel-scheduled thread. +.Pp +If the +.Fa state +argument is not +.Dv NULL , +the location pointed to by the argument is +updated with an arbitrary non-zero value, and an +.Xr _umtx_op 2 +.Dv UMTX_OP_WAKE +operation is consequently performed on the location. +.Pp +Attempts to terminate the last thread in the process are silently ignored. +Use +.Xr _exit 2 +syscall to terminate the process. +.Sh RETURN VALUES +The function does not return a value. +A return from the function indicates that the calling thread was the +last one in the process. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr _umtx_op 2 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn thr_exit +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. diff --git a/lib/libc/sys/thr_kill.2 b/lib/libc/sys/thr_kill.2 new file mode 100644 index 000000000000..04293aa59ee7 --- /dev/null +++ b/lib/libc/sys/thr_kill.2 @@ -0,0 +1,133 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 1, 2016 +.Dt THR_kill 2 +.Os +.Sh NAME +.Nm thr_kill +.Nd send signal to thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_kill "long id" "int sig" +.Ft int +.Fn thr_kill2 "pid_t pid" "long id" "int sig" +.Sh DESCRIPTION +The +.Fn thr_kill +and +.Fn thr_kill2 +system calls allow sending a signal, specified by the +.Fa sig +argument, to some threads in a process. +For the +.Fn thr_kill +function, signalled threads are always limited to the current process. +For the +.Fn thr_kill2 +function, the +.Fa pid +argument specifies the process with threads to be signalled. +.Pp +The +.Fa id +argument specifies which threads get the signal. +If +.Fa id +is equal to \-1, all threads in the specified process are signalled. +Otherwise, only the thread with the thread identifier equal to the +argument is signalled. +.Pp +The +.Fa sig +argument defines the delivered signal. +It must be a valid signal number or zero. +In the latter case no signal is actually sent, and the call is used to +verify the liveness of the thread. +.Pp +The signal is delivered with +.Dv siginfo +.Dv si_code +set to +.Dv SI_LWP . +.Sh RETURN VALUES +If successful, +.Fn thr_kill +and +.Fn thr_kill2 +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_kill +and +.Fn thr_kill2 +operations return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa sig +argument is not zero and does not specify valid signal. +.It Bq Er ESRCH +The specified process or thread was not found. +.El +.Pp +Additionally, the +.Fn thr_kill2 +may return the following errors: +.Bl -tag -width Er +.It Bq Er EPERM +The current process does not have sufficient privilege to check existence or +send a signal to the specified process. +.El +.Sh SEE ALSO +.Xr kill 2 , +.Xr thr_exit 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr _umtx_op 2 , +.Xr pthread_kill 3 , +.Xr signal 3 +.Sh STANDARDS +The +.Fn thr_kill +and +.Fn thr_kill2 +system calls are non-standard and are used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. diff --git a/lib/libc/sys/thr_new.2 b/lib/libc/sys/thr_new.2 new file mode 100644 index 000000000000..27f4191ae8b5 --- /dev/null +++ b/lib/libc/sys/thr_new.2 @@ -0,0 +1,245 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 2, 2016 +.Dt THR_NEW 2 +.Os +.Sh NAME +.Nm thr_new +.Nd create new thread of execution +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_new "struct thr_param *param" "int param_size" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should call +.Xr pthread_create 3 +instead. +.Ef +.Pp +The +.Fn thr_new +system call creates a new kernel-scheduled thread of execution in the context +of the current process. +The newly created thread shares all attributes of the process with the +existing kernel-scheduled threads in the process, but has private processor +execution state. +The machine context for the new thread is copied from the creating thread's +context, including coprocessor state. +FPU state and specific machine registers are excluded from the copy. +These are set according to ABI requirements and syscall parameters. +The FPU state for the new thread is reinitialized to clean. +.Pp +The +.Fa param +structure supplies parameters affecting the thread creation. +The structure is defined in the +.In sys/thr.h +header as follows +.Bd -literal +struct thr_param { + void (*start_func)(void *); + void *arg; + char *stack_base; + size_t stack_size; + char *tls_base; + size_t tls_size; + long *child_tid; + long *parent_tid; + int flags; + struct rtprio *rtp; +}; +.Ed +and contains the following fields: +.Bl -tag -width ".Va parent_tid" +.It Va start_func +Pointer to the thread entry function. +The kernel arranges for the new thread to start executing the function +upon the first return to userspace. +.It Va arg +Opaque argument supplied to the entry function. +.It Va stack_base +Stack base address. +The stack must be allocated by the caller. +On some architectures, the ABI might require that the system put information +on the stack to ensure the execution environment for +.Va start_func . +.It Va stack_size +Stack size. +.It Va tls_base +TLS base address. +The value of TLS base is loaded into the ABI-defined machine register +in the new thread context. +.It Va tls_size +TLS size. +.It Va child_tid +Address to store the new thread identifier, for the child's use. +.It Va parent_tid +Address to store the new thread identifier, for the parent's use. +.Pp +Both +.Va child_tid +and +.Va parent_tid +are provided, with the intent that +.Va child_tid +is used by the new thread to get its thread identifier without +issuing the +.Xr thr_self 2 +syscall, while +.Va parent_tid +is used by the thread creator. +The latter is separate from +.Va child_tid +because the new thread might exit and free its thread data before the parent +has a chance to execute far enough to access it. +.It Va flags +Thread creation flags. +The +.Va flags +member may specify the following flags: +.Bl -tag -width ".Dv THR_SYSTEM_SCOPE" +.It Dv THR_SUSPENDED +Create the new thread in the suspended state. +The flag is not currently implemented. +.It Dv THR_SYSTEM_SCOPE +Create the system scope thread. +The flag is not currently implemented. +.El +.It Va rtp +Real-time scheduling priority for the new thread. +May be +.Dv NULL +to inherit the priority from the +creating thread. +.El +.Pp +The +.Fa param_size +argument should be set to the size of the +.Fa param +structure. +.Pp +After the first successful creation of an additional thread, +the process is marked by the kernel as multi-threaded. +In particular, the +.Dv P_HADTHREADS +flag is set in the process' +.Dv p_flag +(visible in the +.Xr ps 1 +output), and several operations are executed in multi-threaded mode. +For instance, the +.Xr execve 2 +system call terminates all threads but the calling one on successful +execution. +.Sh RETURN VALUES +If successful, +.Fn thr_new +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_new +operation returns the following errors: +.Bl -tag -width Er +.\" When changing this list, consider updating share/man/man3/pthread_create.3, +.\" since that function can return any of these errors. +.It Bq Er EFAULT +The memory pointed to by the +.Fa param +argument is not valid. +.It Bq Er EFAULT +The memory pointed to by the +.Fa param +structure +.Fa child_tid , parent_tid +or +.Fa rtp +arguments is not valid. +.It Bq Er EFAULT +The specified stack base is invalid, or the kernel was unable to put required +initial data on the stack. +.It Bq Er EINVAL +The +.Fa param_size +argument specifies a negative value, or the value is greater than the +largest +.Fa struct param +size the kernel can interpret. +.It Bq Er EINVAL +The +.Fa rtp +member is not +.Dv NULL +and specifies invalid scheduling parameters. +.It Bq Er EINVAL +The specified TLS base is invalid. +.It Bq Er EPERM +The caller does not have permission to set the scheduling parameters or +scheduling policy. +.It Bq Er EPROCLIM +Creation of the new thread would exceed the +.Dv RACCT_NTHR +limit, see +.Xr racct 2 . +.It Bq Er EPROCLIM +Creation of the new thread would exceed the +.Dv kern.threads.max_threads_per_proc +.Xr sysctl 2 +limit. +.It Bq Er ENOMEM +There was not enough kernel memory to allocate the new thread structures. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr execve 2 , +.Xr racct 2 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_self 2 , +.Xr thr_set_name 2 , +.Xr _umtx_op 2 , +.Xr pthread_create 3 +.Sh STANDARDS +The +.Fn thr_new +system call is non-standard and is used by the +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. diff --git a/lib/libc/sys/thr_self.2 b/lib/libc/sys/thr_self.2 new file mode 100644 index 000000000000..949b600a17f7 --- /dev/null +++ b/lib/libc/sys/thr_self.2 @@ -0,0 +1,90 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 1, 2016 +.Dt THR_SELF 2 +.Os +.Sh NAME +.Nm thr_self +.Nd return thread identifier for the calling thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_self "long *id" +.Sh DESCRIPTION +The +.Fn thr_self +system call stores the system-wide thread identifier for the current +kernel-scheduled thread in the variable pointed by the argument +.Va id . +.Pp +The thread identifier is an integer in the range from +.Dv PID_MAX + 2 +(10002) to +.Dv INT_MAX . +The thread identifier is guaranteed to be unique at any given time, +for each running thread in the system. +After the thread exits, the identifier may be reused. +.Sh RETURN VALUES +If successful, +.Fn thr_self +will return zero, otherwise \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_self +operation may return the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa id +argument is not valid. +.El +.Sh SEE ALSO +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_set_name 2 , +.Xr _umtx_op 2 , +.Xr pthread_getthreadid_np 3 , +.Xr pthread_self 3 +.Sh STANDARDS +The +.Fn thr_self +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. diff --git a/lib/libc/sys/thr_set_name.2 b/lib/libc/sys/thr_set_name.2 new file mode 100644 index 000000000000..a83e53109491 --- /dev/null +++ b/lib/libc/sys/thr_set_name.2 @@ -0,0 +1,94 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 2, 2016 +.Dt THR_SET_NAME 2 +.Os +.Sh NAME +.Nm thr_set_name +.Nd set user-visible thread name +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_set_name "long id" "const char *name" +.Sh DESCRIPTION +The +.Fn thr_set_name +system call sets the user-visible name for the thread with the identifier +.Va id +in the current process to the NUL-terminated string +.Va name . +The name will be silently truncated to fit into a buffer of +.Dv MAXCOMLEN + 1 +bytes. +The thread name can be seen in the output of the +.Xr ps 1 +and +.Xr top 1 +commands, in the kernel debuggers and kernel tracing facility outputs, +and in userland debuggers and program core files, as notes. +.Sh RETURN VALUES +If successful, +.Fn thr_set_name +returns zero; otherwise, \-1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn thr_set_name +system call may return the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa name +argument is not valid. +.It Bq Er ESRCH +The thread with the identifier +.Fa id +does not exist in the current process. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_exit 2 , +.Xr thr_kill 2 , +.Xr thr_kill2 2 , +.Xr thr_new 2 , +.Xr thr_self 2 , +.Xr _umtx_op 2 , +.Xr pthread_set_name_np 3 , +.Xr ddb 4 , +.Xr ktr 9 +.Sh STANDARDS +The +.Fn thr_set_name +system call is non-standard and is used by the +.Lb libthr . diff --git a/lib/libc/sys/thr_suspend.2 b/lib/libc/sys/thr_suspend.2 new file mode 100644 index 000000000000..b470d189e45b --- /dev/null +++ b/lib/libc/sys/thr_suspend.2 @@ -0,0 +1,130 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 23, 2016 +.Dt THR_SUSPEND 2 +.Os +.Sh NAME +.Nm thr_suspend +.Nd suspend the calling thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_suspend "struct timespec *timeout" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should use +.Xr pthread_cond_timedwait 3 +together with +.Xr pthread_cond_broadcast 3 +for typical safe suspension with cooperation of the thread +being suspended, or +.Xr pthread_suspend_np 3 +and +.Xr pthread_resume_np 3 +in some specific situations, instead. +.Ef +.Pp +The +.Fn thr_suspend +system call puts the calling thread in a suspended state, where it is +not eligible for CPU time. +This state is exited by another thread calling +.Xr thr_wake 2 , +when the time interval specified by +.Fa timeout +has elapsed, +or by the delivery of a signal to the suspended thread. +.Pp +If the +.Fa timeout +argument is +.Dv NULL , +the suspended state can be only terminated by explicit +.Fn thr_wake +or signal. +.Pp +If a wake from +.Xr thr_wake 2 +was delivered before the +.Nm +call, the thread is not put into a suspended state. +Instead, the call +returns immediately without an error. +.Pp +If a thread previously called +.Xr thr_wake 2 +with its own thread identifier, which resulted in setting the internal kernel +flag to immediately abort interruptible sleeps with an +.Er EINTR +error +.Po +see +.Xr thr_wake 2 +.Pc , +the flag is cleared. +As with +.Xr thr_wake 2 +called from another thread, the next +.Nm +call does not result in suspension. +.Pp +.Sh RETURN VALUES +.Rv -std thr_suspend +.Sh ERRORS +The +.Fn thr_suspend +operation returns the following errors: +.Bl -tag -width Er +.It Bq Er EFAULT +The memory pointed to by the +.Fa timeout +argument is not valid. +.It Bq Er ETIMEDOUT +The specified timeout expired. +.It Bq Er ETIMEDOUT +The +.Fa timeout +argument specified a zero time interval. +.It Bq Er EINTR +The sleep was interrupted by a signal. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_wake 2 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh STANDARDS +The +.Fn thr_suspend +system call is non-standard. diff --git a/lib/libc/sys/thr_wake.2 b/lib/libc/sys/thr_wake.2 new file mode 100644 index 000000000000..59df7d2c903a --- /dev/null +++ b/lib/libc/sys/thr_wake.2 @@ -0,0 +1,112 @@ +.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 23, 2016 +.Dt THR_WAKE 2 +.Os +.Sh NAME +.Nm thr_wake +.Nd wake up the suspended thread +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/thr.h +.Ft int +.Fn thr_wake "long id" +.Sh DESCRIPTION +.Bf -symbolic +This function is intended for implementing threading. +Normal applications should use +.Xr pthread_cond_timedwait 3 +together with +.Xr pthread_cond_broadcast 3 +for typical safe suspension with cooperation of the thread +being suspended, or +.Xr pthread_suspend_np 3 +and +.Xr pthread_resume_np 3 +in some specific situations, instead. +.Ef +.Pp +Passing the thread identifier of the calling thread +.Po +see +.Xr thr_self 2 +.Pc +to +.Fn thr_wake +sets a thread's flag to cause the next signal-interruptible sleep +of that thread in the kernel to fail immediately with the +.Er EINTR +error. +The flag is cleared by an interruptible sleep attempt or by a call to +.Xr thr_suspend 2. +This is used by the system threading library to implement cancellation. +.Pp +If +.Fa id +is not equal to the current thread identifier, the specified thread is +woken up if suspended by the +.Xr thr_suspend +system call. +If the thread is not suspended at the time of the +.Nm +call, the wake is remembered and the next attempt of the thread to +suspend itself with the +.Xr thr_suspend 2 +results in immediate return with success. +Only one wake is remembered. +.Sh RETURN VALUES +.Rv -std thr_wake +.Sh ERRORS +The +.Fn thr_wake +operation returns these errors: +.Bl -tag -width Er +.It Bq Er ESRCH +The specified thread was not found or does not belong to the process +of the calling thread. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr thr_self 2 +.Xr thr_suspend 2 , +.Xr pthread_cancel 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh STANDARDS +The +.Fn thr_suspend +system call is non-standard and is used by +.Lb libthr +to implement +.St -p1003.1-2001 +.Xr pthread 3 +functionality. diff --git a/lib/libc/sys/timer_create.2 b/lib/libc/sys/timer_create.2 new file mode 100644 index 000000000000..1dd0cd5d1fac --- /dev/null +++ b/lib/libc/sys/timer_create.2 @@ -0,0 +1,200 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 15, 2016 +.Dt TIMER_CREATE 2 +.Os +.Sh NAME +.Nm timer_create +.Nd "create a per-process timer (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In time.h +.In signal.h +.Ft int +.Fo timer_create +.Fa "clockid_t clockid" "struct sigevent *restrict evp" +.Fa "timer_t *restrict timerid" +.Fc +.Sh DESCRIPTION +The +.Fn timer_create +system call creates a per-process timer using the specified clock, +.Fa clock_id , +as the timing base. +The +.Fn timer_create +system call returns, in the location referenced by +.Fa timerid , +a timer ID of type +.Vt timer_t +used to identify the timer in timer requests. +This timer ID is unique within the calling process until the timer is deleted. +The particular clock, +.Fa clock_id , +is defined in +.In time.h . +The timer whose ID is returned is in a disarmed state upon return from +.Fn timer_create . +.Pp +The +.Fa evp +argument, if +.Pf non- Dv NULL , +points to a +.Vt sigevent +structure. +This structure, +allocated by the application, defines the asynchronous notification to occur +when the timer expires. +.Pp +If +.Fa evp->sigev_notify +is +.Dv SIGEV_SIGNO +or +.Dv SIGEV_THREAD_ID , +the signal specified in +.Fa evp->sigev_signo +will be sent to the calling process +.Pq Dv SIGEV_SIGNO +or to the thread whose LWP ID is +.Fa evp->sigev_notify_thread_id +.Pq Dv SIGEV_THREAD_ID . +The information for the queued signal will include: +.Bl -column ".Va si_value" +.It Sy Member Ta Sy Value +.It Va si_code Ta Dv SI_TIMER +.It Va si_value Ta +the value stored in +.Fa evp->sigev_value +.It Va si_timerid Ta timer ID +.It Va si_overrun Ta timer overrun count +.It Va si_errno Ta +If timer overrun is +.Brq Dv DELAYTIMER_MAX , +an error code defined in +.In errno.h +.El +.Pp +If the +.Fa evp +argument is +.Dv NULL , +the effect is as if the +.Fa evp +argument pointed to a +.Vt sigevent +structure with the +.Va sigev_notify +member having the value +.Dv SIGEV_SIGNAL , +the +.Va sigev_signo +having a default signal number +.Pq Dv SIGALRM , +and the +.Va sigev_value +member having +the value of the timer ID. +.Pp +This implementation supports a +.Fa clock_id +of +.Dv CLOCK_REALTIME +or +.Dv CLOCK_MONOTONIC . +.Pp +If +.Fa evp->sigev_notify +is +.Dv SIGEV_THREAD +and +.Fa sev->sigev_notify_attributes +is not +.Dv NULL , +if the attribute pointed to by +.Fa sev->sigev_notify_attributes +has +a thread stack address specified by a call to +.Fn pthread_attr_setstack +or +.Fn pthread_attr_setstackaddr , +the results are unspecified if the signal is generated more than once. +.Sh RETURN VALUES +If the call succeeds, +.Fn timer_create +returns zero and updates the location referenced by +.Fa timerid +to a +.Vt timer_t , +which can be passed to the per-process timer calls. +If an error +occurs, the system call returns a value of \-1 +and the global variable +.Va errno +is set to indicate the +error. +The value of +.Fa timerid +is undefined if an error occurs. +.Sh ERRORS +The +.Fn timer_create +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The calling process has already created all of the timers it is allowed by +this implementation. +.It Bq Er EINVAL +The specified clock ID is not supported. +.It Bq Er EINVAL +The specified asynchronous notification method is not supported. +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.El +.Sh SEE ALSO +.Xr clock_getres 2 , +.Xr timer_delete 2 , +.Xr timer_getoverrun 2 , +.Xr sigevent 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn timer_create +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +per-process timer first appeared in +.Fx 7.0 . diff --git a/lib/libc/sys/timer_delete.2 b/lib/libc/sys/timer_delete.2 new file mode 100644 index 000000000000..a7f5ada0eb51 --- /dev/null +++ b/lib/libc/sys/timer_delete.2 @@ -0,0 +1,80 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 11, 2000 +.Dt TIMER_DELETE 2 +.Os +.Sh NAME +.Nm timer_delete +.Nd "delete a per-process timer (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_delete "timer_t timerid" +.Sh DESCRIPTION +The +.Fn timer_delete +system call +deletes the specified timer, +.Fa timerid , +previously created by the +.Xr timer_create 2 +system call. +If the timer is armed when +.Fn timer_delete +is called, the behavior is as if the timer is automatically disarmed before +removal. +Pending signals for the deleted timer are cleared. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn timer_delete +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The timer ID specified by +.Fa timerid +is not a valid timer ID. +.El +.Sh SEE ALSO +.Xr timer_create 2 +.Sh STANDARDS +The +.Fn timer_delete +system call conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +per-process timer first appeared in +.Fx 7.0 . diff --git a/lib/libc/sys/timer_settime.2 b/lib/libc/sys/timer_settime.2 new file mode 100644 index 000000000000..3f7be18c217d --- /dev/null +++ b/lib/libc/sys/timer_settime.2 @@ -0,0 +1,265 @@ +.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 11, 2000 +.Dt TIMER_SETTIME 2 +.Os +.Sh NAME +.Nm timer_getoverrun , +.Nm timer_gettime , +.Nm timer_settime +.Nd "per-process timers (REALTIME)" +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In time.h +.Ft int +.Fn timer_getoverrun "timer_t timerid" +.Ft int +.Fn timer_gettime "timer_t timerid" "struct itimerspec *value" +.Ft int +.Fo timer_settime +.Fa "timer_t timerid" "int flags" "const struct itimerspec *restrict value" +.Fa "struct itimerspec *restrict ovalue" +.Fc +.Sh DESCRIPTION +The +.Fn timer_gettime +system call stores the amount of time until the specified timer, +.Fa timerid , +expires and the reload value of the timer into the space pointed to by the +.Fa value +argument. +The +.Va it_value +member of this structure contains the amount of time +before the timer expires, or zero if the timer is disarmed. +This value is +returned as the interval until timer expiration, even if the timer was armed +with absolute time. +The +.Va it_interval +member of +.Fa value +contains the reload +value last set by +.Fn timer_settime . +.Pp +The +.Fn timer_settime +system call sets the time until the next expiration of the timer specified +by +.Fa timerid +from the +.Va it_value +member of the +.Fa value +argument and arms the timer if the +.Va it_value +member of +.Fa value +is non-zero. +If the specified timer was already +armed when +.Fn timer_settime +is called, this call resets the time until next expiration to the value +specified. +If the +.Va it_value +member of +.Fa value +is zero, the timer is disarmed. +If the timer is disarmed, then pending signal is removed. +.Pp +If the flag +.Dv TIMER_ABSTIME +is not set in the argument +.Fa flags , +.Fn timer_settime +behaves as if the time until next expiration is set to +be equal to the interval specified by the +.Va it_value +member of +.Fa value . +That is, +the timer expires in +.Va it_value +nanoseconds from when the call is made. +If the flag +.Dv TIMER_ABSTIME +is set in the argument +.Fa flags , +.Fn timer_settime +behaves as if the time until next expiration is set to be equal to the +difference between the absolute time specified by the it_value member of +value and the current value of the clock associated with +.Fa timerid . +That is, the timer expires when the clock reaches the value specified by the +.Va it_value +member of +.Fa value . +If the specified time has already passed, the +system call succeeds and the expiration notification is made. +.Pp +The reload value of the timer is set to the value specified by the +.Va it_interval +member of +.Fa value . +When a timer is armed with a non-zero +.Va it_interval , +a periodic +(or repetitive) timer is specified. +.Pp +Time values that are between two consecutive non-negative integer multiples of +the resolution of the specified timer are rounded up to the larger multiple of +the resolution. +Quantization error will not cause the timer to expire earlier +than the rounded time value. +.Pp +If the argument +.Fa ovalue +is not +.Dv NULL , +the +.Fn timer_settime +system call stores, in the location referenced by +.Fa ovalue , +a value representing +the previous amount of time before the timer would have expired, or zero if the +timer was disarmed, together with the previous timer reload value. +Timers do not +expire before their scheduled time. +.Pp +Only a single signal is queued to the process for a given timer at any point in +time. +When a timer for which a signal is still pending expires, no signal is +queued, and a timer overrun will occur. +When a timer expiration signal is +accepted by a process, the +.Fn timer_getoverrun +system call returns the timer expiration overrun count for the specified timer. +The overrun count returned contains the number of extra timer expirations that +occurred between the time the signal was generated (queued) and when it was +accepted, up to but not including an maximum of +.Brq Dv DELAYTIMER_MAX . +If the number of +such extra expirations is greater than or equal to +.Brq Dv DELAYTIMER_MAX , +then the overrun count is set to +.Brq Dv DELAYTIMER_MAX . +The value returned by +.Fn timer_getoverrun +applies to the most recent expiration signal acceptance for the timer. +If no +expiration signal has been delivered for the timer, the return value of +.Fn timer_getoverrun +is unspecified. +.Sh RETURN VALUES +If the +.Fn timer_getoverrun +system call succeeds, it returns the timer expiration overrun count as explained +above. +Otherwise the value \-1 is returned, and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std timer_gettime timer_settime +.Sh ERRORS +The +.Fn timer_settime +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A +.Fa value +structure specified a nanosecond value less than zero or greater than +or equal to 1000 million, and the +.Va it_value +member of that structure did not +specify zero seconds and nanoseconds. +.El +.Pp +These system calls may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa timerid +argument does not correspond to an ID returned by +.Fn timer_create +but not yet deleted by +.Fn timer_delete . +.El +.Pp +The +.Fn timer_settime +system call may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Va it_interval +member of +.Fa value +is not zero and the timer was created with +notification by creation of a new thread +.Va ( sigev_sigev_notify +was +.Dv SIGEV_THREAD ) +and a fixed stack address has been set in the thread attribute pointed to by +.Va sigev_notify_attributes . +.El +.Pp +The +.Fn timer_gettime +and +.Fn timer_settime +system calls +may fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.El +.Sh SEE ALSO +.Xr clock_getres 2 , +.Xr timer_create 2 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn timer_getoverrun , +.Fn timer_gettime , +and +.Fn timer_settime +system calls conform to +.St -p1003.1-2004 . +.Sh HISTORY +Support for +.Tn POSIX +per-process timer first appeared in +.Fx 7.0 . diff --git a/lib/libc/sys/trivial-vdso_tc.c b/lib/libc/sys/trivial-vdso_tc.c new file mode 100644 index 000000000000..ce0c1444f318 --- /dev/null +++ b/lib/libc/sys/trivial-vdso_tc.c @@ -0,0 +1,48 @@ +/*- + * Copyright (c) 2013 Konstantin Belousov <kib@FreeBSD.org> + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/time.h> +#include <sys/vdso.h> +#include <errno.h> + +#pragma weak __vdso_gettc +int +__vdso_gettc(const struct vdso_timehands *th, u_int *tc) +{ + + return (ENOSYS); +} + +#pragma weak __vdso_gettimekeep +int +__vdso_gettimekeep(struct vdso_timekeep **tk) +{ + + return (ENOSYS); +} diff --git a/lib/libc/sys/truncate.2 b/lib/libc/sys/truncate.2 new file mode 100644 index 000000000000..0734464c868c --- /dev/null +++ b/lib/libc/sys/truncate.2 @@ -0,0 +1,165 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)truncate.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd May 4, 2015 +.Dt TRUNCATE 2 +.Os +.Sh NAME +.Nm truncate , +.Nm ftruncate +.Nd truncate or extend a file to a specified length +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn truncate "const char *path" "off_t length" +.Ft int +.Fn ftruncate "int fd" "off_t length" +.Sh DESCRIPTION +The +.Fn truncate +system call +causes the file named by +.Fa path +or referenced by +.Fa fd +to be truncated or extended to +.Fa length +bytes in size. +If the file +was larger than this size, the extra data +is lost. +If the file was smaller than this size, +it will be extended as if by writing bytes +with the value zero. +.Pp +The +.Fn ftruncate +system call causes the file or shared memory object backing the file descriptor +.Fa fd +to be truncated or extended to +.Fa length +bytes in size. +The file descriptor must be a valid file descriptor open for writing. +The file position pointer associated with the file descriptor +.Fa fd +will not be modified. +.Sh RETURN VALUES +.Rv -std +If the file to be modified is not a directory or +a regular file, the +.Fn truncate +call has no effect and returns the value 0. +.Sh ERRORS +The +.Fn truncate +system call +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The named file is not writable by the user. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EISDIR +The named file is a directory. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er ETXTBSY +The file is a pure procedure (shared text) file that is being executed. +.It Bq Er EFBIG +The +.Fa length +argument was greater than the maximum file size. +.It Bq Er EINVAL +The +.Fa length +argument was less than 0. +.It Bq Er EIO +An I/O error occurred updating the inode. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Pp +The +.Fn ftruncate +system call +succeeds unless: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor. +.It Bq Er EINVAL +The +.Fa fd +argument +references a file descriptor that is not a regular file or shared memory object. +.It Bq Er EINVAL +The +.Fa fd +descriptor +is not open for writing. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr open 2 , +.Xr shm_open 2 +.Sh HISTORY +The +.Fn truncate +and +.Fn ftruncate +system calls appeared in +.Bx 4.2 . +.Sh BUGS +These calls should be generalized to allow ranges +of bytes in a file to be discarded. +.Pp +Use of +.Fn truncate +to extend a file is not portable. diff --git a/lib/libc/sys/umask.2 b/lib/libc/sys/umask.2 new file mode 100644 index 000000000000..025a72640e14 --- /dev/null +++ b/lib/libc/sys/umask.2 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)umask.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt UMASK 2 +.Os +.Sh NAME +.Nm umask +.Nd set file creation mode mask +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft mode_t +.Fn umask "mode_t numask" +.Sh DESCRIPTION +The +.Fn umask +routine sets the process's file mode creation mask to +.Fa numask +and returns the previous value of the mask. +The 9 low-order +access permission +bits of +.Fa numask +are used by system calls, including +.Xr open 2 , +.Xr mkdir 2 , +and +.Xr mkfifo 2 , +to turn off corresponding bits +requested in file mode. +(See +.Xr chmod 2 ) . +This clearing allows each user to restrict the default access +to his files. +.Pp +The default mask value is S_IWGRP|S_IWOTH (022, write access for the +owner only). +Child processes inherit the mask of the calling process. +.Sh RETURN VALUES +The previous value of the file mode mask is returned by the call. +.Sh ERRORS +The +.Fn umask +system call is always successful. +.Sh SEE ALSO +.Xr chmod 2 , +.Xr mkfifo 2 , +.Xr mknod 2 , +.Xr open 2 +.Sh STANDARDS +The +.Fn umask +system call is expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn umask +function appeared in +.At v7 . diff --git a/lib/libc/sys/undelete.2 b/lib/libc/sys/undelete.2 new file mode 100644 index 000000000000..f686f5ec1e11 --- /dev/null +++ b/lib/libc/sys/undelete.2 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1994 +.\" Jan-Simon Pendry +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)undelete.2 8.4 (Berkeley) 10/18/94 +.\" $FreeBSD$ +.\" +.Dd January 22, 2006 +.Dt UNDELETE 2 +.Os +.Sh NAME +.Nm undelete +.Nd attempt to recover a deleted file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn undelete "const char *path" +.Sh DESCRIPTION +The +.Fn undelete +system call attempts to recover the deleted file named by +.Fa path . +Currently, this works only when the named object +is a whiteout in a union file system. +The system call removes the whiteout causing +any objects in a lower layer of the +union stack to become visible once more. +.Pp +Eventually, the +.Fn undelete +functionality may be expanded to other file systems able to recover +deleted files such as the log-structured file system. +.Sh RETURN VALUES +.Rv -std undelete +.Sh ERRORS +The +.Fn undelete +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er EEXIST +The path does not reference a whiteout. +.It Bq Er ENOENT +The named whiteout does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write permission is denied on the directory containing the name +to be undeleted. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The directory containing the name is marked sticky, +and the containing directory is not owned by the effective user ID. +.It Bq Er EINVAL +The last component of the path is +.Ql .. . +.It Bq Er EIO +An I/O error occurred while updating the directory entry. +.It Bq Er EROFS +The name resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.El +.Sh SEE ALSO +.Xr unlink 2 , +.Xr mount_unionfs 8 +.Sh HISTORY +The +.Fn undelete +system call first appeared in +.Bx 4.4 Lite . diff --git a/lib/libc/sys/unlink.2 b/lib/libc/sys/unlink.2 new file mode 100644 index 000000000000..e59ecf8b2a93 --- /dev/null +++ b/lib/libc/sys/unlink.2 @@ -0,0 +1,228 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd July 28, 2015 +.Dt UNLINK 2 +.Os +.Sh NAME +.Nm unlink , +.Nm unlinkat +.Nd remove directory entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn unlink "const char *path" +.Ft int +.Fn unlinkat "int fd" "const char *path" "int flag" +.Sh DESCRIPTION +The +.Fn unlink +system call +removes the link named by +.Fa path +from its directory and decrements the link count of the +file which was referenced by the link. +If that decrement reduces the link count of the file +to zero, +and no process has the file open, then +all resources associated with the file are reclaimed. +If one or more process have the file open when the last link is removed, +the link is removed, but the removal of the file is delayed until +all references to it have been closed. +The +.Fa path +argument +may not be a directory. +.Pp +The +.Fn unlinkat +system call is equivalent to +.Fn unlink +or +.Fn rmdir +except in the case where +.Fa path +specifies a relative path. +In this case the directory entry to be removed is determined +relative to the directory associated with the file descriptor +.Fa fd +instead of the current working directory. +.Pp +The values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_REMOVEDIR +Remove the directory entry specified by +.Fa fd +and +.Fa path +as a directory, not a normal file. +.El +.Pp +If +.Fn unlinkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior is +identical to a call to +.Fa unlink +or +.Fa rmdir +respectively, depending on whether or not the +.Dv AT_REMOVEDIR +bit is set in flag. +.Sh RETURN VALUES +.Rv -std unlink +.Sh ERRORS +The +.Fn unlink +succeeds unless: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EISDIR +The named file is a directory. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire path name exceeded 1023 characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +Write permission is denied on the directory containing the link +to be removed. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EPERM +The named file is a directory. +.It Bq Er EPERM +The named file has its immutable, undeletable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EPERM +The parent directory of the named file has its immutable or append-only flag +set. +.It Bq Er EPERM +The directory containing the file is marked sticky, +and neither the containing directory nor the file to be removed +are owned by the effective user ID. +.It Bq Er EIO +An I/O error occurred while deleting the directory entry +or deallocating the inode. +.It Bq Er EROFS +The named file resides on a read-only file system. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er ENOSPC +On file systems supporting copy-on-write or snapshots, there was not enough +free space to record metadata for the delete operation of the file. +.El +.Pp +In addition to the errors returned by the +.Fn unlink , +the +.Fn unlinkat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTEMPTY +The +.Fa flag +parameter has the +.Dv AT_REMOVEDIR +bit set and the +.Fa path +argument names a directory that is not an empty directory, +or there are hard links to the directory other than dot or +a single entry in dot-dot. +.It Bq Er ENOTDIR +The +.Fa flag +parameter has the +.Dv AT_REMOVEDIR +bit set and +.Fa path +does not name a directory. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr close 2 , +.Xr link 2 , +.Xr rmdir 2 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn unlinkat +system call follows The Open Group Extended API Set 2 specification. +.Sh HISTORY +The +.Fn unlink +function appeared in +.At v6 . +The +.Fn unlinkat +system call appeared in +.Fx 8.0 . +.Pp +The +.Fn unlink +system call traditionally allows the super-user to unlink directories which +can damage the file system integrity. +This implementation no longer permits it. diff --git a/lib/libc/sys/utimensat.2 b/lib/libc/sys/utimensat.2 new file mode 100644 index 000000000000..a714b344888b --- /dev/null +++ b/lib/libc/sys/utimensat.2 @@ -0,0 +1,295 @@ +.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2012, Jilles Tjoelker +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd January 17, 2016 +.Dt UTIMENSAT 2 +.Os +.Sh NAME +.Nm futimens , +.Nm utimensat +.Nd set file access and modification times +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.Ft int +.Fn futimens "int fd" "const struct timespec times[2]" +.Ft int +.Fo utimensat +.Fa "int fd" +.Fa "const char *path" +.Fa "const struct timespec times[2]" +.Fa "int flag" +.Fc +.Sh DESCRIPTION +The access and modification times of the file named by +.Fa path +or referenced by +.Fa fd +are changed as specified by the argument +.Fa times . +The inode-change-time of the file is set to the current time. +.Pp +If +.Fa path +specifies a relative path, +it is relative to the current working directory if +.Fa fd +is +.Dv AT_FDCWD +and otherwise relative to the directory associated with the file descriptor +.Fa fd . +.Pp +The +.Va tv_nsec +field of a +.Vt timespec +structure +can be set to the special value +.Dv UTIME_NOW +to set the current time, or to +.Dv UTIME_OMIT +to leave the time unchanged. +In either case, the +.Va tv_sec +field is ignored. +.Pp +If +.Fa times +is +.No non- Ns Dv NULL , +it is assumed to point to an array of two timespec structures. +The access time is set to the value of the first element, and the +modification time is set to the value of the second element. +For file systems that support file birth (creation) times (such as +.Dv UFS2 ) , +the birth time will be set to the value of the second element +if the second element is older than the currently set birth time. +To set both a birth time and a modification time, +two calls are required; the first to set the birth time +and the second to set the (presumably newer) modification time. +Ideally a new system call will be added that allows the setting +of all three times at once. +If +.Fa times +is +.Dv NULL , +this is equivalent to passing +a pointer to an array of two timespec structures +with both +.Va tv_nsec +fields set to +.Dv UTIME_NOW . +.Pp +If both +.Va tv_nsec +fields are +.Dv UTIME_OMIT , +the timestamps remain unchanged and +no permissions are needed for the file itself, +although search permissions may be required for the path prefix. +The call may or may not succeed if the named file does not exist. +.Pp +If both +.Va tv_nsec +fields are +.Dv UTIME_NOW , +the caller must be the owner of the file, have permission to +write the file, or be the super-user. +.Pp +For all other values of the timestamps, +the caller must be the owner of the file or be the super-user. +.Pp +The values for the +.Fa flag +argument of the +.Fn utimensat +system call +are constructed by a bitwise-inclusive OR of flags from the following list, +defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_NOFOLLOW +If +.Fa path +names a symbolic link, the symbolic link's times are changed. +By default, +.Fn utimensat +changes the times of the file referenced by the symbolic link. +.El +.Sh RETURN VALUES +.Rv -std +.Sh COMPATIBILITY +If the running kernel does not support this system call, +a wrapper emulates it using +.Xr fstatat 2 , +.Xr futimesat 2 +and +.Xr lutimes 2 . +As a result, timestamps will be rounded down to the nearest microsecond, +.Dv UTIME_OMIT +is not atomic and +.Dv AT_SYMLINK_NOFOLLOW +is not available with a path relative to a file descriptor. +.Sh ERRORS +These system calls will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The +.Fa times +argument is +.Dv NULL , +or both +.Va tv_nsec +values are +.Dv UTIME_NOW , +and the effective user ID of the process does not +match the owner of the file, and is not the super-user, and write +access is denied. +.It Bq Er EFAULT +The +.Fa times +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Va tv_nsec +component of at least one of the values specified by the +.Fa times +argument has a value less than 0 or greater than 999999999 and is not equal to +.Dv UTIME_NOW +or +.Dv UTIME_OMIT . +.It Bq Er EIO +An I/O error occurred while reading or writing the affected inode. +.It Bq Er EPERM +The +.Fa times +argument is not +.Dv NULL +nor are both +.Va tv_nsec +values +.Dv UTIME_NOW , +nor are both +.Va tv_nsec +values +.Dv UTIME_OMIT +and the calling process's effective user ID +does not match the owner of the file and is not the super-user. +.It Bq Er EPERM +The named file has its immutable or append-only flag set, see the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The file system containing the file is mounted read-only. +.El +.Pp +The +.Fn futimens +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +does not refer to a valid descriptor. +.El +.Pp +The +.Fn utimensat +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor. +.It Bq Er EFAULT +The +.Fa path +argument +points outside the process's allocated address space. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Dv NAME_MAX +characters, or an entire path name exceeded +.Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.It Bq Er ENOTSUP +The running kernel does not support this system call and +.Dv AT_SYMLINK_NOFOLLOW +is used with a path relative to a file descriptor. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr stat 2 , +.Xr symlink 2 , +.Xr utimes 2 , +.Xr utime 3 , +.Xr symlink 7 +.Sh STANDARDS +The +.Fn futimens +and +.Fn utimensat +system calls are expected to conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn futimens +and +.Fn utimensat +system calls appeared in +.Fx 10.3 . diff --git a/lib/libc/sys/utimensat.c b/lib/libc/sys/utimensat.c new file mode 100644 index 000000000000..a1c3c211fe95 --- /dev/null +++ b/lib/libc/sys/utimensat.c @@ -0,0 +1,112 @@ +/*- + * Copyright (c) 2015 Jilles Tjoelker + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include "namespace.h" +#include <sys/stat.h> + +#include <errno.h> +#include <fcntl.h> +#include <time.h> +#include "un-namespace.h" + +#include "libc_private.h" + +int +utimensat(int fd, const char *path, const struct timespec times[2], int flag) +{ + struct timeval now, tv[2], *tvp; + struct stat sb; + int osreldate; + + osreldate = __getosreldate(); + if (osreldate >= 1100056 || + (osreldate >= 1002506 && osreldate < 1100000)) + return (__sys_utimensat(fd, path, times, flag)); + + if ((flag & ~AT_SYMLINK_NOFOLLOW) != 0) { + errno = EINVAL; + return (-1); + } + if (times == NULL || (times[0].tv_nsec == UTIME_NOW && + times[1].tv_nsec == UTIME_NOW)) + tvp = NULL; + else if (times[0].tv_nsec == UTIME_OMIT && + times[1].tv_nsec == UTIME_OMIT) + return (0); + else { + if ((times[0].tv_nsec < 0 || times[0].tv_nsec > 999999999) && + times[0].tv_nsec != UTIME_NOW && + times[0].tv_nsec != UTIME_OMIT) { + errno = EINVAL; + return (-1); + } + if ((times[1].tv_nsec < 0 || times[1].tv_nsec > 999999999) && + times[1].tv_nsec != UTIME_NOW && + times[1].tv_nsec != UTIME_OMIT) { + errno = EINVAL; + return (-1); + } + tv[0].tv_sec = times[0].tv_sec; + tv[0].tv_usec = times[0].tv_nsec / 1000; + tv[1].tv_sec = times[1].tv_sec; + tv[1].tv_usec = times[1].tv_nsec / 1000; + tvp = tv; + if (times[0].tv_nsec == UTIME_OMIT || + times[1].tv_nsec == UTIME_OMIT) { + if (fstatat(fd, path, &sb, flag) == -1) + return (-1); + if (times[0].tv_nsec == UTIME_OMIT) { + tv[0].tv_sec = sb.st_atim.tv_sec; + tv[0].tv_usec = sb.st_atim.tv_nsec / 1000; + } + if (times[1].tv_nsec == UTIME_OMIT) { + tv[1].tv_sec = sb.st_mtim.tv_sec; + tv[1].tv_usec = sb.st_mtim.tv_nsec / 1000; + } + } + if (times[0].tv_nsec == UTIME_NOW || + times[1].tv_nsec == UTIME_NOW) { + if (gettimeofday(&now, NULL) == -1) + return (-1); + if (times[0].tv_nsec == UTIME_NOW) + tv[0] = now; + if (times[1].tv_nsec == UTIME_NOW) + tv[1] = now; + } + } + if ((flag & AT_SYMLINK_NOFOLLOW) == 0) + return (futimesat(fd, path, tvp)); + else if ((flag & AT_SYMLINK_NOFOLLOW) != 0 && + (fd == AT_FDCWD || path[0] == '/')) + return (lutimes(path, tvp)); + else { + errno = ENOTSUP; + return (-1); + } +} diff --git a/lib/libc/sys/utimes.2 b/lib/libc/sys/utimes.2 new file mode 100644 index 000000000000..30d31d27536a --- /dev/null +++ b/lib/libc/sys/utimes.2 @@ -0,0 +1,262 @@ +.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $ +.\" +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 9, 2016 +.Dt UTIMES 2 +.Os +.Sh NAME +.Nm utimes , +.Nm lutimes , +.Nm futimes , +.Nm futimesat +.Nd set file access and modification times +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn utimes "const char *path" "const struct timeval *times" +.Ft int +.Fn lutimes "const char *path" "const struct timeval *times" +.Ft int +.Fn futimes "int fd" "const struct timeval *times" +.Ft int +.Fn futimesat "int fd" "const char *path" "const struct timeval times[2]" +.Sh DESCRIPTION +.Bf -symbolic +These interfaces are obsoleted by +.Xr futimens 2 +and +.Xr utimensat 2 +because they are not accurate to nanoseconds. +.Ef +.Pp +The access and modification times of the file named by +.Fa path +or referenced by +.Fa fd +are changed as specified by the argument +.Fa times . +.Pp +If +.Fa times +is +.Dv NULL , +the access and modification times are set to the current time. +The caller must be the owner of the file, have permission to +write the file, or be the super-user. +.Pp +If +.Fa times +is +.No non- Ns Dv NULL , +it is assumed to point to an array of two timeval structures. +The access time is set to the value of the first element, and the +modification time is set to the value of the second element. +For file systems that support file birth (creation) times (such as +.Dv UFS2 ) , +the birth time will be set to the value of the second element +if the second element is older than the currently set birth time. +To set both a birth time and a modification time, +two calls are required; the first to set the birth time +and the second to set the (presumably newer) modification time. +Ideally a new system call will be added that allows the setting +of all three times at once. +The caller must be the owner of the file or be the super-user. +.Pp +In either case, the inode-change-time of the file is set to the current +time. +.Pp +The +.Fn lutimes +system call +is like +.Fn utimes +except in the case where the named file is a symbolic link, +in which case +.Fn lutimes +changes the access and modification times of the link, +while +.Fn utimes +changes the times of the file the link references. +.Pp +The +.Fn futimesat +system call is equivalent to +.Fn utimes +except in the case where +.Fa path +specifies a relative path. +In this case the access and modification time +is set to that of a file relative to the directory associated with the file +descriptor +.Fa fd +instead of the current working directory. +If +.Fn futimesat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd +parameter, the current working directory is used and the behavior +is identical to a call to +.Fn utimes . +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +All of the system call will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix. +.It Bq Er EACCES +The +.Fa times +argument is +.Dv NULL +and the effective user ID of the process does not +match the owner of the file, and is not the super-user, and write +access is denied. +.It Bq Er EFAULT +The +.Fa path +or +.Fa times +argument +points outside the process's allocated address space. +.It Bq Er EFAULT +The +.Fa times +argument +points outside the process's allocated address space. +.It Bq Er EINVAL +The +.Va tv_usec +component of at least one of the values specified by the +.Fa times +argument has a value less than 0 or greater than 999999. +.It Bq Er EIO +An I/O error occurred while reading or writing the affected inode. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded +.Dv NAME_MAX +characters, or an entire path name exceeded +.Dv PATH_MAX +characters. +.It Bq Er ENOENT +The named file does not exist. +.It Bq Er ENOTDIR +A component of the path prefix is not a directory. +.It Bq Er EPERM +The +.Fa times +argument is not +.Dv NULL +and the calling process's effective user ID +does not match the owner of the file and is not the super-user. +.It Bq Er EPERM +The named file has its immutable or append-only flags set. +See the +.Xr chflags 2 +manual page for more information. +.It Bq Er EROFS +The file system containing the file is mounted read-only. +.El +.Pp +The +.Fn futimes +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +does not refer to a valid descriptor. +.El +.Pp +In addition to the errors returned by the +.Fn utimes , +the +.Fn futimesat +may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa path +argument does not specify an absolute path and the +.Fa fd +argument is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er ENOTDIR +The +.Fa path +argument is not an absolute path and +.Fa fd +is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr stat 2 , +.Xr utimensat 2 , +.Xr utime 3 +.Sh STANDARDS +The +.Fn utimes +function is expected to conform to +.St -xpg4.2 . +The +.Fn futimesat +system call follows The Open Group Extended API Set 2 specification +but was replaced by +.Fn utimensat +in +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn utimes +system call appeared in +.Bx 4.2 . +The +.Fn futimes +and +.Fn lutimes +system calls first appeared in +.Fx 3.0 . +The +.Fn futimesat +system call appeared in +.Fx 8.0 . diff --git a/lib/libc/sys/utrace.2 b/lib/libc/sys/utrace.2 new file mode 100644 index 000000000000..814091aeb30d --- /dev/null +++ b/lib/libc/sys/utrace.2 @@ -0,0 +1,80 @@ +.\" $NetBSD: utrace.2,v 1.11 2003/04/24 12:17:49 wiz Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry <g.mcgarry@ieee.org>. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 11, 2015 +.Dt UTRACE 2 +.Os +.Sh NAME +.Nm utrace +.Nd insert user record in ktrace log +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/uio.h +.In sys/ktrace.h +.Ft int +.Fn utrace "const void *addr" "size_t len" +.Sh DESCRIPTION +Adds a record to the process trace with information supplied by user. +The record contains +.Fa len +bytes from memory pointed to by +.Fa addr . +This call only has an effect if the calling process is being traced. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +Specified data length +.Fa len +was bigger than +.Dv KTR_USER_MAXLEN . +.It Bq Er ENOMEM +Insufficient memory to honor the request. +.It Bq Er ENOSYS +Currently running kernel was compiled without +.Xr ktrace 2 +support +.Pq Cd "options KTRACE" . +.El +.Sh SEE ALSO +.Xr kdump 1 , +.Xr ktrace 1 , +.Xr truss 1 , +.Xr ktrace 2 , +.Xr sysdecode_utrace 3 +.Sh HISTORY +The +.Fn utrace +system call first appeared in +.Fx 2.2 . diff --git a/lib/libc/sys/uuidgen.2 b/lib/libc/sys/uuidgen.2 new file mode 100644 index 000000000000..9c90102b3e2f --- /dev/null +++ b/lib/libc/sys/uuidgen.2 @@ -0,0 +1,142 @@ +.\" Copyright (c) 2002 Marcel Moolenaar +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 26, 2002 +.Dt UUIDGEN 2 +.Os +.Sh NAME +.Nm uuidgen +.Nd generate universally unique identifiers +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/uuid.h +.Ft int +.Fn uuidgen "struct uuid *store" "int count" +.Sh DESCRIPTION +The +.Fn uuidgen +system call generates +.Fa count +universally unique identifiers (UUIDs) and writes them to the buffer +pointed to by +.Fa store . +The identifiers are generated according to the syntax and semantics of the +DCE version 1 variant of universally unique identifiers. +See below for a more in-depth description of the identifiers. +When no IEEE 802 +address is available for the node field, a random multicast address is +generated for each invocation of the system call. +According to the algorithm of generating time-based UUIDs, this will also +force a new random clock sequence, thereby increasing the likelihood for +the identifier to be unique. +.Pp +When multiple identifiers are to be generated, the +.Fn uuidgen +system call will generate a set of identifiers that is dense in such a way +that there is no identifier that is larger than the smallest identifier in the +set and smaller than the largest identifier in the set and that is not already +in the set. +.Pp +Universally unique identifiers, also known as globally unique identifiers +(GUIDs), have a binary representation of 128-bits. +The grouping and meaning of these bits is described by the following +structure and its description of the fields that follow it: +.Bd -literal +struct uuid { + uint32_t time_low; + uint16_t time_mid; + uint16_t time_hi_and_version; + uint8_t clock_seq_hi_and_reserved; + uint8_t clock_seq_low; + uint8_t node[_UUID_NODE_LEN]; +}; +.Ed +.Bl -tag -width ".Va clock_seq_hi_and_reserved" +.It Va time_low +The least significant 32 bits of a 60-bit timestamp. +This field is stored in the native byte-order. +.It Va time_mid +The least significant 16 bits of the most significant 28 bits of the 60-bit +timestamp. +This field is stored in the native byte-order. +.It Va time_hi_and_version +The most significant 12 bits of the 60-bit timestamp multiplexed with a 4-bit +version number. +The version number is stored in the most significant 4 bits of the 16-bit +field. +This field is stored in the native byte-order. +.It Va clock_seq_hi_and_reserved +The most significant 6 bits of a 14-bit sequence number multiplexed with a +2-bit variant value. +Note that the width of the variant value is determined by the variant itself. +Identifiers generated by the +.Fn uuidgen +system call have variant value 10b. +the variant value is stored in the most significant bits of the field. +.It Va clock_seq_low +The least significant 8 bits of a 14-bit sequence number. +.It Va node +The 6-byte IEEE 802 (MAC) address of one of the interfaces of the node. +If no such interface exists, a random multi-cast address is used instead. +.El +.Pp +The binary representation is sensitive to byte ordering. +Any multi-byte field is to be stored in the local or native byte-order and +identifiers must be converted when transmitted to hosts that do not agree +on the byte-order. +The specification does not however document what this means in concrete +terms and is otherwise beyond the scope of this system call. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn uuidgen +system call can fail with: +.Bl -tag -width Er +.It Bq Er EFAULT +The buffer pointed to by +.Fa store +could not be written to for any or all identifiers. +.It Bq Er EINVAL +The +.Fa count +argument is less than 1 or larger than the hard upper limit of 2048. +.El +.Sh SEE ALSO +.Xr uuidgen 1 , +.Xr uuid 3 +.Sh STANDARDS +The identifiers are represented and generated in conformance with the DCE 1.1 +RPC specification. +The +.Fn uuidgen +system call is itself not part of the specification. +.Sh HISTORY +The +.Fn uuidgen +system call first appeared in +.Fx 5.0 . diff --git a/lib/libc/sys/vfork.2 b/lib/libc/sys/vfork.2 new file mode 100644 index 000000000000..07405c5f805a --- /dev/null +++ b/lib/libc/sys/vfork.2 @@ -0,0 +1,145 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)vfork.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd May 22, 2016 +.Dt VFORK 2 +.Os +.Sh NAME +.Nm vfork +.Nd create a new process without copying the address space +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn vfork void +.Sh DESCRIPTION +.Bf -symbolic +Since this function is hard to use correctly from application software, +it is recommended to use +.Xr posix_spawn 3 +or +.Xr fork 2 +instead. +.Ef +.Pp +The +.Fn vfork +system call +can be used to create new processes without fully copying the address +space of the old process, which is inefficient in a paged +environment. +It is useful when the purpose of +.Xr fork 2 +would have been to create a new system context for an +.Xr execve 2 . +The +.Fn vfork +system call +differs from +.Xr fork 2 +in that the child borrows the parent process's address space and the +calling thread's stack +until a call to +.Xr execve 2 +or an exit (either by a call to +.Xr _exit 2 +or abnormally). +The calling thread is suspended while the child is using its resources. +Other threads continue to run. +.Pp +The +.Fn vfork +system call +returns 0 in the child's context and (later) the pid of the child in +the parent's context. +.Pp +Many problems can occur when replacing +.Xr fork 2 +with +.Fn vfork . +For example, it does not work to return while running in the child's context +from the procedure that called +.Fn vfork +since the eventual return from +.Fn vfork +would then return to a no longer existent stack frame. +Also, changing process state which is partially implemented in user space +such as signal handlers with +.Xr libthr 3 +will corrupt the parent's state. +.Pp +Be careful, also, to call +.Xr _exit 2 +rather than +.Xr exit 3 +if you cannot +.Xr execve 2 , +since +.Xr exit 3 +will flush and close standard I/O channels, and thereby mess up the +parent processes standard I/O data structures. +(Even with +.Xr fork 2 +it is wrong to call +.Xr exit 3 +since buffered data would then be flushed twice.) +.Sh RETURN VALUES +Same as for +.Xr fork 2 . +.Sh SEE ALSO +.Xr _exit 2 , +.Xr execve 2 , +.Xr fork 2 , +.Xr rfork 2 , +.Xr sigaction 2 , +.Xr wait 2 , +.Xr exit 3 , +.Xr posix_spawn 3 +.Sh HISTORY +The +.Fn vfork +system call appeared in +.Bx 3 . +.Sh BUGS +To avoid a possible deadlock situation, +processes that are children in the middle +of a +.Fn vfork +are never sent +.Dv SIGTTOU +or +.Dv SIGTTIN +signals; rather, +output or +.Xr ioctl 2 +calls +are allowed +and input attempts result in an end-of-file indication. diff --git a/lib/libc/sys/wait.2 b/lib/libc/sys/wait.2 new file mode 100644 index 000000000000..38b7bb7e6b33 --- /dev/null +++ b/lib/libc/sys/wait.2 @@ -0,0 +1,680 @@ +.\" Copyright (c) 1980, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)wait.2 8.2 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd June 1, 2016 +.Dt WAIT 2 +.Os +.Sh NAME +.Nm wait , +.Nm waitid , +.Nm waitpid , +.Nm wait3 , +.Nm wait4 , +.Nm wait6 +.Nd wait for processes to change status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/wait.h +.Ft pid_t +.Fn wait "int *status" +.Ft pid_t +.Fn waitpid "pid_t wpid" "int *status" "int options" +.In signal.h +.Ft int +.Fn waitid "idtype_t idtype" "id_t id" "siginfo_t *info" "int options" +.In sys/time.h +.In sys/resource.h +.Ft pid_t +.Fn wait3 "int *status" "int options" "struct rusage *rusage" +.Ft pid_t +.Fn wait4 "pid_t wpid" "int *status" "int options" "struct rusage *rusage" +.Ft pid_t +.Fn wait6 "idtype_t idtype" "id_t id" "int *status" "int options" "struct __wrusage *wrusage" "siginfo_t *infop" +.Sh DESCRIPTION +The +.Fn wait +function suspends execution of its calling thread until +.Fa status +information is available for a child process +or a signal is received. +On return from a successful +.Fn wait +call, +the +.Fa status +area contains information about the process that reported a status change +as defined below. +.Pp +The +.Fn wait4 +and +.Fn wait6 +system calls provide a more general interface for programs +that need to wait for specific child processes, +that need resource utilization statistics accumulated by child processes, +or that require options. +The other wait functions are implemented using either +.Fn wait4 +or +.Fn wait6 . +.Pp +The +.Fn wait6 +function is the most general function in this family and its distinct +features are: +.Pp +All of the desired process statuses to be waited on must be explicitly +specified in +.Fa options . +The +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 +functions all implicitly wait for exited and trapped processes, +but the +.Fn waitid +and +.Fn wait6 +functions require the corresponding +.Dv WEXITED +and +.Dv WTRAPPED +flags to be explicitly specified. +This allows waiting for processes which have experienced other +status changes without having to also handle the exit status from +terminated processes. +.Pp +The +.Fn wait6 +function accepts a +.Fa wrusage +argument which points to a structure defined as: +.Bd -literal +struct __wrusage { + struct rusage wru_self; + struct rusage wru_children; +}; +.Ed +.Pp +This allows the calling process to collect resource usage statistics +from both its own child process as well as from its grand children. +When no resource usage statistics are needed this pointer can be +.Dv NULL . +.Pp +The last argument +.Fa infop +must be either +.Dv NULL +or a pointer to a +.Fa siginfo_t +structure. +If +.Pf non- Dv NULL , +the structure is filled with the same data as for a +.Dv SIGCHLD +signal delivered when the process changed state. +.Pp +The set of child processes to be queried is specified by the arguments +.Fa idtype +and +.Fa id . +The separate +.Fa idtype +and +.Fa id +arguments support many other types of +identifiers in addition to process IDs and process group IDs. +.Bl -bullet -offset indent +.It +If +.Fa idtype +is +.Dv P_PID , +.Fn waitid +and +.Fn wait6 +wait for the child process with a process ID equal to +.Dv (pid_t)id . +.It +If +.Fa idtype +is +.Dv P_PGID , +.Fn waitid +and +.Fn wait6 +wait for the child process with a process group ID equal to +.Dv (pid_t)id . +.It +If +.Fa idtype +is +.Dv P_ALL , +.Fn waitid +and +.Fn wait6 +wait for any child process and the +.Dv id +is ignored. +.It +If +.Fa idtype +is +.Dv P_PID +or +.Dv P_PGID +and the +.Dv id +is zero, +.Fn waitid +and +.Fn wait6 +wait for any child process in the same process group as the caller. +.El +.Pp +Non-standard identifier types supported by this +implementation of +.Fn waitid +and +.Fn wait6 +are: +.Bl -tag -width P_JAILID +.It Dv P_UID +Wait for processes whose effective user ID is equal to +.Dv (uid_t) Fa id . +.It Dv P_GID +Wait for processes whose effective group ID is equal to +.Dv (gid_t) Fa id . +.It Dv P_SID +Wait for processes whose session ID is equal to +.Fa id . +.\" This is just how sessions work, not sure this needs to be documented here +If the child process started its own session, +its session ID will be the same as its process ID. +Otherwise the session ID of a child process will match the caller's session ID. +.It Dv P_JAILID +Waits for processes within a jail whose jail identifier is equal to +.Fa id . +.El +.Pp +For the +.Fn waitpid +and +.Fn wait4 +functions, the single +.Fa wpid +argument specifies the set of child processes for which to wait. +.Bl -bullet -offset indent +.It +If +.Fa wpid +is -1, the call waits for any child process. +.It +If +.Fa wpid +is 0, +the call waits for any child process in the process group of the caller. +.It +If +.Fa wpid +is greater than zero, the call waits for the process with process ID +.Fa wpid . +.It +If +.Fa wpid +is less than -1, the call waits for any process whose process group ID +equals the absolute value of +.Fa wpid . +.El +.Pp +The +.Fa status +argument is defined below. +.Pp +The +.Fa options +argument contains the bitwise OR of any of the following options. +.Bl -tag -width WCONTINUED +.It Dv WCONTINUED +Report the status of selected processes that +have continued from a job control stop by receiving a +.Dv SIGCONT +signal. +.It Dv WNOHANG +Do not block when +there are no processes wishing to report status. +.It Dv WUNTRACED +Report the status of selected processes which are stopped due to a +.Dv SIGTTIN , SIGTTOU , SIGTSTP , +or +.Dv SIGSTOP +signal. +.It Dv WSTOPPED +An alias for +.Dv WUNTRACED . +.It Dv WTRAPPED +Report the status of selected processes which are being traced via +.Xr ptrace 2 +and have trapped or reached a breakpoint. +This flag is implicitly set for the functions +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 . +.br +For the +.Fn waitid +and +.Fn wait6 +functions, the flag has to be explicitly included in +.Fa options +if status reports from trapped processes are expected. +.It Dv WEXITED +Report the status of selected processes which have terminated. +This flag is implicitly set for the functions +.Fn wait , +.Fn waitpid , +.Fn wait3 , +and +.Fn wait4 . +.br +For the +.Fn waitid +and +.Fn wait6 +functions, the flag has to be explicitly included in +.Fa options +if status reports from terminated processes are expected. +.It Dv WNOWAIT +Keep the process whose status is returned in a waitable state. +The process may be waited for again after this call completes. +.El +.sp +For the +.Fn waitid +and +.Fn wait6 +functions, at least one of the options +.Dv WEXITED , +.Dv WUNTRACED , +.Dv WSTOPPED , +.Dv WTRAPPED , +or +.Dv WCONTINUED +must be specified. +Otherwise there will be no events for the call to report. +To avoid hanging indefinitely in such a case these functions +return -1 with +.Dv errno +set to +.Dv EINVAL . +.Pp +If +.Fa rusage +is non-NULL, a summary of the resources used by the terminated +process and all its children is returned. +.Pp +If +.Fa wrusage +is non-NULL, separate summaries are returned for the resources used +by the terminated process and the resources used by all its children. +.Pp +If +.Fa infop +is non-NULL, a +.Dv siginfo_t +structure is returned with the +.Fa si_signo +field set to +.Dv SIGCHLD +and the +.Fa si_pid +field set to the process ID of the process reporting status. +For the exited process, the +.Fa si_status +field of the +.Dv siginfo_t +structure contains the full 32 bit exit status passed to +.Xr _exit 2 ; +the +.Fa status +argument of other calls only returns 8 lowest bits of the exit status. +.Pp +When the +.Dv WNOHANG +option is specified and no processes +wish to report status, +.Fn waitid +sets the +.Fa si_signo +and +.Fa si_pid +fields in +.Fa infop +to zero. +Checking these fields is the only way to know if a status change was reported. +.Pp +When the +.Dv WNOHANG +option is specified and no processes +wish to report status, +.Fn wait4 +and +.Fn wait6 +return a +process id +of 0. +.Pp +The +.Fn wait +call is the same as +.Fn wait4 +with a +.Fa wpid +value of -1, +with an +.Fa options +value of zero, +and a +.Fa rusage +value of +.Dv NULL . +The +.Fn waitpid +function is identical to +.Fn wait4 +with an +.Fa rusage +value of +.Dv NULL . +The older +.Fn wait3 +call is the same as +.Fn wait4 +with a +.Fa wpid +value of -1. +The +.Fn wait4 +function is identical to +.Fn wait6 +with the flags +.Dv WEXITED +and +.Dv WTRAPPED +set in +.Fa options +and +.Fa infop +set to +.Dv NULL . +.Pp +The following macros may be used to test the current status of the process. +Exactly one of the following four macros will evaluate to a non-zero +.Pq true +value: +.Bl -tag -width Ds +.It Fn WIFCONTINUED status +True if the process has not terminated, and +has continued after a job control stop. +This macro can be true only if the wait call specified the +.Dv WCONTINUED +option. +.It Fn WIFEXITED status +True if the process terminated normally by a call to +.Xr _exit 2 +or +.Xr exit 3 . +.It Fn WIFSIGNALED status +True if the process terminated due to receipt of a signal. +.It Fn WIFSTOPPED status +True if the process has not terminated, but has stopped and can be restarted. +This macro can be true only if the wait call specified the +.Dv WUNTRACED +option +or if the child process is being traced (see +.Xr ptrace 2 ) . +.El +.Pp +Depending on the values of those macros, the following macros +produce the remaining status information about the child process: +.Bl -tag -width Ds +.It Fn WEXITSTATUS status +If +.Fn WIFEXITED status +is true, evaluates to the low-order 8 bits +of the argument passed to +.Xr _exit 2 +or +.Xr exit 3 +by the child. +.It Fn WTERMSIG status +If +.Fn WIFSIGNALED status +is true, evaluates to the number of the signal +that caused the termination of the process. +.It Fn WCOREDUMP status +If +.Fn WIFSIGNALED status +is true, evaluates as true if the termination +of the process was accompanied by the creation of a core file +containing an image of the process when the signal was received. +.It Fn WSTOPSIG status +If +.Fn WIFSTOPPED status +is true, evaluates to the number of the signal +that caused the process to stop. +.El +.Sh NOTES +See +.Xr sigaction 2 +for a list of termination signals. +A status of 0 indicates normal termination. +.Pp +If a parent process terminates without +waiting for all of its child processes to terminate, +the remaining child processes are assigned the parent +process 1 ID (the init process ID). +.Pp +If a signal is caught while any of the +.Fn wait +calls are pending, +the call may be interrupted or restarted when the signal-catching routine +returns, +depending on the options in effect for the signal; +see discussion of +.Dv SA_RESTART +in +.Xr sigaction 2 . +.Pp +The implementation queues one +.Dv SIGCHLD +signal for each child process whose +status has changed; if +.Fn wait +returns because the status of a child process is available, the pending +SIGCHLD signal associated with the process ID of the child process will +be discarded. +Any other pending +.Dv SIGCHLD +signals remain pending. +.Pp +If +.Dv SIGCHLD +is blocked and +.Fn wait +returns because the status of a child process is available, the pending +.Dv SIGCHLD +signal will be cleared unless another status of the child process +is available. +.Sh RETURN VALUES +If +.Fn wait +returns due to a stopped, continued, +or terminated child process, the process ID of the child +is returned to the calling process. +Otherwise, a value of \-1 +is returned and +.Va errno +is set to indicate the error. +.Pp +If +.Fn wait6 , +.Fn wait4 , +.Fn wait3 , +or +.Fn waitpid +returns due to a stopped, continued, +or terminated child process, the process ID of the child +is returned to the calling process. +If there are no children not previously awaited, +-1 is returned with +.Va errno +set to +.Er ECHILD . +Otherwise, if +.Dv WNOHANG +is specified and there are +no stopped, continued or exited children, +0 is returned. +If an error is detected or a caught signal aborts the call, +a value of -1 +is returned and +.Va errno +is set to indicate the error. +.Pp +If +.Fn waitid +returns because one or more processes have a state change to report, +0 is returned. +If an error is detected, +a value of -1 +is returned and +.Va errno +is set to indicate the error. +If +.Dv WNOHANG +is specified and there are +no stopped, continued or exited children, +0 is returned. +The +.Fa si_signo +and +.Fa si_pid +fields of +.Fa infop +must be checked against zero to determine if a process reported status. +.Pp +.Fn wait +called with -1 to wait for any child process will ignore a child that is +referenced by a process descriptor (see +.Xr pdfork 2 ) . +Specific processes can still be waited on by specifying the process ID +or descriptor (see +.Xr pdwait 4 ) . +.Sh ERRORS +The +.Fn wait +function +will fail and return immediately if: +.Bl -tag -width Er +.It Bq Er ECHILD +The calling process has no existing unwaited-for +child processes. +.It Bq Er ECHILD +No status from the terminated child process is available +because the calling process has asked the system to discard +such status by ignoring the signal +.Dv SIGCHLD +or setting the flag +.Dv SA_NOCLDWAIT +for that signal. +.It Bq Er EFAULT +The +.Fa status +or +.Fa rusage +argument points to an illegal address. +(May not be detected before exit of a child process.) +.It Bq Er EINTR +The call was interrupted by a caught signal, +or the signal did not have the +.Dv SA_RESTART +flag set. +.It Bq Er EINVAL +An invalid value was specified for +.Fa options , +or +.Fa idtype +and +.Fa id +do not specify a valid set of processes. +.El +.Sh SEE ALSO +.Xr _exit 2 , +.Xr ptrace 2 , +.Xr sigaction 2 , +.Xr exit 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn wait , +.Fn waitpid , +and +.Fn waitid +functions are defined by POSIX; +.Fn wait6 , +.Fn wait4 , +and +.Fn wait3 +are not specified by POSIX. +The +.Fn WCOREDUMP +macro +is an extension to the POSIX interface. +.Pp +The ability to use the +.Dv WNOWAIT +flag with +.Fn waitpid +is an extension; +.Tn POSIX +only permits this flag with +.Fn waitid . +.Sh HISTORY +The +.Fn wait +function appeared in +.At v6 . diff --git a/lib/libc/sys/wait4.c b/lib/libc/sys/wait4.c new file mode 100644 index 000000000000..a5dbd0fcb1aa --- /dev/null +++ b/lib/libc/sys/wait4.c @@ -0,0 +1,49 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/wait.h> +#include "libc_private.h" + +__weak_reference(__sys_wait4, __wait4); + +#pragma weak wait4 +pid_t +wait4(pid_t pid, int *status, int options, struct rusage *ru) +{ + + return (((pid_t (*)(pid_t, int *, int, struct rusage *)) + __libc_interposing[INTERPOS_wait4])(pid, status, options, ru)); +} diff --git a/lib/libc/sys/wait6.c b/lib/libc/sys/wait6.c new file mode 100644 index 000000000000..d280a7698747 --- /dev/null +++ b/lib/libc/sys/wait6.c @@ -0,0 +1,52 @@ +/* + * Copyright (c) 2015 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/wait.h> +#include <signal.h> +#include "libc_private.h" + +__weak_reference(__sys_wait6, __wait6); + +#pragma weak wait6 +pid_t +wait6(idtype_t idtype, id_t id, int *status, int options, struct __wrusage *ru, + siginfo_t *infop) +{ + + return (((pid_t (*)(idtype_t, id_t, int *, int, struct __wrusage *, + siginfo_t *))__libc_interposing[INTERPOS_wait6])(idtype, id, + status, options, ru, infop)); +} diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 new file mode 100644 index 000000000000..0bfe56530f7c --- /dev/null +++ b/lib/libc/sys/write.2 @@ -0,0 +1,285 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)write.2 8.5 (Berkeley) 4/2/94 +.\" $FreeBSD$ +.\" +.Dd December 15, 2015 +.Dt WRITE 2 +.Os +.Sh NAME +.Nm write , +.Nm writev , +.Nm pwrite , +.Nm pwritev +.Nd write output +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn write "int fd" "const void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pwrite "int fd" "const void *buf" "size_t nbytes" "off_t offset" +.In sys/uio.h +.Ft ssize_t +.Fn writev "int fd" "const struct iovec *iov" "int iovcnt" +.Ft ssize_t +.Fn pwritev "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset" +.Sh DESCRIPTION +The +.Fn write +system call +attempts to write +.Fa nbytes +of data to the object referenced by the descriptor +.Fa fd +from the buffer pointed to by +.Fa buf . +The +.Fn writev +system call +performs the same action, but gathers the output data +from the +.Fa iovcnt +buffers specified by the members of the +.Fa iov +array: iov[0], iov[1], ..., iov[iovcnt\|-\|1]. +The +.Fn pwrite +and +.Fn pwritev +system calls +perform the same functions, but write to the specified position in +the file without modifying the file pointer. +.Pp +For +.Fn writev +and +.Fn pwritev , +the +.Fa iovec +structure is defined as: +.Pp +.Bd -literal -offset indent -compact +struct iovec { + void *iov_base; /* Base address. */ + size_t iov_len; /* Length. */ +}; +.Ed +.Pp +Each +.Fa iovec +entry specifies the base address and length of an area +in memory from which data should be written. +The +.Fn writev +system call +will always write a complete area before proceeding +to the next. +.Pp +On objects capable of seeking, the +.Fn write +starts at a position +given by the pointer associated with +.Fa fd , +see +.Xr lseek 2 . +Upon return from +.Fn write , +the pointer is incremented by the number of bytes which were written. +.Pp +Objects that are not capable of seeking always write from the current +position. +The value of the pointer associated with such an object +is undefined. +.Pp +If the real user is not the super-user, then +.Fn write +clears the set-user-id bit on a file. +This prevents penetration of system security +by a user who +.Dq captures +a writable set-user-id file +owned by the super-user. +.Pp +When using non-blocking I/O on objects such as sockets that are subject +to flow control, +.Fn write +and +.Fn writev +may write fewer bytes than requested; +the return value must be noted, +and the remainder of the operation should be retried when possible. +.Sh RETURN VALUES +Upon successful completion the number of bytes which were written +is returned. +Otherwise a -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn write , +.Fn writev , +.Fn pwrite +and +.Fn pwritev +system calls +will fail and the file pointer will remain unchanged if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid descriptor open for writing. +.It Bq Er EPIPE +An attempt is made to write to a pipe that is not open +for reading by any process. +.It Bq Er EPIPE +An attempt is made to write to a socket of type +.Dv SOCK_STREAM +that is not connected to a peer socket. +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's +file size limit or the maximum file size. +.It Bq Er EFAULT +Part of +.Fa iov +or data to be written to the file +points outside the process's allocated address space. +.It Bq Er EINVAL +The pointer associated with +.Fa fd +was negative. +.It Bq Er ENOSPC +There is no free space remaining on the file system +containing the file. +.It Bq Er EDQUOT +The user's quota of disk blocks on the file system +containing the file has been exhausted. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EINTR +A signal interrupted the write before it could be completed. +.It Bq Er EAGAIN +The file was marked for non-blocking I/O, +and no data could be written immediately. +.It Bq Er EROFS +An attempt was made to write over a disk label area at the beginning +of a slice. +Use +.Xr disklabel 8 +.Fl W +to enable writing on the disk label area. +.It Bq Er EINVAL +The value +.Fa nbytes +is greater than +.Dv INT_MAX . +.El +.Pp +In addition, +.Fn writev +and +.Fn pwritev +may return one of the following errors: +.Bl -tag -width Er +.It Bq Er EDESTADDRREQ +The destination is no longer available when writing to a +.Ux +domain datagram socket on which +.Xr connect 2 +had been used to set a destination address. +.It Bq Er EINVAL +The +.Fa iovcnt +argument +was less than or equal to 0, or greater than +.Dv IOV_MAX . +.It Bq Er EINVAL +One of the +.Fa iov_len +values in the +.Fa iov +array was negative. +.It Bq Er EINVAL +The sum of the +.Fa iov_len +values in the +.Fa iov +array overflowed a 32-bit integer. +.It Bq Er ENOBUFS +The mbuf pool has been completely exhausted when writing to a socket. +.El +.Pp +The +.Fn pwrite +and +.Fn pwritev +system calls may also return the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa offset +value was negative. +.It Bq Er ESPIPE +The file descriptor is associated with a pipe, socket, or FIFO. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr select 2 +.Sh STANDARDS +The +.Fn write +system call is expected to conform to +.St -p1003.1-90 . +The +.Fn writev +and +.Fn pwrite +system calls are expected to conform to +.St -xpg4.2 . +.Sh HISTORY +The +.Fn pwritev +system call appeared in +.Fx 6.0 . +The +.Fn pwrite +function appeared in +.At V.4 . +The +.Fn writev +system call appeared in +.Bx 4.2 . +The +.Fn write +function appeared in +.At v6 . diff --git a/lib/libc/sys/write.c b/lib/libc/sys/write.c new file mode 100644 index 000000000000..ffb1aa5ffba7 --- /dev/null +++ b/lib/libc/sys/write.c @@ -0,0 +1,50 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_write, __write); + +#pragma weak write +ssize_t +write(int fd, const void *buf, size_t nbytes) +{ + + return (((ssize_t (*)(int, const void *, size_t)) + __libc_interposing[INTERPOS_write])(fd, buf, nbytes)); +} diff --git a/lib/libc/sys/writev.c b/lib/libc/sys/writev.c new file mode 100644 index 000000000000..20b10053dc59 --- /dev/null +++ b/lib/libc/sys/writev.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2014 The FreeBSD Foundation. + * All rights reserved. + * + * Portions of this software were developed by Konstantin Belousov + * under sponsorship from the FreeBSD Foundation. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice(s), this list of conditions and the following disclaimer as + * the first lines of this file unmodified other than the possible + * addition of one or more copyright notices. + * 2. Redistributions in binary form must reproduce the above copyright + * notice(s), this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY + * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE + * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <sys/uio.h> +#include <unistd.h> +#include "libc_private.h" + +__weak_reference(__sys_writev, __writev); + +#pragma weak writev +ssize_t +writev(int fd, const struct iovec *iov, int iovcnt) +{ + + return (((ssize_t (*)(int, const struct iovec *, int)) + __libc_interposing[INTERPOS_writev])(fd, iov, iovcnt)); +} |