diff options
Diffstat (limited to 'lib/libc/sys')
180 files changed, 30701 insertions, 0 deletions
diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc new file mode 100644 index 0000000..7705a41 --- /dev/null +++ b/lib/libc/sys/Makefile.inc @@ -0,0 +1,169 @@ +# @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 +# $FreeBSD$ + +# sys sources +.PATH: ${.CURDIR}/${MACHINE_ARCH}/sys ${.CURDIR}/sys + +# Include the generated makefile containing the *complete* list +# of syscall names in MIASM. +.include "${.CURDIR}/../../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. +# +.if exists(${.CURDIR}/${MACHINE_ARCH}/sys/Makefile.inc) +.include "${.CURDIR}/${MACHINE_ARCH}/sys/Makefile.inc" +.endif + +# Sources common to both syscall interfaces: +SRCS+= ftruncate.c lseek.c mmap.c pread.c pwrite.c stack_protector.c \ + truncate.c __error.c + +# 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 + +OBJS+= ${ASM} ${PSEUDO} + +SASM= ${ASM:S/.o/.S/} + +SPSEUDO= ${PSEUDO:S/.o/.S/} + +SRCS+= ${SASM} ${SPSEUDO} + +SYM_MAPS+= ${.CURDIR}/sys/Symbol.map + +# Generated files +CLEANFILES+= ${SASM} ${SPSEUDO} + +${SASM}: + printf '#include "SYS.h"\nRSYSCALL(${.PREFIX})\n' > ${.TARGET} + +${SPSEUDO}: + printf '#include "SYS.h"\nPSEUDO(${.PREFIX:S/_//})\n' \ + > ${.TARGET} + +MAN+= _exit.2 abort2.2 accept.2 access.2 acct.2 adjtime.2 \ + aio_cancel.2 aio_error.2 aio_read.2 aio_return.2 \ + aio_suspend.2 aio_waitcomplete.2 aio_write.2 \ + bind.2 brk.2 chdir.2 chflags.2 \ + chmod.2 chown.2 chroot.2 clock_gettime.2 close.2 \ + connect.2 dup.2 execve.2 extattr_get_file.2 \ + fcntl.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 \ + 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 kse.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 \ + msync.2 munmap.2 nanosleep.2 ntp_adjtime.2 ntp_gettime.2 \ + nfssvc.2 open.2 pathconf.2 pipe.2 poll.2 profil.2 ptrace.2 quotactl.2 \ + read.2 readlink.2 reboot.2 recv.2 rename.2 revoke.2 rfork.2 rmdir.2 \ + rtprio.2 select.2 semctl.2 semget.2 semop.2 send.2 sendfile.2 \ + setgroups.2 setpgid.2 setregid.2 setresuid.2 setreuid.2 setsid.2 \ + setuid.2 shmat.2 shmctl.2 shmget.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 \ + sctp_generic_recvmsg.2 sctp_generic_sendmsg.2 sctp_peeloff.2 \ + swapon.2 symlink.2 sync.2 sysarch.2 syscall.2 \ + timer_create.2 timer_delete.2 timer_settime.2 \ + truncate.2 umask.2 undelete.2 \ + unlink.2 utimes.2 utrace.2 uuidgen.2 vfork.2 wait.2 write.2 +.if !defined(NO_P1003_1B) +MAN+= sched_get_priority_max.2 sched_setparam.2 \ + sched_setscheduler.2 sched_yield.2 +.endif + +MLINKS+=access.2 eaccess.2 +MLINKS+=brk.2 sbrk.2 +MLINKS+=chdir.2 fchdir.2 +MLINKS+=chflags.2 fchflags.2 chflags.2 lchflags.2 +MLINKS+=chmod.2 fchmod.2 chmod.2 lchmod.2 +MLINKS+=chown.2 fchown.2 chown.2 lchown.2 +MLINKS+=clock_gettime.2 clock_getres.2 clock_gettime.2 clock_settime.2 +MLINKS+=dup.2 dup2.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_list.2 \ + extattr_get_file.2 extattr_get_fd.2 \ + extattr_get_file.2 extattr_get_list.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+=fhopen.2 fhstat.2 fhopen.2 fhstatfs.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+=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 +MLINKS+=kqueue.2 kevent.2 +MLINKS+=kse.2 kse_create.2 kse.2 kse_exit.2 kse.2 kse_release.2 \ + kse.2 kse_switchin.2 kse.2 kse_thr_interrupt.2 kse.2 kse_wakeup.2 +MLINKS+=madvise.2 posix_madvise.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_send.2 mq_timedsend.2 +MLINKS+=mq_receive.2 mq_timedreceive.2 +MLINKS+=pathconf.2 fpathconf.2 +MLINKS+=read.2 pread.2 read.2 readv.2 read.2 preadv.2 +MLINKS+=recv.2 recvfrom.2 recv.2 recvmsg.2 +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 setresgid.2 setresuid.2 getresuid.2 setresuid.2 getresgid.2 +MLINKS+=setuid.2 setegid.2 setuid.2 seteuid.2 setuid.2 setgid.2 +MLINKS+=shmat.2 shmdt.2 +MLINKS+=sigwaitinfo.2 sigtimedwait.2 +MLINKS+=stat.2 fstat.2 stat.2 lstat.2 +MLINKS+=statfs.2 fstatfs.2 +MLINKS+=syscall.2 __syscall.2 +MLINKS+=swapon.2 swapoff.2 +MLINKS+=timer_settime.2 timer_gettime.2 timer_settime.2 timer_getoverrun.2 +MLINKS+=truncate.2 ftruncate.2 +MLINKS+=utimes.2 futimes.2 utimes.2 lutimes.2 +MLINKS+=wait.2 wait3.2 wait.2 wait4.2 wait.2 waitpid.2 +MLINKS+=write.2 pwrite.2 write.2 writev.2 write.2 pwritev.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 diff --git a/lib/libc/sys/Symbol.map b/lib/libc/sys/Symbol.map new file mode 100644 index 0000000..18d58eb --- /dev/null +++ b/lib/libc/sys/Symbol.map @@ -0,0 +1,962 @@ +/* + * $FreeBSD$ + */ + +/* + * It'd be nice to have this automatically generated, but we don't + * know to what version they will eventually belong, 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; + __semctl; + __setugid; + __syscall; + __sysctl; + _umtx_lock; + _umtx_op; + _umtx_unlock; + 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; + __chk_fail; + 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; + kse_create; + kse_exit; + kse_release; + kse_switchin; + kse_thr_interrupt; + kse_wakeup; + 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; + msgctl; + msgget; + msgrcv; + msgsnd; + msgsys; + msync; + munlock; + munlockall; + munmap; + nanosleep; + netbsd_lchown; + netbsd_msync; + nfsclnt; + nfssvc; + nfstat; + nlstat; + nmount; + nstat; + ntp_adjtime; + ntp_gettime; + oaio_read; + oaio_write; + olio_listio; + open; + pathconf; + pipe; + poll; + preadv; + profil; + 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; + setcontext; + setegid; + seteuid; + setgid; + setgroups; + setitimer; + setlogin; + setpgid; + setpriority; + setregid; + setresgid; + setresuid; + setreuid; + setrlimit; + setsid; + setsockopt; + settimeofday; + setuid; + shmat; + shmctl; + shmdt; + shmget; + shmsys; + shutdown; + sigaction; + sigaltstack; + sigpending; + sigprocmask; + sigqueue; + sigreturn; + sigsuspend; + sigtimedwait; + sigwait; + sigwaitinfo; + socket; + socketpair; + __stack_chk_fail; + __stack_chk_guard; + stat; + statfs; + swapcontext; + swapoff; + swapon; + symlink; + sync; + sysarch; + syscall; + thr_create; + thr_exit; + thr_kill; + 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; +}; + +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_lock; + __sys__umtx_lock; + __umtx_op; + __sys__umtx_op; + __umtx_unlock; + __sys__umtx_unlock; + _abort2; + __sys_abort2; + _accept; + __sys_accept; + _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_getres; + __sys_clock_getres; + _clock_gettime; + __sys_clock_gettime; + _clock_settime; + __sys_clock_settime; + _close; + __sys_close; + _connect; + __sys_connect; + _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; + _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; + _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; + _kse_create; + __sys_kse_create; + _kse_exit; + __sys_kse_exit; + _kse_release; + __sys_kse_release; + _kse_switchin; + __sys_kse_switchin; + _kse_thr_interrupt; + __sys_kse_thr_interrupt; + _kse_wakeup; + __sys_kse_wakeup; + _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; + _nfsclnt; + __sys_nfsclnt; + _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; + _oaio_read; + __sys_oaio_read; + _oaio_write; + __sys_oaio_write; + _olio_listio; + __sys_olio_listio; + _open; + __sys_open; + _pathconf; + __sys_pathconf; + _pipe; + __sys_pipe; + _poll; + __sys_poll; + _preadv; + __sys_preadv; + _profil; + __sys_profil; + _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; + _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; + __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_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; + _write; + __sys_write; + _writev; + __sys_writev; + __error_unthreaded; +}; diff --git a/lib/libc/sys/__error.c b/lib/libc/sys/__error.c new file mode 100644 index 0000000..d7b5529 --- /dev/null +++ b/lib/libc/sys/__error.c @@ -0,0 +1,45 @@ +/* + * 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$"); + +extern int errno; + +/* + * Declare a weak reference in case the application is not linked + * with libpthread. + */ +__weak_reference(__error_unthreaded, __error); + +int * +__error_unthreaded() +{ + return(&errno); +} diff --git a/lib/libc/sys/_exit.2 b/lib/libc/sys/_exit.2 new file mode 100644 index 0000000..b35e7c4 --- /dev/null +++ b/lib/libc/sys/_exit.2 @@ -0,0 +1,123 @@ +.\" 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 June 4, 1993 +.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 1; the initialization process +inherits each of these processes +(see +.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/abort2.2 b/lib/libc/sys/abort2.2 new file mode 100644 index 0000000..4698c72 --- /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 phk@FreeBSD.org . +It was implemented by +.An "Wojciech A. Koszek" Aq dunstan@freebsd.czest.pl . diff --git a/lib/libc/sys/accept.2 b/lib/libc/sys/accept.2 new file mode 100644 index 0000000..7103cc1 --- /dev/null +++ b/lib/libc/sys/accept.2 @@ -0,0 +1,181 @@ +.\" 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 December 11, 1993 +.Dt ACCEPT 2 +.Os +.Sh NAME +.Nm accept +.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" +.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 +property from the original socket +.Fa s . +.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. +.Sh RETURN VALUES +The call returns \-1 on error. +If it succeeds, it returns a non-negative +integer that is a descriptor for the accepted socket. +.Sh ERRORS +The +.Fn accept +system call 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 EINVAL +The +.Fa addrlen +argument is negative. +.It Bq Er EFAULT +The +.Fa addr +argument is not in a writable part of the +user address space. +.It Bq Er EWOULDBLOCK +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 +.Sh SEE ALSO +.Xr bind 2 , +.Xr connect 2 , +.Xr getpeername 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 . diff --git a/lib/libc/sys/access.2 b/lib/libc/sys/access.2 new file mode 100644 index 0000000..e43e271 --- /dev/null +++ b/lib/libc/sys/access.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. +.\" +.\" @(#)access.2 8.2 (Berkeley) 4/1/94 +.\" $FreeBSD$ +.\" +.Dd September 21, 2001 +.Dt ACCESS 2 +.Os +.Sh NAME +.Nm access , eaccess +.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" +.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 +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 +Access to the file is denied 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 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 +.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. +.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 . +.Sh HISTORY +The +.Fn access +function appeared in +.At v7 . diff --git a/lib/libc/sys/acct.2 b/lib/libc/sys/acct.2 new file mode 100644 index 0000000..caf1aea --- /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 0000000..95cfca0 --- /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 0000000..08102cf --- /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 wes@softweyr.com . +.An Christopher M Sedore Aq 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 0000000..f63a2dd --- /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 wes@softweyr.com . diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 new file mode 100644 index 0000000..2c78040 --- /dev/null +++ b/lib/libc/sys/aio_read.2 @@ -0,0 +1,215 @@ +.\" 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 November 17, 1998 +.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. +.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. +For this reason, use of auto (stack) variables +for these objects is discouraged. +.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 after the request has been enqueued, but before the +request has completed, are not allowed. +.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 ENOSYS +The +.Fn aio_read +system call is not supported. +.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 . +.Pp +.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 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 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 0000000..2034f9d --- /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 October 7, 2006 +.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 int +.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 wes@softweyr.com . diff --git a/lib/libc/sys/aio_suspend.2 b/lib/libc/sys/aio_suspend.2 new file mode 100644 index 0000000..db704f1 --- /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 wes@softweyr.com . diff --git a/lib/libc/sys/aio_waitcomplete.2 b/lib/libc/sys/aio_waitcomplete.2 new file mode 100644 index 0000000..5145f78 --- /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 January 19, 2000 +.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 int +.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 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 0000000..dd1e0f5 --- /dev/null +++ b/lib/libc/sys/aio_write.2 @@ -0,0 +1,210 @@ +.\" 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_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. +.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. +For this reason, use of auto (stack) variables +for these objects is discouraged. +.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 after the request has been enqueued, but before the +request has completed, are not allowed. +.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 ENOSYS +The +.Fn aio_write +system call is not supported. +.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 . +.Pp +.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 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 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 0000000..bd51040 --- /dev/null +++ b/lib/libc/sys/bind.2 @@ -0,0 +1,131 @@ +.\" 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 June 4, 1993 +.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/types.h +.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 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 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/brk.2 b/lib/libc/sys/brk.2 new file mode 100644 index 0000000..31dea32 --- /dev/null +++ b/lib/libc/sys/brk.2 @@ -0,0 +1,171 @@ +.\" 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 July 12, 1999 +.Dt BRK 2 +.Os +.Sh NAME +.Nm brk , +.Nm sbrk +.Nd change data segment size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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/chdir.2 b/lib/libc/sys/chdir.2 new file mode 100644 index 0000000..33940c3 --- /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 0000000..7780427 --- /dev/null +++ b/lib/libc/sys/chflags.2 @@ -0,0 +1,227 @@ +.\" 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 May 16, 2006 +.Dt CHFLAGS 2 +.Os +.Sh NAME +.Nm chflags , +.Nm lchflags , +.Nm fchflags +.Nd set file flags +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/stat.h +.In unistd.h +.Ft int +.Fn chflags "const char *path" "u_long flags" +.Ft int +.Fn lchflags "const char *path" "int flags" +.Ft int +.Fn fchflags "int fd" "u_long flags" +.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 flags specified are formed by +.Em or Ns 'ing +the following values +.Pp +.Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent +.It Dv UF_NODUMP +Do not dump the file. +.It Dv UF_IMMUTABLE +The file may not be changed. +.It Dv UF_APPEND +The file may only be appended to. +.It Dv UF_NOUNLINK +The file may not be renamed or deleted. +.It Dv UF_OPAQUE +The directory is opaque when viewed through a union stack. +.It Dv SF_ARCHIVED +The file may be archived. +.It Dv SF_IMMUTABLE +The file may not be changed. +.It Dv SF_APPEND +The file may only be appended to. +.It Dv SF_NOUNLINK +The file may not be renamed or deleted. +.It Dv SF_SNAPSHOT +The file is a snapshot file. +.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 greater than 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 set these flags by non-super-users are rejected, attempts by +non-superusers to clear flags that are already unset are silently ignored. +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 +.Dv SF_SNAPSHOT +flag is maintained by the system and cannot be changed by any user. +.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 tries to set one of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK . +.It Bq Er EPERM +User tries to set or remove 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. +.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 tries to set one of +.Dv SF_IMMUTABLE , SF_APPEND , +or +.Dv SF_NOUNLINK . +.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. +.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 . diff --git a/lib/libc/sys/chmod.2 b/lib/libc/sys/chmod.2 new file mode 100644 index 0000000..185463d --- /dev/null +++ b/lib/libc/sys/chmod.2 @@ -0,0 +1,244 @@ +.\" 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 January 16, 2006 +.Dt CHMOD 2 +.Os +.Sh NAME +.Nm chmod , +.Nm fchmod , +.Nm lchmod +.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" +.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 +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 */ +#ifndef __BSD_VISIBLE +#define S_ISTXT 0001000 /* sticky bit */ +#endif +.Ed +.Pp +The +.Fx +VM system totally ignores the sticky bit +.Pq Dv ISTXT +for executables. +On UFS-based file systems (FFS, LFS) the sticky +bit may only be set upon directories. +.Pp +If mode +.Dv ISTXT +(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 8 . +.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 +.Sh SEE ALSO +.Xr chmod 1 , +.Xr chflags 2 , +.Xr chown 2 , +.Xr open 2 , +.Xr stat 2 , +.Xr sticky 8 +.Sh STANDARDS +The +.Fn chmod +system call is expected to conform to +.St -p1003.1-90 , +except for the return of +.Er EFTYPE +and the use of +.Dv S_ISTXT . +.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 . diff --git a/lib/libc/sys/chown.2 b/lib/libc/sys/chown.2 new file mode 100644 index 0000000..b95612e --- /dev/null +++ b/lib/libc/sys/chown.2 @@ -0,0 +1,184 @@ +.\" 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 December 9, 2006 +.Dt CHOWN 2 +.Os +.Sh NAME +.Nm chown , +.Nm fchown , +.Nm lchown +.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" +.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 +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 +.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 . +.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. diff --git a/lib/libc/sys/chroot.2 b/lib/libc/sys/chroot.2 new file mode 100644 index 0000000..ecf2eb5 --- /dev/null +++ b/lib/libc/sys/chroot.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. +.\" +.\" @(#)chroot.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.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 +.Pp +Upon successful completion, a value of 0 is returned. +Otherwise, +a value of -1 is returned and +.Va errno +is set to indicate an error. +.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 . +.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. diff --git a/lib/libc/sys/clock_gettime.2 b/lib/libc/sys/clock_gettime.2 new file mode 100644 index 0000000..39231b6 --- /dev/null +++ b/lib/libc/sys/clock_gettime.2 @@ -0,0 +1,136 @@ +.\" $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 November 4, 2006 +.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 +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 five values: +.Dv CLOCK_REALTIME +for time that increments as +a wall clock should, +.Dv CLOCK_MONOTONIC +which increments in SI seconds, +.Dv CLOCK_UPTIME +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, or +.Dv CLOCK_PROF +for time that increments when the CPU is running in user or +kernel mode. +.Pp +The structure pointed to by +.Fa tp +is defined in +.In sys/timespec.h +as: +.Pp +.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. +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 +argument +was not a valid value. +.It Bq Er EFAULT +The +.Fa *tp +argument address referenced invalid memory. +.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 . diff --git a/lib/libc/sys/close.2 b/lib/libc/sys/close.2 new file mode 100644 index 0000000..aef0379 --- /dev/null +++ b/lib/libc/sys/close.2 @@ -0,0 +1,139 @@ +.\" 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 December 4, 2006 +.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 d" +.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 d +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 +.Sh SEE ALSO +.Xr accept 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/connect.2 b/lib/libc/sys/connect.2 new file mode 100644 index 0000000..c673a83 --- /dev/null +++ b/lib/libc/sys/connect.2 @@ -0,0 +1,170 @@ +.\" 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 16, 2006 +.Dt CONNECT 2 +.Os +.Sh NAME +.Nm connect +.Nd initiate a connection on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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. +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 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 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. +.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/dup.2 b/lib/libc/sys/dup.2 new file mode 100644 index 0000000..c87b386 --- /dev/null +++ b/lib/libc/sys/dup.2 @@ -0,0 +1,162 @@ +.\" 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 4, 1993 +.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 value must be less +than the size of the table, which is returned by +.Xr getdtablesize 2 . +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 +The value -1 is returned if an error occurs in either call. +The external variable +.Va errno +indicates the cause of the error. +.Sh ERRORS +The +.Fn dup +and +.Fn dup2 +system calls fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa oldd +or +.Fa newd +argument +is not a valid active descriptor +.It Bq Er EMFILE +Too many descriptors are active. +.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 +.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 0000000..feac99b --- /dev/null +++ b/lib/libc/sys/execve.2 @@ -0,0 +1,306 @@ +.\" 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 June 1, 1994 +.Dt EXECVE 2 +.Os +.Sh NAME +.Nm execve +.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[]" +.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 . +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 sigvec 2 , +.Xr sigsetmask 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. +.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 ENAMETOOLONG +When invoking an interpreted script, the interpreter name +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 or reading 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 +.Sh CAVEAT +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. +.Sh SEE ALSO +.Xr ktrace 1 , +.Xr _exit 2 , +.Xr fork 2 , +.Xr execl 3 , +.Xr exit 3 , +.Xr sysctl 3 , +.Xr a.out 5 , +.Xr elf 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. +.Sh HISTORY +The +.Fn execve +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/extattr_get_file.2 b/lib/libc/sys/extattr_get_file.2 new file mode 100644 index 0000000..6fd2a18 --- /dev/null +++ b/lib/libc/sys/extattr_get_file.2 @@ -0,0 +1,269 @@ +.\" +.\" 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 February 23, 2005 +.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 int +.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 int +.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 int +.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 +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 , +and +.Fn extattr_delete_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 +and +.Fn extattr_set_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 +returns 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 , +and +.Fn extattr_delete_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 0000000..a476cff --- /dev/null +++ b/lib/libc/sys/fcntl.2 @@ -0,0 +1,582 @@ +.\" 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 January 12, 1994 +.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_GETOWNX +.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 associated with the new file descriptor +is set to remain open across +.Xr execve 2 +system calls. +.El +.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. +.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 */ +}; +.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 +field is only used with +.Dv F_GETLK +to return the process ID of the process holding a blocking lock. +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 +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_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_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 execve 2 , +.Xr flock 2 , +.Xr getdtablesize 2 , +.Xr open 2 , +.Xr sigvec 2 , +.Xr lockf 3 , +.Xr tcgetpgrp 3 , +.Xr tcsetpgrp 3 +.Sh HISTORY +The +.Fn fcntl +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/fhopen.2 b/lib/libc/sys/fhopen.2 new file mode 100644 index 0000000..2a609c1 --- /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 0000000..5ee93ba --- /dev/null +++ b/lib/libc/sys/flock.2 @@ -0,0 +1,170 @@ +.\" 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 December 11, 1993 +.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. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr execve 2 , +.Xr fcntl 2 , +.Xr fork 2 , +.Xr open 2 , +.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 0000000..4a8a646 --- /dev/null +++ b/lib/libc/sys/fork.2 @@ -0,0 +1,134 @@ +.\" 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 June 4, 1993 +.Dt FORK 2 +.Os +.Sh NAME +.Nm fork +.Nd create a new process +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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. +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 . +.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 vfork 2 , +.Xr wait 2 +.Sh HISTORY +The +.Fn fork +function appeared in +.At v6 . diff --git a/lib/libc/sys/fsync.2 b/lib/libc/sys/fsync.2 new file mode 100644 index 0000000..7bdc487 --- /dev/null +++ b/lib/libc/sys/fsync.2 @@ -0,0 +1,87 @@ +.\" 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. +.\" +.\" @(#)fsync.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt FSYNC 2 +.Os +.Sh NAME +.Nm fsync +.Nd "synchronise changes to a file" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn fsync "int fd" +.Sh DESCRIPTION +The +.Fn fsync +system call +causes all modified data and attributes of +.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 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. +.Sh RETURN VALUES +.Rv -std fsync +.Sh ERRORS +The +.Fn fsync +fails 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 . diff --git a/lib/libc/sys/ftruncate.c b/lib/libc/sys/ftruncate.c new file mode 100644 index 0000000..fcd2ef8 --- /dev/null +++ b/lib/libc/sys/ftruncate.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 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. + */ + +#if defined(LIBC_SCCS) && !defined(lint) +static char sccsid[] = "@(#)ftruncate.c 8.1 (Berkeley) 6/17/93"; +#endif /* LIBC_SCCS and not lint */ +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <unistd.h> + +/* + * This function provides 64-bit offset padding that + * is not supplied by GCC 1.X but is supplied by GCC 2.X. + */ +int +ftruncate(fd, length) + int fd; + off_t length; +{ + + return(__syscall((quad_t)SYS_ftruncate, fd, 0, length)); +} diff --git a/lib/libc/sys/getdirentries.2 b/lib/libc/sys/getdirentries.2 new file mode 100644 index 0000000..e16e7f2 --- /dev/null +++ b/lib/libc/sys/getdirentries.2 @@ -0,0 +1,185 @@ +.\" 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 +u_int32_t d_fileno; +u_int16_t d_reclen; +u_int8_t d_type; +u_int8_t d_namlen; +char d_name[MAXNAMELEN + 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 MAXNAMELEN +\&+ 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 +.Fn ( getdirentries +only) +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 0000000..916b91e --- /dev/null +++ b/lib/libc/sys/getdtablesize.2 @@ -0,0 +1,60 @@ +.\" 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 June 4, 1993 +.Dt GETDTABLESIZE 2 +.Os +.Sh NAME +.Nm getdtablesize +.Nd get descriptor table size +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn getdtablesize void +.Sh DESCRIPTION +Each process has a fixed size descriptor table, +which is guaranteed to have at least 20 slots. +The entries in +the descriptor table are numbered with small integers starting at 0. +The +.Fn getdtablesize +system call returns the size of this table. +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr open 2 , +.Xr select 2 +.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 0000000..1488196 --- /dev/null +++ b/lib/libc/sys/getfh.2 @@ -0,0 +1,111 @@ +.\" 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 6, 2004 +.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 lgetfgh +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 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 0000000..c27c6c2 --- /dev/null +++ b/lib/libc/sys/getfsstat.2 @@ -0,0 +1,122 @@ +.\" 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 November 20, 2003 +.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 flags" +.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 flags +should be specified as +.Dv MNT_WAIT . +If +.Fa flags +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. +.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 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 0000000..b03040b --- /dev/null +++ b/lib/libc/sys/getgid.2 @@ -0,0 +1,81 @@ +.\" 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 June 4, 1993 +.Dt GETGID 2 +.Os +.Sh NAME +.Nm getgid , +.Nm getegid +.Nd get group process identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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 0000000..5eadfe1 --- /dev/null +++ b/lib/libc/sys/getgroups.2 @@ -0,0 +1,99 @@ +.\" 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 March 5, 1999 +.Dt GETGROUPS 2 +.Os +.Sh NAME +.Nm getgroups +.Nd get group access list +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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 . +No more than +.Dv NGROUPS_MAX +will ever +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 . +.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 +.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 0000000..260f8f0 --- /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 sigvec 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 0000000..b7c27df --- /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/getpeername.2 b/lib/libc/sys/getpeername.2 new file mode 100644 index 0000000..9037119 --- /dev/null +++ b/lib/libc/sys/getpeername.2 @@ -0,0 +1,94 @@ +.\" 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 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 0000000..f5e81a8 --- /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 0000000..aefa770 --- /dev/null +++ b/lib/libc/sys/getpid.2 @@ -0,0 +1,91 @@ +.\" 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 November 2, 2006 +.Dt GETPID 2 +.Os +.Sh NAME +.Nm getpid , +.Nm getppid +.Nd get parent or calling process identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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 0000000..28d1f14 --- /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 +.Bl -tag -width Er +In addition to the errors indicated above, +.Fn setpriority +will fail if: +.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 0000000..93d91f6 --- /dev/null +++ b/lib/libc/sys/getrlimit.2 @@ -0,0 +1,192 @@ +.\" 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 June 13, 2004 +.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_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_RSS +The maximum size (in bytes) to which a process's resident set size may +grow. +This imposes a limit on the amount of physical memory to be given to +a process; if memory is tight, the system will prefer to take memory +from processes that are exceeding their declared resident set size. +.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. +.El +.Pp +A resource limit is specified as a soft limit and a hard limit. +When a +soft limit is exceeded a process may receive a signal (for example, if +the cpu time or file size is exceeded), but it will be allowed to +continue execution until it reaches the hard limit (or modifies +its resource limit). +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 signal +.Dv SIGXCPU +is sent to the +offending process. +.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 sigaltstack 2 , +.Xr sigvec 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 0000000..bdf5d45 --- /dev/null +++ b/lib/libc/sys/getrusage.2 @@ -0,0 +1,180 @@ +.\" 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 June 4, 1993 +.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" +.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 +process, or all its terminated child processes. +The +.Fa who +argument is either +.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 . +.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 0000000..8d31074 --- /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 0000000..f1537c7 --- /dev/null +++ b/lib/libc/sys/getsockname.2 @@ -0,0 +1,94 @@ +.\" 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 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 0000000..3ea34c9 --- /dev/null +++ b/lib/libc/sys/getsockopt.2 @@ -0,0 +1,478 @@ +.\" 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 March 8, 2007 +.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. +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_ERROR Ta "get and clear error on the socket (get only)" +.El +.Pp +.Dv SO_DEBUG +enables debugging in the underlying protocol modules. +.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. +.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. +.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. +.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. +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. +.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. +.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. +.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_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: +.Bd -literal + cmsg_len = sizeof(struct timeval); + cmsg_level = SOL_SOCKET; + cmsg_type = SCM_TIMESTAMP; +.Ed +.Pp +and for +.Dv SO_BINTIME : +.Bd -literal + cmsg_len = sizeof(struct bintime); + cmsg_level = SOL_SOCKET; + cmsg_type = SCM_BINTIME; +.Ed +.Pp +Finally, +.Dv SO_ACCEPTCONN , +.Dv SO_TYPE +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_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. +.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 sysctl 3 , +.Xr protocols 5 , +.Xr sysctl 8 , +.Xr accept_filter 9 , +.Xr bintime 9 +.Sh HISTORY +The +.Fn getsockopt +system call 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 0000000..9ffd0b3 --- /dev/null +++ b/lib/libc/sys/gettimeofday.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. +.\" +.\" @(#)gettimeofday.2 8.2 (Berkeley) 5/26/95 +.\" $FreeBSD$ +.\" +.Dd May 26, 1995 +.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: +.Pp +.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 EFAULT +An argument address referenced invalid memory. +.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/getuid.2 b/lib/libc/sys/getuid.2 new file mode 100644 index 0000000..eae0b23 --- /dev/null +++ b/lib/libc/sys/getuid.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. +.\" +.\" @(#)getuid.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt GETUID 2 +.Os +.Sh NAME +.Nm getuid , +.Nm geteuid +.Nd get user identification +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.In sys/types.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/intro.2 b/lib/libc/sys/intro.2 new file mode 100644 index 0000000..7338f8b --- /dev/null +++ b/lib/libc/sys/intro.2 @@ -0,0 +1,735 @@ +.\" 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 February 27, 1995 +.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). +.Pp +.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 file descriptors allowable on the system +has been reached and a requests for an open cannot be satisfied +until at least one has been closed. +.It Er 24 EMFILE Em "Too many open files" . +(As released, the limit on the number of +open files per process is 64.) +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. +.Pp +.It Er 49 EADDRNOTAVAIL Em "Cannot 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 "Cannot 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. +.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 a system process, +.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 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 0000000..02da906 --- /dev/null +++ b/lib/libc/sys/ioctl.2 @@ -0,0 +1,133 @@ +.\" 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 December 11, 1993 +.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 d" "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 d +must be an open file descriptor. +.Pp +The third argument to +.Fn ioctl +is traditionally named +.Va "char *argp" . +Most uses of +.Fn ioctl +in +.Fx 3.0 , +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 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 d +argument +is not a valid descriptor. +.It Bq Er ENOTTY +The +.Fa d +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 d +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 0000000..aed5062 --- /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 0000000..5cba4bf --- /dev/null +++ b/lib/libc/sys/jail.2 @@ -0,0 +1,142 @@ +.\" +.\" ---------------------------------------------------------------------------- +.\" "THE BEER-WARE LICENSE" (Revision 42): +.\" <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you +.\" can do whatever you want with this stuff. If we meet some day, and you think +.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp +.\" ---------------------------------------------------------------------------- +.\" +.\" $FreeBSD$ +.\" +.Dd April 8, 2003 +.Dt JAIL 2 +.Os +.Sh NAME +.Nm jail , jail_attach +.Nd imprison current process and future descendants +.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" +.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 { + u_int32_t version; + char *path; + char *hostname; + u_int32_t ip_number; +}; +.Ed +.Pp +.Dq Li version +defines the version of the API in use. +It should be set to zero at this time. +.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 ip_number +can be set to the IP number assigned to the prison. +.Pp +The +.Fn jail_attach +system call attaches the current process to an existing jail, +identified by +.Fa jid . +.Sh RETURN VALUES +If successful, +.Fn jail +returns a non-negative integer, termed the jail identifier (JID). +It returns \-1 on failure, and sets +.Va errno +to indicate the error. +.Pp +.Rv -std jail_attach +.Sh PRISON? +Once a process has been put in a prison, it and its descendants cannot escape +the prison. +.Pp +Inside the prison, the concept of +.Dq superuser +is very diluted. +In general, +it can be assumed that nothing can be mangled from inside a prison which +does not exist entirely inside that prison. +For instance the directory +tree below +.Dq Li path +can be manipulated all the ways a root can normally do it, including +.Dq Li "rm -rf /*" +but new device special nodes cannot be created because they reference +shared resources (the device drivers in the kernel). +The effective +.Dq securelevel +for a process is the greater of the global +.Dq securelevel +or, if present, the per-jail +.Dq securelevel . +.Pp +All IP activity will be forced to happen to/from the IP number specified, +which should be an alias on one of the network interfaces. +.Pp +It is possible to identify a process as jailed by examining +.Dq Li /proc/<pid>/status : +it will show a field near the end of the line, either as +a single hyphen for a process at large, or the hostname currently +set for the prison for jailed processes. +.Sh ERRORS +The +.Fn jail +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The version number of the argument is not correct. +.El +.Pp +Further +.Fn jail +calls +.Xr chroot 2 +internally, so it 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 +.Sh HISTORY +The +.Fn jail +system call appeared in +.Fx 4.0 . +The +.Fn jail_attach +system call appeared in +.Fx 5.1 . +.Sh AUTHORS +The jail feature was written by +.An Poul-Henning Kamp +for R&D Associates +.Dq Li http://www.rndassociates.com/ +who contributed it to +.Fx . diff --git a/lib/libc/sys/kenv.2 b/lib/libc/sys/kenv.2 new file mode 100644 index 0000000..866c0d38 --- /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 davidc@FreeBSD.org . +.Pp +The +.Fn kenv +system call was written by +.An Maxime Henrion Aq mux@FreeBSD.org . diff --git a/lib/libc/sys/kill.2 b/lib/libc/sys/kill.2 new file mode 100644 index 0000000..d46dc1f --- /dev/null +++ b/lib/libc/sys/kill.2 @@ -0,0 +1,151 @@ +.\" 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 April 19, 1994 +.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 real or effective user ID of the receiving process must match +that of the sending process or the user must have appropriate privileges +(such as given by a set-user-ID program or the user is the super-user). +A single exception is the signal SIGCONT, which may always be sent +to any process with the same session ID as the caller. +.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 can be found corresponding to that specified by +.Fa pid . +.It Bq Er ESRCH +The process id was given as 0 +but the sending process does not have a process group. +.It Bq Er EPERM +The sending process is not the super-user and its effective +user id does not match the effective user-id of the receiving process. +When signaling a process group, this error is returned if any members +of the group could not be signaled. +.El +.Sh SEE ALSO +.Xr getpgrp 2 , +.Xr getpid 2 , +.Xr killpg 2 , +.Xr sigaction 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 0000000..a8892ed --- /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 0000000..d9967cc --- /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 0000000..d31cc08 --- /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 0000000..c856a2e --- /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 0000000..946417a --- /dev/null +++ b/lib/libc/sys/kldstat.2 @@ -0,0 +1,125 @@ +.\" +.\" 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 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(linker_file_stat) */ + char name[MAXPATHLEN]; + int refs; + int id; + caddr_t address; /* load address */ + size_t size; /* size in bytes */ +}; +.Ed +.Pp +.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 size of the file. +.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 . diff --git a/lib/libc/sys/kldsym.2 b/lib/libc/sys/kldsym.2 new file mode 100644 index 0000000..acd6fcd --- /dev/null +++ b/lib/libc/sys/kldsym.2 @@ -0,0 +1,122 @@ +.\" 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 July 26, 2001 +.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 command" "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 command +implemented is +.Dv KLDSYM_LOOKUP . +.Pp +The +.Fa data +argument is of the following structure: +.Pp +.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 command . +.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 0000000..ef6282b --- /dev/null +++ b/lib/libc/sys/kldunload.2 @@ -0,0 +1,78 @@ +.\" +.\" 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 KLDUNLOAD 2 +.Os +.Sh NAME +.Nm kldunload +.Nd unload kld files +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/param.h +.In sys/linker.h +.Ft int +.Fn kldunload "int fileid" +.Sh DESCRIPTION +The +.Fn kldunload +system call +unloads a kld file from the kernel that was previously linked via +.Xr kldload 2 . +.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. +.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 0000000..3466422 --- /dev/null +++ b/lib/libc/sys/kqueue.2 @@ -0,0 +1,560 @@ +.\" 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 August 25, 2006 +.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 XXXfilter +.It ident +Value used to identify this event. +The exact interpretation is determined by the attached filter, +but often is a file descriptor. +.It filter +Identifies the kernel filter used to process this event. +The pre-defined +system filters are described below. +.It flags +Actions to perform on the event. +.It fflags +Filter-specific flags. +.It data +Filter-specific data value. +.It udata +Opaque user-defined value passed through the kernel unchanged. +.El +.Pp +The +.Va flags +field can contain the following values: +.Bl -tag -width XXXEV_ONESHOT +.It 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 EV_ENABLE +Permit +.Fn kevent +to return the event if it is triggered. +.It EV_DISABLE +Disable the event so +.Fn kevent +will not return it. +The filter itself is not disabled. +.It 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 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 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 EV_EOF +Filters may set this flag to indicate filter-specific EOF condition. +.It 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 EVFILT_SIGNAL +.It 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. +.Pp +.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 +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 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. +.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 EV_EOF in +.Va flags . +This may be cleared by passing in 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 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 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 EVFILT_READ case. +.It 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_value +containing the udata value, and +.Va sigev_notify +set to 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 aio_error. +.It 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 XXNOTE_RENAME +.It NOTE_DELETE +The +.Fn unlink +system call +was called on the file referenced by the descriptor. +.It NOTE_WRITE +A write occurred on the file referenced by the descriptor. +.It NOTE_EXTEND +The file referenced by the descriptor was extended. +.It NOTE_ATTRIB +The file referenced by the descriptor had its attributes changed. +.It NOTE_LINK +The link count on the file changed. +.It NOTE_RENAME +The file referenced by the descriptor was renamed. +.It NOTE_REVOKE +Access to the file was revoked via +.Xr revoke 2 +or the underlying file system was unmounted. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It 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 XXNOTE_TRACKERR +.It NOTE_EXIT +The process has exited. +The exit status will be stored in +.Va data . +.It NOTE_FORK +The process has called +.Fn fork . +.It NOTE_EXEC +The process has executed a new process via +.Xr execve 2 +or similar call. +.It NOTE_TRACK +Follow a process across +.Fn fork +calls. +The parent process will return with NOTE_TRACK set in the +.Va fflags +field, while the child process will return with NOTE_CHILD set in +.Va fflags +and the parent PID in +.Va data . +.It NOTE_TRACKERR +This flag is returned if the system was unable to attach an event to +the child process, usually due to resource limitations. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.It 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 SIG_IGN. +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 EV_CLEAR flag internally. +.It EVFILT_TIMER +Establishes an arbitrary timer identified by +.Va ident . +When adding a timer, +.Va data +specifies the timeout period in milliseconds. +The timer will be periodic unless 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. +.It Dv EVFILT_NETDEV +Takes a descriptor to a network interface as the identifier, and the events to watch for in +.Va fflags . +It returns, when one or more of the requested events occur on the descriptor. +The events to monitor are: +.Bl -tag -width XXNOTE_LINKDOWN +.It Dv NOTE_LINKUP +The link is up. +.It Dv NOTE_LINKDOWN +The link is down. +.It Dv NOTE_LINKINV +The link state is invalid. +.El +.Pp +On return, +.Va fflags +contains the events which triggered the filter. +.El +.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 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 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 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 +.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 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 jlemon@FreeBSD.org . +.Sh BUGS +It is currently not possible to watch a +.Xr vnode 9 +that resides on anything but +a UFS file system. +.Pp +The +.Dv EVFILT_NETDEV +filter is currently only implemented for devices that use the +.Xr miibus 4 +driver for LINKUP and LINKDOWN operations. +Therefore, it will not work with many non-ethernet devices. +.Pp +The +.Fa timeout +value is limited to 24 hours; longer timeouts will be silently +reinterpreted as 24 hours. diff --git a/lib/libc/sys/kse.2 b/lib/libc/sys/kse.2 new file mode 100644 index 0000000..92c1de2 --- /dev/null +++ b/lib/libc/sys/kse.2 @@ -0,0 +1,679 @@ +.\" Copyright (c) 2002 Packet Design, LLC. +.\" All rights reserved. +.\" +.\" Subject to the following obligations and disclaimer of warranty, +.\" use and redistribution of this software, in source or object code +.\" forms, with or without modifications are expressly permitted by +.\" Packet Design; provided, however, that: +.\" +.\" (i) Any and all reproductions of the source or object code +.\" must include the copyright notice above and the following +.\" disclaimer of warranties; and +.\" (ii) No rights are granted, in any manner or form, to use +.\" Packet Design trademarks, including the mark "PACKET DESIGN" +.\" on advertising, endorsements, or otherwise except as such +.\" appears in the above copyright notice or in the software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND +.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO +.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING +.\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED +.\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, +.\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, +.\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS +.\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, +.\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE +.\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE +.\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, +.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL +.\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF +.\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 13, 2007 +.Dt KSE 2 +.Os +.Sh NAME +.Nm kse +.Nd "kernel support for user threads" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/kse.h +.Ft int +.Fn kse_create "struct kse_mailbox *mbx" "int sys-scope" +.Ft int +.Fn kse_exit void +.Ft int +.Fn kse_release "struct timespec *timeout" +.Ft int +.Fn kse_switchin "struct kse_thr_mailbox *tmbx" "int flags" +.Ft int +.Fn kse_thr_interrupt "struct kse_thr_mailbox *tmbx" "int cmd" "long data" +.Ft int +.Fn kse_wakeup "struct kse_mailbox *mbx" +.Sh DESCRIPTION +These system calls implement kernel support for multi-threaded processes. +.\" +.Ss Overview +.\" +Traditionally, user threading has been implemented in one of two ways: +either all threads are managed in user space and the kernel is unaware +of any threading (also known as +.Dq "N to 1" ) , +or else separate processes sharing +a common memory space are created for each thread (also known as +.Dq "N to N" ) . +These approaches have advantages and disadvantages: +.Bl -column "- Cannot utilize multiple CPUs" "+ Can utilize multiple CPUs" +.It Sy "User threading Kernel threading" +.It "+ Lightweight - Heavyweight" +.It "+ User controls scheduling - Kernel controls scheduling" +.It "- Syscalls must be wrapped + No syscall wrapping required" +.It "- Cannot utilize multiple CPUs + Can utilize multiple CPUs" +.El +.Pp +The KSE system is a +hybrid approach that achieves the advantages of both the user and kernel +threading approaches. +The underlying philosophy of the KSE system is to give kernel support +for user threading without taking away any of the user threading library's +ability to make scheduling decisions. +A kernel-to-user upcall mechanism is used to pass control to the user +threading library whenever a scheduling decision needs to be made. +An arbitrarily number of user threads are multiplexed onto a fixed number of +virtual CPUs supplied by the kernel. +This can be thought of as an +.Dq "N to M" +threading scheme. +.Pp +Some general implications of this approach include: +.Bl -bullet +.It +The user process can run multiple threads simultaneously on multi-processor +machines. +The kernel grants the process virtual CPUs to schedule as it +wishes; these may run concurrently on real CPUs. +.It +All operations that block in the kernel become asynchronous, allowing +the user process to schedule another thread when any thread blocks. +.El +.\" +.Ss Definitions +.\" +KSE allows a user process to have multiple +.Sy threads +of execution in existence at the same time, some of which may be blocked +in the kernel while others may be executing or blocked in user space. +A +.Sy "kernel scheduling entity" +(KSE) is a +.Dq "virtual CPU" +granted to the process for the purpose of executing threads. +A thread that is currently executing is always associated with +exactly one KSE, whether executing in user space or in the kernel. +The KSE is said to be +.Sy assigned +to the thread. +KSEs (a user abstraction) are implemented on top +of kernel threads using an 'upcall' entity. +.Pp +The KSE becomes +.Sy unassigned , +and the associated thread is suspended, when the KSE has an associated +.Sy mailbox , +(see below) the thread has an associated +.Sy thread mailbox , +(also see below) and any of the following occurs: +.Bl -bullet +.It +The thread invokes a system call that blocks. +.It +The thread makes any other demand of the kernel that cannot be immediately +satisfied, e.g., touches a page of memory that needs to be fetched from disk, +causing a page fault. +.It +Another thread that was previously blocked in the kernel completes its +work in the kernel (or is +.Sy interrupted ) +and becomes ready to return to user space, and the current thread is returning +to user space. +.It +A signal is delivered to the process, and this KSE is chosen to deliver it. +.El +.Pp +In other words, as soon as there is a scheduling decision to be made, +the KSE becomes unassigned, because the kernel does not presume to know +how the process' other runnable threads should be scheduled. +Unassigned KSEs always return to user space as soon as possible via +the +.Sy upcall +mechanism (described below), allowing the user process to decide how +that KSE should be utilized next. +KSEs always complete as much work as possible in the kernel before +becoming unassigned. +.Pp +Individual KSEs within a process are effectively indistinguishable, +and any KSE in a process may be assigned by the kernel to any runnable +(in the kernel) thread associated with that process. +In practice, the kernel attempts to preserve the affinity between threads +and actual CPUs to optimize cache behavior, but this is invisible to the +user process. +(Affinity is not yet fully implemented.) +.Pp +Each KSE has a unique +.Sy "KSE mailbox" +supplied by the user process. +A mailbox consists of a control structure containing a pointer to an +.Sy "upcall function" +and a user stack. +The KSE invokes this function whenever it becomes unassigned. +The kernel updates this structure with information about threads that have +become runnable and signals that have been delivered before each upcall. +Upcalls may be temporarily blocked by the user thread scheduling code +during critical sections. +.Pp +Each user thread has a unique +.Sy "thread mailbox" +as well. +Threads are referred to using pointers to these mailboxes when communicating +between the kernel and the user thread scheduler. +Each KSE's mailbox contains a pointer to the mailbox of the user thread +that the KSE is currently executing. +This pointer is saved when the thread blocks in the kernel. +.Pp +Whenever a thread blocked in the kernel is ready to return to user space, +it is added to the process's list of +.Sy completed +threads. +This list is presented to the user code at the next upcall as a linked list +of thread mailboxes. +.Pp +There is a kernel-imposed limit on the number of threads in a process +that may be simultaneously blocked in the kernel (this number is not +currently visible to the user). +When this limit is reached, upcalls are blocked and no work is performed +for the process until one of the threads completes (or a signal is +received). +.\" +.Ss Managing KSEs +.\" +To become multi-threaded, a process must first invoke +.Fn kse_create . +The +.Fn kse_create +system call +creates a new KSE (except for the very first invocation; see below). +The KSE will be associated with the mailbox pointed to by +.Fa mbx . +If +.Fa sys_scope +is non-zero, then the new thread will be counted as a system scope +thread. Other things must be done as well to make a system scope thread +so this is not sufficient (yet). +System scope variables are not covered +in detail in this manual page yet, but briefly, they never perform +upcalls and do not return to the user thread scheduler. +Once launched they run autonomously. +The pthreads library knows how to make system +scope threads and users are encouraged to use the library interface. +.Pp +Each process initially has a single KSE executing a single user thread. +Since the KSE does not have an associated mailbox, it must remain assigned +to the thread and does not perform any upcalls. +(It is by definition a system scope thread). +The result is the traditional, unthreaded mode of operation. +Therefore, as a special case, the first call to +.Fn kse_create +by this initial thread with +.Fa sys_scope +equal to zero does not create a new KSE; instead, it simply associates the +current KSE with the supplied KSE mailbox, and no immediate upcall results. +However, an upcall will be triggered the next time the thread blocks and +the required conditions are met. +.Pp +The kernel does not allow more KSEs to exist in a process than the +number of physical CPUs in the system (this number is available as the +.Xr sysctl 3 +variable +.Va hw.ncpu ) . +Having more KSEs than CPUs would not add any value to the user process, +as the additional KSEs would just compete with each other for access to +the real CPUs. +Since the extra KSEs would always be side-lined, the result +to the application would be exactly the same as having fewer KSEs. +There may however be arbitrarily many user threads, and it is up to the +user thread scheduler to handle mapping the application's user threads +onto the available KSEs. +.Pp +The +.Fn kse_exit +system call +causes the KSE assigned to the currently running thread to be destroyed. +If this KSE is the last one in the process, there must be no remaining +threads associated with that process blocked in the kernel. +This system call does not return unless there is an error. +Calling +.Fn kse_exit +from the last thread is the same as calling +.Fn exit . +.Pp +The +.Fn kse_release +system call +is used to +.Dq park +the KSE assigned to the currently running thread when it is not needed, +e.g., when there are more available KSEs than runnable user threads. +The thread converts to an upcall but does not get scheduled until +there is a new reason to do so, e.g., a previously +blocked thread becomes runnable, or the timeout expires. +If successful, +.Fn kse_release +does not return to the caller. +.Pp +The +.Fn kse_switchin +system call can be used by the UTS, when it has selected a new thread, +to switch to the context of that thread. +The use of +.Fn kse_switchin +is machine dependent. +Some platforms do not need a system call to switch to a new context, +while others require its use in particular cases. +.Pp +The +.Fn kse_wakeup +system call +is the opposite of +.Fn kse_release . +It causes the (parked) KSE associated with the mailbox pointed to by +.Fa mbx +to be woken up, causing it to upcall. +If the KSE has already woken up for another reason, this system call has no +effect. +The +.Fa mbx +argument +may be +.Dv NULL +to specify +.Dq "any KSE in the current process" . +.Pp +The +.Fn kse_thr_interrupt +system call +is used to interrupt a currently blocked thread. +The thread must either be blocked in the kernel or assigned to a KSE +(i.e., executing). +The thread is then marked as interrupted. +As soon as the thread invokes an interruptible system call (or immediately +for threads already blocked in one), the thread will be made runnable again, +even though the kernel operation may not have completed. +The effect on the interrupted system call is the same as if it had been +interrupted by a signal; typically this means an error is returned with +.Va errno +set to +.Er EINTR . +.\" +.Ss Signals +.\" +The current implementation creates a special signal thread. +Kernel threads (KSEs) in a process mask all signals, and only the signal +thread waits for signals to be delivered to the process, the signal thread +is responsible +for dispatching signals to user threads. +.Pp +A downside of this is that if a multiplexed thread +calls the +.Fn execve +syscall, its signal mask and pending signals may not be +available in the kernel. +They are stored +in userland and the kernel does not know where to get them, however +.Tn POSIX +requires them to be restored and passed them to new process. +Just setting the mask for the thread before calling +.Fn execve +is only a +close approximation to the problem as it does not re-deliver back to the kernel +any pending signals that the old process may have blocked, and it allows a +window in which new signals may be delivered to the process between the setting +of the mask and the +.Fn execve . +.Pp +For now this problem has been solved by adding a special combined +.Fn kse_thr_interrupt Ns / Ns Fn execve +mode to the +.Fn kse_thr_interrupt +syscall. +The +.Fn kse_thr_interrupt +syscall has a sub command +.Dv KSE_INTR_EXECVE , +that allows it to accept a +.Vt kse_execv_args +structure, and allowing it to adjust the signals and then atomically +convert into an +.Fn execve +call. +Additional pending signals and the correct signal mask can be passed +to the kernel in this way. +The thread library overrides the +.Fn execve +syscall +and translates it into +.Fn kse_intr_interrupt +call, allowing a multiplexed thread +to restore pending signals and the correct signal mask before doing the +.Fn exec . +This solution to the problem may change. +.\" +.Ss KSE Mailboxes +.\" +Each KSE has a unique mailbox for user-kernel communication defined in +.In sys/kse.h . +Some of the fields there are: +.Pp +.Va km_version +describes the version of this structure and must be equal to +.Dv KSE_VER_0 . +.Va km_udata +is an opaque pointer ignored by the kernel. +.Pp +.Va km_func +points to the KSE's upcall function; +it will be invoked using +.Va km_stack , +which must remain valid for the lifetime of the KSE. +.Pp +.Va km_curthread +always points to the thread that is currently assigned to this KSE if any, +or +.Dv NULL +otherwise. +This field is modified by both the kernel and the user process as follows. +.Pp +When +.Va km_curthread +is not +.Dv NULL , +it is assumed to be pointing at the mailbox for the currently executing +thread, and the KSE may be unassigned, e.g., if the thread blocks in the +kernel. +The kernel will then save the contents of +.Va km_curthread +with the blocked thread, set +.Va km_curthread +to +.Dv NULL , +and upcall to invoke +.Fn km_func . +.Pp +When +.Va km_curthread +is +.Dv NULL , +the kernel will never perform any upcalls with this KSE; in other words, +the KSE remains assigned to the thread even if it blocks. +.Va km_curthread +must be +.Dv NULL +while the KSE is executing critical user thread scheduler +code that would be disrupted by an intervening upcall; +in particular, while +.Fn km_func +itself is executing. +.Pp +Before invoking +.Fn km_func +in any upcall, the kernel always sets +.Va km_curthread +to +.Dv NULL . +Once the user thread scheduler has chosen a new thread to run, +it should point +.Va km_curthread +at the thread's mailbox, re-enabling upcalls, and then resume the thread. +.Em Note : +modification of +.Va km_curthread +by the user thread scheduler must be atomic +with the loading of the context of the new thread, to avoid +the situation where the thread context area +may be modified by a blocking async operation, while there +is still valid information to be read out of it. +.Pp +.Va km_completed +points to a linked list of user threads that have completed their work +in the kernel since the last upcall. +The user thread scheduler should put these threads back into its +own runnable queue. +Each thread in a process that completes a kernel operation +(synchronous or asynchronous) that results in an upcall is guaranteed to be +linked into exactly one KSE's +.Va km_completed +list; which KSE in the group, however, is indeterminate. +Furthermore, the completion will be reported in only one upcall. +.Pp +.Va km_sigscaught +contains the list of signals caught by this process since the previous +upcall to any KSE in the process. +As long as there exists one or more KSEs with an associated mailbox in +the user process, signals are delivered this way rather than the +traditional way. +(This has not been implemented and may change.) +.Pp +.Va km_timeofday +is set by the kernel to the current system time before performing +each upcall. +.Pp +.Va km_flags +may contain any of the following bits OR'ed together: +.Bl -tag -width indent +.It Dv KMF_NOUPCALL +Block upcalls from happening. +The thread is in some critical section. +.It Dv KMF_NOCOMPLETED , KMF_DONE , KMF_BOUND +This thread should be considered to be permanently bound to +its KSE, and treated much like a non-threaded process would be. +It is a +.Dq "long term" +version of +.Dv KMF_NOUPCALL +in some ways. +.It Dv KMF_WAITSIGEVENT +Implement characteristics needed for the signal delivery thread. +.El +.\" +.Ss Thread Mailboxes +.\" +Each user thread must have associated with it a unique +.Vt "struct kse_thr_mailbox" +as defined in +.In sys/kse.h . +It includes the following fields. +.Pp +.Va tm_udata +is an opaque pointer ignored by the kernel. +.Pp +.Va tm_context +stores the context for the thread when the thread is blocked in user space. +This field is also updated by the kernel before a completed thread is returned +to the user thread scheduler via +.Va km_completed . +.Pp +.Va tm_next +links the +.Va km_completed +threads together when returned by the kernel with an upcall. +The end of the list is marked with a +.Dv NULL +pointer. +.Pp +.Va tm_uticks +and +.Va tm_sticks +are time counters for user mode and kernel mode execution, respectively. +These counters count ticks of the statistics clock (see +.Xr clocks 7 ) . +While any thread is actively executing in the kernel, the corresponding +.Va tm_sticks +counter is incremented. +While any KSE is executing in user space and that KSE's +.Va km_curthread +pointer is not equal to +.Dv NULL , +the corresponding +.Va tm_uticks +counter is incremented. +.Pp +.Va tm_flags +may contain any of the following bits OR'ed together: +.Bl -tag -width indent +.It Dv TMF_NOUPCALL +Similar to +.Dv KMF_NOUPCALL . +This flag inhibits upcalling for critical sections. +Some architectures require this to be in one place and some in the other. +.El +.Sh RETURN VALUES +The +.Fn kse_create , +.Fn kse_wakeup , +and +.Fn kse_thr_interrupt +system calls +return zero if successful. +The +.Fn kse_exit +and +.Fn kse_release +system calls +do not return if successful. +.Pp +All of these system calls return a non-zero error code in case of an error. +.Sh ERRORS +The +.Fn kse_create +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ENXIO +There are already as many KSEs in the process as hardware processors. +.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 EFAULT +The +.Fa mbx +argument +points to an address which is not a valid part of the process address space. +.El +.Pp +The +.Fn kse_exit +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The current KSE is the last in its process and there are still one or more +threads associated with the process blocked in the kernel. +.It Bq Er ESRCH +The current KSE has no associated mailbox, i.e., the process is operating +in traditional, unthreaded mode (in this case use +.Xr _exit 2 +to exit the process). +.El +.Pp +The +.Fn kse_release +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +The current KSE has no associated mailbox, i.e., the process is operating is +traditional, unthreaded mode. +.El +.Pp +The +.Fn kse_wakeup +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +The +.Fa mbx +argument +is not +.Dv NULL +and the mailbox pointed to by +.Fa mbx +is not associated with any KSE in the process. +.It Bq Er ESRCH +The +.Fa mbx +argument +is +.Dv NULL +and the current KSE has no associated mailbox, i.e., the process is operating +in traditional, unthreaded mode. +.El +.Pp +The +.Fn kse_thr_interrupt +system call +will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +The thread corresponding to +.Fa tmbx +is neither currently assigned to any KSE in the process nor blocked in the +kernel. +.El +.Sh SEE ALSO +.Xr rfork 2 , +.Xr pthread 3 , +.Xr ucontext 3 +.Rs +.%A "Thomas E. Anderson" +.%A "Brian N. Bershad" +.%A "Edward D. Lazowska" +.%A "Henry M. Levy" +.%J "ACM Transactions on Computer Systems" +.%N Issue 1 +.%V Volume 10 +.%D February 1992 +.%I ACM Press +.%P pp. 53-79 +.%T "Scheduler activations: effective kernel support for the user-level management of parallelism" +.Re +.Sh HISTORY +The KSE system calls first appeared in +.Fx 5.0 . +.Sh AUTHORS +KSE was originally implemented by +.An -nosplit +.An "Julian Elischer" Aq julian@FreeBSD.org , +with additional contributions by +.An "Jonathan Mini" Aq mini@FreeBSD.org , +.An "Daniel Eischen" Aq deischen@FreeBSD.org , +and +.An "David Xu" Aq davidxu@FreeBSD.org . +.Pp +This manual page was written by +.An "Archie Cobbs" Aq archie@FreeBSD.org . +.Sh BUGS +The KSE code is +.Ud . diff --git a/lib/libc/sys/ktrace.2 b/lib/libc/sys/ktrace.2 new file mode 100644 index 0000000..598cc91 --- /dev/null +++ b/lib/libc/sys/ktrace.2 @@ -0,0 +1,196 @@ +.\" 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 June 4, 1993 +.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 Enable trace points specified in" +.Fa trpoints . +.It "KTROP_CLEAR Disable trace points specified in +.Fa trpoints . +.It "KTROP_CLEARFILE Stop all tracing." +.It "KTRFLAG_DESCEND 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_SYSCALLXXX -offset indent +.It "KTRFAC_SYSCALL Trace system calls." +.It "KTRFAC_SYSRET Trace return values from system calls." +.It "KTRFAC_NAMEI Trace name lookup operations." +.It "KTRFAC_GENIO Trace all I/O (note that this option can" +generate much output). +.It "KTRFAC_PSIG Trace posted signals." +.It "KTRFAC_CSW Trace context switch points." +.It "KTRFAC_INHERIT 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 */ + caddr_t ktr_buf; +}; +.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_buf +is an internal kernel pointer and is not useful. +.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 0000000..edf2e03 --- /dev/null +++ b/lib/libc/sys/link.2 @@ -0,0 +1,180 @@ +.\" 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 December 9, 2006 +.Dt LINK 2 +.Os +.Sh NAME +.Nm link +.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" +.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. +.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 +.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 . +.Sh HISTORY +The +.Fn link +function appeared in +.At v7 . +.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 0000000..0ffbcdd --- /dev/null +++ b/lib/libc/sys/lio_listio.2 @@ -0,0 +1,175 @@ +.\" 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 January 12, 2003 +.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 , +the requests are processed asynchronously, and the signal specified by +.Fa sig +is sent when all operations have completed. +If +.Fa sig +is +.Dv NULL , +the calling process is not notified of I/O completion. +.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 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 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 0000000..bd6abde --- /dev/null +++ b/lib/libc/sys/listen.2 @@ -0,0 +1,170 @@ +.\" 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 29, 2005 +.Dt LISTEN 2 +.Os +.Sh NAME +.Nm listen +.Nd listen for connections on a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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.somaxconn +specifies a hard limit on +.Fa backlog ; +if a value greater than +.Va kern.ipc.somaxconn +or less than zero is specified, +.Fa backlog +is silently forced to +.Va kern.ipc.somaxconn . +.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 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 . diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 new file mode 100644 index 0000000..874c523 --- /dev/null +++ b/lib/libc/sys/lseek.2 @@ -0,0 +1,209 @@ +.\" 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 April 5, 2007 +.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 of the start of the next hole greater than or equal to the supplied +.Fa offset +is returned. +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. +The existence of a hole at the end of every data region allows for easy +programming and implies that a virtual hole exists at the end of the file. +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. +For +.Dv SEEK_HOLE , +there are no more holes past the supplied offset. +.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/lseek.c b/lib/libc/sys/lseek.c new file mode 100644 index 0000000..8613678 --- /dev/null +++ b/lib/libc/sys/lseek.c @@ -0,0 +1,51 @@ +/* + * Copyright (c) 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. + */ + +#if defined(LIBC_SCCS) && !defined(lint) +static char sccsid[] = "@(#)lseek.c 8.1 (Berkeley) 6/17/93"; +#endif /* LIBC_SCCS and not lint */ +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <unistd.h> + +/* + * This function provides 64-bit offset padding that + * is not supplied by GCC 1.X but is supplied by GCC 2.X. + */ +off_t +lseek(fd, offset, whence) + int fd; + off_t offset; + int whence; +{ + return(__syscall((quad_t)SYS_lseek, fd, 0, offset, whence)); +} diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2 new file mode 100644 index 0000000..48f0e5a --- /dev/null +++ b/lib/libc/sys/madvise.2 @@ -0,0 +1,182 @@ +.\" 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 19, 1996 +.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 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 range. +Additionally future references to +this address range will 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 +.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 0000000..6a7bd54 --- /dev/null +++ b/lib/libc/sys/mincore.2 @@ -0,0 +1,113 @@ +.\" 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. +.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 0000000..1dc4fb8 --- /dev/null +++ b/lib/libc/sys/minherit.2 @@ -0,0 +1,137 @@ +.\" $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 February 17, 1996 +.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 . +.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 0000000..94317d6 --- /dev/null +++ b/lib/libc/sys/mkdir.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. +.\" +.\" @(#)mkdir.2 8.2 (Berkeley) 12/11/93 +.\" $FreeBSD$ +.\" +.Dd December 9, 2006 +.Dt MKDIR 2 +.Os +.Sh NAME +.Nm mkdir +.Nd make a directory file +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.Ft int +.Fn mkdir "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. +.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 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 +.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 . diff --git a/lib/libc/sys/mkfifo.2 b/lib/libc/sys/mkfifo.2 new file mode 100644 index 0000000..2011924 --- /dev/null +++ b/lib/libc/sys/mkfifo.2 @@ -0,0 +1,129 @@ +.\" 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 December 10, 2006 +.Dt MKFIFO 2 +.Os +.Sh NAME +.Nm mkfifo +.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" +.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. +.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 +.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 . diff --git a/lib/libc/sys/mknod.2 b/lib/libc/sys/mknod.2 new file mode 100644 index 0000000..51f5876 --- /dev/null +++ b/lib/libc/sys/mknod.2 @@ -0,0 +1,126 @@ +.\" 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 June 4, 1993 +.Dt MKNOD 2 +.Os +.Sh NAME +.Nm mknod +.Nd make a special file node +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn mknod "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. +.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 +.Sh SEE ALSO +.Xr chmod 2 , +.Xr mkfifo 2 , +.Xr stat 2 , +.Xr umask 2 +.Sh HISTORY +The +.Fn mknod +function appeared in +.At v6 . diff --git a/lib/libc/sys/mlock.2 b/lib/libc/sys/mlock.2 new file mode 100644 index 0000000..0c05b7b --- /dev/null +++ b/lib/libc/sys/mlock.2 @@ -0,0 +1,165 @@ +.\" 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 August 10, 2004 +.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. +A single process can +.Fn mlock +the minimum of +a system-wide ``wired pages'' limit and +the per-process +.Li RLIMIT_MEMLOCK +resource limit. +.Pp +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 +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 either the system or per-process +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. +.El +The +.Fn munlock +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 address given is not page aligned or the length is negative. +.It Bq Er ENOMEM +Some portion of the indicated address range is not allocated. +.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 0000000..db4c4a9 --- /dev/null +++ b/lib/libc/sys/mlockall.2 @@ -0,0 +1,140 @@ +.\" $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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation 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 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 June 12, 1999 +.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 and the per-process +.Dv RLIMIT_MEMLOCK +resource limit. +.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 0000000..da31179 --- /dev/null +++ b/lib/libc/sys/mmap.2 @@ -0,0 +1,364 @@ +.\" 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 April 21, 2006 +.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_HASSEMAPHORE +.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 is ignored. +.\".It Dv MAP_FILE +.\"Mapped from a regular file or character-special device memory. +.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 a +.Dv MAP_FIXED +request is successful, the mapping established by +.Fn mmap +replaces any previous mappings for the process' pages in the range from +.Fa addr +to +.Fa addr ++ +.Fa len . +Use of this option is discouraged. +.It Dv MAP_HASSEMAPHORE +Notify the kernel that the region may contain semaphores and that special +handling may be necessary. +.It Dv MAP_INHERIT +This flag never operated as advertised and is no longer supported. +Please refer to +.Xr minherit 2 +for further information. +.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). +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 obsolete 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_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. +.Pp +The current design does not allow a process to specify the location of +swap space. +In the future we may define an additional mapping type, +.Dv MAP_SWAP , +in which +the file descriptor argument specifies a file or device to which swapping +should be done. +.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 +.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 +The +.Fa len +argument +was negative. +.It Bq Er EINVAL +.Dv MAP_ANON +was specified and the +.Fa fd +argument was not -1. +The +.Fa offset +argument +was not page-aligned. +(See +.Sx BUGS +below.) +.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. +The system has reached the per-process mmap limit specified in the +.Va vm.max_proc_mmap +sysctl. +.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 make.conf 5 +.Sh BUGS +The +.Fa len +argument +is limited to the maximum file size or available userland address +space. +Files may not be able to be made more than 1TB large on 32 bit systems +due to file systems restrictions and bugs, but address space is far more +restrictive. +Larger files may be possible on 64 bit systems. +.Pp +The previous documented limit of 2GB was a documentation bug. +That limit has not existed since +.Fx 2.2 . +.Pp +Note that an attempt to +.Fn mmap +zero bytes has no effect and succeeds, while an attempt to +.Fn munmap +zero bytes will return +.Bq Er EINVAL . diff --git a/lib/libc/sys/mmap.c b/lib/libc/sys/mmap.c new file mode 100644 index 0000000..8b22147 --- /dev/null +++ b/lib/libc/sys/mmap.c @@ -0,0 +1,57 @@ +/* + * Copyright (c) 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. + */ + +#if defined(LIBC_SCCS) && !defined(lint) +static char sccsid[] = "@(#)mmap.c 8.1 (Berkeley) 6/17/93"; +#endif /* LIBC_SCCS and not lint */ +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/mman.h> +#include <sys/syscall.h> +#include <unistd.h> + +/* + * This function provides 64-bit offset padding that + * is not supplied by GCC 1.X but is supplied by GCC 2.X. + */ +void * +mmap(addr, len, prot, flags, fd, offset) + void * addr; + size_t len; + int prot; + int flags; + int fd; + off_t offset; +{ + + return ((void *)(intptr_t)__syscall((quad_t)SYS_mmap, addr, len, prot, + flags, fd, 0, offset)); +} diff --git a/lib/libc/sys/modfind.2 b/lib/libc/sys/modfind.2 new file mode 100644 index 0000000..3f48579 --- /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 file . +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 0000000..c0c0a0d --- /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 0000000..9356232 --- /dev/null +++ b/lib/libc/sys/modstat.2 @@ -0,0 +1,128 @@ +.\" +.\" 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 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[MAXPATHLEN]; + int refs; + int id; + modspecific_t data; +}; +typedef union modspecific { + int intval; + u_int u_intval; + long longval; + u_long u_longval; +} modspecific_t; +.Ed +.Pp +.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 0000000..6ce2d4d --- /dev/null +++ b/lib/libc/sys/mount.2 @@ -0,0 +1,372 @@ +.\" 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 February 23, 2005 +.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 -item -offset indent -compact +.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. +.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 +.Pp +A +.Em ufs +mount can also fail if the maximum number of file systems are currently +mounted. +.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 . +.Sh BUGS +Some of the error codes need translation to more obvious messages. diff --git a/lib/libc/sys/mprotect.2 b/lib/libc/sys/mprotect.2 new file mode 100644 index 0000000..8fc3621 --- /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 June 9, 1993 +.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 "const 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 0000000..c2968fb --- /dev/null +++ b/lib/libc/sys/mq_close.2 @@ -0,0 +1,85 @@ +.\" 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 November 29, 2005 +.Dt MQ_CLOSE 2 +.Os +.Sh NAME +.Nm mq_close +.Nd "close a message queue (REALTIME)" +.Sh LIBRARY +.Lb libc +.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 . diff --git a/lib/libc/sys/mq_getattr.2 b/lib/libc/sys/mq_getattr.2 new file mode 100644 index 0000000..f34c498 --- /dev/null +++ b/lib/libc/sys/mq_getattr.2 @@ -0,0 +1,107 @@ +.\" 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 November 29, 2005 +.Dt MQ_GETATTR 2 +.Os +.Sh NAME +.Nm mq_getattr +.Nd "get message queue attributes (REALTIME)" +.Sh LIBRARY +.Lb libc +.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_flags" +.It Va mq_flags +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 . diff --git a/lib/libc/sys/mq_notify.2 b/lib/libc/sys/mq_notify.2 new file mode 100644 index 0000000..e7361d4 --- /dev/null +++ b/lib/libc/sys/mq_notify.2 @@ -0,0 +1,131 @@ +.\" 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 November 29, 2005 +.Dt MQ_NOTIFY 2 +.Os +.Sh NAME +.Nm mq_notify +.Nd "notify process that a message is available (REALTIME)" +.Sh LIBRARY +.Lb libc +.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. +If +.Fa notification->sigev_notify +is +.Dv SIGEV_SIGNAL , +then the signal specified in +.Fa notification->sigev_signo +will be sent to the process. +The signal will be queued to the process and the value specified in +.Fa notification->sigev_value +will be the +.Va si_value +component of the generated signal. +.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. +.El +.Sh SEE ALSO +.Xr mq_open 2 , +.Xr mq_send 2 , +.Xr mq_timedsend 2 , +.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 . diff --git a/lib/libc/sys/mq_open.2 b/lib/libc/sys/mq_open.2 new file mode 100644 index 0000000..940ddfc --- /dev/null +++ b/lib/libc/sys/mq_open.2 @@ -0,0 +1,303 @@ +.\" 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 November 29, 2005 +.Dt MQ_OPEN 2 +.Os +.Sh NAME +.Nm mq_open +.Nd "open a message queue (REALTIME)" +.Sh LIBRARY +.Lb libc +.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. +.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 +.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. diff --git a/lib/libc/sys/mq_receive.2 b/lib/libc/sys/mq_receive.2 new file mode 100644 index 0000000..e9e5efd --- /dev/null +++ b/lib/libc/sys/mq_receive.2 @@ -0,0 +1,197 @@ +.\" 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 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 libc +.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 . diff --git a/lib/libc/sys/mq_send.2 b/lib/libc/sys/mq_send.2 new file mode 100644 index 0000000..0d63a40 --- /dev/null +++ b/lib/libc/sys/mq_send.2 @@ -0,0 +1,216 @@ +.\" 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 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 libc +.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 . diff --git a/lib/libc/sys/mq_setattr.2 b/lib/libc/sys/mq_setattr.2 new file mode 100644 index 0000000..e5f0726 --- /dev/null +++ b/lib/libc/sys/mq_setattr.2 @@ -0,0 +1,103 @@ +.\" 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 November 29, 2005 +.Dt MQ_SETATTR 2 +.Os +.Sh NAME +.Nm mq_setattr +.Nd "set message queue attributes (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fo mq_setattr +.Fa "mqd_t mqdes" +.Fa "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 . diff --git a/lib/libc/sys/msync.2 b/lib/libc/sys/msync.2 new file mode 100644 index 0000000..cb15925 --- /dev/null +++ b/lib/libc/sys/msync.2 @@ -0,0 +1,121 @@ +.\" 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 June 21, 1994 +.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 EINVAL +The +.Fa len +argument +is too large or negative. +.It Bq Er EINVAL +The +.Fa flags +argument +was both MS_ASYNC and MS_INVALIDATE. +Only one of these flags is allowed. +.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 obsolete 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/munmap.2 b/lib/libc/sys/munmap.2 new file mode 100644 index 0000000..6431072 --- /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 0000000..18e4c88 --- /dev/null +++ b/lib/libc/sys/nanosleep.2 @@ -0,0 +1,109 @@ +.\" $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 process to sleep for the specified time. +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/nfssvc.2 b/lib/libc/sys/nfssvc.2 new file mode 100644 index 0000000..cf52187 --- /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 */ + u_int32_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 */ + u_int32_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 0000000..a7bf4f1 --- /dev/null +++ b/lib/libc/sys/ntp_adjtime.2 @@ -0,0 +1,150 @@ +.\" +.\" Copyright (c) 2003 Tom Rhodes +.\" 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 April 1, 2003 +.Dt NTP_ADJTIME 2 +.Os +.Sh NAME +.Nm ntp_adjtime +.Nd NTP daemon application interface +.Sh SYNOPSIS +.In sys/types.h +.In sys/timex.h +.Ft int +.Fn ntp_adjtime "struct timex *tp" +.Sh DESCRIPTION +The +.Fn ntp_adjtime +system call is used as a kernel interface +for the Network Time Protocol daemon, +.Xr ntpd 8 . +Certain fields of the +.Vt timex +structure are interpreted in either +microseconds or nanoseconds, according to the state of the +.Dv STA_NANO +bit in the +.Va status +word. +.Pp +In the +.Fx +kernel, the +.Fn ntp_adjtime +and +.Xr ntp_gettime 2 +system calls can be used to determine which +resolution is in use, and to select either one at any time. +The resolution selected affects the scaling of certain fields in the +.Fn ntp_gettime +and +.Fn ntp_adjtime +system calls. +.Pp +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. +.Bd -literal +/* + * NTP daemon interface (ntp_adjtime()) - used to discipline CPU clock + * oscillator and determine status. + * + * Note: The offset, precision and jitter members are in microseconds if + * STA_NANO is zero and nanoseconds if not. + */ +struct timex { + unsigned int modes; /* clock mode bits (wo) */ + long offset; /* time offset (ns/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; /* poll interval (log2 s) (rw) */ + long precision; /* clock precision (ns/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. They are included in all configurations to insure + * portability. + */ + long ppsfreq; /* PPS frequency (scaled PPM) (ro) */ + long jitter; /* PPS jitter (ns/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 +Upon successful completion, +.Fn ntp_adjtime +will fill the +.Fa tp +argument with the current clock state. +.Sh RETURN VALUES +Upon successful completion the clock state is returned. +Otherwise a -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +Possible states of the clock are: +.Pp +.Bl -tag -compact -width ".Dv TIME_ERROR" +.It Dv TIME_OK +Everything okay, no leap second warning. +.It Dv TIME_INS +insert leap second warning. +.It Dv TIME_DEL +delete leap second warning. +.It Dv TIME_OOP +Leap second in progress. +.It Dv TIME_WAIT +Leap second has occurred. +.It Dv 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 ntp_gettime 2 , +.Xr ntpd 8 +.Sh AUTHORS +This manual page was written by +.An Tom Rhodes Aq trhodes@FreeBSD.org . diff --git a/lib/libc/sys/ntp_gettime.2 b/lib/libc/sys/ntp_gettime.2 new file mode 100644 index 0000000..f556d74 --- /dev/null +++ b/lib/libc/sys/ntp_gettime.2 @@ -0,0 +1,116 @@ +.\" +.\" Copyright (c) 2003 Tom Rhodes +.\" 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 21, 2003 +.Dt NTP_GETTIME 2 +.Os +.Sh NAME +.Nm ntp_gettime +.Nd NTP user application interface +.Sh SYNOPSIS +.In sys/timex.h +.Ft int +.Fn ntp_gettime "struct ntptimeval *ntv" +.Sh DESCRIPTION +The time returned by +.Fn ntp_gettime +is in a +.Vt timespec +structure, but may be in either microsecond +(seconds and microseconds) or nanosecond (seconds and nanoseconds) format. +The particular format in use is determined by the +.Dv STA_NANO +bit of the status +word returned by the +.Fn ntp_adjtime +system call. +.Fn ntp_gettime +has as argument a pointer to the +.Vt ntptimeval +structure with the following members: +.Bd -literal +struct ntptimeval { + struct timespec time; /* current time (ns) (ro) */ + long maxerror; /* maximum error (us) (ro) */ + long esterror; /* estimated error (us) (ro) */ + long tai; /* TAI-UTC offset */ + int time_state; /* time status */ +}; +.Ed +.Pp +These are understood as: +.Bl -tag -width ".Va time_state" +.It Va time +Current time (read-only). +.It Va maxerror +Maximum error in microseconds (read-only). +.It Va esterror +Estimated error in microseconds (read-only). +.It Va tai +Offset in seconds between the TAI and UTC time scales. +This offset is published twice a year and is an integral number of +seconds between TAI (which does not have leap seconds) and UTC (which +does). +.Xr ntpd 8 +or some other agent maintains this value. +A value of 0 means unknown. +As of the date of the manual page, the offset is 32 seconds. +.It Va time_state +Current time status. +.El +.Sh RETURN VALUES +.Rv -std ntp_gettime +.Pp +Possible states of the clock are: +.Pp +.Bl -tag -compact -width ".Dv TIME_ERROR" +.It Dv TIME_OK +Everything okay, no leap second warning. +.It Dv TIME_INS +Positive leap second warning. +At the end of the day, an additional second will be inserted after 23:59:59. +.It Dv TIME_DEL +Negative leap second warning. +At the end of the day, 23:59:59 is skipped. +.It Dv TIME_OOP +Leap second in progress. +.It Dv TIME_WAIT +Leap second has occurred. +.It Dv TIME_ERROR +Clock not synchronized. +.El +.Sh SEE ALSO +.Xr ntp_adjtime 2 , +.Xr ntpd 8 +.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 AUTHORS +This manual page was written by +.An Tom Rhodes Aq trhodes@FreeBSD.org . diff --git a/lib/libc/sys/open.2 b/lib/libc/sys/open.2 new file mode 100644 index 0000000..423cf8b --- /dev/null +++ b/lib/libc/sys/open.2 @@ -0,0 +1,369 @@ +.\" 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 7, 2007 +.Dt OPEN 2 +.Os +.Sh NAME +.Nm open +.Nd open or create a file for reading or writing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In fcntl.h +.Ft int +.Fn open "const char *path" "int flags" "..." +.Sh DESCRIPTION +The file name specified by +.Fa path +is opened +for 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 +requires a third 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 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_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 don't assign controlling terminal +.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 +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 +When a new file is created it is given the group of the directory +which contains it. +.Pp +The new descriptor is set to remain open across +.Xr execve 2 +system calls; see +.Xr close 2 +and +.Xr fcntl 2 . +.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 +returns a non-negative integer, termed a file descriptor. +It returns -1 on failure, and sets +.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 +.Dv The named file has its immutable flag set and the file is to be modified. +.It Bq Er EPERM +.Dv 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 , +and +.Dv O_RDWR . +.El +.Sh SEE ALSO +.Xr chmod 2 , +.Xr close 2 , +.Xr dup 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 . diff --git a/lib/libc/sys/pathconf.2 b/lib/libc/sys/pathconf.2 new file mode 100644 index 0000000..7a16a4d --- /dev/null +++ b/lib/libc/sys/pathconf.2 @@ -0,0 +1,238 @@ +.\" 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 April 5, 2007 +.Dt PATHCONF 2 +.Os +.Sh NAME +.Nm pathconf , +.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 fpathconf "int fd" "int name" +.Sh DESCRIPTION +The +.Fn pathconf +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 , +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 available values are as follows: +.Pp +.Bl -tag -width 6n +.Pp +.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_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 +.Bl -tag -width Er +The +.Fn fpathconf +system call +will fail if: +.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 . diff --git a/lib/libc/sys/pipe.2 b/lib/libc/sys/pipe.2 new file mode 100644 index 0000000..faf1a91 --- /dev/null +++ b/lib/libc/sys/pipe.2 @@ -0,0 +1,118 @@ +.\" 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 January 30, 2006 +.Dt PIPE 2 +.Os +.Sh NAME +.Nm pipe +.Nd create descriptor pair for interprocess communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn pipe "int *fildes" +.Sh DESCRIPTION +The +.Fn pipe +system call +creates a +.Em pipe , +which is an object allowing +bidirectional data flow, +and allocates a pair of file descriptors. +.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 RETURN VALUES +.Rv -std pipe +.Sh ERRORS +The +.Fn pipe +system call will fail if: +.Bl -tag -width Er +.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. +.It Bq Er EFAULT +The +.Fa fildes +buffer is in an invalid area of the process's address +space. +.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 . diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 new file mode 100644 index 0000000..932186d --- /dev/null +++ b/lib/libc/sys/poll.2 @@ -0,0 +1,213 @@ +.\" $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 July 8, 2002 +.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" +.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. +.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 negative. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr kqueue 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr write 2 +.Sh HISTORY +The +.Fn poll +function appeared in +.At V . +This manual page and the core of the implementation was taken from +.Nx . +.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/pread.c b/lib/libc/sys/pread.c new file mode 100644 index 0000000..1d2fee6 --- /dev/null +++ b/lib/libc/sys/pread.c @@ -0,0 +1,52 @@ +/* + * Copyright (c) 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. + */ + +#if defined(LIBC_SCCS) && !defined(lint) +static char sccsid[] = "@(#)mmap.c 8.1 (Berkeley) 6/17/93"; +#endif /* LIBC_SCCS and not lint */ +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <unistd.h> + +/* + * This function provides 64-bit offset padding that + * is not supplied by GCC 1.X but is supplied by GCC 2.X. + */ +ssize_t +pread(fd, buf, nbyte, offset) + int fd; + void *buf; + size_t nbyte; + off_t offset; +{ + return ((ssize_t)__syscall((quad_t)SYS_pread, fd, buf, nbyte, 0, offset)); +} diff --git a/lib/libc/sys/profil.2 b/lib/libc/sys/profil.2 new file mode 100644 index 0000000..444d3c3 --- /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/ptrace.2 b/lib/libc/sys/ptrace.2 new file mode 100644 index 0000000..44fc1ea --- /dev/null +++ b/lib/libc/sys/ptrace.2 @@ -0,0 +1,404 @@ +.\" $FreeBSD$ +.\" $NetBSD: ptrace.2,v 1.2 1995/02/27 12:35:37 cgd Exp $ +.\" +.\" This file is in the public domain. +.Dd April 9, 2007 +.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, system calls, or stepping by the tracing +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 +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. +The +.Fa request +argument +can be: +.Bl -tag -width 12n +.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. +.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; /* LWP described. */ + int pl_event; /* Event received. */ +}; +.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. +.It PT_GETNUMLWPS +This request returns the number of kernel threads associated with the +traced process. +.It 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. +.El +.Pp +Additionally, machine-specific requests can exist. +.Sh RETURN VALUES +Some requests can cause +.Fn ptrace +to return +\-1 +as a non-error value; to disambiguate, +.Va errno +can be set to 0 before the call and checked afterwards. +.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.) +.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 +.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/pwrite.c b/lib/libc/sys/pwrite.c new file mode 100644 index 0000000..ebbb1ec --- /dev/null +++ b/lib/libc/sys/pwrite.c @@ -0,0 +1,52 @@ +/* + * Copyright (c) 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. + */ + +#if defined(LIBC_SCCS) && !defined(lint) +static char sccsid[] = "@(#)mmap.c 8.1 (Berkeley) 6/17/93"; +#endif /* LIBC_SCCS and not lint */ +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> +#include <unistd.h> + +/* + * This function provides 64-bit offset padding that + * is not supplied by GCC 1.X but is supplied by GCC 2.X. + */ +ssize_t +pwrite(fd, buf, nbyte, offset) + int fd; + const void *buf; + size_t nbyte; + off_t offset; +{ + return ((ssize_t)__syscall((quad_t)SYS_pwrite, fd, buf, nbyte, 0, offset)); +} diff --git a/lib/libc/sys/quotactl.2 b/lib/libc/sys/quotactl.2 new file mode 100644 index 0000000..4b4dca5 --- /dev/null +++ b/lib/libc/sys/quotactl.2 @@ -0,0 +1,247 @@ +.\" 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_QUOTAOFFxx +.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_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_GETQUOTA +and +.Dv Q_SETQUOTA , +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 , +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/read.2 b/lib/libc/sys/read.2 new file mode 100644 index 0000000..19e4ffe --- /dev/null +++ b/lib/libc/sys/read.2 @@ -0,0 +1,283 @@ +.\" 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 October 11, 2006 +.Dt READ 2 +.Os +.Sh NAME +.Nm read , +.Nm readv , +.Nm pread , +.Nm preadv +.Nd read input +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/uio.h +.In unistd.h +.Ft ssize_t +.Fn read "int d" "void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" +.Ft ssize_t +.Fn readv "int d" "const struct iovec *iov" "int iovcnt" +.Ft ssize_t +.Fn preadv "int d" "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 d +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 d +(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 d +argument +is not a valid file or socket descriptor open for reading. +.It Bq Er ECONNRESET +The +.Fa d +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 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 d +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/readlink.2 b/lib/libc/sys/readlink.2 new file mode 100644 index 0000000..0f630f8 --- /dev/null +++ b/lib/libc/sys/readlink.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. +.\" +.\" @(#)readlink.2 8.1 (Berkeley) 6/4/93 +.\" $FreeBSD$ +.\" +.Dd June 4, 1993 +.Dt READLINK 2 +.Os +.Sh NAME +.Nm readlink +.Nd read value of a symbolic link +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn readlink "const char *path" "char *buf" "int bufsiz" +.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 . +.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 +.Sh SEE ALSO +.Xr lstat 2 , +.Xr stat 2 , +.Xr symlink 2 , +.Xr symlink 7 +.Sh HISTORY +The +.Fn readlink +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/reboot.2 b/lib/libc/sys/reboot.2 new file mode 100644 index 0000000..f5571ae --- /dev/null +++ b/lib/libc/sys/reboot.2 @@ -0,0 +1,166 @@ +.\" 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 June 4, 1993 +.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_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 . +.Sh BUGS +The HP300 implementation supports neither +.Dv RB_DFLTROOT +nor +.Dv RB_KDB . diff --git a/lib/libc/sys/recv.2 b/lib/libc/sys/recv.2 new file mode 100644 index 0000000..79d8f09 --- /dev/null +++ b/lib/libc/sys/recv.2 @@ -0,0 +1,333 @@ +.\" 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 December 28, 2006 +.Dt RECV 2 +.Os +.Sh NAME +.Nm recv , +.Nm recvfrom , +.Nm recvmsg +.Nd receive a message from a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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 * restrict 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" +.Sh DESCRIPTION +The +.Fn recvfrom +and +.Fn recvmsg +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. +As it is redundant, it may not be supported in future releases. +.Pp +All three routines return the length of the message on successful +completion. +If a message is too long to fit in the supplied buffer, +excess bytes may be discarded depending on the type of socket +the message is received from (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 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 . +.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_DONTWAIT" -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 +.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. +.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 : +.Pp +.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 . +.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: +.Pp +.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 +The kernel will fill in the credential information of the sending process +and deliver it to the receiver. +.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. +.Sh RETURN VALUES +These calls return the number of bytes received, or -1 +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 +.Sh HISTORY +The +.Fn recv +function appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/rename.2 b/lib/libc/sys/rename.2 new file mode 100644 index 0000000..3c3001c --- /dev/null +++ b/lib/libc/sys/rename.2 @@ -0,0 +1,226 @@ +.\" 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 December 9, 2006 +.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" +.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. +.\".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 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 +.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 . diff --git a/lib/libc/sys/revoke.2 b/lib/libc/sys/revoke.2 new file mode 100644 index 0000000..c88222e --- /dev/null +++ b/lib/libc/sys/revoke.2 @@ -0,0 +1,105 @@ +.\" 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 June 4, 1993 +.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. +.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 close 2 +.Sh HISTORY +The +.Fn revoke +system call first appeared in +.Bx 4.3 Reno . diff --git a/lib/libc/sys/rfork.2 b/lib/libc/sys/rfork.2 new file mode 100644 index 0000000..c0f264a --- /dev/null +++ b/lib/libc/sys/rfork.2 @@ -0,0 +1,194 @@ +.\" +.\" 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 May 14, 2007 +.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. +.It Dv RFSIGSHARE +If set, the kernel will force sharing the sigacts structure between the +child and the parent. +.It Dv RFLINUXTHPN +If set, the kernel will return SIGUSR1 instead of SIGCHILD 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 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 rfork_thread 3 +.Sh HISTORY +The +.Fn rfork +function first appeared in Plan9. +.Sh BUGS +.Fx +does not yet implement a native +.Fn clone +library call, and the current pthreads implementation does not use +.Fn rfork +with RFMEM. +A native port of the linux threads library, +.Pa /usr/ports/devel/linuxthreads , +contains a working +.Fn clone +call that utilizes RFMEM. +The +.Xr rfork_thread 3 +function can often be used instead of +.Fn clone . diff --git a/lib/libc/sys/rmdir.2 b/lib/libc/sys/rmdir.2 new file mode 100644 index 0000000..597c946 --- /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 0000000..afed81e --- /dev/null +++ b/lib/libc/sys/rtprio.2 @@ -0,0 +1,126 @@ +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd July 23, 1994 +.Dt RTPRIO 2 +.Os +.Sh NAME +.Nm rtprio +.Nd examine or modify a process 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" +.Sh DESCRIPTION +The +.Fn rtprio +system call +is used to lookup or change the realtime or idle priority of a process. +.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. +The +.Fa pid +argument +specifies the process to be used, 0 for the current process. +.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 (usually 31) . +0 is the highest possible priority. +.Pp +Realtime and idle priority is inherited through fork() and exec(). +.Pp +A realtime process can only be preempted by a process of equal or +higher priority, or by an interrupt; idle priority processes will run only +when no other real/normal priority process is runnable. +Higher real/idle priority processes +preempt lower real/idle priority processes. +Processes of equal real/idle priority are run round-robin. +.Sh RETURN VALUES +.Rv -std rtprio +.Sh ERRORS +The +.Fn rtprio +system call +will fail if +.Bl -tag -width Er +.It Bq Er EINVAL +The specified +.Fa prio +was out of range. +.It Bq Er EPERM +The calling process is not allowed to set the realtime priority. +Only +root is allowed to change the realtime priority of any process, and non-root +may only change the idle priority of the current process. +.It Bq Er ESRCH +The specified process was not found. +.El +.Sh SEE ALSO +.Xr nice 1 , +.Xr ps 1 , +.Xr rtprio 1 , +.Xr setpriority 2 , +.Xr nice 3 , +.Xr renice 8 +.Sh AUTHORS +.An -nosplit +The original author was +.An Henrik Vestergaard Draboel Aq hvd@terry.ping.dk . +This implementation in +.Fx +was substantially rewritten by +.An David Greenman . 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 0000000..88d1d6d --- /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 0000000..315fd82 --- /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 0000000..21b34e0 --- /dev/null +++ b/lib/libc/sys/sched_setscheduler.2 @@ -0,0 +1,167 @@ +.\" $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> : +.Pp +.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_getparam 2 , +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 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 0000000..9db8942 --- /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 0000000..3c6088d --- /dev/null +++ b/lib/libc/sys/sctp_generic_recvmsg.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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 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 15, 2006 +.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" +.Ft int +.Sh DESCRIPTION +The +.Fn sctp_generic_recvmsg +is the true system calls used by the +.Fn sctp_recvmsg +function call. This call is more efficient since it is a +true system calls but it is specific to FreeBSD and +can be expected NOT to be present on any other Operating +System. For detailed useage please see either the +.Fn sctp_recvmsg +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 4 , +.Xr sctp_recvmsg 3 , + diff --git a/lib/libc/sys/sctp_generic_sendmsg.2 b/lib/libc/sys/sctp_generic_sendmsg.2 new file mode 100644 index 0000000..f936c43 --- /dev/null +++ b/lib/libc/sys/sctp_generic_sendmsg.2 @@ -0,0 +1,88 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 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 15, 2006 +.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 +The +.Fn sctp_generic_sendmsg +and +.Fn sctp_generic_sendmsg_iov +are the true system calls used by the +.Fn sctp_sendmsg +and +.Fn sctp_send +function calls. These are more efficient since they are +true system calls but they are specific to FreeBSD and +can be expected NOT to be present on any other Operating +System. For detailed useage please see either the +.Fn sctp_send +or +.Fn sctp_sendmsg +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 4 , +.Xr sctp_send 3 , +.Xr sctp_sendx 3 , +.Xr sctp_sendmsg 3 , +.Xr sctp_sendmsgx 3 , + diff --git a/lib/libc/sys/sctp_peeloff.2 b/lib/libc/sys/sctp_peeloff.2 new file mode 100644 index 0000000..e5bf7b2 --- /dev/null +++ b/lib/libc/sys/sctp_peeloff.2 @@ -0,0 +1,82 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 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 15, 2006 +.Dt SCTP_PEELOFF 2 +.Os +.Sh NAME +.Nm sctp_peeloff +.Nd detach an association from an one-to-many socket to its on sd +.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 seperate socket. +.Pp +.Sh RETURN VALUES +The call returns -1 on failure and the new socket descriptor +upon success. +.Sh ERRORS +The +.Fn sctp_peeloff +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 0000000..17fdbc4 --- /dev/null +++ b/lib/libc/sys/select.2 @@ -0,0 +1,224 @@ +.\" 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. diff --git a/lib/libc/sys/semctl.2 b/lib/libc/sys/semctl.2 new file mode 100644 index 0000000..01a984a --- /dev/null +++ b/lib/libc/sys/semctl.2 @@ -0,0 +1,203 @@ +.\" +.\" 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 */ + long sem_pad1; /* SVABI/386 says I need this here */ + time_t sem_ctime; /* last change time */ + /* Times measured in secs since */ + /* 00:00:00 GMT, Jan. 1, 1970 */ + long sem_pad2; /* SVABI/386 says I need this here */ + long sem_pad3[4]; /* SVABI/386 says I need this here */ +}; +.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 0000000..945044d --- /dev/null +++ b/lib/libc/sys/semget.2 @@ -0,0 +1,148 @@ +.\" +.\" 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 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 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 0000000..86200ee --- /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 insure 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 0000000..6a61426 --- /dev/null +++ b/lib/libc/sys/send.2 @@ -0,0 +1,232 @@ +.\" 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 September 13, 2006 +.Dt SEND 2 +.Os +.Sh NAME +.Nm send , +.Nm sendto , +.Nm sendmsg +.Nd send a message from a socket +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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" +.Sh DESCRIPTION +The +.Fn send +function, +and +.Fn sendto +and +.Fn sendmsg +system calls +are used to transmit a message to another socket. +The +.Fn send +function +may be used only when the socket is in a +.Em connected +state, while +.Fn sendto +and +.Fn sendmsg +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 +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. +.Sh RETURN VALUES +The call returns the number of characters sent, or -1 +if an error occurred. +.Sh ERRORS +The +.Fn send +function 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 EPERM +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 . +.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 0000000..93420f6 --- /dev/null +++ b/lib/libc/sys/sendfile.2 @@ -0,0 +1,295 @@ +.\" 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 24, 2006 +.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 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 +.Fa flags +argument has one possible value: +.Dv SF_NODISKIO . +This flag causes any +.Fn sendfile +call which would block on disk I/O to instead +return +.Er EBUSY . +Busy servers may benefit by transferring requests that would +block to a separate I/O worker thread. +.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 IMPLEMENTATION NOTES +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 +Completing the entire transfer would have required disk I/O, so +it was aborted. +Partial data may have been sent. +(This error can only occur when +.Dv SF_NODISKIO +is specified.) +.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 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 . +.Sh AUTHORS +The +.Fn sendfile +system call +and this manual page were written by +.An David G. Lawrence Aq dg@dglawrence.com . diff --git a/lib/libc/sys/setgroups.2 b/lib/libc/sys/setgroups.2 new file mode 100644 index 0000000..e481229 --- /dev/null +++ b/lib/libc/sys/setgroups.2 @@ -0,0 +1,89 @@ +.\" 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 , +as defined in +.In sys/param.h . +.Pp +Only the super-user may set new groups. +.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 +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 0000000..a56d831 --- /dev/null +++ b/lib/libc/sys/setpgid.2 @@ -0,0 +1,105 @@ +.\" 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. +.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 0000000..2eedae2 --- /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 0000000..08d07f3 --- /dev/null +++ b/lib/libc/sys/setresuid.2 @@ -0,0 +1,99 @@ +.\" 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 April 13, 2001 +.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 STANDARDS +These system calls are not available on many platforms. +They exist in +.Fx +to support Linux binaries linked against GNU libc2. +.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 0000000..2983820 --- /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 0000000..a09a31a --- /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 0000000..78e4ab8 --- /dev/null +++ b/lib/libc/sys/setuid.2 @@ -0,0 +1,193 @@ +.\" 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 June 4, 1993 +.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 sys/types.h +.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 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 is set: +.Bd -literal +void +pseudocode(void) +{ + int fd; + /* ... */ + + fd = open("/path/to/sensitive/data", O_RDWR); + if (fd == -1) + err(1, "open"); + + /* + * Set close-on-exec flag; see fcntl(2) for more information. + */ + if (fcntl(fd, F_SETFD, FD_CLOEXEC) == -1) + err(1, "fcntl(F_SETFD)"); + /* ... */ + execve(path, argv, environ); +} +.Ed +.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 . diff --git a/lib/libc/sys/shm_open.2 b/lib/libc/sys/shm_open.2 new file mode 100644 index 0000000..b68e85b --- /dev/null +++ b/lib/libc/sys/shm_open.2 @@ -0,0 +1,192 @@ +.\" +.\" 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 March 24, 2000 +.Dt SHM_OPEN 3 +.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 +.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 +function opens (or optionally creates) a +.Tn POSIX +shared memory object named +.Fa path . +The +.Fn shm_unlink +function removes a shared memory object named +.Fa path . +.Pp +In the +.Fx +implementation, +.Tn POSIX +shared memory objects are implemented as ordinary files. +The +.Fn shm_open +and +.Fn shm_unlink +act as wrappers around the +.Xr open 2 +and +.Xr unlink 2 +routines, and +.Fa path , +.Fa flags , +and +.Fa mode +arguments are as specified for those functions. +The +.Fa flags +argument is checked to ensure that the access mode specified is not +.Dv O_WRONLY +(which is not defined for shared memory objects). +.Pp +In addition, the +.Fx +implementation causes +.Fn mmap +of a descriptor returned by +.Fn shm_open +to behave as if the +.Dv MAP_NOSYNC +flag had been specified to +.Xr mmap 2 . +(It does so by setting a special file flag using +.Xr fcntl 2 . ) +.Pp +The +.Fn shm_unlink +function makes no effort to ensure that +.Fa path +refers to a shared memory object. +.Sh RETURN VALUES +If successful, +.Fn shm_open +returns a non-negative integer; +.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 this +and 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 +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. +It is also undefined whether the shared memory object itself, or its +contents, persist across reboots. +.Sh ERRORS +The +.Fn shm_open +and +.Fn shm_unlink +functions can fail with any error defined for +.Fn open +and +.Fn unlink , +respectively. +In addition, the following errors are defined for +.Fn shm_open : +.Bl -tag -width Er +.It Bq Er EINVAL +The object named by +.Fa path +is not a shared memory object +(i.e., it is not a regular file). +.It Bq Er EINVAL +The +.Fa flags +argument to +.Fn shm_open +specifies an access mode of +.Dv O_WRONLY . +.El +.Sh SEE ALSO +.Xr mmap 2 , +.Xr munmap 2 , +.Xr open 2 , +.Xr unlink 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 . +.Sh AUTHORS +.An Garrett A. Wollman Aq wollman@FreeBSD.org +(C library support and this manual page) +.Pp +.An Matthew Dillon Aq 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 0000000..8fe340c --- /dev/null +++ b/lib/libc/sys/shmat.2 @@ -0,0 +1,123 @@ +.\" +.\" 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 machine/param.h +.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 0000000..90c61c9 --- /dev/null +++ b/lib/libc/sys/shmctl.2 @@ -0,0 +1,140 @@ +.\" +.\" 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 July 17, 1995 +.Dt SHMCTL 2 +.Os +.Sh NAME +.Nm shmctl +.Nd shared memory control +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/param.h +.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; +however, once the IPC_RMID operation has taken place, no further +processes will be allowed to attach the segment. +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. +.\" .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 */ + int 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 */ + short 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() */ + void *shm_internal; /* sysv stupidity */ +}; +.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 0000000..e7fd6d1 --- /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 July 3, 1995 +.Dt SHMGET 2 +.Os +.Sh NAME +.Nm shmget +.Nd obtain a shared memory identifier +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In machine/param.h +.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 SHM_R +Read access for user. +.It Dv SHM_W +Write access for user. +.It Dv ( SHM_R>>3 ) +Read access for group. +.It Dv ( SHM_W>>3 ) +Write access for group. +.It Dv ( SHM_R>>6 ) +Read access for other. +.It Dv ( SHM_W>>6 ) +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 ftok 3 diff --git a/lib/libc/sys/shutdown.2 b/lib/libc/sys/shutdown.2 new file mode 100644 index 0000000..70211ff --- /dev/null +++ b/lib/libc/sys/shutdown.2 @@ -0,0 +1,191 @@ +.\" 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 March 5, 2007 +.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 Return value and action +.It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta +Return \-1. +The global variable +.Va errno +will be set to +.Er EOPNOTSUPP . +.It Dv PF_INET Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta +Return 0. +ICMP messages will +.Em not +be generated. +.It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta +Return 0. +Send queued data and tear down association. +.It Dv PF_INET Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta +Return 0. +Send queued data, wait for ACK, then send FIN. +.It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_SCTP Ta +Return \-1. +The global variable +.Va errno +will be set to +.Er EOPNOTSUPP . +.It Dv PF_INET6 Ta Dv SOCK_DGRAM Ta Dv IPPROTO_UDP Ta +Return 0. +ICMP messages will +.Em not +be generated. +.It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_SCTP Ta +Return 0. +Send queued data and tear down association. +.It Dv PF_INET6 Ta Dv SOCK_STREAM Ta Dv IPPROTO_TCP Ta +Return 0. +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 EOPNOTSUPP +The socket associated with the file descriptor +.Fa s +does not support this operation. +.It Bq Er ENOTCONN +The +.Fa s +argument specifies a +.Dv SOCK_STREAM +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 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 0000000..4c4f18f --- /dev/null +++ b/lib/libc/sys/sigaction.2 @@ -0,0 +1,665 @@ +.\" 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 June 7, 2004 +.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 { + union { + void (*__sa_handler)(int); + void (*__sa_sigaction)(int, struct __siginfo *, void *); + } __sigaction_u; /* signal handler */ + int sa_flags; /* see signal options below */ + sigset_t sa_mask; /* signal mask to apply */ +}; + +#define sa_handler __sigaction_u.__sa_handler +#define sa_sigaction __sigaction_u.__sa_sigaction +.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 process +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 , +in which case its delivery is postponed 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 process. +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 process. +The signal mask for a process is initialized +from that of its parent (normally empty). +It may be changed with a +.Xr sigprocmask 2 +call, or when a signal is delivered to the process. +.Pp +When a signal +condition arises for a process, the signal is added to a set of +signals pending for the process. +If the signal is not currently +.Em blocked +by the process then it is delivered to the process. +Signals may be delivered any time a process 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 process 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 process will resume execution in the context +from before the signal's delivery. +If the process 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 process 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 +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 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 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 Default Action Description" +.It Dv SIGHUP No " terminate process" " terminal line hangup" +.It Dv SIGINT No " terminate process" " interrupt program" +.It Dv SIGQUIT No " create core image" " quit program" +.It Dv SIGILL No " create core image" " illegal instruction" +.It Dv SIGTRAP No " create core image" " trace trap" +.It Dv SIGABRT No " create core image" Ta Xr abort 3 +call (formerly +.Dv SIGIOT ) +.It Dv SIGEMT No " create core image" " emulate instruction executed" +.It Dv SIGFPE No " create core image" " floating-point exception" +.It Dv SIGKILL No " terminate process" " kill program" +.It Dv SIGBUS No " create core image" " bus error" +.It Dv SIGSEGV No " create core image" " segmentation violation" +.It Dv SIGSYS No " create core image" " non-existent system call invoked" +.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" +.It Dv SIGALRM No " terminate process" " real-time timer expired" +.It Dv SIGTERM No " terminate process" " software termination signal" +.It Dv SIGURG No " discard signal" " urgent condition present on socket" +.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" +.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" +.It Dv SIGCONT No " discard signal" " continue after stop" +.It Dv SIGCHLD No " discard signal" " child status has changed" +.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" +.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" +.It Dv SIGIO No " discard signal" Tn " I/O" +is possible on a descriptor (see +.Xr fcntl 2 ) +.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" +.Xr setitimer 2 ) +.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" +.Xr setitimer 2 ) +.It Dv SIGWINCH No " discard signal" " Window size change" +.It Dv SIGINFO No " discard signal" " status request from keyboard" +.It Dv SIGUSR1 No " terminate process" " User defined signal 1" +.It Dv SIGUSR2 No " terminate process" " 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: +.Pp +Base Interfaces: +.Pp +.Fn _exit , +.Fn access , +.Fn alarm , +.Fn cfgetispeed , +.Fn cfgetospeed , +.Fn cfsetispeed , +.Fn cfsetospeed , +.Fn chdir , +.Fn chmod , +.Fn chown , +.Fn close , +.Fn creat , +.Fn dup , +.Fn dup2 , +.Fn execle , +.Fn execve , +.Fn fcntl , +.Fn fork , +.Fn fpathconf , +.Fn fstat , +.Fn fsync , +.Fn getegid , +.Fn geteuid , +.Fn getgid , +.Fn getgroups , +.Fn getpgrp , +.Fn getpid , +.Fn getppid , +.Fn getuid , +.Fn kill , +.Fn link , +.Fn lseek , +.Fn mkdir , +.Fn mkfifo , +.Fn open , +.Fn pathconf , +.Fn pause , +.Fn pipe , +.Fn raise , +.Fn read , +.Fn rename , +.Fn rmdir , +.Fn setgid , +.Fn setpgid , +.Fn setsid , +.Fn setuid , +.Fn sigaction , +.Fn sigaddset , +.Fn sigdelset , +.Fn sigemptyset , +.Fn sigfillset , +.Fn sigismember , +.Fn signal , +.Fn sigpending , +.Fn sigprocmask , +.Fn sigsuspend , +.Fn sleep , +.Fn stat , +.Fn sysconf , +.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 utime , +.Fn wait , +.Fn waitpid , +.Fn write . +.Pp +Realtime Interfaces: +.Pp +.Fn aio_error , +.Fn clock_gettime , +.Fn sigpause , +.Fn timer_getoverrun , +.Fn aio_return , +.Fn fdatasync , +.Fn sigqueue , +.Fn timer_gettime , +.Fn aio_suspend , +.Fn sem_post , +.Fn sigset , +.Fn timer_settime . +.Pp +.Tn ANSI C +Interfaces: +.Pp +.Fn strcpy , +.Fn strcat , +.Fn strncpy , +.Fn strncat , +and perhaps some others. +.Pp +Extension Interfaces: +.Pp +.Fn strlcpy , +.Fn strlcat . +.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 when called from a signal handler is undefined. +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 EFAULT +Either +.Fa act +or +.Fa oact +points to memory that is not a valid part of the process +address space. +.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 sigaltstack 2 , +.Xr sigblock 2 , +.Xr sigpause 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsetmask 2 , +.Xr sigsuspend 2 , +.Xr sigvec 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/sigaltstack.2 b/lib/libc/sys/sigaltstack.2 new file mode 100644 index 0000000..da6877e --- /dev/null +++ b/lib/libc/sys/sigaltstack.2 @@ -0,0 +1,164 @@ +.\" 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 1, 1995 +.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 sigaltstack { + 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 users to define an alternate stack on which signals +are to be processed. +If +.Fa ss +is non-zero, +it specifies a pointer to and the size of a +.Em "signal stack" +on which to deliver signals, +and tells the system if the process is currently executing +on that stack. +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 process is currently executing on that stack. +If the process 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 +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. +Trying to disable an active stack will cause +.Fn sigaltstack +to return -1 with +.Va errno +set to +.Er EINVAL . +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 process 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,0) < 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 EINVAL +An attempt was made to disable an active stack. +.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 0000000..37f92d8 --- /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 January 12, 1994 +.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 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 0000000..ef555a4 --- /dev/null +++ b/lib/libc/sys/sigprocmask.2 @@ -0,0 +1,125 @@ +.\" 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 June 4, 1993 +.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. +.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 sigsetops 3 +.Sh STANDARDS +The +.Fn sigprocmask +system call is expected to +conform to +.St -p1003.1-90 . diff --git a/lib/libc/sys/sigqueue.2 b/lib/libc/sys/sigqueue.2 new file mode 100644 index 0000000..780b6a0 --- /dev/null +++ b/lib/libc/sys/sigqueue.2 @@ -0,0 +1,148 @@ +.\" 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 November 11, 2005 +.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 EEPERM +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 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 0000000..a022470 --- /dev/null +++ b/lib/libc/sys/sigreturn.2 @@ -0,0 +1,93 @@ +.\" 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 June 4, 1993 +.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 processes 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 NOTES +This system call is not available in +.Bx 4.2 +hence it should not be used if backward compatibility is needed. +.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 process 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 sigvec 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 0000000..efd7ed7 --- /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 0000000..3a67b53 --- /dev/null +++ b/lib/libc/sys/sigsuspend.2 @@ -0,0 +1,81 @@ +.\" 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 May 16, 1995 +.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 sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 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/sigwait.2 b/lib/libc/sys/sigwait.2 new file mode 100644 index 0000000..8c00cf4 --- /dev/null +++ b/lib/libc/sys/sigwait.2 @@ -0,0 +1,119 @@ +.\" 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 November 11, 2005 +.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 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 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. +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.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/sigwaitinfo.2 b/lib/libc/sys/sigwaitinfo.2 new file mode 100644 index 0000000..41be9e2 --- /dev/null +++ b/lib/libc/sys/sigwaitinfo.2 @@ -0,0 +1,199 @@ +.\" 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 November 11, 2005 +.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. +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. +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.Pp +.El +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/socket.2 b/lib/libc/sys/socket.2 new file mode 100644 index 0000000..1cf3af8 --- /dev/null +++ b/lib/libc/sys/socket.2 @@ -0,0 +1,293 @@ +.\" 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 November 24, 1997 +.Dt SOCKET 2 +.Os +.Sh NAME +.Nm socket +.Nd create an endpoint for communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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, formerly called PF_UNIX, +PF_UNIX Host-internal protocols, deprecated, use PF_LOCAL, +PF_INET Internet version 4 protocols, +PF_PUP PUP protocols, like BSP, +PF_APPLETALK AppleTalk protocols, +PF_ROUTE Internal Routing protocol, +PF_LINK Link layer interface, +PF_IPX Novell Internet Packet eXchange protocol, +PF_RTIP Help Identify RTIP packets, +PF_PIP Help Identify PIP packets, +PF_ISDN Integrated Services Digital Network, +PF_KEY Internal key-management function, +PF_INET6 Internet version 6 protocols, +PF_NATM Native ATM access, +PF_ATM ATM, +PF_NETGRAPH Netgraph sockets +.Ed +.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 +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 +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 +insure 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). +A +.Dv SIGPIPE +signal is raised if a process sends +on a broken stream; this causes naive processes, +which do not handle the signal, to exit. +.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 EPROTONOSUPPORT +The protocol type or the specified protocol is not supported +within this domain. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.It Bq Er ENOBUFS +Insufficient buffer space is available. +The socket cannot be created until sufficient resources are freed. +.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 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 0000000..c86db43 --- /dev/null +++ b/lib/libc/sys/socketpair.2 @@ -0,0 +1,91 @@ +.\" 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 June 4, 1993 +.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 d" "int type" "int protocol" "int *sv" +.Sh DESCRIPTION +The +.Fn socketpair +system call creates an unnamed pair of connected sockets in +the specified domain +.Fa d , +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. +.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 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/stack_protector.c b/lib/libc/sys/stack_protector.c new file mode 100644 index 0000000..08a68f1 --- /dev/null +++ b/lib/libc/sys/stack_protector.c @@ -0,0 +1,119 @@ +/* $FreeBSD$ */ +/* $NetBSD: stack_protector.c,v 1.4 2006/11/22 17:23:25 christos Exp $ */ +/* $OpenBSD: stack_protector.c,v 1.10 2006/03/31 05:34:44 deraadt Exp $ */ +/* + * Copyright (c) 2002 Hiroaki Etoh, Federico G. Schwindt, and Miodrag Vallat. + * 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 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. + * + */ + +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/param.h> +#include <sys/sysctl.h> +#include <sys/types.h> +#include <signal.h> +#include <string.h> +#include <syslog.h> +#include <unistd.h> + +extern int __sysctl(int *name, u_int namelen, void *oldp, size_t *oldlenp, + void *newp, size_t newlen); + +long __stack_chk_guard[8] = {0, 0, 0, 0, 0, 0, 0, 0}; +static void __guard_setup(void) __attribute__((__constructor__, __used__)); +static void __fail(const char *); +void __stack_chk_fail(void); +void __chk_fail(void); +void __stack_chk_fail_local(void); + +/*LINTED used*/ +static void +__guard_setup(void) +{ + int mib[2]; + size_t len; + + if (__stack_chk_guard[0] != 0) + return; + + mib[0] = CTL_KERN; + mib[1] = KERN_ARND; + + len = sizeof(__stack_chk_guard); + if (__sysctl(mib, 2, __stack_chk_guard, &len, NULL, 0) == -1 || + len != sizeof(__stack_chk_guard)) { + /* If sysctl was unsuccessful, use the "terminator canary". */ + ((unsigned char *)(void *)__stack_chk_guard)[0] = 0; + ((unsigned char *)(void *)__stack_chk_guard)[1] = 0; + ((unsigned char *)(void *)__stack_chk_guard)[2] = '\n'; + ((unsigned char *)(void *)__stack_chk_guard)[3] = 255; + } +} + +/*ARGSUSED*/ +static void +__fail(const char *msg) +{ + struct sigaction sa; + sigset_t mask; + + /* Immediately block all signal handlers from running code */ + (void)sigfillset(&mask); + (void)sigdelset(&mask, SIGABRT); + (void)sigprocmask(SIG_BLOCK, &mask, NULL); + + /* This may fail on a chroot jail... */ + syslog(LOG_CRIT, msg); + + (void)memset(&sa, 0, sizeof(sa)); + (void)sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + sa.sa_handler = SIG_DFL; + (void)sigaction(SIGABRT, &sa, NULL); + (void)kill(getpid(), SIGABRT); + _exit(127); +} + +void +__stack_chk_fail(void) +{ + __fail("stack overflow detected; terminated"); +} + +void +__chk_fail(void) +{ + __fail("buffer overflow detected; terminated"); +} + +void +#ifdef __GNUC__ +__attribute__((visibility ("hidden"))) +#endif +__stack_chk_fail_local(void) +{ + __stack_chk_fail(); +} diff --git a/lib/libc/sys/stat.2 b/lib/libc/sys/stat.2 new file mode 100644 index 0000000..e767451 --- /dev/null +++ b/lib/libc/sys/stat.2 @@ -0,0 +1,351 @@ +.\" 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 October 12, 2006 +.Dt STAT 2 +.Os +.Sh NAME +.Nm stat , +.Nm lstat , +.Nm fstat +.Nd get file status +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/stat.h +.Ft int +.Fn stat "const char *path" "struct stat *sb" +.Ft int +.Fn lstat "const char *path" "struct stat *sb" +.Ft int +.Fn fstat "int fd" "struct stat *sb" +.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 +.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_birthtime" +.It Va st_atime +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_mtime +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_ctime +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_birthtime +Time when the inode was created. +.El +.Pp +If +.Dv _POSIX_SOURCE +is not defined, the time-related fields are defined as: +.Bd -literal +#ifndef _POSIX_SOURCE +#define st_atime st_atimespec.tv_sec +#define st_mtime st_mtimespec.tv_sec +#define st_ctime st_ctimespec.tv_sec +#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 +.Bl -tag -width Er +The +.Fn fstat +system call will fail if: +.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 +.Sh SEE ALSO +.Xr access 2 , +.Xr chmod 2 , +.Xr chown 2 , +.Xr fhstat 2 , +.Xr statfs 2 , +.Xr utimes 2 , +.Xr symlink 7 , +.Xr sticky 8 +.Sh STANDARDS +The +.Fn stat +and +.Fn fstat +system calls are expected to conform to +.St -p1003.1-90 . +.Sh HISTORY +The +.Fn stat +and +.Fn fstat +system calls appeared in +.At v7 . +The +.Fn lstat +system call appeared in +.Bx 4.2 . +.Sh BUGS +Applying +.Fn fstat +to a socket (and thus to a pipe) +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 0000000..888f976 --- /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/swapon.2 b/lib/libc/sys/swapon.2 new file mode 100644 index 0000000..b3e4474 --- /dev/null +++ b/lib/libc/sys/swapon.2 @@ -0,0 +1,147 @@ +.\" 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 June 4, 1993 +.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 EINVAL +The system has reached the boot-time limit on the number of +swap devices, +.Va vm.nswapdev . +.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 0000000..28d77f5 --- /dev/null +++ b/lib/libc/sys/symlink.2 @@ -0,0 +1,150 @@ +.\" 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 December 9, 2006 +.Dt SYMLINK 2 +.Os +.Sh NAME +.Nm symlink +.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" +.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. +.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 +.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 HISTORY +The +.Fn symlink +system call appeared in +.Bx 4.2 . diff --git a/lib/libc/sys/sync.2 b/lib/libc/sys/sync.2 new file mode 100644 index 0000000..ff588ff --- /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 user 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 0000000..bd060d1 --- /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 0000000..a9402d6 --- /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/timer_create.2 b/lib/libc/sys/timer_create.2 new file mode 100644 index 0000000..9e4bc23 --- /dev/null +++ b/lib/libc/sys/timer_create.2 @@ -0,0 +1,164 @@ +.\" 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_CREATE 2 +.Os +.Sh NAME +.Nm timer_create +.Nd "create a per-process timer (REALTIME)" +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In time.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. +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, and the +.Va sigev_value +member having +the value of the timer ID. +.Pp +The implementations supports a +.Fa clock_id +of +.Dv CLOCK_REALTIME +or +.Dv CLOCK_MONOTONIC . +.Pp +If +.Fa evp->sigev_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 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_getoverun 2 , +.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 0000000..36d9775 --- /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 libc +.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 0000000..82f3eb7 --- /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 libc +.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/truncate.2 b/lib/libc/sys/truncate.2 new file mode 100644 index 0000000..f06c1eb --- /dev/null +++ b/lib/libc/sys/truncate.2 @@ -0,0 +1,153 @@ +.\" 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 December 13, 2006 +.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. +With +.Fn ftruncate , +the file must be open for writing. +.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 socket, not a file. +.It Bq Er EINVAL +The +.Fa fd +descriptor +is not open for writing. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr open 2 +.Sh HISTORY +The +.Fn truncate +system call 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/truncate.c b/lib/libc/sys/truncate.c new file mode 100644 index 0000000..e26f3f5 --- /dev/null +++ b/lib/libc/sys/truncate.c @@ -0,0 +1,52 @@ +/* + * Copyright (c) 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. + */ + +#if defined(LIBC_SCCS) && !defined(lint) +static char sccsid[] = "@(#)truncate.c 8.1 (Berkeley) 6/17/93"; +#endif /* LIBC_SCCS and not lint */ +#include <sys/cdefs.h> +__FBSDID("$FreeBSD$"); + +#include <sys/types.h> +#include <sys/syscall.h> + +#include <unistd.h> + +/* + * This function provides 64-bit offset padding that + * is not supplied by GCC 1.X but is supplied by GCC 2.X. + */ +int +truncate(path, length) + const char *path; + off_t length; +{ + + return(__syscall((quad_t)SYS_truncate, path, 0, length)); +} diff --git a/lib/libc/sys/umask.2 b/lib/libc/sys/umask.2 new file mode 100644 index 0000000..025a726 --- /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 0000000..f686f5e --- /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 0000000..11a3b36 --- /dev/null +++ b/lib/libc/sys/unlink.2 @@ -0,0 +1,124 @@ +.\" 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 December 10, 2006 +.Dt UNLINK 2 +.Os +.Sh NAME +.Nm unlink +.Nd remove directory entry +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fn unlink "const char *path" +.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. +.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 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. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr close 2 , +.Xr link 2 , +.Xr rmdir 2 , +.Xr symlink 7 +.Sh HISTORY +The +.Fn unlink +function appeared in +.At v6 . +.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/utimes.2 b/lib/libc/sys/utimes.2 new file mode 100644 index 0000000..c67af8e --- /dev/null +++ b/lib/libc/sys/utimes.2 @@ -0,0 +1,214 @@ +.\" $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 December 9, 2006 +.Dt UTIMES 2 +.Os +.Sh NAME +.Nm utimes , +.Nm lutimes , +.Nm futimes +.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" +.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 . +.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. +.Sh RETURN VALUES +.Rv -std +.Sh ERRORS +The +.Fn utimes +and +.Fn lutimes +system calls +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +Search permission is denied for a component of the path prefix; +or 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 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 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 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 +All of the system calls will fail if: +.Bl -tag -width Er +.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 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 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 EROFS +The file system containing the file is mounted read-only. +.El +.Sh SEE ALSO +.Xr chflags 2 , +.Xr stat 2 , +.Xr utime 3 +.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 . diff --git a/lib/libc/sys/utrace.2 b/lib/libc/sys/utrace.2 new file mode 100644 index 0000000..a83c185 --- /dev/null +++ b/lib/libc/sys/utrace.2 @@ -0,0 +1,86 @@ +.\" $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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation 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 ``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 28, 2000 +.Dt UTRACE 2 +.Os +.Sh NAME +.Nm utrace +.Nd insert user record in ktrace log +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.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 ktrace 2 +.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 0000000..9c90102 --- /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 0000000..928130b --- /dev/null +++ b/lib/libc/sys/vfork.2 @@ -0,0 +1,137 @@ +.\" 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 June 4, 1993 +.Dt VFORK 2 +.Os +.Sh NAME +.Nm vfork +.Nd spawn new process in a virtual memory efficient way +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In unistd.h +.Ft pid_t +.Fn vfork void +.Sh DESCRIPTION +The +.Fn vfork +system call +can be used to create new processes without fully copying the address +space of the old process, which is horrendously 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's memory and thread of +control until a call to +.Xr execve 2 +or an exit (either by a call to +.Xr _exit 2 +or abnormally). +The parent process is suspended while the child is using its resources. +.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 +The +.Fn vfork +system call +can normally be used just like +.Xr fork 2 . +It does not work, however, 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. +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 execve 2 , +.Xr _exit 2 , +.Xr fork 2 , +.Xr rfork 2 , +.Xr sigvec 2 , +.Xr wait 2 , +.Xr exit 3 +.Sh HISTORY +The +.Fn vfork +system call appeared in +.Bx 2.9 . +.Sh BUGS +This system call will be eliminated when proper system sharing +mechanisms are implemented. +Users should not depend on the memory +sharing semantics of +.Fn vfork +as it will, in that case, be made synonymous to +.Xr fork 2 . +.Pp +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 0000000..f4dfe9d --- /dev/null +++ b/lib/libc/sys/wait.2 @@ -0,0 +1,344 @@ +.\" 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 November 12, 2005 +.Dt WAIT 2 +.Os +.Sh NAME +.Nm wait , +.Nm waitpid , +.Nm wait4 , +.Nm wait3 +.Nd wait for process termination +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/wait.h +.Ft pid_t +.Fn wait "int *status" +.In sys/time.h +.In sys/resource.h +.Ft pid_t +.Fn waitpid "pid_t wpid" "int *status" "int options" +.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" +.Sh DESCRIPTION +The +.Fn wait +function suspends execution of its calling process until +.Fa status +information is available for a terminated child process, +or a signal is received. +On return from a successful +.Fn wait +call, +the +.Fa status +area contains termination information about the process that exited +as defined below. +.Pp +The +.Fn wait4 +system call provides a more general interface for programs +that need to wait for certain child processes, +that need resource utilization statistics accumulated by child processes, +or that require options. +The other wait functions are implemented using +.Fn wait4 . +.Pp +The +.Fa wpid +argument specifies the set of child processes for which to wait. +If +.Fa wpid +is -1, the call waits for any child process. +If +.Fa wpid +is 0, +the call waits for any child process in the process group of the caller. +If +.Fa wpid +is greater than zero, the call waits for the process with process id +.Fa wpid . +If +.Fa wpid +is less than -1, the call waits for any process whose process group id +equals the absolute value of +.Fa wpid . +.Pp +The +.Fa status +argument is defined below. +The +.Fa options +argument contains the bitwise OR of any of the following options. +The +.Dv WCONTINUED +option indicates that children of the current process that +have continued from a job control stop, by receiving a +.Dv SIGCONT +signal, should also have their status reported. +The +.Dv WNOHANG +option +is used to indicate that the call should not block if +there are no processes that wish to report status. +If the +.Dv WUNTRACED +option is set, +children of the current process that are stopped +due to a +.Dv SIGTTIN , SIGTTOU , SIGTSTP , +or +.Dv SIGSTOP +signal also have +their status reported. +.Pp +If +.Fa rusage +is non-zero, a summary of the resources used by the terminated +process and all its +children is returned (this information is currently not available +for stopped or continued processes). +.Pp +When the +.Dv WNOHANG +option is specified and no processes +wish to report status, +.Fn wait4 +returns a +process id +of 0. +.Pp +The +.Fn waitpid +function is identical to +.Fn wait4 +with an +.Fa rusage +value of zero. +The older +.Fn wait3 +call is the same as +.Fn wait4 +with a +.Fa wpid +value of -1. +.Pp +The following macros may be used to test the manner of exit of the process. +One of the first three macros will evaluate to a non-zero (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, +.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 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. +.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. +.El +.Sh SEE ALSO +.Xr _exit 2 , +.Xr ptrace 2 , +.Xr sigaction 2 , +.Xr exit 3 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Fn wait +and +.Fn waitpid +functions are defined by POSIX; +.Fn wait4 +and +.Fn wait3 +are not specified by POSIX. +The +.Fn WCOREDUMP +macro +and the ability to restart a pending +.Fn wait +call are extensions to the POSIX interface. +.Sh HISTORY +The +.Fn wait +function appeared in +.At v6 . diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2 new file mode 100644 index 0000000..6d60835 --- /dev/null +++ b/lib/libc/sys/write.2 @@ -0,0 +1,286 @@ +.\" 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 July 7, 2005 +.Dt WRITE 2 +.Os +.Sh NAME +.Nm write , +.Nm writev , +.Nm pwrite , +.Nm pwritev +.Nd write output +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/types.h +.In sys/uio.h +.In unistd.h +.Ft ssize_t +.Fn write "int d" "const void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset" +.Ft ssize_t +.Fn writev "int d" "const struct iovec *iov" "int iovcnt" +.Ft ssize_t +.Fn pwritev "int d" "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 d +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 d , +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 d +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 d +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 . |
